postbase.toml

Project configuration file for Postbase.

Overview

The postbase.toml file configures your Postbase project:

[project]
name = "myapp"
 
[database]
name = "myapp"
 
[migrations]
directory = "./migrations"
schema = "public"

Location

Place postbase.toml in your project root:

myapp/
├── postbase.toml
├── migrations/
├── src/
└── package.json

Configuration Sections

[project]

[project]
name = "myapp"           # Project name (used in cloud)

[database]

[database]
name = "myapp"           # Default database name
host = "localhost"       # Database host (optional)
port = 5432              # Database port (optional)
user = "postgres"        # Database user (optional)
password = "postgres"    # Database password (optional)

[migrations]

[migrations]
directory = "./migrations"    # Migration files directory
schema = "public"             # Default schema for migrations

[types]

[types]
output = "./src/db/types.ts"  # Generated types output path
include_functions = true      # Include PostgreSQL functions
include_views = true          # Include database views
include_enums = true          # Include enum types
dates_as_strings = false      # Map timestamps to string

[environments]

[environments.development]
database = "myapp_dev"
connection_string = "postgresql://postgres:postgres@localhost:5432/myapp_dev"
 
[environments.staging]
database = "myapp_staging"
connection_string = "${STAGING_DATABASE_URL}"
 
[environments.production]
database = "myapp_production"
connection_string = "${PRODUCTION_DATABASE_URL}"

Full Example

[project]
name = "myapp"
 
[database]
name = "myapp"
 
[migrations]
directory = "./migrations"
schema = "public"
 
[types]
output = "./src/db/types.ts"
include_functions = true
include_views = true
include_enums = true
 
[environments.development]
database = "myapp_dev"
connection_string = "postgresql://postgres:postgres@localhost:5432/myapp_dev"
 
[environments.staging]
database = "myapp_staging"
connection_string = "${STAGING_DATABASE_URL}"
 
[environments.production]
database = "myapp_production"
connection_string = "${PRODUCTION_DATABASE_URL}"

Using Environments

CLI Usage

# Use default (development)
postbase migrate up
 
# Use specific environment
postbase migrate up --env staging
 
# Use production
postbase migrate up --env production

Environment Variables

Reference environment variables with ${VAR_NAME}:

[environments.production]
connection_string = "${DATABASE_URL}"

Creating Config

Initialize

postbase init

Creates postbase.toml with defaults.

Interactive Setup

postbase init --interactive

Prompts for configuration values.

Validation

Validate your configuration:

postbase config validate

Override with CLI

CLI flags override config file:

# Override database
postbase migrate up --database other_db
 
# Override migrations directory
postbase migrate new create_users --dir ./db/migrations
 
# Override schema
postbase migrate up --schema auth

Environment Inheritance

Environments inherit from base:

[database]
user = "postgres"
password = "postgres"
 
[environments.development]
host = "localhost"
port = 5432
 
[environments.production]
host = "prod.example.com"
port = 5432
# Inherits user and password from [database]

Best Practices

Keep Secrets Out

Never commit secrets:

# Bad - hardcoded password
[environments.production]
connection_string = "postgresql://postgres:secret123@..."
 
# Good - use environment variable
[environments.production]
connection_string = "${PRODUCTION_DATABASE_URL}"

Use .env Files

# .env (development)
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/myapp"
 
# .env.production
DATABASE_URL="postgresql://postgres:xxx@prod.example.com:5432/myapp"

Version Control

Commit postbase.toml:

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

But keep .env files out of version control.