Environment Variables

Configure Postbase with environment variables.

CLI Environment Variables

Variable	Description	Default
`DATABASE_URL`	Default database connection string	-
`POSTBASE_API_URL`	Cloud API URL	https://api.postbase.sh
`POSTBASE_DAEMON_URL`	Local daemon URL	http://localhost:9432
`POSTBASE_DATA_DIR`	Data directory	~/.postbase
`POSTBASE_TOKEN`	Cloud API token	-

Usage

DATABASE_URL

Most commands use this for database connection:

export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/myapp"
 
# Now commands use this database
postbase migrate up
postbase types generate --output ./types.ts

POSTBASE_TOKEN

For CI/CD environments:

export POSTBASE_TOKEN="pb_xxx..."
 
# CLI uses this token instead of stored credentials
postbase cloud projects list

.env Files

Local Development

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

Load with dotenv

# package.json
{
  "scripts": {
    "dev": "dotenv -- tsx src/index.ts",
    "migrate": "dotenv -- postbase migrate up"
  }
}

Or in code:

import 'dotenv/config'

Environment-Specific Files

myapp/
├── .env                  # Default (development)
├── .env.staging          # Staging
├── .env.production       # Production
├── .env.example          # Template (committed)
└── .env.local            # Local overrides (not committed)

Example Files

# .env.example (commit this)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp
POSTBASE_TOKEN=
 
# .env.production (don't commit)
DATABASE_URL=postgresql://postgres:xxx@prod.example.com:5432/myapp
POSTBASE_TOKEN=pb_xxx...

CI/CD Configuration

GitHub Actions

env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  POSTBASE_TOKEN: ${{ secrets.POSTBASE_TOKEN }}
 
steps:
  - name: Run Migrations
    run: postbase migrate up

Vercel

vercel env add DATABASE_URL production

Railway

Environment variables are automatic for Railway databases.

Docker

FROM node:22-alpine
 
ENV DATABASE_URL=""
 
# Or use ARG for build-time
ARG DATABASE_URL

docker run -e DATABASE_URL="postgresql://..." myapp

SDK Configuration

The SDK reads DATABASE_URL automatically:

import { createClient } from '@postbase/sdk'
 
// Uses DATABASE_URL if no connectionString provided
const db = createClient()
 
// Or explicitly
const db = createClient({
  connectionString: process.env.DATABASE_URL,
})

Security Best Practices

Never Commit Secrets

# .gitignore
.env
.env.*
!.env.example

Use Secret Managers

Production deployments should use secret managers:

AWS Secrets Manager
HashiCorp Vault
Doppler
1Password Secrets

Rotate Credentials

Regularly rotate database passwords:

# Generate new password
NEW_PASSWORD=$(openssl rand -base64 24)
 
# Update in Railway/secret manager
# Update DATABASE_URL

Troubleshooting

Variable Not Set

Error: DATABASE_URL environment variable is not set

Ensure the variable is exported:

export DATABASE_URL="..."
# or
source .env

Wrong Environment

Check which .env file is loaded:

echo $DATABASE_URL

Quotes in Values

Avoid quotes in .env files:

# Bad
DATABASE_URL="postgresql://..."
 
# Good
DATABASE_URL=postgresql://...

(Unless you need spaces or special characters)