This guide walks you through bringing a Supabase project into PostKit's migration workflow without disrupting your existing data.

What Changes (and What Doesn't)​

PostKit does not replace Supabase's auth, storage, or realtime features. If you use PostgREST/Supabase's auto-API, PostKit manages the underlying schema while your application code stays the same.

Step 1: Install PostKit​

npm install -g @appritech/postkit

Verify:

postkit --version

Step 2: Initialize PostKit in Your Project​

In your project root:

postkit init

This creates:

• postkit.config.json — committed, non-sensitive settings
• postkit.secrets.json — gitignored, your credentials
• postkit.secrets.example.json — template for teammates
• db/schema/ — where your schema files will live

Step 3: Add Your Supabase Database as a Remote​

Your Supabase project has a direct PostgreSQL connection URL. Find it in the Supabase dashboard under Settings → Database → Connection string → URI.

postkit db remote add supabase "postgres://postgres:[password]@db.[project-ref].supabase.co:5432/postgres" --default

Step 4: Import the Existing Schema​

PostKit's db import command connects to your Supabase database, dumps the schema, and organizes it into PostKit's directory structure:

postkit db import --url "postgres://postgres:[password]@db.[project-ref].supabase.co:5432/postgres"

For projects with multiple schemas (e.g. public and a custom app schema):

postkit db import --url "postgres://..." --schemas "public,app"

This automatically:

• Dumps all tables, views, functions, triggers, indexes, and constraints
• Organizes files into db/schema/public/tables/, views/, functions/, etc.
• Extracts roles and schemas into db/infra/
• Creates a baseline migration in .postkit/db/migrations/
• Updates postkit.config.json with the imported schema names

Step 5: Review the Generated Schema Files​

After import, your directory looks like:

db/
├── infra/
│   ├── roles.sql          # Any custom roles from Supabase
│   └── schemas.sql        # Schema definitions
└── schema/
    └── public/
        ├── tables/
        │   ├── 001_users.sql
        │   ├── 002_posts.sql
        │   └── ...
        ├── views/
        ├── functions/
        └── grants/

Take a few minutes to review. Supabase often creates helper functions and policies automatically — you'll want to understand what's there before making changes.

Supabase-specific objects to watch for​

• auth.* schema — Supabase's internal auth tables. Do not touch these — they're managed by Supabase, not your migrations.
• storage.* schema — same, managed by Supabase.
• Row-level security (RLS) policies — pgschema captures these in grants/ files.
• supabase_admin role — Supabase-internal role. Ignore or exclude.

If you only want to manage your own schemas (e.g. public and app) and leave auth and storage alone:

// postkit.config.json
{
  "db": {
    "schemas": ["public", "app"]
  }
}

Step 6: Make Your First Change with PostKit​

Now the normal workflow applies. Start a session:

postkit db start

Edit a schema file — for example, add a column:

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

Preview the diff:

postkit db plan

PostKit shows you exactly what SQL will be generated — no surprises.

Apply locally to test:

postkit db apply

Commit and deploy:

postkit db commit --message "add display_name to users"
postkit db deploy

PostKit runs a dry-run first (on a local clone of your Supabase DB), confirms the migration works, then deploys to the real database.

Common Supabase Migration Gotchas​

RLS policies after import​

Supabase enables RLS on many tables. pgschema captures existing policies, but new policies you add to schema files are planned per-schema in isolation. Policies that reference roles from auth.* (like auth.uid()) are fine — pgschema recognizes these as external references.

Extensions​

Supabase pre-installs extensions like uuid-ossp, pgcrypto, and pg_stat_statements. These were captured by import in db/infra/. The CREATE EXTENSION IF NOT EXISTS form means re-running them is safe.

The public schema default​

Supabase's public schema has a broad default grant (GRANT ALL ON SCHEMA public TO public). After import, this appears in your grants/ file. You can tighten or customize it.

What to Do With Existing Supabase Migrations​

If you have existing Supabase migration files (.sql files in supabase/migrations/), you don't need to port them. PostKit's db import creates a single baseline from the current database state — all prior history is collapsed into that baseline. Future changes go through PostKit's workflow.

Summary​

Your Supabase database is now under PostKit's session-based migration workflow. Schema changes are reviewed, tested locally, and deployed with a dry-run safety check before they ever touch production.

The Problem with "Write and Pray"​

Typical migration workflow:

1. Write an ALTER TABLE statement
2. Run it against staging
3. If staging looks okay, run it against production

The failure modes here are well-known:

• Missing index on a large table: migration takes 3 hours, locks the table, site goes down
• Foreign key constraint violation: existing data fails the new constraint, migration rolls back
• Wrong column type cast: ALTER COLUMN foo TYPE integer USING foo::integer fails because some rows have non-numeric values
• Schema drift: staging has been modified manually over time, production has a different column order or default value

These failures share a root cause: you didn't test the migration against a copy of the actual data.

The Session-Based Approach​

PostKit's model:

postkit db start   →  clone production data to local DB
postkit db plan    →  generate schema diff (pgschema)
postkit db apply   →  apply migration to local clone
postkit db commit  →  lock in the migration files
postkit db deploy  →  dry-run on fresh clone, then deploy to production

The key step is start. It uses pg_dump inside a version-matched Docker container to clone your remote database to a local PostgreSQL instance. This means:

• Your apply runs against real data, not an empty schema
• Version mismatch is impossible: the container image is selected to match your remote's major version
• No surprises on deploy: the migration has already run successfully on a copy of the exact database it will target

The Dry-Run Step​

Even with local testing, we run one more safety check during deploy: a fresh clone of the target database is spun up, the migration is applied there first, and only if it succeeds does PostKit apply to the real target.

deploy:
  1. Clone target DB to a new local container
  2. Run the migration on that clone
  3. If it fails → stop, report the error, touch nothing
  4. If it succeeds → apply to the real target

This catches the rare case where your local clone diverged from the target (e.g. someone else applied a manual change directly to staging).

pgschema: Diff Instead of Write​

PostKit uses pgschema to generate migration SQL. Rather than writing ALTER TABLE statements by hand, you declare the desired state in SQL files:

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

postkit db plan compares this file against the current database state and generates the minimal diff:

ALTER TABLE public.users ADD COLUMN name TEXT;

You don't write the migration — you write the schema. The tool figures out what needs to change.

What This Workflow Prevents​

The Trade-off​

The session approach costs you the time to clone the database at the start. For a 10GB database, that can be 2–5 minutes. For most teams this is a worthwhile investment — the alternative is discovering production issues after deployment.

For databases where a full clone is impractical (100GB+), you can use a representative subset or a pre-existing local PostgreSQL instance by setting localDbUrl in postkit.secrets.json. PostKit then skips the clone and connects directly.

Getting Started​

npm install -g @appritech/postkit
postkit init
postkit db remote add prod "postgres://..." --default
postkit db start    # clone happens here

From there, edit your schema files and run postkit db plan to see what changes.

PostKit handles multiple schemas natively, with a clear model for what goes where.

Why Multiple Schemas?​

Common reasons teams reach for multiple schemas:

• Application vs. internal separation: public for user-facing tables, app for internal/operational tables, audit for immutable audit logs
• Feature namespacing: each major domain gets its own schema to prevent table name collisions and enforce clear ownership
• Permission isolation: different roles can be granted access to different schemas with a single GRANT USAGE ON SCHEMA
• Multi-tenant: per-tenant schemas (advanced use case, not covered here)

The Challenge: Tools That Think in One Schema​

Most migration tools (Flyway, Liquibase, Prisma Migrate, plain dbmate) run a list of SQL files in order. They don't understand schema structure — they just execute. This works fine for public. It breaks when you have public.users and app.orders with a foreign key between them, because you have to manually manage the execution order across files.

PostKit's approach:

• Each schema is planned independently by pgschema (the diff engine)
• Schemas execute in config order — dependencies go earlier in the array
• Cross-schema SQL (FKs, views, triggers spanning two schemas) uses manual migrations applied after all schemas are set up

Setup: Adding a Second Schema​

1. Scaffold the directory​

postkit db schema add app

This creates db/schema/app/ with subdirectories for tables, views, functions, etc., and updates postkit.config.json:

{
  "db": {
    "schemas": ["public", "app"],
    "infraPath": "db/infra",
    "schemaPath": "db/schema"
  }
}

Array order matters — public runs before app.

2. Add the schema creation to infra​

PostKit's infra step handles DB-level objects that pgschema doesn't manage:

-- db/infra/002_schemas.sql
CREATE SCHEMA IF NOT EXISTS app;

3. Write schema files for the new schema​

-- db/schema/app/tables/orders.sql
CREATE TABLE app.orders (
  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id    UUID NOT NULL,
  status     TEXT NOT NULL DEFAULT 'pending',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Note: user_id is a plain UUID column here, not a foreign key to public.users. Cross-schema FKs require a different approach (below).

How Planning Works with Multiple Schemas​

When you run postkit db plan, PostKit processes schemas in config order:

1. Apply infra (CREATE SCHEMA app, CREATE ROLE ...) to local DB
2. Plan public schema:
   - pgschema compares db/schema/public/ against local DB
   - Generates plan_public.sql if changes exist
   - Intermediate apply: runs plan_public.sql on local DB
3. Plan app schema:
   - pgschema compares db/schema/app/ against local DB
   - public schema objects are now present (from step 2)
   - Generates plan_app.sql if changes exist

The intermediate apply in step 2 is what makes cross-schema resolution possible during the plan phase — app can reference tables from public via intra-session state, even though pgschema plans each schema in isolation.

Cross-Schema Foreign Keys​

Here's where developers get confused. pgschema plans each schema in an isolated environment. If you write this in db/schema/app/tables/orders.sql:

-- This will fail during plan:
REFERENCES public.users(id)  -- ❌ public.users doesn't exist in pgschema's isolated env

You'll get:

ERROR: relation "public.users" does not exist

The correct approach: keep the column as a plain UUID in the schema file, then add the constraint as a manual migration.

postkit db migration add_cross_schema_fks

-- migrate:up
ALTER TABLE app.orders
  ADD CONSTRAINT fk_orders_user
  FOREIGN KEY (user_id) REFERENCES public.users(id);

-- migrate:down
ALTER TABLE app.orders DROP CONSTRAINT IF EXISTS fk_orders_user;

Manual migrations run via dbmate after all schemas are applied — at that point, public.users exists and the FK works.

What Belongs Where​

Importing an Existing Multi-Schema Database​

If you already have a multi-schema database, import everything at once:

postkit db import --url "postgres://..." --schemas "public,app,audit"

PostKit dumps all three schemas, organizes them into subdirectories, and creates a single baseline migration covering all schemas.

The Result​

Once set up, the workflow is identical to single-schema projects:

postkit db start
# edit db/schema/public/ or db/schema/app/ files
postkit db plan    # shows diffs per schema
postkit db apply
postkit db commit
postkit db deploy

Each schema's changes are shown separately in the plan output, so you can review public and app changes independently before applying.

The Traditional Approach​

Tools like Flyway, Liquibase, and raw dbmate work like this:

migrations/
├── 001_create_users.sql
├── 002_add_email_to_users.sql
├── 003_create_posts.sql
├── 004_add_index_on_posts_user_id.sql
└── 005_rename_posts_to_articles.sql

To understand your current schema, you have to mentally replay all 200+ migrations. To change a column type, you write an ALTER COLUMN. To add an index, you write CREATE INDEX. Every migration is a manual, imperative instruction.

This model has real benefits — migrations are explicit, auditable, and easy to reason about individually. But it has a compounding cost: as the migration count grows, the cognitive overhead of understanding and maintaining the schema grows with it.

The Declarative Approach​

PostKit uses pgschema, a diff engine for PostgreSQL. Instead of writing migrations, you maintain SQL files that describe what your schema should look like:

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

When you want to add a column, you add it to the file. When you want to remove an index, you delete it from the file. The schema files are always the single source of truth for your current schema shape.

postkit db plan compares those files against the actual database and generates the minimal migration:

-- Generated by pgschema — you don't write this
ALTER TABLE public.users ADD COLUMN display_name TEXT;

What You Don't Have to Write​

With pgschema generating the diffs, you stop writing:

• ALTER TABLE ... ADD COLUMN
• ALTER TABLE ... DROP COLUMN
• CREATE INDEX / DROP INDEX
• ALTER TABLE ... ALTER COLUMN ... TYPE
• CREATE TABLE for new tables
• DROP TABLE for removed tables
• Column default additions and removals
• Constraint additions and removals (within a schema)

These are the bread-and-butter of day-to-day schema work. Getting them for free removes a whole category of typos and missed steps.

What You Still Write Manually​

Some SQL has to be written as manual migrations because pgschema can't diff it:

• CREATE ROLE / CREATE EXTENSION / CREATE SCHEMA → use db/infra/
• Cross-schema foreign keys and views → use postkit db migration
• Data backfills (UPDATE, INSERT) → use postkit db migration
• One-off operations (RENAME, column type changes with custom casts) → use postkit db migration

See Plan Command Limitations for the full list.

The pattern: structural schema changes within a single schema → let pgschema generate it. Everything else → write a manual migration.

The Schema Files as Documentation​

A side effect of the declarative model: your db/schema/ directory is always an accurate picture of your current database schema. No need to reconstruct it from 200 migration files. Junior developers joining the team can read db/schema/public/tables/ and understand the data model immediately.

Compare to the traditional model where the "documentation" is the migration history — useful for understanding how you got here, not for understanding where you are now.

Mixing Both Approaches​

PostKit doesn't force you to abandon explicit migrations. The postkit db migration command creates a manual migration file that runs alongside pgschema-generated ones. In a single session:

1. Edit schema files (pgschema generates the diff on plan)
2. Add a manual migration for a data backfill
3. postkit db apply runs both in sequence: pgschema's SQL first, then the manual migrations

This means you get the declarative model for structural changes and the imperative model for everything else — each where it's appropriate.

The Workflow at a Glance​

# Edit db/schema/public/tables/users.sql — add a column
# Edit db/schema/public/indexes/ — add an index

postkit db plan
# → Shows: ADD COLUMN display_name, CREATE INDEX idx_users_display_name

postkit db apply
# → Runs the migration on your local clone

postkit db commit
postkit db deploy
# → Dry-run, then deploy to production

The migration files are generated, not authored. Your job is maintaining the schema declaration; PostKit's job is figuring out the SQL.

When Prisma Migrate Stops Scaling​

Prisma Migrate works by translating your schema.prisma model into SQL migrations. This is great until you need:

• PostgreSQL views — not supported natively in schema.prisma
• RLS policies — not expressible in Prisma schema
• Custom functions and triggers — require raw SQL blocks in Prisma with db.execute
• Multi-schema projects — Prisma has limited multi-schema support and it varies by database connector
• Complex index types — GIN, BRIN, partial indexes require @@index raw map or custom SQL

Teams usually end up with a hybrid: Prisma Migrate for tables, a separate folder of raw SQL files for everything else. PostKit unifies these under one workflow.

What the Migration Looks Like​

The transition has two phases: getting your current schema into PostKit, then switching your ongoing workflow.

Phase 1: Import your existing database​

PostKit's db import command reads your current PostgreSQL database (not your schema.prisma) and generates schema files:

npm install -g @appritech/postkit
postkit init

# Add your database as a remote
postkit db remote add dev "postgres://..." --default

# Import the current schema
postkit db import --url "postgres://..."

This creates db/schema/public/ with all your current tables, views, functions, and constraints organized into subdirectories. Your Prisma-managed tables appear as plain SQL files — PostKit doesn't know or care how they were created.

Phase 2: Stop running prisma migrate​

From this point forward:

• Schema changes go in db/schema/<name>/ files
• postkit db plan generates the SQL diff
• postkit db apply → postkit db commit → postkit db deploy replaces prisma migrate dev / prisma migrate deploy

You can keep using Prisma as your ORM (queries, type generation, prisma generate). Just stop using prisma migrate.

Side-by-Side Comparison​

Keeping Prisma for Queries​

PostKit manages your schema; Prisma manages your application queries. These don't conflict. Your workflow becomes:

# Schema change:
# 1. Edit db/schema/public/tables/users.sql
postkit db plan
postkit db apply

# 2. Regenerate Prisma client to pick up the new column:
npx prisma db pull  # update schema.prisma from DB
npx prisma generate # regenerate client

prisma db pull reads the current database schema into schema.prisma, which you then commit alongside the PostKit schema file changes. PostKit owns the source of truth; Prisma reads it.

What About Existing Prisma Migrations?​

You don't need to port them. postkit db import creates a single baseline from the current database state — all prior migration history (Prisma or otherwise) is collapsed into that baseline. PostKit only cares about the current state and future changes.

Your existing prisma/migrations/ folder can stay in your repo as historical reference or be removed — PostKit doesn't interact with it.

The Practical Transition Checklist​

• Run postkit init in your project root
• Add your remote database: postkit db remote add dev "postgres://..."
• Run postkit db import --url "postgres://..." to generate db/schema/
• Review generated files — especially db/infra/ for roles and extensions
• Add prisma/migrations/ to your "no longer needed" list (keep for history, stop running)
• On schema changes: edit db/schema/ → postkit db plan → postkit db apply
• After schema changes: npx prisma db pull && npx prisma generate to update the Prisma client
• On deploy: postkit db commit && postkit db deploy

If you're running a pure SQL application (PostgREST, raw pg queries), skip the Prisma steps entirely — PostKit stands alone.