@venturekit/data 0.0.0-dev.20260427225816 → 0.0.0-dev.20260429114130

package/README.md

@@ -89,15 +89,19 @@ const rdsConfig = createRdsConfig({
 
 ## Migrations
 
-VentureKit uses [Drizzle Kit](https://orm.drizzle.team) for migrations. Use the CLI:
+`@venturekit/data` ships a pure-SQL migration runner. Drop `.sql` files
+into `db/migrations/` and apply them with the CLI:
 
 ```bash
-vk migrate generate   # Generate from schema changes
-vk migrate up         # Apply pending migrations
-vk migrate status     # Check migration status
-vk migrate studio     # Open Drizzle Studio GUI
+vk migrate            # Apply pending schema migrations
+vk migrate --seed     # Apply migrations, then seeds from db/seeds/
+vk migrate status     # Show which migrations and seeds have been applied
 ```
 
+Applied files are tracked in `__vk_migrations` / `__vk_seeds`. The
+file-content hash is locked once recorded — editing an applied file
+hard-fails on the next run; write a new migration instead.
+
 ## API Reference
 
 See the [API reference](https://venturekit.dev/api-reference/data) for full documentation.

package/dist/index.d.ts

@@ -6,7 +6,8 @@
 export * from './types/index.js';
 export { createRdsConfig, DEFAULT_RDS_CONFIG, buildRdsConfig, } from './rds/index.js';
 export type { RdsOutputs, RdsInfraConfig } from './rds/index.js';
-export { createMigrationConfig, DEFAULT_MIGRATION_CONFIG, getFlywayEnv, } from './migrations/index.js';
-export { query, getPool, mapResults, mapRow, beginTransaction, withTransaction, buildTransaction, } from './query/index.js';
-export type { Transaction, ResultsMapper } from './query/index.js';
+export { createMigrationConfig, DEFAULT_MIGRATION_CONFIG, getFlywayEnv, runMigrations, getMigrationStatus, runSeeds, getSeedStatus, MIGRATIONS_TRACKING_TABLE, SEEDS_TRACKING_TABLE, MigrationToolNotImplementedError, MigrationHashMismatchError, applyDatabaseUrlToEnv, } from './migrations/index.js';
+export type { RunResult, StatusEntry, RunOptions, SeedRunOptions, } from './migrations/index.js';
+export { query, getPool, mapResults, mapRow, configureMapper, getMapperConfig, beginTransaction, withTransaction, buildTransaction, } from './query/index.js';
+export type { Transaction, ResultsMapper, Querier, MapperOptions, } from './query/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGjE,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,EACL,OAAO,EACP,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKjE,OAAO,EAEL,qBAAqB,EACrB,wBAAwB,EACxB,YAAY,EAEZ,aAAa,EACb,kBAAkB,EAClB,QAAQ,EACR,aAAa,EACb,yBAAyB,EACzB,oBAAoB,EAEpB,gCAAgC,EAChC,0BAA0B,EAG1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,cAAc,GACf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,EACL,OAAO,EACP,UAAU,EACV,MAAM,EACN,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,aAAa,EACb,OAAO,EACP,aAAa,GACd,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -7,8 +7,19 @@
 export * from './types/index.js';
 // RDS
 export { createRdsConfig, DEFAULT_RDS_CONFIG, buildRdsConfig, } from './rds/index.js';
-// Migrations (recommends Flyway, golang-migrate, Prisma, or Drizzle)
-export { createMigrationConfig, DEFAULT_MIGRATION_CONFIG, getFlywayEnv, } from './migrations/index.js';
+// Migrations + seeds — bundled pure-SQL runner (`tool: 'custom'`) plus
+// config helpers for integrating Flyway / Drizzle Kit / Prisma /
+// golang-migrate from your own deploy pipeline.
+export { 
+// config helpers (existing)
+createMigrationConfig, DEFAULT_MIGRATION_CONFIG, getFlywayEnv, 
+// built-in runner — pure SQL, tracked in __vk_migrations / __vk_seeds
+runMigrations, getMigrationStatus, runSeeds, getSeedStatus, MIGRATIONS_TRACKING_TABLE, SEEDS_TRACKING_TABLE, 
+// errors
+MigrationToolNotImplementedError, MigrationHashMismatchError, 
+// env-var bridge: parses DATABASE_URL into the granular DB_* vars used
+// by getPool(). Auto-applied at the top of runMigrations / runSeeds.
+applyDatabaseUrlToEnv, } from './migrations/index.js';
 // Query utility, result mapping, and transactions
-export { query, getPool, mapResults, mapRow, beginTransaction, withTransaction, buildTransaction, } from './query/index.js';
+export { query, getPool, mapResults, mapRow, configureMapper, getMapperConfig, beginTransaction, withTransaction, buildTransaction, } from './query/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,MAAM;AACN,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,qEAAqE;AACrE,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAE/B,kDAAkD;AAClD,OAAO,EACL,KAAK,EACL,OAAO,EACP,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,MAAM;AACN,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,uEAAuE;AACvE,iEAAiE;AACjE,gDAAgD;AAChD,OAAO;AACL,4BAA4B;AAC5B,qBAAqB,EACrB,wBAAwB,EACxB,YAAY;AACZ,sEAAsE;AACtE,aAAa,EACb,kBAAkB,EAClB,QAAQ,EACR,aAAa,EACb,yBAAyB,EACzB,oBAAoB;AACpB,SAAS;AACT,gCAAgC,EAChC,0BAA0B;AAC1B,uEAAuE;AACvE,qEAAqE;AACrE,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAQ/B,kDAAkD;AAClD,OAAO,EACL,KAAK,EACL,OAAO,EACP,UAAU,EACV,MAAM,EACN,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/migrations/dispatcher.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Migration runner dispatcher.
+ *
+ * Reads `MigrationConfig.tool` and routes to the matching runner. Only the
+ * `'custom'` runner (pure-SQL files, tracked in `__vk_migrations`) is
+ * implemented in this package today; the others throw a clear
+ * `MigrationToolNotImplementedError` pointing at the workaround.
+ *
+ * Kept in its own file so `migrations/index.ts` stays focused on its
+ * existing public-config helpers (`createMigrationConfig`, `getFlywayEnv`).
+ */
+import type { MigrationConfig } from '../types/migration.js';
+import type { RunOptions, RunResult, StatusEntry } from './types.js';
+/** Tracking-table name for migrations. Mirrors `__vk_seeds` for seeds. */
+export declare const MIGRATIONS_TRACKING_TABLE = "__vk_migrations";
+/**
+ * Apply pending schema migrations using the runner selected by
+ * `config.tool`.
+ *
+ * For `tool: 'custom'`, reads `*.sql` files from `config.migrationsDir`,
+ * applies the pending ones inside transactions, and tracks them in the
+ * `__vk_migrations` table.
+ *
+ * For other tools (`'drizzle'`, `'flyway'`, `'golang-migrate'`,
+ * `'prisma'`), throws `MigrationToolNotImplementedError` with a hint
+ * pointing at the workaround.
+ */
+export declare function runMigrations(config: MigrationConfig, opts?: RunOptions): Promise<RunResult>;
+/**
+ * Read-only counterpart of `runMigrations`. Returns one `StatusEntry` per
+ * `.sql` file in `config.migrationsDir`. Same dispatch rules as
+ * `runMigrations`.
+ */
+export declare function getMigrationStatus(config: MigrationConfig): Promise<StatusEntry[]>;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/migrations/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/migrations/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAM7D,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAErE,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,oBAAoB,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,SAAS,CAAC,CAiBpB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,WAAW,EAAE,CAAC,CAgBxB"}

package/dist/migrations/dispatcher.js

@@ -0,0 +1,71 @@
+/**
+ * Migration runner dispatcher.
+ *
+ * Reads `MigrationConfig.tool` and routes to the matching runner. Only the
+ * `'custom'` runner (pure-SQL files, tracked in `__vk_migrations`) is
+ * implemented in this package today; the others throw a clear
+ * `MigrationToolNotImplementedError` pointing at the workaround.
+ *
+ * Kept in its own file so `migrations/index.ts` stays focused on its
+ * existing public-config helpers (`createMigrationConfig`, `getFlywayEnv`).
+ */
+import { runSqlFiles, getSqlFilesStatus } from './runners/custom.js';
+import { drizzleNotImplemented } from './runners/drizzle.js';
+import { flywayNotImplemented } from './runners/flyway.js';
+import { golangMigrateNotImplemented } from './runners/golang-migrate.js';
+import { prismaNotImplemented } from './runners/prisma.js';
+/** Tracking-table name for migrations. Mirrors `__vk_seeds` for seeds. */
+export const MIGRATIONS_TRACKING_TABLE = '__vk_migrations';
+/**
+ * Apply pending schema migrations using the runner selected by
+ * `config.tool`.
+ *
+ * For `tool: 'custom'`, reads `*.sql` files from `config.migrationsDir`,
+ * applies the pending ones inside transactions, and tracks them in the
+ * `__vk_migrations` table.
+ *
+ * For other tools (`'drizzle'`, `'flyway'`, `'golang-migrate'`,
+ * `'prisma'`), throws `MigrationToolNotImplementedError` with a hint
+ * pointing at the workaround.
+ */
+export async function runMigrations(config, opts = {}) {
+    switch (config.tool) {
+        case 'custom':
+            return runSqlFiles({
+                dir: config.migrationsDir,
+                trackingTable: MIGRATIONS_TRACKING_TABLE,
+                onApply: opts.onApply,
+            });
+        case 'drizzle':
+            return drizzleNotImplemented();
+        case 'flyway':
+            return flywayNotImplemented();
+        case 'golang-migrate':
+            return golangMigrateNotImplemented();
+        case 'prisma':
+            return prismaNotImplemented();
+    }
+}
+/**
+ * Read-only counterpart of `runMigrations`. Returns one `StatusEntry` per
+ * `.sql` file in `config.migrationsDir`. Same dispatch rules as
+ * `runMigrations`.
+ */
+export async function getMigrationStatus(config) {
+    switch (config.tool) {
+        case 'custom':
+            return getSqlFilesStatus({
+                dir: config.migrationsDir,
+                trackingTable: MIGRATIONS_TRACKING_TABLE,
+            });
+        case 'drizzle':
+            return drizzleNotImplemented();
+        case 'flyway':
+            return flywayNotImplemented();
+        case 'golang-migrate':
+            return golangMigrateNotImplemented();
+        case 'prisma':
+            return prismaNotImplemented();
+    }
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/migrations/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/migrations/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAG3D,0EAA0E;AAC1E,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAuB,EACvB,OAAmB,EAAE;IAErB,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,WAAW,CAAC;gBACjB,GAAG,EAAE,MAAM,CAAC,aAAa;gBACzB,aAAa,EAAE,yBAAyB;gBACxC,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,CAAC,CAAC;QACL,KAAK,SAAS;YACZ,OAAO,qBAAqB,EAAE,CAAC;QACjC,KAAK,QAAQ;YACX,OAAO,oBAAoB,EAAE,CAAC;QAChC,KAAK,gBAAgB;YACnB,OAAO,2BAA2B,EAAE,CAAC;QACvC,KAAK,QAAQ;YACX,OAAO,oBAAoB,EAAE,CAAC;IAClC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAuB;IAEvB,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,iBAAiB,CAAC;gBACvB,GAAG,EAAE,MAAM,CAAC,aAAa;gBACzB,aAAa,EAAE,yBAAyB;aACzC,CAAC,CAAC;QACL,KAAK,SAAS;YACZ,OAAO,qBAAqB,EAAE,CAAC;QACjC,KAAK,QAAQ;YACX,OAAO,oBAAoB,EAAE,CAAC;QAChC,KAAK,gBAAgB;YACnB,OAAO,2BAA2B,EAAE,CAAC;QACvC,KAAK,QAAQ;YACX,OAAO,oBAAoB,EAAE,CAAC;IAClC,CAAC;AACH,CAAC"}

package/dist/migrations/env.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `DATABASE_URL` → `DB_*` env-var bridge used by the migration runner.
+ *
+ * The implementation lives in `query/pool.ts` so a single function fills
+ * the granular slots that `getPool()` reads — and so `getPool()` itself
+ * can call it on first connection (covers consumers that boot via
+ * `query()` / `withTransaction()` without ever touching the migration
+ * runner). This file re-exports for backward compatibility with code
+ * that imports from `@venturekit/data`'s `migrations/env` path.
+ */
+export { applyDatabaseUrlToEnv } from '../query/pool.js';
+//# sourceMappingURL=env.d.ts.map

package/dist/migrations/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/migrations/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/migrations/env.js

@@ -0,0 +1,12 @@
+/**
+ * `DATABASE_URL` → `DB_*` env-var bridge used by the migration runner.
+ *
+ * The implementation lives in `query/pool.ts` so a single function fills
+ * the granular slots that `getPool()` reads — and so `getPool()` itself
+ * can call it on first connection (covers consumers that boot via
+ * `query()` / `withTransaction()` without ever touching the migration
+ * runner). This file re-exports for backward compatibility with code
+ * that imports from `@venturekit/data`'s `migrations/env` path.
+ */
+export { applyDatabaseUrlToEnv } from '../query/pool.js';
+//# sourceMappingURL=env.js.map

package/dist/migrations/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/migrations/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/migrations/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Error classes thrown by the migration / seed runners.
+ *
+ * Exposed as named exports so callers (e.g. the `vk migrate` CLI) can
+ * `instanceof`-check them and surface friendlier UX than a generic
+ * `Error.message`.
+ */
+/**
+ * Thrown by `runMigrations` / `getMigrationStatus` when `MigrationConfig.tool`
+ * points at a runner that hasn't been wired up yet (drizzle, flyway,
+ * golang-migrate, prisma). The bundled `'custom'` runner is the only one
+ * implemented today — the rest exist for future opt-in.
+ */
+export declare class MigrationToolNotImplementedError extends Error {
+    readonly tool: string;
+    readonly hint: string;
+    constructor(tool: string, hint: string);
+}
+/**
+ * Thrown when a `.sql` file's contents have changed AFTER the runner already
+ * recorded an `applied` row for it. Migrations and seeds are immutable once
+ * applied; editing them is a real footgun (different DBs end up with
+ * different schemas / data while both think they're up-to-date), so we hard-
+ * fail instead of silently skipping or re-running.
+ */
+export declare class MigrationHashMismatchError extends Error {
+    readonly version: string;
+    readonly storedHash: string;
+    readonly currentHash: string;
+    readonly trackingTable: string;
+    constructor(version: string, storedHash: string, currentHash: string, trackingTable: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/migrations/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/migrations/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAQvC;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAG7B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM;CAcxB"}

package/dist/migrations/errors.js

@@ -0,0 +1,48 @@
+/**
+ * Error classes thrown by the migration / seed runners.
+ *
+ * Exposed as named exports so callers (e.g. the `vk migrate` CLI) can
+ * `instanceof`-check them and surface friendlier UX than a generic
+ * `Error.message`.
+ */
+/**
+ * Thrown by `runMigrations` / `getMigrationStatus` when `MigrationConfig.tool`
+ * points at a runner that hasn't been wired up yet (drizzle, flyway,
+ * golang-migrate, prisma). The bundled `'custom'` runner is the only one
+ * implemented today — the rest exist for future opt-in.
+ */
+export class MigrationToolNotImplementedError extends Error {
+    tool;
+    hint;
+    constructor(tool, hint) {
+        super(`Migration runner for tool '${tool}' is not implemented in @venturekit/data. ${hint}`);
+        this.name = 'MigrationToolNotImplementedError';
+        this.tool = tool;
+        this.hint = hint;
+    }
+}
+/**
+ * Thrown when a `.sql` file's contents have changed AFTER the runner already
+ * recorded an `applied` row for it. Migrations and seeds are immutable once
+ * applied; editing them is a real footgun (different DBs end up with
+ * different schemas / data while both think they're up-to-date), so we hard-
+ * fail instead of silently skipping or re-running.
+ */
+export class MigrationHashMismatchError extends Error {
+    version;
+    storedHash;
+    currentHash;
+    trackingTable;
+    constructor(version, storedHash, currentHash, trackingTable) {
+        super(`[migrate] file '${version}.sql' was edited after it was already applied. ` +
+            `Stored hash=${storedHash.slice(0, 12)}..., current hash=${currentHash.slice(0, 12)}.... ` +
+            `Migrations and seeds are immutable once applied. Either revert your edits, ` +
+            `drop the row from ${trackingTable}, or write a new ${trackingTable === '__vk_seeds' ? 'seed' : 'migration'} to make the desired change.`);
+        this.name = 'MigrationHashMismatchError';
+        this.version = version;
+        this.storedHash = storedHash;
+        this.currentHash = currentHash;
+        this.trackingTable = trackingTable;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/migrations/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/migrations/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,OAAO,gCAAiC,SAAQ,KAAK;IAChD,IAAI,CAAS;IACb,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,IAAY;QACpC,KAAK,CACH,8BAA8B,IAAI,6CAA6C,IAAI,EAAE,CACtF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,OAAO,CAAS;IAChB,UAAU,CAAS;IACnB,WAAW,CAAS;IACpB,aAAa,CAAS;IAE/B,YACE,OAAe,EACf,UAAkB,EAClB,WAAmB,EACnB,aAAqB;QAErB,KAAK,CACH,mBAAmB,OAAO,iDAAiD;YACzE,eAAe,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO;YAC1F,6EAA6E;YAC7E,qBAAqB,aAAa,oBAAoB,aAAa,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,8BAA8B,CAC5I,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -1,18 +1,30 @@
 /**
  * Migrations
  *
- * VentureKit recommends using established migration tools rather than custom code.
- * This module provides configuration helpers for integrating with popular tools.
+ * Two surfaces exposed from this module:
  *
- * Recommended tools:
- * - Flyway (https://flywaydb.org) - Java-based, widely used
- * - golang-migrate (https://github.com/golang-migrate/migrate) - Lightweight CLI
- * - Prisma Migrate (https://www.prisma.io/migrate) - If using Prisma ORM
- * - Drizzle Kit (https://orm.drizzle.team/kit-docs/overview) - If using Drizzle ORM
+ *   1. **Config helpers** (`createMigrationConfig`, `DEFAULT_MIGRATION_CONFIG`,
+ *      `getFlywayEnv`) — for projects that want to integrate with an
+ *      established migration tool from their own deploy pipeline.
+ *
+ *   2. **Built-in runner** (`runMigrations`, `getMigrationStatus`,
+ *      `runSeeds`, `getSeedStatus`) — applies pure-SQL files from
+ *      `db/migrations/` and `db/seeds/`, tracked in `__vk_migrations` and
+ *      `__vk_seeds` respectively. Selected by `MigrationConfig.tool ===
+ *      'custom'`. This is what `vk migrate` calls under the hood.
+ *
+ * The `'custom'` runner is the only one bundled today. Setting `tool` to
+ * `'drizzle'` / `'flyway'` / `'golang-migrate'` / `'prisma'` throws
+ * `MigrationToolNotImplementedError` — those are kept in the type union as
+ * opt-in points for future runners; for now use the established tool's CLI
+ * directly.
  */
 import type { MigrationConfig, MigrationConfigInput } from '../types/index.js';
 /**
- * Default migration configuration
+ * Default migration configuration. Defaults to the bundled pure-SQL runner
+ * (`tool: 'custom'`) so `vk migrate` works in any project that drops `.sql`
+ * files into `db/migrations/` — no Java install (Flyway) or external CLI
+ * required.
  */
 export declare const DEFAULT_MIGRATION_CONFIG: MigrationConfig;
 /**
@@ -20,9 +32,18 @@ export declare const DEFAULT_MIGRATION_CONFIG: MigrationConfig;
  */
 export declare function createMigrationConfig(input?: MigrationConfigInput): MigrationConfig;
 /**
- * Get Flyway configuration for deployment
+ * Get Flyway configuration for deployment.
  *
- * Returns environment variables to pass to Flyway container/Lambda
+ * Returns environment variables to pass to a Flyway container / Lambda /
+ * CLI invocation. Use this when you've set `MigrationConfig.tool: 'flyway'`
+ * and want to shell out to the `flyway` binary yourself — `runMigrations`
+ * with `tool: 'flyway'` currently throws `MigrationToolNotImplementedError`
+ * and points at this helper.
  */
 export declare function getFlywayEnv(config: MigrationConfig, dbUrl: string): Record<string, string>;
+export { runMigrations, getMigrationStatus, MIGRATIONS_TRACKING_TABLE, } from './dispatcher.js';
+export { runSeeds, getSeedStatus, SEEDS_TRACKING_TABLE, } from './seeds.js';
+export { MigrationToolNotImplementedError, MigrationHashMismatchError, } from './errors.js';
+export { applyDatabaseUrlToEnv } from './env.js';
+export type { RunResult, StatusEntry, RunOptions, SeedRunOptions, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAGtC,CAAC;AAEF;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,eAAe,CAOnF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO3F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAI/E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAGtC,CAAC;AAEF;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,eAAe,CAOnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO3F;AAID,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,YAAY,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/migrations/index.js

@@ -1,20 +1,33 @@
 /**
  * Migrations
  *
- * VentureKit recommends using established migration tools rather than custom code.
- * This module provides configuration helpers for integrating with popular tools.
+ * Two surfaces exposed from this module:
  *
- * Recommended tools:
- * - Flyway (https://flywaydb.org) - Java-based, widely used
- * - golang-migrate (https://github.com/golang-migrate/migrate) - Lightweight CLI
- * - Prisma Migrate (https://www.prisma.io/migrate) - If using Prisma ORM
- * - Drizzle Kit (https://orm.drizzle.team/kit-docs/overview) - If using Drizzle ORM
+ *   1. **Config helpers** (`createMigrationConfig`, `DEFAULT_MIGRATION_CONFIG`,
+ *      `getFlywayEnv`) — for projects that want to integrate with an
+ *      established migration tool from their own deploy pipeline.
+ *
+ *   2. **Built-in runner** (`runMigrations`, `getMigrationStatus`,
+ *      `runSeeds`, `getSeedStatus`) — applies pure-SQL files from
+ *      `db/migrations/` and `db/seeds/`, tracked in `__vk_migrations` and
+ *      `__vk_seeds` respectively. Selected by `MigrationConfig.tool ===
+ *      'custom'`. This is what `vk migrate` calls under the hood.
+ *
+ * The `'custom'` runner is the only one bundled today. Setting `tool` to
+ * `'drizzle'` / `'flyway'` / `'golang-migrate'` / `'prisma'` throws
+ * `MigrationToolNotImplementedError` — those are kept in the type union as
+ * opt-in points for future runners; for now use the established tool's CLI
+ * directly.
  */
+// ─── Config helpers (existing public API) ───────────────────────────────
 /**
- * Default migration configuration
+ * Default migration configuration. Defaults to the bundled pure-SQL runner
+ * (`tool: 'custom'`) so `vk migrate` works in any project that drops `.sql`
+ * files into `db/migrations/` — no Java install (Flyway) or external CLI
+ * required.
  */
 export const DEFAULT_MIGRATION_CONFIG = {
-    tool: 'flyway',
+    tool: 'custom',
     migrationsDir: 'db/migrations',
 };
 /**
@@ -29,9 +42,13 @@ export function createMigrationConfig(input) {
     };
 }
 /**
- * Get Flyway configuration for deployment
+ * Get Flyway configuration for deployment.
  *
- * Returns environment variables to pass to Flyway container/Lambda
+ * Returns environment variables to pass to a Flyway container / Lambda /
+ * CLI invocation. Use this when you've set `MigrationConfig.tool: 'flyway'`
+ * and want to shell out to the `flyway` binary yourself — `runMigrations`
+ * with `tool: 'flyway'` currently throws `MigrationToolNotImplementedError`
+ * and points at this helper.
  */
 export function getFlywayEnv(config, dbUrl) {
     return {
@@ -41,4 +58,9 @@ export function getFlywayEnv(config, dbUrl) {
         ...(config.baselineVersion && { FLYWAY_BASELINE_VERSION: config.baselineVersion }),
     };
 }
+// ─── Built-in runner (new public API) ────────────────────────────────────
+export { runMigrations, getMigrationStatus, MIGRATIONS_TRACKING_TABLE, } from './dispatcher.js';
+export { runSeeds, getSeedStatus, SEEDS_TRACKING_TABLE, } from './seeds.js';
+export { MigrationToolNotImplementedError, MigrationHashMismatchError, } from './errors.js';
+export { applyDatabaseUrlToEnv } from './env.js';
 //# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,IAAI,EAAE,QAAQ;IACd,aAAa,EAAE,eAAe;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAA4B;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,wBAAwB,CAAC;IAE5C,OAAO;QACL,GAAG,wBAAwB;QAC3B,GAAG,KAAK;KACT,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB,EAAE,KAAa;IACjE,OAAO;QACL,UAAU,EAAE,KAAK;QACjB,gBAAgB,EAAE,cAAc,MAAM,CAAC,aAAa,EAAE;QACtD,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QACvD,GAAG,CAAC,MAAM,CAAC,eAAe,IAAI,EAAE,uBAAuB,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC;KACnF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,2EAA2E;AAE3E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,IAAI,EAAE,QAAQ;IACd,aAAa,EAAE,eAAe;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAA4B;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,wBAAwB,CAAC;IAE5C,OAAO;QACL,GAAG,wBAAwB;QAC3B,GAAG,KAAK;KACT,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB,EAAE,KAAa;IACjE,OAAO;QACL,UAAU,EAAE,KAAK;QACjB,gBAAgB,EAAE,cAAc,MAAM,CAAC,aAAa,EAAE;QACtD,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QACvD,GAAG,CAAC,MAAM,CAAC,eAAe,IAAI,EAAE,uBAAuB,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC;KACnF,CAAC;AACJ,CAAC;AAED,4EAA4E;AAE5E,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC"}

package/dist/migrations/runners/custom.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Built-in pure-SQL migration / seed runner.
+ *
+ * Used by both `runMigrations` (when `MigrationConfig.tool === 'custom'`)
+ * and `runSeeds` (always). The only difference between the two callers is
+ * the source directory and the tracking-table name; the apply / skip /
+ * hash-check logic is identical.
+ *
+ * ### Tracking table
+ *
+ * Auto-created on first run with this shape:
+ *
+ *   CREATE TABLE IF NOT EXISTS <table> (
+ *     version    text        PRIMARY KEY,
+ *     hash       text        NOT NULL,
+ *     applied_at timestamptz NOT NULL DEFAULT now()
+ *   )
+ *
+ * `version` is the file basename without the `.sql` extension. `hash` is a
+ * sha-256 of the file contents at apply time; on subsequent runs we
+ * compare the stored hash to the current file hash and hard-fail (via
+ * `MigrationHashMismatchError`) if they differ — migrations and seeds are
+ * immutable once applied.
+ *
+ * ### Atomicity
+ *
+ * Each pending file runs inside its own transaction with
+ * `statement_timeout = 0` (migrations / seeds can legitimately take
+ * minutes — e.g. building large indexes — and we don't want the data-
+ * package's default 10-second cap killing them mid-flight). On any
+ * exception the transaction rolls back, the tracking-row is NOT inserted,
+ * and the runner re-throws so the operator sees the failing file.
+ */
+import type { RunResult, RunOptions, StatusEntry } from '../types.js';
+/**
+ * Options for the shared SQL-file runner. Both `runMigrations(config)` and
+ * `runSeeds(opts)` shape themselves into this struct.
+ */
+export interface RunSqlFilesOptions extends RunOptions {
+    /** Absolute or cwd-relative path to a directory of `*.sql` files. */
+    dir: string;
+    /**
+     * Name of the tracking table to use. Must match
+     * `/^[A-Za-z_][A-Za-z0-9_]*$/` (this name is interpolated into raw SQL —
+     * Postgres doesn't allow parameterized identifiers — so we restrict it
+     * to a conservative whitelist that makes injection structurally
+     * impossible).
+     */
+    trackingTable: string;
+}
+/**
+ * Apply pending `.sql` files in `opts.dir`, tracked in `opts.trackingTable`.
+ *
+ * Returns `{ applied, skipped }` — both arrays of file basenames, in
+ * filesystem order. A file lands in `skipped` when its tracking row
+ * already exists AND its current hash matches the stored hash.
+ *
+ * Throws `MigrationHashMismatchError` if any already-applied file has
+ * been edited.
+ */
+export declare function runSqlFiles(opts: RunSqlFilesOptions): Promise<RunResult>;
+/**
+ * Read-only counterpart of `runSqlFiles`. Returns one entry per `.sql` file
+ * in `opts.dir`, with `applied` true for files that have a matching
+ * tracking row.
+ *
+ * Files whose tracking row is hash-mismatched are reported with
+ * `applied: false` (so the operator sees them as "pending again") — this
+ * is a status query and shouldn't throw.
+ */
+export declare function getSqlFilesStatus(opts: RunSqlFilesOptions): Promise<StatusEntry[]>;
+//# sourceMappingURL=custom.d.ts.map

package/dist/migrations/runners/custom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../../src/migrations/runners/custom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AASH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAgBD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,CA8B9E;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,WAAW,EAAE,CAAC,CAcxB"}