@pikku/cli 0.12.89 → 0.12.90

package/dist/src/functions/db/local-db.js

@@ -4,7 +4,8 @@ import { createRequire } from 'node:module';
 import { runInNewContext } from 'node:vm';
 import { transformSync } from 'esbuild';
 import { CamelCasePlugin, Kysely, PostgresDialect } from 'kysely';
-import { migrate } from './db-migrator.js';
+import { migrate, baselineMigrations, } from './db-migrator.js';
+import { applyPikkuSchemas, compilePikkuSchemas, pikkuSchemas, resolveRequirements, } from '@pikku/kysely';
 import { loadAuthOptions, getAuthMigrations } from './better-auth-schema.js';
 import { generateSchemaTypes } from './db-codegen.js';
 import { generateZodTypes } from './zod-codegen.js';
@@ -163,16 +164,18 @@ async function loadCoercionPlugin(coercionFile) {
         return undefined;
     }
 }
-export async function migrateAndCodegen(resolved) {
+export async function migrateAndCodegen(resolved, options = {}) {
     let migrateResult;
     let codegenResult;
     // Compile any authored db/annotations.ts → sidecar BEFORE codegen so edits
     // reflect in a single `db migrate` (codegen reads the sidecar).
     compileClassifications(resolved.classificationsFile, resolved.classificationsGenJsonFile);
     if (resolved.dialect === 'sqlite') {
-        mkdirSync(dirname(resolved.dbFile), { recursive: true });
         const runtime = await loadSqliteRuntime();
-        const db = runtime.open(resolved.dbFile);
+        if (!options.scratch) {
+            mkdirSync(dirname(resolved.dbFile), { recursive: true });
+        }
+        const db = runtime.open(options.scratch ? ':memory:' : resolved.dbFile);
         try {
             const executor = new SqliteMigrationExecutor(db);
             migrateResult = await migrate(executor, resolved.migrationsDir);
@@ -194,7 +197,10 @@ export async function migrateAndCodegen(resolved) {
         }
     }
     else {
-        await withPostgresClient(resolved, async (client) => {
+        const withClient = options.scratch
+            ? (_r, run) => withScratchPostgresDatabase(run)
+            : withPostgresClient;
+        await withClient(resolved, async (client) => {
             const introspector = new PostgresIntrospector(client);
             await introspector.connect();
             try {
@@ -436,36 +442,44 @@ export async function createKysely(resolved) {
 async function introspectorToMap(intro) {
     const map = new Map();
     for (const [table, cols] of await intro.getAllColumns()) {
-        map.set(table, new Set(cols.map((c) => c.name)));
+        map.set(table, new Map(cols.map((c) => [c.name, c])));
     }
     return map;
 }
 function diffSchemas(desired, actual) {
     const missingTables = [];
     const missingColumns = [];
-    const findSchemaQualifiedMatch = (table) => {
-        if (table.includes('.'))
-            return undefined;
-        const matches = [...actual.entries()].filter(([actualTable]) => {
-            const parts = actualTable.split('.');
-            return parts.length === 2 && parts[1] === table;
-        });
-        if (matches.length !== 1)
-            return undefined;
-        return matches[0][1];
-    };
     for (const [table, cols] of desired) {
-        const actualCols = actual.get(table) ?? findSchemaQualifiedMatch(table);
+        const actualCols = actual.get(table) ?? schemaQualifiedMatch(actual, table);
         if (!actualCols) {
             missingTables.push(table);
             continue;
         }
-        const missing = [...cols].filter((c) => !actualCols.has(c));
+        const missing = [...cols.keys()].filter((c) => !actualCols.has(c));
         if (missing.length)
             missingColumns.push({ table, columns: missing });
     }
     return { missingTables, missingColumns };
 }
+/**
+ * The one table in `actual` whose name matches `table` once its schema is
+ * dropped, if there is exactly one.
+ *
+ * A migration that names no schema lands in whichever one is default, so a bare
+ * desired name legitimately matches a qualified table. Only when it is
+ * unambiguous: two candidates mean the shadowing bug, not a match.
+ */
+function schemaQualifiedMatch(actual, table) {
+    if (table.includes('.'))
+        return undefined;
+    const matches = [...actual.entries()].filter(([actualTable]) => {
+        const parts = actualTable.split('.');
+        return parts.length === 2 && parts[1] === table;
+    });
+    if (matches.length !== 1)
+        return undefined;
+    return matches[0][1];
+}
 function isPostgresAuthDatabase(options) {
     return options.database?.type === 'postgres';
 }
@@ -476,7 +490,7 @@ function isPostgresAuthDatabase(options) {
 // target server. Creating a real database via `CREATE DATABASE` would require
 // elevated privileges that application roles (correctly) don't have, which made
 // `pikku db migrate` fail against managed/locked-down Postgres (error 42501).
-async function withScratchPostgresDatabase(_resolved, _prefix, run) {
+async function withScratchPostgresDatabase(run) {
     const scratchDb = await createEmbeddedPostgres();
     try {
         return await run(pgliteAsClient(scratchDb));
@@ -497,8 +511,8 @@ async function postgresDatabaseToMap(client) {
         await intro.close();
     }
 }
-async function desiredPostgresAuthSchema(resolved, rootDir, srcDirectories, logger) {
-    return withScratchPostgresDatabase(resolved, 'pikku_auth', async (scratchDb) => {
+async function desiredPostgresAuthSchema(rootDir, srcDirectories, logger) {
+    return withScratchPostgresDatabase(async (scratchDb) => {
         // The scratch DB is always an embedded PGlite instance (see
         // withScratchPostgresDatabase), so drive Better Auth's migration codegen
         // through the PGlite-backed Kysely regardless of how the app DB is
@@ -544,7 +558,7 @@ export async function desiredAuthSchema(resolved, rootDir, srcDirectories, logge
             if (resolved.dialect !== 'postgres') {
                 throw new Error('Better Auth database.type is postgres, but the resolved app database is not postgres.');
             }
-            return desiredPostgresAuthSchema(resolved, rootDir, srcDirectories, logger);
+            return desiredPostgresAuthSchema(rootDir, srcDirectories, logger);
         }
         const { runMigrations, compileMigrations } = await getAuthMigrations(options);
         await runMigrations();
@@ -556,6 +570,99 @@ export async function desiredAuthSchema(resolved, rootDir, srcDirectories, logge
         db.close();
     }
 }
+/**
+ * Run Better Auth's own migrator against `kysely`, if the project configures it.
+ *
+ * Separate from `desiredAuthSchema` because the auth tables are a prerequisite
+ * of the runtime ones, not just a peer of them: both have to land in the same
+ * throwaway database, in that order, for the scope tables' foreign keys onto
+ * `user.id` to resolve.
+ */
+async function applyAuthSchema(kysely, rootDir, srcDirectories, logger) {
+    const options = await loadAuthOptions({
+        rootDir,
+        srcDirectories,
+        kysely,
+        logger,
+    });
+    if (!options)
+        return false;
+    const { runMigrations } = await getAuthMigrations(options);
+    await runMigrations();
+    return true;
+}
+/**
+ * The tables `@pikku/kysely`'s runtime services need, as declared.
+ *
+ * Materialized the same way the auth schema is: applied to a throwaway database
+ * and introspected, so one declaration answers both "what should exist" and
+ * "what SQL creates it" without a hand-written per-dialect copy.
+ *
+ * Auth goes into the same database first, because it is a prerequisite — the
+ * scope tables grant to a user, so they reference the table Better Auth owns.
+ * Its tables are subtracted from the result: they are covered by auth's own
+ * source, and counting them twice would have `db generate` write them twice.
+ *
+ * A project with no auth configured is not an error here. It genuinely has no
+ * scope tables, so the schemas that wanted them are left out and returned in
+ * `skipped` — reported rather than dropped, because the tables they would have
+ * recognised now have nothing to explain them.
+ */
+export async function desiredRuntimeSchema(resolved, rootDir, srcDirectories, logger) {
+    const skipped = [];
+    const collect = async (db, introspect) => {
+        await applyAuthSchema(db, rootDir, srcDirectories, logger);
+        const before = await introspect();
+        const { types, unmet } = await resolveRequirements(db);
+        for (const { schema, requirement } of unmet) {
+            skipped.push({
+                schema: schema.name,
+                requires: `${requirement.table}.${requirement.column}`,
+                owner: requirement.owner,
+            });
+        }
+        const unavailable = new Set(unmet.map(({ schema }) => schema.name));
+        const schemas = pikkuSchemas.filter((s) => !unavailable.has(s.name));
+        await applyPikkuSchemas(db, schemas);
+        const after = await introspect();
+        for (const table of before.keys())
+            after.delete(table);
+        return { tables: after, schemas, types };
+    };
+    if (resolved.dialect === 'sqlite') {
+        const runtime = await loadSqliteRuntime();
+        const db = runtime.open(':memory:');
+        try {
+            const kysely = createSqliteKysely({ db, camelCase: true });
+            const { tables, schemas, types } = await collect(kysely, () => introspectorToMap(new SqliteIntrospector(db)));
+            return {
+                tables,
+                sql: compilePikkuSchemas(kysely, schemas, types),
+                skipped,
+            };
+        }
+        finally {
+            db.close();
+        }
+    }
+    return withScratchPostgresDatabase(async (db) => {
+        const kysely = createPGliteKysely({
+            db: db.__pglite,
+            camelCase: true,
+        });
+        try {
+            const { tables, schemas, types } = await collect(kysely, () => postgresDatabaseToMap(db));
+            return {
+                tables,
+                sql: compilePikkuSchemas(kysely, schemas, types),
+                skipped,
+            };
+        }
+        finally {
+            await kysely.destroy();
+        }
+    });
+}
 export async function introspectSchema(resolved) {
     if (resolved.dialect === 'sqlite') {
         const runtime = await loadSqliteRuntime();
@@ -589,12 +696,93 @@ async function coveredSqliteSchema(migrationsDir) {
         db.close();
     }
 }
-async function coveredPostgresSchema(resolved, migrationsDir) {
-    return withScratchPostgresDatabase(resolved, 'pikku_migrate', async (client) => {
+async function coveredPostgresSchema(migrationsDir) {
+    return withScratchPostgresDatabase(async (client) => {
         await migrate(new PostgresMigrationExecutor(client), migrationsDir);
         return postgresDatabaseToMap(client);
     });
 }
+/**
+ * Compare the schema the migration files define against the one the configured
+ * database actually has.
+ *
+ * The two halves are asymmetric and must stay that way. Something missing from
+ * the database is a database that is behind — the fix only ever adds, so it is
+ * safe to automate. Something present in the database but absent from the
+ * migrations is a table nobody wrote down: a runtime that created its own at
+ * boot, or the remains of a reverted branch. Dropping those is how data gets
+ * lost, so they are reported and never acted on.
+ *
+ * The pikku runtime declares tables of its own, and they are used here to
+ * recognise rather than to require. A project that never constructs the
+ * workflow or AI services should not be told it is missing their tables, so
+ * absence is not a finding. Presence is: a runtime table in the database that
+ * no migration creates gets reported as such, separately from the genuinely
+ * unexplained ones, because for those the remedy is known — `db generate`
+ * writes them down.
+ */
+export async function computeSchemaDrift(resolved, rootDir, srcDirectories, logger) {
+    const covered = resolved.dialect === 'sqlite'
+        ? await coveredSqliteSchema(resolved.migrationsDir)
+        : await coveredPostgresSchema(resolved.migrationsDir);
+    const actual = await introspectSchema(resolved);
+    const { missingTables, missingColumns } = diffSchemas(covered, actual);
+    // Compare on the full name. A migration that names no schema lands in
+    // whichever one is default, so a BARE covered name still matches a qualified
+    // table — but a QUALIFIED one must match exactly. Relaxing that second case
+    // hides the failure this is here to catch: a second copy of a table in the
+    // wrong schema (`public.orders` shadowing `app.orders`) would otherwise look
+    // like the table the migrations created.
+    const coveredFull = new Set(covered.keys());
+    const coveredBare = new Set([...covered.keys()].filter((t) => !t.includes('.')));
+    const unrecorded = [...actual.keys()].filter((t) => !coveredFull.has(t) && !coveredBare.has(t.split('.').pop()));
+    const runtime = await desiredRuntimeSchema(resolved, rootDir, srcDirectories, logger);
+    const runtimeTables = unrecorded.filter((t) => runtime.tables.has(t.split('.').pop()));
+    const extraTables = unrecorded.filter((t) => !runtimeTables.includes(t));
+    return {
+        missingTables,
+        missingColumns,
+        runtimeTables,
+        extraTables,
+        skippedRuntimeSchemas: runtime.skipped,
+        inSync: missingTables.length === 0 && missingColumns.length === 0,
+    };
+}
+/**
+ * Record the pending migrations as applied, for a database that already has
+ * what they describe.
+ *
+ * The situation this exists for: a runtime created its tables at boot, and the
+ * migration writing them down was authored afterwards. Every existing
+ * deployment already has those tables, so running that migration fails; not
+ * running it leaves the history claiming the schema is something else.
+ *
+ * Guarded by the same question `db check` answers. If the database is behind
+ * its migrations in any way then the premise is false — the tables are not all
+ * there — and recording them would hide a real gap behind a history that says
+ * everything is applied. So it refuses and hands back the drift.
+ */
+export async function baseline(resolved, rootDir, srcDirectories, logger) {
+    const drift = await computeSchemaDrift(resolved, rootDir, srcDirectories, logger);
+    if (!drift.inSync)
+        return { status: 'behind', drift };
+    if (resolved.dialect === 'sqlite') {
+        const runtime = await loadSqliteRuntime();
+        mkdirSync(dirname(resolved.dbFile), { recursive: true });
+        const db = runtime.open(resolved.dbFile);
+        try {
+            const recorded = await baselineMigrations(new SqliteMigrationExecutor(db), resolved.migrationsDir);
+            return { status: 'recorded', recorded };
+        }
+        finally {
+            db.close();
+        }
+    }
+    return withPostgresClient(resolved, async (client) => {
+        const recorded = await baselineMigrations(new PostgresMigrationExecutor(client), resolved.migrationsDir);
+        return { status: 'recorded', recorded };
+    });
+}
 export async function computeAuthDrift(resolved, rootDir, srcDirectories, logger) {
     const desired = await desiredAuthSchema(resolved, rootDir, srcDirectories, logger);
     if (!desired) {
@@ -630,24 +818,221 @@ function nextMigrationFile(migrationsDir, label) {
     const num = String(max + 1).padStart(4, '0');
     return join(migrationsDir, `${num}-${label}.sql`);
 }
-export async function generateAuthMigration(resolved, rootDir, srcDirectories, logger) {
-    const desired = await desiredAuthSchema(resolved, rootDir, srcDirectories, logger);
-    if (!desired)
-        return { status: 'no-auth' };
-    const covered = resolved.dialect === 'sqlite'
-        ? await coveredSqliteSchema(resolved.migrationsDir)
-        : await coveredPostgresSchema(resolved, resolved.migrationsDir);
-    const { missingTables, missingColumns } = diffSchemas(desired.tables, covered);
-    if (missingTables.length === 0 && missingColumns.length === 0) {
-        return { status: 'up-to-date' };
-    }
-    const coveredHasAnyAuthTable = [...desired.tables.keys()].some((t) => covered.has(t));
-    if (coveredHasAnyAuthTable) {
-        return { status: 'incremental-unsupported', missingTables, missingColumns };
-    }
-    const file = nextMigrationFile(resolved.migrationsDir, 'better-auth');
-    const header = '-- Generated by `pikku db generate` from pikkuBetterAuth (Better Auth).\n' +
-        '-- Re-run the command after changing the auth config.\n\n';
-    writeFileSync(file, header + desired.sql + '\n', 'utf8');
-    return { status: 'written', file, missingTables };
+// ─── The addon schema channel ────────────────────────────────────────────────
+/**
+ * Where an addon publishes its schema, relative to its package root.
+ *
+ * One more channel beside `.pikku/function`, `.pikku/scopes` and the rest, so a
+ * consumer reaches it the same way they do: through the package name, never a
+ * path into somebody else's tree.
+ */
+const ADDON_DB_ARTIFACT = '.pikku/db/pikku-db-meta.gen.json';
+const serializeSchemaMap = (tables) => Object.fromEntries([...tables].map(([table, columns]) => [table, [...columns.values()]]));
+const deserializeSchemaMap = (tables) => new Map(Object.entries(tables).map(([table, columns]) => [
+    table,
+    new Map(columns.map((column) => [column.name, column])),
+]));
+const concatMigrations = (migrationsDir) => readdirSync(migrationsDir)
+    .filter((f) => f.endsWith('.sql'))
+    .sort()
+    .map((f) => readFileSync(join(migrationsDir, f), 'utf8').trim())
+    .join('\n\n');
+/**
+ * Materialize this package's own migrations into something a consumer can use.
+ *
+ * The producer half of the addon channel, and the same trick the auth and
+ * runtime sources use: run the SQL into a throwaway database and introspect it,
+ * so the artifact answers both "what must exist" and "what creates it" without
+ * a second, hand-written description that drifts.
+ *
+ * Every dialect the package has migrations for is exported, not just the one it
+ * happens to be configured against — an addon is published once and consumed by
+ * projects on either engine.
+ */
+export async function exportSchema(rootDir) {
+    const artifact = {};
+    const sqliteDir = join(rootDir, 'db', 'sqlite');
+    if (existsSync(sqliteDir)) {
+        artifact.sqlite = {
+            sql: concatMigrations(sqliteDir),
+            tables: serializeSchemaMap(await coveredSqliteSchema(sqliteDir)),
+        };
+    }
+    const postgresDir = join(rootDir, 'db', 'postgres');
+    if (existsSync(postgresDir)) {
+        artifact.postgres = {
+            sql: concatMigrations(postgresDir),
+            tables: serializeSchemaMap(await coveredPostgresSchema(postgresDir)),
+        };
+    }
+    return artifact;
+}
+/**
+ * The schema every wired addon publishes, as sources.
+ *
+ * An addon never creates its own tables. It has no database of its own — it
+ * runs inside the consumer, against the consumer's — so the only honest place
+ * for its DDL is the consumer's own migration history, which is what turning it
+ * into a `SchemaSource` achieves.
+ */
+export async function addonSchemaSources(rootDir, dialect, addons, logger) {
+    if (addons.length === 0)
+        return [];
+    const require = createRequire(join(rootDir, 'package.json'));
+    const sources = [];
+    const seen = new Set();
+    for (const addon of addons) {
+        if (addon.remote || seen.has(addon.package))
+            continue;
+        seen.add(addon.package);
+        let artifactPath;
+        try {
+            artifactPath = require.resolve(`${addon.package}/${ADDON_DB_ARTIFACT}`);
+        }
+        catch {
+            // Most addons have no schema at all, so an unresolvable artifact is the
+            // ordinary case and says nothing is contributed — not that anything failed.
+            continue;
+        }
+        const artifact = JSON.parse(readFileSync(artifactPath, 'utf8'));
+        const exported = artifact[dialect];
+        if (!exported) {
+            logger.error(`The '${addon.package}' addon publishes a schema, but not for ${dialect} — ` +
+                `it supports ${Object.keys(artifact).join(', ') || 'no dialect'}. ` +
+                'Its tables cannot be created here, so its services will fail at runtime.');
+            continue;
+        }
+        sources.push({
+            name: addon.package.replace(/^@/, '').replace(/[^a-zA-Z0-9]+/g, '-'),
+            desired: {
+                tables: deserializeSchemaMap(exported.tables),
+                sql: exported.sql,
+            },
+            origin: `the '${addon.package}' addon`,
+        });
+    }
+    return sources;
+}
+/**
+ * Every schema source the project has, in the order they must be applied.
+ *
+ * Auth comes first because the runtime's scope tables reference its `user`
+ * table; addons come last because they may reference either.
+ */
+export async function schemaSources(resolved, rootDir, srcDirectories, logger, addons = []) {
+    const sources = [];
+    const auth = await desiredAuthSchema(resolved, rootDir, srcDirectories, logger);
+    if (auth) {
+        sources.push({
+            name: 'better-auth',
+            desired: auth,
+            origin: 'pikkuBetterAuth (Better Auth)',
+        });
+    }
+    const runtime = await desiredRuntimeSchema(resolved, rootDir, srcDirectories, logger);
+    if (runtime.tables.size > 0) {
+        sources.push({
+            name: 'pikku-runtime',
+            desired: runtime,
+            origin: "@pikku/kysely's runtime services",
+        });
+    }
+    sources.push(...(await addonSchemaSources(rootDir, resolved.dialect, addons, logger)));
+    return sources;
+}
+/**
+ * Render the columns a table is missing as `ALTER TABLE … ADD COLUMN`.
+ *
+ * A column that is `NOT NULL` with no default cannot be added to a table that
+ * already has rows — the value for those rows is a decision only the author can
+ * make. Rather than guessing one or quietly dropping the constraint, the
+ * statement is emitted with the problem written above it, so it surfaces during
+ * the review the command already asks for.
+ */
+function addColumnStatements(table, columns) {
+    const sql = [];
+    const needsBackfill = [];
+    for (const column of columns) {
+        const parts = [
+            `ALTER TABLE ${table} ADD COLUMN ${column.name} ${column.type}`,
+        ];
+        if (column.defaultValue !== null) {
+            parts.push(`DEFAULT ${column.defaultValue}`);
+        }
+        if (column.notNull)
+            parts.push('NOT NULL');
+        if (column.notNull && column.defaultValue === null) {
+            needsBackfill.push(`${table}.${column.name}`);
+            sql.push(`-- REVIEW: ${column.name} is NOT NULL with no default. This fails if ${table} has rows.\n` +
+                `-- Add a default, or split this into: add nullable, backfill, then set NOT NULL.\n` +
+                `${parts.join(' ')};`);
+        }
+        else {
+            sql.push(`${parts.join(' ')};`);
+        }
+    }
+    return { sql, needsBackfill };
+}
+/**
+ * Write a migration for every schema source the migrations do not yet cover.
+ *
+ * Three cases per source, and the distinction matters. Fully covered is
+ * nothing to do. Nothing covered writes the source's own SQL verbatim, which is
+ * the one case where the source knows better than any diff — it carries the
+ * indexes, constraints and ordering a table-and-column comparison cannot see.
+ * Partially covered writes the delta, because re-emitting the whole schema
+ * would fail on the tables that already exist.
+ *
+ * Migrations are written one file per source, numbered in dependency order, so
+ * a project can review and apply them independently.
+ */
+export async function generateMigrations(resolved, rootDir, srcDirectories, logger, addons = []) {
+    const sources = await schemaSources(resolved, rootDir, srcDirectories, logger, addons);
+    const result = { upToDate: [], written: [] };
+    for (const source of sources) {
+        // Re-read after each write: a migration just written for an earlier source
+        // is part of what the next one is compared against.
+        const covered = resolved.dialect === 'sqlite'
+            ? await coveredSqliteSchema(resolved.migrationsDir)
+            : await coveredPostgresSchema(resolved.migrationsDir);
+        const { missingTables, missingColumns } = diffSchemas(source.desired.tables, covered);
+        if (missingTables.length === 0 && missingColumns.length === 0) {
+            result.upToDate.push(source.name);
+            continue;
+        }
+        const partial = [...source.desired.tables.keys()].some((t) => covered.has(t));
+        let body;
+        let needsBackfill = [];
+        if (!partial) {
+            body = source.desired.sql;
+        }
+        else {
+            const statements = [];
+            for (const table of missingTables) {
+                const columns = source.desired.tables.get(table);
+                statements.push(`-- REVIEW: ${table} is new. Copy its CREATE TABLE from the source's own SQL —\n` +
+                    `-- the column list below carries no indexes, constraints or foreign keys.\n` +
+                    `CREATE TABLE ${table} (\n` +
+                    [...(columns?.values() ?? [])]
+                        .map((c) => `  ${c.name} ${c.type}${c.notNull ? ' NOT NULL' : ''}`)
+                        .join(',\n') +
+                    '\n);');
+            }
+            for (const { table, columns } of missingColumns) {
+                const infos = columns
+                    .map((name) => source.desired.tables.get(table)?.get(name))
+                    .filter((c) => c !== undefined);
+                const added = addColumnStatements(table, infos);
+                statements.push(...added.sql);
+                needsBackfill.push(...added.needsBackfill);
+            }
+            body = statements.join('\n\n');
+        }
+        const file = nextMigrationFile(resolved.migrationsDir, source.name);
+        const header = `-- Generated by \`pikku db generate\` from ${source.origin}.\n` +
+            '-- Re-run the command after changing that source.\n\n';
+        writeFileSync(file, header + body + '\n', 'utf8');
+        result.written.push({ source: source.name, file, needsBackfill });
+    }
+    return result;
 }

package/dist/src/functions/db/postgres/postgres-introspector.js

@@ -1,8 +1,20 @@
 import { Pool } from 'pg';
+import { MIGRATION_TRACKING_TABLE } from '../db-migrator.js';
 /** Table display name matching `listTables` (schema-qualified unless `public`). */
 function tableKey(schema, table) {
     return schema === 'public' ? table : `${schema}.${table}`;
 }
+/**
+ * Whether a table is the migrator's own bookkeeping, which no schema owns.
+ *
+ * Matched on the bare name in any schema: the tracking table is created
+ * unqualified, so it lands wherever `search_path` points and there is no one
+ * schema to pin it to. The SQLite introspector hides the same name; see
+ * {@link MIGRATION_TRACKING_TABLE} for what showing it breaks.
+ */
+function isMigrationTracking(table) {
+    return table === MIGRATION_TRACKING_TABLE;
+}
 /**
  * Resolve the SQL type string for a column, preserving array-ness. Postgres
  * reports every array column with `data_type = 'ARRAY'`; the element type lives
@@ -43,7 +55,9 @@ export class PostgresIntrospector {
          AND table_schema NOT LIKE 'pg_temp_%'
          AND table_type = 'BASE TABLE'
        ORDER BY table_schema, table_name`);
-        return result.rows.map((r) => tableKey(r.table_schema, r.table_name));
+        return result.rows
+            .filter((r) => !isMigrationTracking(r.table_name))
+            .map((r) => tableKey(r.table_schema, r.table_name));
     }
     async getColumns(table) {
         const dotIdx = table.indexOf('.');
@@ -141,6 +155,8 @@ export class PostgresIntrospector {
        ORDER BY c.table_schema, c.table_name, c.ordinal_position`);
         const byTable = new Map();
         for (const r of result.rows) {
+            if (isMigrationTracking(r.table_name))
+                continue;
             const key = tableKey(r.table_schema, r.table_name);
             let cols = byTable.get(key);
             if (!cols) {
@@ -181,6 +197,8 @@ export class PostgresIntrospector {
        ORDER BY kcu.table_schema, kcu.table_name, kcu.ordinal_position`);
         const byTable = new Map();
         for (const r of result.rows) {
+            if (isMigrationTracking(r.owner_table))
+                continue;
             const key = tableKey(r.owner_schema, r.owner_table);
             let fks = byTable.get(key);
             if (!fks) {

package/dist/src/functions/db/postgres/postgres-migrator.d.ts

@@ -10,5 +10,6 @@ export declare class PostgresMigrationExecutor implements MigrationExecutor {
     constructor(client: PostgresMigrationClient);
     ensureTrackingTable(): Promise<void>;
     getApplied(): Promise<AppliedMigration[]>;
+    recordMigration(name: string, hash: string): Promise<void>;
     runMigration(sql: string, name: string, hash: string): Promise<void>;
 }

package/dist/src/functions/db/postgres/postgres-migrator.js

@@ -1,4 +1,4 @@
-const TRACKING_TABLE = 'sql_migrations';
+import { MIGRATION_TRACKING_TABLE as TRACKING_TABLE } from '../db-migrator.js';
 export class PostgresMigrationExecutor {
     client;
     constructor(client) {
@@ -17,6 +17,9 @@ export class PostgresMigrationExecutor {
         const { rows } = await this.client.query(`SELECT name, hash, applied_at FROM ${TRACKING_TABLE} ORDER BY name`);
         return rows;
     }
+    async recordMigration(name, hash) {
+        await this.client.query(`INSERT INTO ${TRACKING_TABLE} (name, hash) VALUES ($1, $2)`, [name, hash]);
+    }
     async runMigration(sql, name, hash) {
         await this.client.query('BEGIN');
         try {

package/dist/src/functions/db/sqlite/sqlite-introspector.js

@@ -1,4 +1,5 @@
-const SKIP_TABLES = new Set(['sqlite_sequence', 'sql_migrations']);
+import { MIGRATION_TRACKING_TABLE } from '../db-migrator.js';
+const SKIP_TABLES = new Set(['sqlite_sequence', MIGRATION_TRACKING_TABLE]);
 export class SqliteIntrospector {
     db;
     constructor(db) {

package/dist/src/functions/db/sqlite/sqlite-migrator.d.ts

@@ -5,6 +5,7 @@ export declare class SqliteMigrationExecutor implements MigrationExecutor {
     constructor(db: SyncSqliteDatabase);
     ensureTrackingTable(): Promise<void>;
     getApplied(): Promise<AppliedMigration[]>;
+    recordMigration(name: string, hash: string): Promise<void>;
     runMigration(sql: string, name: string, hash: string): Promise<void>;
 }
 export declare function dropTrackingTable(db: SyncSqliteDatabase): void;

package/dist/src/functions/db/sqlite/sqlite-migrator.js

@@ -1,4 +1,4 @@
-const TRACKING_TABLE = 'sql_migrations';
+import { MIGRATION_TRACKING_TABLE as TRACKING_TABLE } from '../db-migrator.js';
 export class SqliteMigrationExecutor {
     db;
     constructor(db) {
@@ -16,6 +16,11 @@ export class SqliteMigrationExecutor {
             .prepare(`SELECT name, hash, applied_at FROM ${TRACKING_TABLE} ORDER BY name`)
             .all();
     }
+    async recordMigration(name, hash) {
+        this.db
+            .prepare(`INSERT INTO ${TRACKING_TABLE} (name, hash) VALUES (?, ?)`)
+            .run(name, hash);
+    }
     async runMigration(sql, name, hash) {
         this.db.exec('BEGIN');
         try {