SDK Installation

Install and configure the Postbase SDK.

Installation

npm install @postbase/sdk pg

Or with pnpm:

pnpm add @postbase/sdk pg

TypeScript Support

Install type definitions:

npm install -D @types/pg typescript

Basic Setup

Create Client

import { createClient } from '@postbase/sdk'
 
const db = createClient({
  connectionString: process.env.DATABASE_URL,
})

With Types

import { createClient } from '@postbase/sdk'
import type { Database } from './db/types'
 
const db = createClient<Database>({
  connectionString: process.env.DATABASE_URL,
})

Configuration Options

Connection String

const db = createClient({
  connectionString: 'postgresql://user:password@host:5432/database',
})

Individual Parameters

const db = createClient({
  host: 'localhost',
  port: 5432,
  database: 'myapp',
  user: 'postgres',
  password: 'postgres',
})

Connection Pool

const db = createClient({
  connectionString: process.env.DATABASE_URL,
  pool: {
    min: 2,           // Minimum connections
    max: 10,          // Maximum connections
    idleTimeoutMillis: 30000,  // Close idle connections after 30s
  },
})

SSL Configuration

// Require SSL
const db = createClient({
  connectionString: process.env.DATABASE_URL,
  ssl: true,
})
 
// With certificate
const db = createClient({
  connectionString: process.env.DATABASE_URL,
  ssl: {
    ca: fs.readFileSync('/path/to/ca.crt'),
    rejectUnauthorized: true,
  },
})
 
// Railway (no SSL needed)
const db = createClient({
  connectionString: process.env.DATABASE_URL + '?sslmode=disable',
})

Environment Setup

Development

# .env.development
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/myapp"

Production

# .env.production
DATABASE_URL="postgresql://postgres:xxx@xxx.proxy.rlwy.net:12345/railway?sslmode=disable"

Loading Environment

import 'dotenv/config'
import { createClient } from '@postbase/sdk'
 
const db = createClient({
  connectionString: process.env.DATABASE_URL!,
})

Generate Types

Generate TypeScript types from your database:

postbase types generate \
  --database myapp \
  --all \
  --output ./src/db/types.ts

See Type Generation for details.

Project Structure

Recommended file structure:

src/
├── db/
│   ├── client.ts    # Database client
│   └── types.ts     # Generated types
├── services/
│   └── users.ts     # Service using db client
└── index.ts

db/client.ts

import { createClient } from '@postbase/sdk'
import type { Database } from './types'
 
export const db = createClient<Database>({
  connectionString: process.env.DATABASE_URL!,
  pool: {
    min: 2,
    max: 10,
  },
})
 
export type { Database }

services/users.ts

import { db } from '../db/client'
 
export async function getActiveUsers() {
  return db.from('users').eq('active', true).execute()
}
 
export async function getUserById(id: number) {
  return db.from('users').eq('id', id).single()
}

Framework Integration

Express

import express from 'express'
import { db } from './db/client'
 
const app = express()
 
app.get('/users', async (req, res) => {
  const users = await db.from('users').execute()
  res.json(users)
})
 
// Graceful shutdown
process.on('SIGTERM', async () => {
  await db.close()
  process.exit(0)
})

Next.js

// lib/db.ts
import { createClient } from '@postbase/sdk'
import type { Database } from './types'
 
const globalForDb = globalThis as { db?: ReturnType<typeof createClient<Database>> }
 
export const db = globalForDb.db ?? createClient<Database>({
  connectionString: process.env.DATABASE_URL!,
})
 
if (process.env.NODE_ENV !== 'production') {
  globalForDb.db = db
}

Fastify

import Fastify from 'fastify'
import { db } from './db/client'
 
const fastify = Fastify()
 
fastify.get('/users', async () => {
  return db.from('users').execute()
})
 
fastify.addHook('onClose', async () => {
  await db.close()
})

Connection Lifecycle

Opening Connections

Connections are opened lazily on first query:

const db = createClient({ connectionString: '...' })
 
// No connection yet
 
const users = await db.from('users').execute()
// Connection opened here

Closing Connections

Always close connections when done:

// Graceful shutdown
process.on('SIGTERM', async () => {
  await db.close()
  process.exit(0)
})

Health Check

Verify database connectivity:

app.get('/health', async (req, res) => {
  try {
    await db.raw(sql`SELECT 1`)
    res.json({ database: 'connected' })
  } catch (error) {
    res.status(503).json({ database: 'disconnected' })
  }
})

Troubleshooting

Connection Refused

Error: connect ECONNREFUSED 127.0.0.1:5432

Ensure PostgreSQL is running
Check host and port in connection string

Authentication Failed

Error: password authentication failed for user "postgres"

Verify username and password
Check pg_hba.conf allows your connection

SSL Required

Error: The server does not support SSL connections

Add ?sslmode=disable for Railway
Or configure SSL properly for production