Quick Start

1. Initialize a project

shki init db --dialect postgres

init creates a project layout like:

db/
  shki.toml
  postgres-language-server.jsonc
  schema/
    main.sql
  migrations/
    _meta/

For PostgreSQL projects, postgres-language-server.jsonc is generated from the same init defaults so editor tooling points at the Declarative Schema entrypoint.

2. Configure your live database URL

export DATABASE_URL='postgres://user:pass@localhost:5432/mydb'

3. Edit the Declarative Schema entrypoint

-- db/schema/main.sql
CREATE TABLE users (
  id integer PRIMARY KEY,
  email text NOT NULL UNIQUE
);

4. Preview the Migration Plan

shki diff

5. Generate migration artifacts

shki generate create_users --down

This writes the migration SQL, its Snapshot, and a Journal entry (plus a Down Migration, thanks to --down):

db/migrations/
  0000_create_users.sql
  0000_create_users.down.sql
  _meta/
    0000_create_users.snapshot.json
    _journal.json

Commit all of it — the Snapshot is the baseline the next diff compares against.

6. Apply pending migrations

shki migrate            # everything pending
shki migrate --dry      # or preview first

migrate runs each pending file and records it, with its checksum, in the migrations table. Check where things stand at any point:

shki status

From here

Steps 3–6 are the loop: edit the schema, diff, generate, migrate.

• How It Works — what the Shadow Database, Snapshots, and Journal are doing
• Declarative Schema — extensions, multi-file schemas, external Shadow Database
• Migrations — hand-written SQL, rollback, adopting an existing database
• Already have a database? Adopt an existing database instead of starting from init.