@pikku/cli 0.12.96 → 0.12.100

package/dist/src/functions/db/local-db.d.ts

@@ -3,7 +3,7 @@ import { type MigrateResult } from './db-migrator.js';
 import type { ColumnInfo } from './db-introspector.js';
 import { type CodegenResult } from './db-codegen.js';
 import { type ZodCodegenResult } from './zod-codegen.js';
-import { type SeedResult } from './sqlite/seed.js';
+import { type DevSeedResult } from './sqlite/dev-seed.js';
 import type { UserConfigShape } from '../commands/db-shared.js';
 interface ResolvedDbBase {
     rootDir: string;
@@ -18,12 +18,18 @@ interface ResolvedDbBase {
     enumsFile: string;
     zodFile: string;
     camelCase: boolean;
+    /**
+     * Schema whose qualifier the generated types drop, from `db.defaultSchema`.
+     * Unlike `schema` this applies to both dialects — sqlite has no schemas to
+     * qualify with, so it is simply inert there.
+     */
+    defaultSchema?: string;
 }
 export interface ResolvedSqliteDb extends ResolvedDbBase {
     dialect: 'sqlite';
     dbFile: string;
     runtimeDir: string;
-    seedFile: string;
+    devSeedFile: string;
 }
 export interface ResolvedPostgresDb extends ResolvedDbBase {
     dialect: 'postgres';
@@ -31,7 +37,25 @@ export interface ResolvedPostgresDb extends ResolvedDbBase {
     connectionString?: string;
     pgliteDir?: string;
     runtimeDir: string;
-    seedFile: string;
+    devSeedFile: string;
+    /**
+     * Postgres extensions the embedded PGlite databases must load, as declared by
+     * `pgliteExtensions` in the project's config. See
+     * {@link loadPGliteExtensions}.
+     *
+     * Carried even in `url` mode: the shadow database the CLI migrates and
+     * introspects is PGlite whichever server the project itself runs against, so
+     * a migration that needs an extension needs it here too.
+     */
+    pgliteExtensions: string[];
+    /**
+     * The schema generated migrations create their tables in, from `db.schema`.
+     *
+     * Postgres only — hence its absence from `ResolvedSqliteDb` rather than a
+     * runtime check. sqlite's `REFERENCES` clause takes a bare table name, so
+     * qualified DDL does not compile there at all.
+     */
+    schema?: string;
 }
 export type ResolvedDb = ResolvedSqliteDb | ResolvedPostgresDb;
 /**
@@ -45,9 +69,47 @@ export declare function parseDatabaseUrl(url: string): Pick<UserConfigShape, 'sq
  * Resolve a UserConfigShape into an absolute-path descriptor.
  * Returns null when neither sqliteDb nor postgresUrl is configured.
  */
-export declare function resolveDb(userConfig: UserConfigShape, rootDir: string, outDir: string, runtimeDir?: string): ResolvedDb | null;
+export declare function resolveDb(userConfig: UserConfigShape, rootDir: string, outDir: string, runtimeDir?: string, dbConfig?: {
+    schema?: string;
+    defaultSchema?: string;
+} | string): ResolvedDb | null;
 /** @deprecated Use resolveDb(userConfig, ...) instead. */
 export declare function resolveLocalDb(sqliteDb: string | undefined, rootDir: string, outDir: string, runtimeDir?: string): ResolvedSqliteDb | null;
+/**
+ * What an embedded PGlite instance needs beyond its data directory: where to
+ * resolve extension packages from, and which ones to load.
+ *
+ * A `ResolvedPostgresDb` already is one, which is what lets every call site
+ * that has one pass it straight through.
+ */
+export interface PGliteExtensionContext {
+    rootDir: string;
+    pgliteExtensions: string[];
+}
+/**
+ * A PGlite extension, as the packages that publish one export it: an object
+ * carrying the `setup` that hands PGlite the WASM bundle, or a URL/string
+ * pointing at a remote one.
+ *
+ * Structural rather than imported from PGlite so a project's extension package
+ * — built against its own copy of `@electric-sql/pglite` — is recognised
+ * whatever the two versions are.
+ */
+type PGliteExtension = {
+    name?: string;
+    setup: (...args: any[]) => unknown;
+};
+/**
+ * Load every extension the project declares, keyed the way PGlite wants them.
+ *
+ * The key is the export name (`vector`, `hstore`), which is also the name the
+ * SQL uses, so `CREATE EXTENSION vector` finds what a declaration of
+ * `@electric-sql/pglite-pgvector` loaded. A module exporting several is fine —
+ * all of them are taken — and a `default` export is used only when it is the
+ * only extension there, so a package that default-exports the same object it
+ * also names is not registered twice.
+ */
+export declare function loadPGliteExtensions(rootDir: string, specs: string[]): Promise<Record<string, PGliteExtension>>;
 export interface MigrateAndCodegenOutcome {
     migrate: MigrateResult;
     codegen: CodegenResult;
@@ -73,7 +135,15 @@ export interface MigrateAndCodegenOptions {
     scratch?: boolean;
 }
 export declare function migrateAndCodegen(resolved: ResolvedDb, options?: MigrateAndCodegenOptions): Promise<MigrateAndCodegenOutcome>;
-export declare function seed(resolved: ResolvedDb): Promise<SeedResult>;
+/**
+ * Apply the dev seed file. Only {@link reset} calls this, immediately after
+ * migrating a database it has just wiped, which is what lets a seed file be
+ * plain `INSERT`s rather than idempotent ones.
+ *
+ * `reset` refuses production before it gets here, so this guard is unreachable
+ * through the CLI. It stays because the export is reachable without it.
+ */
+export declare function devSeed(resolved: ResolvedDb): Promise<DevSeedResult>;
 export declare function reset(resolved: ResolvedDb, rootDir: string): Promise<void>;
 export declare function createKysely<DB>(resolved: ResolvedDb): Promise<Kysely<DB>>;
 /**
@@ -229,6 +299,17 @@ export interface SchemaSource {
     desired: DesiredSchema;
     /** Prose for the migration header, saying where the SQL came from. */
     origin: string;
+    /**
+     * The schema this source's SQL is qualified into, when it is.
+     *
+     * Carried per source rather than read off the resolved database because only
+     * the sources pikku compiles can honour it. Better Auth writes its own
+     * migration SQL through its own migrator and an addon ships SQL as text —
+     * neither goes through the schema builder, so neither can be qualified from
+     * here, and claiming otherwise on their behalf would emit a delta that names
+     * a table in a schema their `CREATE TABLE` never put it in.
+     */
+    schema?: string;
 }
 /** One dialect's worth of a published schema. */
 export interface ExportedSchema {
@@ -265,7 +346,7 @@ export interface AddonDeclaration {
  * happens to be configured against — an addon is published once and consumed by
  * projects on either engine.
  */
-export declare function exportSchema(rootDir: string): Promise<SchemaArtifact>;
+export declare function exportSchema(rootDir: string, pgliteExtensions?: string[]): Promise<SchemaArtifact>;
 /**
  * The schema every wired addon publishes, as sources.
  *

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

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, readdirSync, } from 'node:fs';
 import { resolve, isAbsolute, relative, dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import { runInNewContext } from 'node:vm';
 import { transformSync } from 'esbuild';
 import { CamelCasePlugin, Kysely, PostgresDialect } from 'kysely';
@@ -15,7 +16,7 @@ import { SqliteMigrationExecutor } from './sqlite/sqlite-migrator.js';
 import { SqliteIntrospector } from './sqlite/sqlite-introspector.js';
 import { createSqliteKysely } from './sqlite/sqlite-kysely.js';
 import { loadSqliteRuntime } from './sqlite/sqlite-runtime.js';
-import { seed as runSeed } from './sqlite/seed.js';
+import { devSeed as runDevSeed } from './sqlite/dev-seed.js';
 import { PostgresMigrationExecutor } from './postgres/postgres-migrator.js';
 import { createPGliteKysely } from './postgres/pglite-kysely.js';
 import { PostgresIntrospector } from './postgres/postgres-introspector.js';
@@ -37,7 +38,11 @@ export function parseDatabaseUrl(url) {
  * Resolve a UserConfigShape into an absolute-path descriptor.
  * Returns null when neither sqliteDb nor postgresUrl is configured.
  */
-export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
+export function resolveDb(userConfig, rootDir, outDir, runtimeDir, dbConfig) {
+    // The parameter took a bare schema string before `defaultSchema` existed;
+    // both forms are accepted so callers outside this repo keep working.
+    const schema = typeof dbConfig === 'string' ? dbConfig : dbConfig?.schema;
+    const defaultSchema = typeof dbConfig === 'string' ? undefined : dbConfig?.defaultSchema;
     const resolvedRuntimeDir = runtimeDir
         ? resolveAgainst(rootDir, runtimeDir)
         : join(rootDir, '.pikku-runtime');
@@ -58,17 +63,21 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
         classificationsGenJsonFile: join(rootDir, 'db', 'annotations.gen.json'),
         zodFile: join(outDir, 'db', 'zod.gen.ts'),
         camelCase: true,
+        defaultSchema,
     });
     if (userConfig.postgresUrl && userConfig.sqliteDb) {
         throw new Error('Both postgresUrl and sqliteDb are set. Configure exactly one database dialect.');
     }
+    const pgliteExtensions = userConfig.pgliteExtensions ?? [];
     if (userConfig.postgresUrl) {
         return {
             dialect: 'postgres',
             mode: 'url',
             connectionString: userConfig.postgresUrl,
             runtimeDir: resolvedRuntimeDir,
-            seedFile: resolveAgainst(rootDir, 'db/postgres-seed.sql'),
+            devSeedFile: resolveAgainst(rootDir, 'db/postgres-dev-seed.sql'),
+            pgliteExtensions,
+            schema,
             ...base('db/postgres'),
         };
     }
@@ -77,11 +86,17 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
             ? '.pikku-runtime/dev.db'
             : undefined);
     if (sqliteDb) {
+        if (schema) {
+            throw new Error(`db.schema is set to '${schema}', but the resolved database is sqlite. ` +
+                'sqlite has one schema to be in, and its REFERENCES clause takes a bare ' +
+                'table name, so qualified DDL does not compile there. Remove db.schema, ' +
+                'or configure postgres.');
+        }
         return {
             dialect: 'sqlite',
             dbFile: resolveAgainst(rootDir, sqliteDb),
             runtimeDir: resolvedRuntimeDir,
-            seedFile: resolveAgainst(rootDir, 'db/sqlite-seed.sql'),
+            devSeedFile: resolveAgainst(rootDir, 'db/sqlite-dev-seed.sql'),
             ...base('db/sqlite'),
         };
     }
@@ -91,7 +106,9 @@ export function resolveDb(userConfig, rootDir, outDir, runtimeDir) {
             mode: 'pglite',
             pgliteDir: join(resolvedRuntimeDir, 'dev-postgres'),
             runtimeDir: resolvedRuntimeDir,
-            seedFile: resolveAgainst(rootDir, 'db/postgres-seed.sql'),
+            devSeedFile: resolveAgainst(rootDir, 'db/postgres-dev-seed.sql'),
+            pgliteExtensions,
+            schema,
             ...base('db/postgres'),
         };
     }
@@ -120,7 +137,7 @@ async function createPostgresClient(resolved) {
         throw new Error('PGlite Postgres resolution is missing pgliteDir.');
     }
     mkdirSync(dirname(resolved.pgliteDir), { recursive: true });
-    const db = await createEmbeddedPostgres(resolved.pgliteDir);
+    const db = await createEmbeddedPostgres(resolved, resolved.pgliteDir);
     return pgliteAsClient(db);
 }
 let embeddedPostgresWasm;
@@ -157,21 +174,107 @@ async function loadEmbeddedPostgresWasm() {
         return undefined;
     }
 }
-async function createEmbeddedPostgres(dataDir) {
+const isPGliteExtension = (value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.setup === 'function';
+/**
+ * Turn a declared extension specifier into the module that publishes it.
+ *
+ * A bare name is one of PGlite's own contrib extensions (`hstore`, `citext`,
+ * `uuid_ossp`), which ship with the CLI's copy of PGlite and need nothing
+ * installed. Anything else is a package the project depends on — pgvector, say,
+ * as `@electric-sql/pglite-pgvector` — so it is resolved from the project first
+ * and only then from the CLI, since the project is where a user installs it.
+ */
+async function importPGliteExtensionModule(spec, rootDir) {
+    const id = spec.includes('/') || spec.startsWith('@')
+        ? spec
+        : `@electric-sql/pglite/contrib/${spec}`;
+    for (const from of [join(rootDir, 'package.json'), import.meta.url]) {
+        let resolvedPath;
+        try {
+            resolvedPath = createRequire(from).resolve(id);
+        }
+        catch {
+            continue;
+        }
+        return (await import(pathToFileURL(resolvedPath).href));
+    }
+    throw new Error(`The PGlite extension '${spec}' could not be resolved as '${id}', ` +
+        `from either the project (${rootDir}) or the pikku CLI. ` +
+        `Install it in your project, or name one of PGlite's bundled contrib ` +
+        `extensions (hstore, citext, uuid_ossp, …), which need no install.`);
+}
+/**
+ * Load every extension the project declares, keyed the way PGlite wants them.
+ *
+ * The key is the export name (`vector`, `hstore`), which is also the name the
+ * SQL uses, so `CREATE EXTENSION vector` finds what a declaration of
+ * `@electric-sql/pglite-pgvector` loaded. A module exporting several is fine —
+ * all of them are taken — and a `default` export is used only when it is the
+ * only extension there, so a package that default-exports the same object it
+ * also names is not registered twice.
+ */
+export async function loadPGliteExtensions(rootDir, specs) {
+    const extensions = {};
+    for (const spec of specs) {
+        const module = await importPGliteExtensionModule(spec, rootDir);
+        const found = Object.entries(module).filter(([, value]) => isPGliteExtension(value));
+        const named = found.filter(([name]) => name !== 'default');
+        const chosen = named.length > 0 ? named : found;
+        if (chosen.length === 0) {
+            throw new Error(`'${spec}' exports no PGlite extension. A PGlite extension is an ` +
+                `object with a 'setup' function — check that the package is one, ` +
+                `and that its version matches the PGlite the CLI runs.`);
+        }
+        for (const [name, extension] of chosen) {
+            extensions[name === 'default' ? (extension.name ?? spec) : name] =
+                extension;
+        }
+    }
+    return extensions;
+}
+async function createEmbeddedPostgres(context, dataDir) {
     embeddedPostgresWasm ??= loadEmbeddedPostgresWasm();
-    const [{ PGlite }, { pgcrypto }, wasm] = await Promise.all([
+    const [{ PGlite }, { pgcrypto }, wasm, declared] = await Promise.all([
         import('@electric-sql/pglite'),
         import('@electric-sql/pglite/contrib/pgcrypto'),
         embeddedPostgresWasm,
+        loadPGliteExtensions(context.rootDir, context.pgliteExtensions),
     ]);
     return new PGlite({
         ...(dataDir ? { dataDir } : {}),
         ...wasm,
         extensions: {
             pgcrypto,
+            ...declared,
         },
     });
 }
+/**
+ * PGlite reports an extension it was never given as a plain
+ * `extension "x" is not available`, which reads as though the SQL is at fault.
+ * It is not: the database is real Postgres, the migration is fine, and the one
+ * thing missing is the declaration that would have loaded the extension into
+ * this particular instance. Say so, since nothing else in the message points
+ * anywhere near the fix.
+ */
+function explainMissingExtension(error, declared) {
+    const message = error instanceof Error ? error.message : '';
+    const match = /extension "([^"]+)" is not available/.exec(message);
+    if (!match)
+        return error;
+    const name = match[1];
+    return new Error(`The embedded PGlite database has no '${name}' extension. ` +
+        `The CLI migrates a PGlite shadow database to type and diff your schema, ` +
+        `so every extension your migrations use has to be declared as ` +
+        `pgliteExtensions in createConfig — e.g. pgliteExtensions: ['${name}'] ` +
+        `for a PGlite contrib extension, or the package that publishes it ` +
+        `('@electric-sql/pglite-pgvector' for pgvector).` +
+        (declared.length > 0
+            ? ` Currently declared: ${declared.join(', ')}.`
+            : ''), { cause: error });
+}
 function pgliteAsClient(db) {
     return {
         query: (sql, params) => db.query(sql, params),
@@ -189,6 +292,14 @@ async function withPostgresClient(resolved, run) {
     try {
         return await run(client);
     }
+    catch (error) {
+        // Only the embedded database's missing extensions are the declaration's
+        // doing. On a real server it is the server that lacks the extension, and
+        // pointing at the CLI's config would send the reader the wrong way.
+        throw resolved.mode === 'pglite'
+            ? explainMissingExtension(error, resolved.pgliteExtensions)
+            : error;
+    }
     finally {
         await client.end();
     }
@@ -226,6 +337,7 @@ export async function migrateAndCodegen(resolved, options = {}) {
                 schemaJsonFile: resolved.schemaJsonFile,
                 enumsFile: resolved.enumsFile,
                 camelCase: resolved.camelCase,
+                defaultSchema: resolved.defaultSchema,
                 rootDir: resolved.rootDir,
                 dialect: 'sqlite',
                 migrationsDir: resolved.migrationsDir,
@@ -237,7 +349,7 @@ export async function migrateAndCodegen(resolved, options = {}) {
     }
     else {
         const withClient = options.scratch
-            ? (_r, run) => withScratchPostgresDatabase(run)
+            ? (r, run) => withScratchPostgresDatabase(r, run)
             : withPostgresClient;
         await withClient(resolved, async (client) => {
             const introspector = new PostgresIntrospector(client);
@@ -253,6 +365,7 @@ export async function migrateAndCodegen(resolved, options = {}) {
                     schemaJsonFile: resolved.schemaJsonFile,
                     enumsFile: resolved.enumsFile,
                     camelCase: resolved.camelCase,
+                    defaultSchema: resolved.defaultSchema,
                     rootDir: resolved.rootDir,
                     dialect: 'postgres',
                     migrationsDir: resolved.migrationsDir,
@@ -282,21 +395,32 @@ export async function migrateAndCodegen(resolved, options = {}) {
     };
 }
 // ─── SQLite-only operations ───────────────────────────────────────────────────
-export async function seed(resolved) {
+/**
+ * Apply the dev seed file. Only {@link reset} calls this, immediately after
+ * migrating a database it has just wiped, which is what lets a seed file be
+ * plain `INSERT`s rather than idempotent ones.
+ *
+ * `reset` refuses production before it gets here, so this guard is unreachable
+ * through the CLI. It stays because the export is reachable without it.
+ */
+export async function devSeed(resolved) {
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error(`pikku dev seed refused: NODE_ENV=production. Seed data is test data — it only runs in dev.`);
+    }
     if (resolved.dialect === 'sqlite') {
         const runtime = await loadSqliteRuntime();
         const db = runtime.open(resolved.dbFile);
         try {
-            return runSeed(db, resolved.seedFile);
+            return runDevSeed(db, resolved.devSeedFile);
         }
         finally {
             db.close();
         }
     }
-    if (!existsSync(resolved.seedFile)) {
+    if (!existsSync(resolved.devSeedFile)) {
         return { applied: false, bytes: 0 };
     }
-    const sql = readFileSync(resolved.seedFile, 'utf8');
+    const sql = readFileSync(resolved.devSeedFile, 'utf8');
     if (sql.trim().length === 0) {
         return { applied: false, bytes: 0 };
     }
@@ -346,8 +470,7 @@ export async function reset(resolved, rootDir) {
         AND schema_name NOT LIKE 'pg_temp_%'
     `);
         for (const { schema_name: schemaName } of result.rows) {
-            const quoted = `"${schemaName.replace(/"/g, '""')}"`;
-            await client.query(`DROP SCHEMA IF EXISTS ${quoted} CASCADE`);
+            await client.query(`DROP SCHEMA IF EXISTS ${quoteIdentifier(schemaName)} CASCADE`);
         }
         await client.query('CREATE SCHEMA IF NOT EXISTS public');
     });
@@ -474,7 +597,7 @@ export async function createKysely(resolved) {
     }
     mkdirSync(dirname(resolved.pgliteDir), { recursive: true });
     return createPGliteKysely({
-        db: await createEmbeddedPostgres(resolved.pgliteDir),
+        db: await createEmbeddedPostgres(resolved, resolved.pgliteDir),
         camelCase: resolved.camelCase,
         plugins,
     });
@@ -486,11 +609,22 @@ async function introspectorToMap(intro) {
     }
     return map;
 }
-function diffSchemas(desired, actual) {
+/**
+ * The tables and columns `desired` has that `actual` does not.
+ *
+ * `schema` is the one the desired bare names belong in, when the caller knows.
+ * Given it, only that schema's copy of a table counts: a `workflow_step` in
+ * `public` is a different table from the `app.workflow_step` a source with
+ * `db.schema: "app"` wants, and letting it match would report the source
+ * satisfied by a table its SQL never creates.
+ */
+function diffSchemas(desired, actual, schema) {
     const missingTables = [];
     const missingColumns = [];
     for (const [table, cols] of desired) {
-        const actualCols = actual.get(table) ?? schemaQualifiedMatch(actual, table);
+        const actualCols = schema
+            ? actual.get(qualifiedTableKey(schema, table))
+            : (actual.get(table) ?? schemaQualifiedMatch(actual, table));
         if (!actualCols) {
             missingTables.push(table);
             continue;
@@ -501,6 +635,19 @@ function diffSchemas(desired, actual) {
     }
     return { missingTables, missingColumns };
 }
+/**
+ * How an introspected schema map keys a table in a given schema.
+ *
+ * Introspection elides `public`, so the key for a table there is the bare name.
+ * Anything else carries its qualifier.
+ */
+function qualifiedTableKey(schema, table) {
+    return schema === 'public' ? table : `${schema}.${table}`;
+}
+/** A PostgreSQL identifier, quoted so its casing survives the parser. */
+function quoteIdentifier(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
 /**
  * The one table in `actual` whose name matches `table` once its schema is
  * dropped, if there is exactly one.
@@ -530,11 +677,14 @@ 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(run) {
-    const scratchDb = await createEmbeddedPostgres();
+async function withScratchPostgresDatabase(context, run) {
+    const scratchDb = await createEmbeddedPostgres(context);
     try {
         return await run(pgliteAsClient(scratchDb));
     }
+    catch (error) {
+        throw explainMissingExtension(error, context.pgliteExtensions);
+    }
     finally {
         if (!scratchDb.closed) {
             await scratchDb.close();
@@ -551,8 +701,8 @@ async function postgresDatabaseToMap(client) {
         await intro.close();
     }
 }
-async function desiredPostgresAuthSchema(rootDir, srcDirectories, logger) {
-    return withScratchPostgresDatabase(async (scratchDb) => {
+async function desiredPostgresAuthSchema(context, rootDir, srcDirectories, logger) {
+    return withScratchPostgresDatabase(context, 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
@@ -598,7 +748,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(rootDir, srcDirectories, logger);
+            return desiredPostgresAuthSchema(resolved, rootDir, srcDirectories, logger);
         }
         const { runMigrations, compileMigrations } = await getAuthMigrations(options);
         await runMigrations();
@@ -685,7 +835,7 @@ export async function desiredRuntimeSchema(resolved, rootDir, srcDirectories, lo
             db.close();
         }
     }
-    return withScratchPostgresDatabase(async (db) => {
+    return withScratchPostgresDatabase(resolved, async (db) => {
         const kysely = createPGliteKysely({
             db: db.__pglite,
             camelCase: true,
@@ -694,7 +844,7 @@ export async function desiredRuntimeSchema(resolved, rootDir, srcDirectories, lo
             const { tables, schemas, types } = await collect(kysely, () => postgresDatabaseToMap(db));
             return {
                 tables,
-                sql: compilePikkuSchemas(kysely, schemas, types),
+                sql: compilePikkuSchemas(kysely, schemas, types, resolved.schema),
                 skipped,
             };
         }
@@ -736,8 +886,8 @@ async function coveredSqliteSchema(migrationsDir) {
         db.close();
     }
 }
-async function coveredPostgresSchema(migrationsDir) {
-    return withScratchPostgresDatabase(async (client) => {
+async function coveredPostgresSchema(migrationsDir, context) {
+    return withScratchPostgresDatabase(context, async (client) => {
         await migrate(new PostgresMigrationExecutor(client), migrationsDir);
         return postgresDatabaseToMap(client);
     });
@@ -764,7 +914,7 @@ async function coveredPostgresSchema(migrationsDir) {
 export async function computeSchemaDrift(resolved, rootDir, srcDirectories, logger) {
     const covered = resolved.dialect === 'sqlite'
         ? await coveredSqliteSchema(resolved.migrationsDir)
-        : await coveredPostgresSchema(resolved.migrationsDir);
+        : await coveredPostgresSchema(resolved.migrationsDir, resolved);
     const actual = await introspectSchema(resolved);
     const { missingTables, missingColumns } = diffSchemas(covered, actual);
     // Compare on the full name. A migration that names no schema lands in
@@ -889,7 +1039,7 @@ const concatMigrations = (migrationsDir) => readdirSync(migrationsDir)
  * happens to be configured against — an addon is published once and consumed by
  * projects on either engine.
  */
-export async function exportSchema(rootDir) {
+export async function exportSchema(rootDir, pgliteExtensions = []) {
     const artifact = {};
     const sqliteDir = join(rootDir, 'db', 'sqlite');
     if (existsSync(sqliteDir)) {
@@ -902,7 +1052,7 @@ export async function exportSchema(rootDir) {
     if (existsSync(postgresDir)) {
         artifact.postgres = {
             sql: concatMigrations(postgresDir),
-            tables: serializeSchemaMap(await coveredPostgresSchema(postgresDir)),
+            tables: serializeSchemaMap(await coveredPostgresSchema(postgresDir, { rootDir, pgliteExtensions })),
         };
     }
     return artifact;
@@ -975,6 +1125,7 @@ export async function schemaSources(resolved, rootDir, srcDirectories, logger, a
             name: 'pikku-runtime',
             desired: runtime,
             origin: "@pikku/kysely's runtime services",
+            schema: resolved.dialect === 'postgres' ? resolved.schema : undefined,
         });
     }
     sources.push(...(await addonSchemaSources(rootDir, resolved.dialect, addons, logger)));
@@ -1042,15 +1193,31 @@ export async function generateMigrations(resolved, rootDir, srcDirectories, logg
         // 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);
+            : await coveredPostgresSchema(resolved.migrationsDir, resolved);
+        const { missingTables, missingColumns } = diffSchemas(source.desired.tables, covered, source.schema);
         if (missingTables.length === 0 && missingColumns.length === 0) {
             result.upToDate.push(source.name);
             continue;
         }
-        const partial = [...source.desired.tables.keys()].some((t) => covered.has(t));
+        // Matched the same way `diffSchemas` matches, qualifier and all. A project
+        // that keeps its tables in a schema has them covered as `app.workflow_step`
+        // while the declaration names them bare, so a strict `covered.has(t)` reads
+        // "nothing is covered" and re-emits the whole schema over tables that are
+        // already there — and a copy in some other schema is not that table, so it
+        // must not count either.
+        const partial = [...source.desired.tables.keys()].some((t) => source.schema
+            ? covered.has(qualifiedTableKey(source.schema, t))
+            : covered.has(t) || schemaQualifiedMatch(covered, t) !== undefined);
         let body;
         let needsBackfill = [];
+        // The source's own SQL is already qualified when it can be; the delta below
+        // is written here from bare introspected names, so it has to be qualified
+        // to match, or it alters a table in whichever schema `search_path` finds.
+        // Quoted, because the compiled SQL this delta has to line up with goes
+        // through the schema builder and is quoted there. `db.schema: "App"` left
+        // raw folds to `app`, so the delta would alter a table in a schema the
+        // runtime never uses.
+        const qualify = (table) => source.schema ? `${quoteIdentifier(source.schema)}.${table}` : table;
         if (!partial) {
             body = source.desired.sql;
         }
@@ -1071,7 +1238,7 @@ export async function generateMigrations(resolved, rootDir, srcDirectories, logg
                 statements.push(`-- REVIEW: ${table} is new, and its CREATE TABLE could not be found in the\n` +
                     `-- source's own SQL. The column list below carries no indexes, constraints\n` +
                     `-- or foreign keys — copy the real statement over it before applying.\n` +
-                    `CREATE TABLE ${table} (\n` +
+                    `CREATE TABLE ${qualify(table)} (\n` +
                     [...(columns?.values() ?? [])]
                         .map((c) => `  ${c.name} ${c.type}${c.notNull ? ' NOT NULL' : ''}`)
                         .join(',\n') +
@@ -1081,7 +1248,7 @@ export async function generateMigrations(resolved, rootDir, srcDirectories, logg
                 const infos = columns
                     .map((name) => source.desired.tables.get(table)?.get(name))
                     .filter((c) => c !== undefined);
-                const added = addColumnStatements(table, infos);
+                const added = addColumnStatements(qualify(table), infos);
                 statements.push(...added.sql);
                 needsBackfill.push(...added.needsBackfill);
             }

package/dist/src/functions/db/sqlite/dev-seed.d.ts

@@ -0,0 +1,12 @@
+import type { SyncSqliteDatabase } from './sqlite-runtime.js';
+export interface DevSeedResult {
+    applied: boolean;
+    bytes: number;
+}
+/**
+ * Apply db/<engine>-dev-seed.sql to the open db. Only `pikku db reset` reaches
+ * here, against a database it has just wiped and migrated, so the file may be
+ * plain `INSERT`s — it is never applied twice. Returns `applied: false` if the
+ * file doesn't exist; throws on SQL errors.
+ */
+export declare function devSeed(db: SyncSqliteDatabase, devSeedFile: string): DevSeedResult;

package/dist/src/functions/db/sqlite/dev-seed.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync } from 'node:fs';
+/**
+ * Apply db/<engine>-dev-seed.sql to the open db. Only `pikku db reset` reaches
+ * here, against a database it has just wiped and migrated, so the file may be
+ * plain `INSERT`s — it is never applied twice. Returns `applied: false` if the
+ * file doesn't exist; throws on SQL errors.
+ */
+export function devSeed(db, devSeedFile) {
+    if (!existsSync(devSeedFile)) {
+        return { applied: false, bytes: 0 };
+    }
+    const raw = readFileSync(devSeedFile);
+    db.exec('BEGIN');
+    try {
+        db.exec(raw.toString('utf8'));
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+    return { applied: true, bytes: raw.length };
+}