Local Development Overview

Postbase provides a complete local PostgreSQL development environment that runs entirely on your machine.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Your Machine                          │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   ┌─────────────┐      ┌─────────────────────────────┐ │
│   │   Your App  │      │       Admin UI              │ │
│   │             │      │    localhost:3000           │ │
│   └──────┬──────┘      └────────────┬────────────────┘ │
│          │                          │                   │
│          │         ┌────────────────┴────────────────┐ │
│          │         │         Postbase Daemon         │ │
│          │         │       localhost:9432            │ │
│          │         │                                 │ │
│          │         │  • Database Management          │ │
│          │         │  • Migration Engine             │ │
│          │         │  • Schema Operations            │ │
│          │         │  • Query Execution              │ │
│          │         └────────────────┬────────────────┘ │
│          │                          │                   │
│          │         ┌────────────────┴────────────────┐ │
│          └────────▶│      PostgreSQL (Docker)        │ │
│                    │       localhost:5432            │ │
│                    │                                 │ │
│                    │  • Single instance              │ │
│                    │  • Multiple databases           │ │
│                    │  • Pre-installed extensions     │ │
│                    └─────────────────────────────────┘ │
│                                                          │
└─────────────────────────────────────────────────────────┘

Key Features

Single PostgreSQL Instance

Unlike solutions that create one container per project, Postbase uses a single PostgreSQL instance that hosts multiple databases. This approach:

Reduces resource usage - One container instead of many
Simplifies management - Single point of control
Enables cross-database queries - Connect to multiple databases
Mirrors production - Same pattern as managed databases

SQL-First Migrations

Migrations are plain SQL files, giving you full control:

-- migrations/20260125_create_users.up.sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
 
CREATE INDEX idx_users_email ON users(email);

Benefits:

No abstraction layer - Write real PostgreSQL SQL
Version control friendly - Review changes in PRs
Checksum verification - Detect unauthorized changes
Multi-schema support - Organize by schema

Modern Admin UI

A web-based interface for database management:

Schema browser - Navigate tables, views, functions
Data viewer - Browse and edit data with inline editing
SQL editor - Execute queries with Monaco editor
Migration manager - Apply and rollback migrations

Pre-installed Extensions

The Supabase PostgreSQL image includes popular extensions:

Extension	Purpose
`pg_cron`	Job scheduling
`pgvector`	Vector similarity search
`PostGIS`	Geospatial queries
`pg_stat_statements`	Query performance
`uuid-ossp`	UUID generation
`pgcrypto`	Cryptographic functions

Getting Started

Start the Daemon

postbase start

Create a Database

postbase db create myapp

Get Connection Info

postbase connect myapp

Open Admin UI

# Start the UI (from postbase repo)
pnpm --filter @postbase/ui dev

Then open http://localhost:3000

Configuration

Default Ports

Service	Port
Daemon API	9432
PostgreSQL	5432
Admin UI	3000

Default Credentials

Host:     localhost
Port:     5432
User:     postgres
Password: postgres

Data Directory

All data is stored in ~/.postbase/:

~/.postbase/
├── data/           # PostgreSQL data files
├── state.json      # Daemon state
└── logs/           # Log files

Next Steps

Database Management - Create, list, delete databases
Migrations - Manage schema changes
Admin UI - Use the web interface