What the checksum actually covers

A Kit migration is a small object with a version, a name, an optional declarative ops list, and an imperative up() callback that does the work:

await migrate(db, schema, [
  {
    version: 5,
    name: 'tighten_products',
    ops: [{ kind: 'addUnique', table: 'products', constraint: 'products_sku_uq' }],
    async up({ kit }) {
      await addUnique(kit, 'products', unique(['sku'], { name: 'products_sku_uq' }));
    },
  },
]);

The checksum is a SHA-256 over one canonical serialization of the version, the name, and the ordered op list, with the key order fixed and standard JSON string escaping, so there is exactly one byte string that represents a given logical migration:

sha256('{"version":<n>,"name":<json>,"ops":[<op>,...]}')

The canonical form matters more than the hash algorithm, because the same logical migration has to produce the identical checksum in TypeScript, in Rust, and in Python, and any serialization that leaves wiggle room, a space here, a reordered key there, breaks that property the moment two languages disagree about whitespace. There is a small two-layer wrinkle worth naming, since the discriminator in your TypeScript ops is kind while the canonical serialization calls it op, a renaming step in the canonicalizer (kind: 'addUnique' serializes as {"op":"add_unique",...}) that maps camelCase input onto the snake_case wire vocabulary every language shares, so the object you write and the bytes that get hashed are deliberately not identical. The conformance tests pin two known vectors so a drift in any language’s canonicalizer fails a build instead of failing a deploy: {"version":1,"name":"init","ops":[{"op":"create_table","name":"users"}]} hashes to fe2f521793591207bd4d8645c2631e4b7ce43e30fe7ea5691a2846c74ea71cc3, and the empty form {"version":1,"name":"init","ops":[]} hashes to 6408373a4372a2c49859db2a4548ea43308e5ba7dd3609998ca376606cf09757, and both are asserted byte-for-byte on both sides of the language boundary. When ops is omitted, as it often is in TypeScript where the list is metadata rather than an execution plan, the checksum covers the version and name against an empty op list, so even the smallest possible migration is content-addressed.

When the checksum gets verified

The runner records each applied migration in the internal __kit_schema_migrations table, one row carrying the version, the name, the checksum, the applied timestamp, the kit version that ran it, and a status, and that record is written in the same transaction discipline as everything else the kit does. The part that earns the word “content-addressed” is what happens on every subsequent run: before computing the pending set, the runner recomputes the checksum of every supplied migration that claims to correspond to an already-applied record and compares it, and the name, against what is stored, and any mismatch, or any applied version that has vanished from the supplied list entirely, raises a KitSchemaDriftError and stops the run:

migration 5 (tighten_products) checksum mismatch: stored a1b2..., expected c3d4...

That ordering is the whole point, because drift detection happens before any new migration is applied, so a tampered history aborts the deploy while the database is still untouched rather than halfway through a run of new DDL on top of a history nobody trusts. The pending set itself is computed from a high-water mark, meaning only versions above the maximum already applied are eligible to run, which is what makes re-running the runner a no-op and what makes the classic renumbering attack, slipping a new file in as 003b and hoping it replays, a non-event: a renumbered migration either sits below the high-water mark and never runs, or it collides with an applied record whose checksum it cannot reproduce, and either way the runner says so. Records left in failed status are deliberately skipped by the drift check, and the high-water mark counts only versions that reached applied, which means a failed migration sits below the watermark and blocks itself and everything after it until you repair or remove the record; that is the intended posture, because a failed run leaves the history genuinely ambiguous and the runner refuses to guess its way forward.

The honest tradeoff

The cost of this design is that the checksum is only as faithful as the ops you declare, and this is the seam I would point at before recommending it to anyone: in the TypeScript runner the ops array never drives the work, your up() does, so if you list an addUnique op and then quietly do something extra inside the callback, the checksum certifies the list and not the deed, and the discipline the system actually demands is that you keep the two in sync so the audited description stays content-aware. I consider that a fair price, and the comparison that settles it for me is the old PHP habit of a migrations folder full of numbered SQL files that everyone knew better than to edit but everyone edited anyway, where the only enforcement was social and the social contract lost to the first hotfix under deadline; the modern equivalent of doing it right is a checksum computed from a canonical form, stored next to the version, and re-verified on every run before anything else is allowed to happen, so the boring discipline that used to live in a code-review comment now lives in the runner, and the runner does not get tired on Fridays.

The DSL does not emit SQL

The natural assumption, the one I made before reading the source, is that a declaration like this gets compiled down into CREATE TABLE text and that the query builder assembles SELECT strings under the hood:

export const orders = table('orders', {
  columns: [
    int('id', { primaryKey: true, default: sequenceDefault('orders_id_seq') }),
    int('customer_id', { nullable: false }),
    text('status', {
      enumValues: ['pending', 'paid', 'shipped', 'cancelled'],
      default: staticDefault('pending'),
    }),
    timestamp('placed_at', { default: nowDefault() }),
  ],
  primaryKey: 'id',
  indexes: [index(['customer_id'])],
  foreignKeys: [
    foreignKey(['customer_id'], { table: 'customers', columns: ['id'] }, { onDelete: 'cascade' }),
  ],
});

That assumption is wrong, and it is wrong in an interesting way. The table() call builds a TableSpec, a typed descriptor that Kit validates at construction time (duplicate column names, a primary key referencing a column that does not exist, an index over nothing), persists into the engine’s schema catalog with stable table and column ids, and then uses directly: reads and writes through selectFrom / insertInto push the predicates they can down into the storage engine’s native indexes and compute the rest, joins and grouping and ordering overflow, in memory, with no SQL text produced at any point. Even at the wire boundary the two surfaces stay separate; the remote client speaks typed endpoints, POST /kit/query for a native typed query and POST /kit/txn for an atomic write batch, while SQL statements go to POST /sql, so “the DSL compiles to the same wire format as raw SQL” is not the architecture, it is the thing we deliberately did not build. The payoff for skipping the SQL round trip is that one set of declarations drives type inference, validation, constraint enforcement, and migrations all at once, so renaming a column is a compile error in your TypeScript rather than a runtime surprise three deploys later, and the int('id') up there coming back as a bigint, with the compiler refusing row.id === 1, is the kind of pedantry that has saved me real money.

Where raw SQL is the right door

The DSL is honest about its ceiling, and the ceiling is exactly where the SQL frontend starts. Recursive CTEs, window functions, CREATE TABLE AS SELECT, materialized views, and multi-statement execution live on the raw surface, and the embedded TypeScript API is two calls wide:

const result = await db.sql('SELECT count(*) AS n FROM users');
const rows = await db.sqlRows('SELECT id, email FROM users ORDER BY id');

db.sql(...) hands back an Apache Arrow table and db.sqlRows(...) decodes it to plain objects, while the remote client exposes the same names synchronously because the native binding performs the HTTP call internally, so the shape of your code does not change when you move from embedded to daemon. On top of that surface Kit ships small expression helpers for the extended function catalog, things like percentileCont(events.latency_ms, 0.95) and jsonExtract(events.payload, '$.city'), each returning a { sql: string } fragment you splice into a statement yourself, plus mongreldbFtsRank(text, query) for BM25-style relevance ordering, and virtual tables follow the same pattern, with virtualTable(...) describing a module-backed table that generates its own CREATE VIRTUAL TABLE ... USING ... statement. The rule of thumb I use is that the builder owns the hot paths, the typed CRUD and the filtered scans that run a thousand times a minute, and SQL owns the analytical long tail, the reports and one-off probes where nobody wants type inference anyway; the builder is not an ORM trying to swallow SQL, it is a typed fast lane with a clearly marked exit.

Mixing both inside one migration

The place the two surfaces genuinely meet is the migration runner, and this is where the “one system, two doors” claim either holds or falls apart. A TypeScript migration’s up(ctx) is imperative, and the context object carries both doors: helpers like ctx.ensureTable(table) and ctx.addColumn(...) work from the typed TableSpec, and ctx.sql(sql) runs raw SQL inside the same migration transaction, so a single versioned change can create a table from its spec and then install a view over it without leaving the runner:

await migrate(db, schema, [
  {
    version: 7,
    name: 'orders_reporting_view',
    async up(ctx) {
      await ctx.ensureTable(orders);
      await ctx.sql(`
        CREATE VIEW paid_orders AS
        SELECT id, customer_id, placed_at FROM orders WHERE status = 'paid'
      `);
    },
  },
]);

There are two catches worth knowing before you reach for this, and both are load-bearing rather than incidental. First, ctx.sql() is available in async migrations only and throws in migrateSync, because the sync runner has no suspension point for the SQL frontend, so the moment a migration needs raw SQL you commit to the async migrate(db, schema, migrations) helper for the whole run. Second, the optional ops array on a migration is metadata in TypeScript, not an execution plan; the runner folds it into the content-addressed checksum so that an after-the-fact edit to an applied migration is caught as drift, but your up() is what actually does the work, which is exactly the split you want, since the thing that runs and the thing that is audited are allowed to be expressed differently. Either way both doors land in the same __kit_schema_migrations history under the same advisory lock, which is the entire point: there is no shadow schema state that only the SQL side knows about.

The tradeoff you actually sign

The seam I watch in production is the remote-mode authority boundary, because it is the one place the two doors are not symmetric. The daemon enforces engine-level constraints, unique, foreign-key actions, checks, atomically and server-side for both surfaces, but the Kit-specific field validations, defaults, enums, min/max bounds, regex patterns, live in the client, so a remote caller who bypasses the typed layer and hand-writes INSERT statements against /sql is opting out of that richer validation and accepting the engine’s floor as the whole contract, and that is a deliberate boundary, not an accident we plan to paper over. I will take that trade every time, and the comparison I keep reaching for is the old LAMP habit of treating the query builder as a toy and raw SQL as the real thing, which gave you one honest surface and one decorative one; the modern equivalent of doing it right is two surfaces that share a catalog, a transaction, and a migration history, where choosing between them is a per-query judgment about types and ergonomics rather than a per-project bet about which subsystem will still be maintained in three years.

Creating a table as data, not as a string

createTable() takes a name, a list of column definitions, and optional constraint and index lists, and it returns the table ID the engine assigned; each column is a plain PHP array with an id, a name, a type under ty, and the flags you would expect, so the definition reads like a config file rather than a dialect you have to quote and escape:

use Visorcraft\MongrelDB\Database;

$db = new Database('http://127.0.0.1:8453');

$tableId = $db->createTable('orders', [
    ['id' => 1, 'name' => 'id',     'ty' => 'int64',   'primary_key' => true,  'nullable' => false],
    ['id' => 2, 'name' => 'status', 'ty' => 'enum',    'primary_key' => false, 'nullable' => false,
        'enum_variants' => ['new', 'paid', 'cancelled']],
    ['id' => 3, 'name' => 'amount', 'ty' => 'float64', 'nullable' => false],
    ['id' => 4, 'name' => 'tag',    'ty' => 'varchar', 'default_value' => 'standard'],
    ['id' => 5, 'name' => 'ref',    'ty' => 'varchar', 'default_expr' => 'uuid'],
    ['id' => 6, 'name' => 'placed', 'ty' => 'timestamp', 'default_expr' => 'now'],
]);

The distinction between default_value and default_expr is worth a beat, because it is the kind of thing a DDL string blurs: default_value is a literal the engine stores as-is, so the tag column above really does get the four characters standard on every insert that omits it, while default_expr names an expression the engine evaluates at insert time, which is how uuid and now end up generating a fresh identifier and a server-side timestamp instead of a string that merely says “uuid”. The client is also careful about the wire shape it emits, and this is the unglamorous detail that saves you later: optional keys you did not set are simply absent from the JSON body, so a column without an enum does not send an empty enum_variants array for the server to misread, and the conformance tests in the repo assert exactly that by capturing the literal POST to /kit/create_table.

Indexes and constraints ride in the same call

Because the schema is a payload rather than a statement, the indexes and check constraints are just more arrays on the same request, which means a table and its access paths are created atomically instead of in three migrations you hope ran in order:

$db->createTable('docs', [
    ['id' => 1, 'name' => 'id',     'ty' => 'int64',   'primary_key' => true],
    ['id' => 2, 'name' => 'status', 'ty' => 'varchar', 'nullable' => false],
    ['id' => 3, 'name' => 'body',   'ty' => 'varchar', 'nullable' => false],
    ['id' => 4, 'name' => 'hits',   'ty' => 'int64',   'default_value' => 0],
], [
    'checks' => [[
        'id'   => 1,
        'name' => 'ck_hits_range',
        'expr' => ['And' => [
            ['Ge' => [['Col' => 4], ['Lit' => ['Int64' => 0]]]],
            ['Le' => [['Col' => 4], ['Lit' => ['Int64' => 1000000]]]],
        ]],
    ]],
], [
    ['name' => 'bm',    'column_id' => 2, 'kind' => 'bitmap'],
    ['name' => 'fm',    'column_id' => 3, 'kind' => 'fm_index'],
    ['name' => 'range', 'column_id' => 4, 'kind' => 'learned_range'],
]);

The check expression is a small typed tree rather than a SQL fragment, with Col naming a column by ID, Lit carrying a typed value, and the comparison and boolean nodes composing them, so ck_hits_range reads as “0 <= hits <= 1000000” and the engine evaluates it atomically at commit time against the whole transaction instead of row-by-row as a trigger would. The kind strings in the index list name the same index families the query builder targets, so the bitmap on status, the FM-index on body, and the learned-range index on hits you declare here are the ones your where('bitmap_eq', ...) and where('fm_contains', ...) conditions will hit later, and keeping both sides in one typed vocabulary is what makes the schema the contract rather than a suggestion.

Reading the catalog back

The half of schema management most clients skip is the read path, and it is the half that pays for the typed approach; tables() lists names, schema() returns the full catalog as a map of table name to descriptor, and schemaFor() fetches one table, all over plain GETs against /kit/schema:

$names = $db->tables();                 // ['orders', 'docs', ...]
$catalog = $db->schema();               // every table descriptor, keyed by name
$orders = $db->schemaFor('orders');     // one table's descriptor

// The drift check that used to require a parser:
$amount = array_values(array_filter(
    $orders['columns'],
    fn (array $c) => $c['name'] === 'amount',
))[0] ?? null;

if ($amount === null || $amount['nullable'] !== false) {
    throw new RuntimeException('orders.amount drifted; aborting deploy');
}

That last block is the whole argument in miniature, because the descriptor the server returns is the same shape as the definition you sent, so verifying a deploy is an array_filter and an equality check rather than a regex over SHOW CREATE TABLE output, and the check can live in a deploy script or a PHPUnit bootstrap where it fails loudly instead of silently corrupting a quarter of reports. When the table is genuinely done, dropTable() removes it by name, and the catalog read will confirm that too.

When raw sql() is still the right tool

None of this makes the escape hatch wrong, and the client keeps sql() around for the things a typed surface should not pretend to own, like recursive CTEs over the org chart or a one-off analytical query that will never run twice; the honest split is that DDL and schema verification belong in typed calls where both directions are data, while exploratory SQL belongs in a string where flexibility beats structure. The rule I would hand a team is the one we would have wanted in the mysql_* era, when we edited schemas in phpMyAdmin and prayed: create and verify through the typed API, explore through SQL, and never let a string you cannot read back be the only record of what your database looks like.