Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ The **Schema Change** page works on a saved live connection, not on the diagram

1. **Find the tables (optional).** You do not have to choose any. The catalog (names, columns, keys, estimated rows, sizes) is read in one round trip. The words of your request are matched against table, schema and column names, weighted by how rare each word is in *your* database, and the foreign-key neighbours of the best matches are added. The scope is shown with the reason for each table and you can add or remove tables. It matches names, not meanings: a request that calls `clients` "customers" finds nothing, and the plan then goes ahead with no table in scope. That is how a request for **new tables** works: the model is told the names of the existing tables (not their contents), creates the new ones with `create_table`, and any existing table its foreign keys point at is read afterwards so the keys are checked against that table's real columns. Names already taken in the database are refused.
2. **Give the planner facts.** Only the tables in scope are sent in full (the others by name): columns, keys, existing indexes with how often each was scanned (`pg_stat_user_indexes`), row estimates, data sizes, dependent views, and two aggregate statistics per column (NULL fraction, distinct-value estimate). Never rows, default expressions, index predicates or credentials.
3. **A model proposes operations; fixed rules write the SQL.** Each operation is checked against the real catalog (names exist, types are real, a foreign key points at a unique column, a NOT NULL column has a default when the table has rows, an index name is free, a default is accepted by PostgreSQL) and compiled into a runbook: `CREATE INDEX CONCURRENTLY`, foreign keys and checks `NOT VALID` then `VALIDATE`, `NOT NULL` through a validated `CHECK`, a `lock_timeout` on every step, batched committed backfills, and for a type change that would rewrite the table an expand/contract sequence (new column, trigger, batched copy, swap in one `DO` block, the old column dropped in a step that is commented out). Every step states its lock, the work it does, the size of the table and a risk class that follows from those three by a fixed rule, plus how to undo it where that is possible. The operations are `create_table`, `rename_table`, `drop_table`, `add_column`, `alter_column`, `drop_column`, `add_relationship`, `drop_relationship`, `add_index`, `drop_index`, `add_unique`, `add_check`, `drop_constraint`, `add_primary_key`, `create_enum` and `add_enum_value`. `create_enum` makes a type (a column can use it later in the same plan, with a default that is one of its labels) and `add_enum_value` adds a label, optionally before or after another: neither locks any table, and a label can never be removed again. An existing integer column can become an identity column (`alter_column` with `autoIncrement`): the sequence is started after the column's largest value in the same transaction, which needs an index on the column unless the table is small, and a serial column's old default is dropped in the same change. A drop or a type change is refused, naming what depends on the column or table (views, triggers, policies, generated columns, SQL-body functions, publications), exactly where PostgreSQL would refuse it without `CASCADE`. Renaming an existing table keeps the old name working as a view (with the table's grants copied; from PostgreSQL 15 the view runs with the caller's own rights, and before that a table with row-level security is refused) until an optional last step drops it. The lock levels and the "rewrites the table" predictions are checked against real servers from PostgreSQL 12 to 18 (`npm run test:schema-pg:versions`).
3. **A model proposes operations; fixed rules write the SQL.** Each operation is checked against the real catalog (names exist, types are real, a foreign key points at a unique column, a NOT NULL column has a default when the table has rows, an index name is free, a default is accepted by PostgreSQL) and compiled into a runbook: `CREATE INDEX CONCURRENTLY`, foreign keys and checks `NOT VALID` then `VALIDATE`, `NOT NULL` through a validated `CHECK`, a `lock_timeout` on every step, batched committed backfills, and for a type change that would rewrite the table an expand/contract sequence (new column, trigger, batched copy, swap in one `DO` block, the old column dropped in a step that is commented out). Every step states its lock, the work it does, the size of the table and a risk class that follows from those three by a fixed rule, plus how to undo it where that is possible. The operations are `create_table`, `rename_table`, `drop_table`, `add_column`, `alter_column`, `drop_column`, `add_relationship`, `drop_relationship`, `add_index`, `drop_index`, `add_unique`, `add_check`, `drop_constraint`, `add_primary_key`, `create_enum` and `add_enum_value`. `create_enum` makes a type (a column can use it later in the same plan, with a default that is one of its labels) and `add_enum_value` adds a label, optionally before or after another: neither locks any table, and a label can never be removed again. An existing integer column can become an identity column (`alter_column` with `autoIncrement`): the sequence is started after the column's largest value in the same transaction, which needs an index on the column unless the table is small, and a serial column's old default is dropped in the same change. A drop or a type change is refused, naming what depends on the column or table (views, triggers, policies, generated columns, SQL-body functions, publications), exactly where PostgreSQL would refuse it without `CASCADE`. Renaming a column of an existing table adds a second column with the new name, keeps the two in step in both directions with a trigger, copies the data in batches and the indexes, and leaves dropping the old column and the trigger to a last step that is not run by default (a column in a key, a foreign key or a check, or one a view uses, is refused: turn `compatColumns` off to rename it directly). Renaming an existing table keeps the old name working as a view (with the table's grants copied; from PostgreSQL 15 the view runs with the caller's own rights, and before that a table with row-level security is refused) until an optional last step drops it. The lock levels and the "rewrites the table" predictions are checked against real servers from PostgreSQL 12 to 18 (`npm run test:schema-pg:versions`).
4. **Check the database, then run it.** *Check the database first* reads, without writing, who holds or waits for the tables (found through `pg_locks`, so even a role that may not read other roles' sessions sees them), transactions open for 30 seconds or more, strong locks, prepared transactions, replicas that are behind, replication slots holding WAL, vacuum running on the tables, and the timeouts the role runs with; each check says "can't tell" instead of "ok" when it cannot read something. Free disk space cannot be read from a connection, so that is for you to check. *Run it here, one step at a time* then runs each step on its own in a SQL session of its own (no transaction, because `CONCURRENTLY` and the batched backfills need that): only the next step can run, the first failure stops the run, a step can be run again or stopped, and the most recent finished step can be undone with the statement the compiler wrote for it. A step that needs a strong lock on an existing table waits at most 2 seconds per attempt and tries up to 8 times, backing off between tries; if the table never frees up it stops with the sessions holding it and changes nothing. After the last step the catalog is read again and compared, table by table, with the state the compiler said it would leave (columns, types, NOT NULL, keys, unique and check constraints, foreign keys, indexes, views); every difference is listed. Optional clean-up steps (dropping an old column, a compatibility view) are never run for you. The runbook can also be opened in the SQL Editor with the transaction switch off, or copied.
5. **Health.** A read-only report from catalog queries: tables without a primary key, foreign keys without an index, duplicate, redundant, unused and invalid indexes, constraints that were never validated, wide tables, missing or stale statistics, tables with many dead rows, sequences past half their range. A model may be asked to order and explain the findings; it can only point at findings that exist.
6. **Governance.** The model is called through the OpenAI API with your key (see above; GoForge does not store it), an allow-list of model ids, optional redaction of schema, table, column, index and constraint names into placeholders before anything leaves the server (the answer is translated back), and an audit log of every request with exactly what was sent, every plan, every runbook opened and every settings change, exportable as CSV or JSON. The audit log records that a runbook was *opened*; what you run in the SQL Editor is not tracked.
Expand All @@ -119,7 +119,7 @@ Limits worth knowing: the compiler's rules assume PostgreSQL 12 or newer; the si

**What has and has not been checked.**

- *Checked, on real servers:* `npm run test:schema-pg:versions` runs 15 sections against PostgreSQL 12, 13, 14, 15, 16, 17 and 18, one container each, and all pass. They check the lock level each step takes against `pg_locks`; which type changes rewrite a table, by watching the table's file; every compiled scenario executed, with the end state read back from the catalog and compared with the compiler's prediction; the drop and type-change refusals against what PostgreSQL itself refuses; the pre-flight check and the lock retry with real sessions (a transaction held open, a queued `ACCESS EXCLUSIVE`, an unread replication slot, a role timeout, a role that cannot read other sessions); the table rename with real roles and grants, row-level security, undo and the contract step; and the probes of defaults and checks.
- *Checked, on real servers:* `npm run test:schema-pg:versions` runs 16 sections against PostgreSQL 12, 13, 14, 15, 16, 17 and 18, one container each, and all pass. They check the lock level each step takes against `pg_locks`; which type changes rewrite a table, by watching the table's file; every compiled scenario executed, with the end state read back from the catalog and compared with the compiler's prediction; the drop and type-change refusals against what PostgreSQL itself refuses; the pre-flight check and the lock retry with real sessions (a transaction held open, a queued `ACCESS EXCLUSIVE`, an unread replication slot, a role timeout, a role that cannot read other sessions); the table rename with real roles and grants, row-level security, undo and the contract step; and the probes of defaults and checks.
- *Checked on small data only:* the test tables hold up to a few hundred thousand rows. Whether a step stays short on a table of many gigabytes, how long a validation or index build takes, and replica lag during a large backfill have not been measured. The size classes and risk classes are fixed rules, not measurements.
- *Not run against a real server:* the index build of a partitioned table (the SQL is written and unit-tested; only the catalog reading of partitioned tables is checked on a server), replicas and logical replication (the pre-flight reads them, and the rules for them are unit-tested only), prepared transactions beyond the empty case, and extensions that change how types or indexes behave.
- *Models:* the planner's answers are accepted by OpenAI's structured-output check (`npm run check:openai` in `server/`), and a few real requests were planned by `gpt-5.6-luna` and their runbooks read through by hand; there is no scored evaluation of how often a model proposes the right operations. The compiler checks every operation against the catalog, so a wrong proposal is refused or shown, but a plausible wrong one that PostgreSQL accepts is not caught: read the plan.
Expand All @@ -130,7 +130,7 @@ How it is tested:
npm run test:schema-pg:versions # every section on PostgreSQL 12 to 18 (starts and removes one Docker container per version)
docker run -d --name goforge-schema -e POSTGRES_PASSWORD=schema -p 54330:5432 postgres:16 -c max_locks_per_transaction=1024
npm run test:schema-pg # every section against that one server
npm run test:schema-pg -- model # one section: drops, dependents, lockwait, preflight, model, rename, planner, health, locks, rewrites, compile, catalog, retrieval, facts, probe
npm run test:schema-pg -- model # one section: drops, dependents, lockwait, preflight, model, rename, columnrename, planner, health, locks, rewrites, compile, catalog, retrieval, facts, probe
```

The generated-database evaluation below (`scripts/schema-change-eval.ts`, `npm run eval:schema`) is not in this repository yet.
Expand Down
52 changes: 52 additions & 0 deletions scripts/schema-change-pg.ts
Original file line number Diff line number Diff line change
Expand Up @@ -324,6 +324,16 @@ const SCENARIOS: Scenario[] = [
checks.equal((await client.query("SELECT enumlabel AS l FROM pg_enum WHERE enumtypid = 'mood'::regtype ORDER BY enumsortorder")).rows.map((row) => row.l), ["sad", "meh", "ok", "happy"], "the label is where it was asked to be");
},
},
{
name: "rename a column and keep the old one in step (add the new column, trigger, copy, index, NOT NULL)",
setup: "CREATE TABLE accounts (id bigserial PRIMARY KEY, email text NOT NULL DEFAULT 'none', age int, note text, pad text); INSERT INTO accounts (email, age, note, pad) SELECT 'u' || g || '@example.test', g % 90, 'n' || g, repeat('x', 40) FROM generate_series(1, 300000) g; CREATE INDEX accounts_email_idx ON accounts (email); ANALYZE accounts;",
tables: ["public.accounts"],
operations: [{ type: "alter_column", tableName: "accounts", columnName: "email", changes: { newName: "contact" } }],
async verify(client, checks) {
checks.equal((await client.query("SELECT attname AS n FROM pg_attribute WHERE attrelid = 'accounts'::regclass AND attname IN ('email', 'contact') AND NOT attisdropped ORDER BY attname")).rows.map((row) => row.n), ["contact", "email"], "both columns exist");
checks.equal(Number((await one(client, "SELECT count(*)::int AS n FROM accounts WHERE contact IS DISTINCT FROM email"))?.n), 0, "every row has the same value in both");
},
},
{
name: "refuses NOT NULL without a default on a table with rows",
tables: ["public.orders"],
Expand Down Expand Up @@ -1150,6 +1160,44 @@ async function renameSection(checks: Checks) {
}
}

async function columnRenameSection(checks: Checks) {
// A renamed column with the old one kept in step: both names work, in both directions, until the last step drops the old column.
await withDatabase(async (client) => {
await client.query("CREATE TABLE accounts (id bigserial PRIMARY KEY, email text NOT NULL DEFAULT 'none', age int, note text, pad text); INSERT INTO accounts (email, age, note, pad) SELECT 'u' || g || '@example.test', g % 90, 'n' || g, repeat('x', 40) FROM generate_series(1, 300000) g; CREATE INDEX accounts_email_idx ON accounts (email); ANALYZE accounts;");
const { runbook } = await compileOn(client, parsePlan([{ type: "alter_column", tableName: "accounts", columnName: "email", changes: { newName: "contact" } }]), ["public.accounts"]);
checks.equal(runbook.findings.filter((finding) => finding.severity === "error"), [], "the rename compiles");
const ran = await runRunbook(client, runbook);
checks.ok(ran.ok, "the steps that run by default run", ran.failure);
const value = async (sql: string) => (await client.query(sql)).rows[0] as Record<string, unknown>;

checks.equal(await value("SELECT count(*)::int AS n FROM accounts WHERE contact IS DISTINCT FROM email"), { n: 0 }, "existing rows were copied");
checks.equal(await value("SELECT attnotnull AS n FROM pg_attribute WHERE attrelid = 'accounts'::regclass AND attname = 'contact'"), { n: true }, "the new column is NOT NULL, like the old one");
checks.equal(await value("SELECT indisvalid AS v FROM pg_index WHERE indexrelid = 'accounts_contact_idx'::regclass"), { v: true }, "the index was copied and is valid");

checks.equal(await value("INSERT INTO accounts (email) VALUES ('old@example.test') RETURNING contact"), { contact: "old@example.test" }, "an insert through the old name reaches the new column");
checks.equal(await value("INSERT INTO accounts (contact) VALUES ('new@example.test') RETURNING email"), { email: "new@example.test" }, "an insert through the new name reaches the old column");
checks.equal(await value("INSERT INTO accounts (note) VALUES ('neither') RETURNING email, contact"), { email: "none", contact: "none" }, "an insert that gives neither gets the old default in both");
checks.equal(await value("UPDATE accounts SET email = 'changed-old@example.test' WHERE id = 1 RETURNING contact"), { contact: "changed-old@example.test" }, "an update through the old name reaches the new column");
checks.equal(await value("UPDATE accounts SET contact = 'changed-new@example.test' WHERE id = 2 RETURNING email"), { email: "changed-new@example.test" }, "an update through the new name reaches the old column");
checks.equal(await value("UPDATE accounts SET age = 7 WHERE id = 3 RETURNING (email = contact) AS same"), { same: true }, "an update of another column leaves them equal");
await client.query("INSERT INTO accounts (email, contact) VALUES ('a@example.test', 'b@example.test')").then(() => undefined, () => undefined);
checks.equal(await value("SELECT contact AS c FROM accounts WHERE email = 'b@example.test' OR contact = 'b@example.test' LIMIT 1"), { c: "b@example.test" }, "an insert that gives both keeps the new name's value");

const actual = await loadFacts(asRunner(client), runbook.expected.tables.map((table) => table.qualified));
const mismatches = diffExpected(runbook.expected, actual);
checks.ok(mismatches.length === 0, "the catalog is as the compiler said", mismatches.map((mismatch) => mismatch.message));

const contract = runbook.steps.find((step) => step.optional)!;
const done = await runRunbook(client, { ...runbook, steps: [contract] }, { includeOptional: true });
checks.ok(done.ok, "the last step runs", done.failure);
checks.equal(await value("SELECT count(*)::int AS n FROM pg_attribute WHERE attrelid = 'accounts'::regclass AND attname = 'email' AND NOT attisdropped"), { n: 0 }, "the old column is gone");
checks.equal(await value("SELECT count(*)::int AS n FROM pg_trigger WHERE tgrelid = 'accounts'::regclass AND NOT tgisinternal"), { n: 0 }, "and so is the trigger");
checks.equal(await value("SELECT count(*)::int AS n FROM pg_proc WHERE proname LIKE 'accounts_email_contact__sync'"), { n: 0 }, "and its function");
checks.equal(await value("INSERT INTO accounts (note) VALUES ('after') RETURNING contact"), { contact: "none" }, "the new column has the old default");
checks.equal(await value("SELECT indisvalid AS v FROM pg_index WHERE indexrelid = 'accounts_contact_idx'::regclass"), { v: true }, "and the copied index stays");
});
}

const sections: Record<string, Section> = {
async drops(checks) {
await dropsSection(checks);
Expand All @@ -1175,6 +1223,10 @@ const sections: Record<string, Section> = {
await renameSection(checks);
},

async columnrename(checks) {
await columnRenameSection(checks);
},


async planner(checks) {
await plannerSection(checks);
Expand Down
Loading
Loading