Skip to main content

Quick Start

This guide will walk you through setting up PostKit and running your first database migration.

1. Initialize a Project​

# Create a new directory
mkdir my-app && cd my-app

# Initialize with PostKit CLI
postkit init

This creates:

  • postkit.config.json - Non-sensitive configuration (committed to git)
  • postkit.secrets.json - Your credentials (gitignored)
  • postkit.secrets.example.json - Credentials template for teammates (committed)
  • db/schema/ - Your schema files directory
  • .postkit/ - Runtime state (ephemeral files gitignored; committed migrations and auth config are tracked by git)

To scaffold only one module instead of everything — e.g. to add auth to a project you only ever ran postkit init db on — pass its name: postkit init db, postkit init auth, or postkit init stack. See the Init Command reference for what each variant creates.

2. Configure Remotes​

Add your remote databases (all remote data is stored in postkit.secrets.json — remotes are user-specific and never committed):

# Add development remote (set as default)
postkit db remote add dev "postgres://user:pass@dev-host:5432/myapp" --default

# Add staging remote
postkit db remote add staging "postgres://user:pass@staging-host:5432/myapp"

3. Start a Migration Session​

Clone a remote database to your local machine:

postkit db start

This:

  1. Detects the remote PostgreSQL version
  2. Clones the remote database to local (auto-starts a Docker container if localDbUrl is empty)
  3. Creates a session to track your changes
  4. Prepares for schema modifications

4. Make Schema Changes​

Edit files in db/schema/<name>/:

-- db/schema/public/tables/users.sql
CREATE TABLE public.users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT NOT NULL UNIQUE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

5. Preview Changes​

See what will change:

postkit db plan

6. Apply Changes Locally​

Test your changes on the local clone:

postkit db apply

7. Commit for Deployment​

postkit db commit

This creates a migration file ready for deployment.

8. Deploy to Remote​

postkit db deploy --remote staging

PostKit performs a dry-run first to verify the migration works, then deploys to your remote database.

Common Commands​

CommandDescription
postkit db startStart a migration session
postkit db planPreview schema changes
postkit db applyApply changes to local DB
postkit db commitCommit migrations for deployment
postkit db deployDeploy to remote database
postkit db statusShow session state
postkit db abortCancel session and clean up
postkit stack upStart local backend stack (Postgres, Keycloak, PostgREST, Traefik)
postkit stack downStop all stack services
postkit stack statusShow stack service health

Next Steps​