apso migrate

Detect schema changes, generate migration SQL, and test it against a local PGlite sandbox. No Docker or external database required.

Usage

apso migrate
apso migrate --apply
apso migrate --reset
apso migrate --sql

Options

How it works

The migration sandbox maintains a snapshot of your last-known schema state in .apso/sandbox/schema-snapshot.json. When you run apso migrate:

1. Compares your current .apsorc against the snapshot to detect changes
2. Builds the previous schema in an in-process Postgres database (PGlite)
3. Generates the migration SQL needed to move from the old schema to the new one
4. Executes the migration against the local database to verify it works
5. Reports the results with the SQL statements

If the migration succeeds locally, you know the SQL is valid before it touches any real database.

Examples

Check for schema changes and preview the migration:

apso migrate

Output:

Schema changes detected. Running migration sandbox...

Migration SQL (up):
---
  ALTER TABLE "project" ADD "priority" integer NOT NULL DEFAULT 0;
  CREATE TABLE "label" ("id" SERIAL PRIMARY KEY, "name" text NOT NULL);
---

2 statement(s) generated and tested.
Migration validated against local PGlite.
Run with --apply to update the snapshot.

Apply the migration (update the snapshot so future runs compare against the new state):

apso migrate --apply

Pipe raw SQL to a file:

apso migrate --sql > migration.sql

Reset the sandbox to start from a clean state:

apso migrate --reset

First run

On the first run, there is no previous snapshot. The sandbox generates CREATE TABLE statements for all entities and validates them. Run with --apply to establish the initial baseline.

Notes

• PGlite runs entirely in-process — no Docker, no external Postgres installation needed
• The snapshot file is stored at .apso/sandbox/schema-snapshot.json
• apso deploy runs the migration sandbox automatically before deploying