@remix-run/data-table 0.2.1 → 0.4.0

package/README.md

@@ -4,13 +4,14 @@ Typed relational query toolkit for JavaScript runtimes.
 
 ## Features
 
-- **One API Across Databases**: Same query and relation APIs across PostgreSQL, MySQL, and SQLite adapters
+- **One API Across Databases**: Same query and relation APIs across PostgreSQL, MySQL, and SQLite
 - **One Query API**: Build reusable `Query` objects with `query(table)` and execute them with `db.exec(...)`, or use `db.query(table)` as shorthand
 - **Type-Safe Reads**: Typed `select`, relation loading, and predicate keys
 - **Optional Runtime Validation**: Add `validate(context)` at the table level for create/update validation and coercion
 - **Relation-First Queries**: `hasMany`, `hasOne`, `belongsTo`, `hasManyThrough`, and nested eager loading
 - **Safe Scoped Writes**: `update`/`delete` with `orderBy`/`limit` run safely in a transaction
-- **First-Class Migrations**: Up/down migrations with schema builders, runner controls, and dry-run planning
+- **First-Class Migrations**: Plain SQL `up.sql`/`down.sql` files with a journaling runner and dry-run planning
+- **Database Lifecycle Commands**: Wipe, migrate, inspect, seed, and reset through `remix db`
 - **Raw SQL Escape Hatch**: Execute SQL directly with `db.exec(sql\`...\`)`
 
 `data-table` gives you two complementary APIs:
@@ -33,12 +34,11 @@ npm i mysql2
 
 ## Setup
 
-Define tables once, then create a database with an adapter.
+Define tables once, then create a database for your SQL dialect.
 
 ```ts
-import { Pool } from 'pg'
-import { column as c, createDatabase, hasMany, query, table } from 'remix/data-table'
-import { createPostgresDatabaseAdapter } from 'remix/data-table-postgres'
+import { column as c, hasMany, query, table } from 'remix/data-table'
+import { createPostgresDatabase } from 'remix/data-table/postgres'
 
 let users = table({
   name: 'users',
@@ -63,8 +63,7 @@ let orders = table({
 
 let userOrders = hasMany(users, orders)
 
-let pool = new Pool({ connectionString: process.env.DATABASE_URL })
-let db = createDatabase(createPostgresDatabaseAdapter(pool))
+let db = createPostgresDatabase({ connectionString: process.env.DATABASE_URL })
 ```
 
 ## Query Objects
@@ -201,7 +200,7 @@ let createManyResult = await db.createMany(orders, [
   { id: 'o_102', user_id: 'u_003', status: 'pending', total: 48.5, created_at: Date.now() },
 ])
 
-// Return inserted rows (requires adapter RETURNING support)
+// Return inserted rows (requires database RETURNING support)
 let insertedRows = await db.createMany(
   orders,
   [{ id: 'o_103', user_id: 'u_003', status: 'pending', total: 12, created_at: Date.now() }],
@@ -249,8 +248,7 @@ Return behavior:
 
 ### Validation and Lifecycle
 
-Validation is optional and table-scoped. Define `validate(context)` to validate/coerce write
-payloads, and add lifecycle callbacks when you need custom read/write/delete behavior.
+Validation is optional and table-scoped. Define `validate(context)` to validate/coerce write payloads, and add lifecycle callbacks when you need custom read/write/delete behavior.
 
 ```ts
 import { column as c, fail, table } from 'remix/data-table'
@@ -344,11 +342,7 @@ await db.transaction(async (tx) => {
 
 ## Migrations
 
-`data-table` includes a first-class migration system under `remix/data-table/migrations`.
-Migrations are adapter-driven: adapters execute SQL for their dialect/runtime, and SQL compilation
-is handled by adapter-owned compilers (with optional shared pure helpers from `data-table`).
-For adapter authors (including third-party adapters), shared SQL helper utilities are available at
-`remix/data-table/sql-helpers`.
+`data-table` ships a SQL-first migration system under `remix/data-table/migrations`. Each migration is a directory containing hand-written `up.sql` and (optionally) `down.sql`. The runner journals applied migrations, detects checksum drift and missing applied migrations, and wraps each migration in a transaction when the database supports transactional DDL.
 
 ### Example Setup
 
@@ -356,159 +350,187 @@ For adapter authors (including third-party adapters), shared SQL helper utilitie
 app/
   db/
     migrations/
-      20260228090000_create_users.ts
-      20260301113000_add_user_status.ts
-    migrate.ts
+      20260228090000_create_users/
+        up.sql
+        down.sql
+      20260301113000_add_user_status/
+        up.sql
+        down.sql
+  db.ts
 ```
 
-- Keep migration files in one directory (for example `app/db/migrations`).
-- Name each file as `YYYYMMDDHHmmss_name.ts` (or `.js`, `.mjs`, `.cjs`, `.cts`).
-- Each file must `default` export `createMigration(...)`; `id` and `name` are inferred from filename.
+- Keep migration directories in one parent directory (for example `app/db/migrations`).
+- Each directory is named `YYYYMMDDHHmmss_<slug>`.
+- `up.sql` is required. `down.sql` is optional (omit for irreversible migrations).
+- Scripts may contain multiple statements. `id` and `name` are inferred from the directory name.
 
 ### Migration File Example
 
-```ts
-import { column as c, table } from 'remix/data-table'
-import { createMigration } from 'remix/data-table/migrations'
+`20260228090000_create_users/up.sql`:
 
-let users = table({
-  name: 'users',
-  columns: {
-    id: c.integer().primaryKey(),
-    email: c.varchar(255).notNull().unique(),
-    created_at: c.timestamp({ withTimezone: true }).defaultNow(),
-  },
-})
+```sql
+create table users (
+  id serial primary key,
+  email varchar(255) not null unique,
+  created_at timestamptz not null default now()
+);
 
-export default createMigration({
-  async up({ db, schema }) {
-    await schema.createTable(users)
-    await schema.createIndex(users, 'email', { unique: true })
+create unique index users_email_idx on users (email);
+```
 
-    if (db.adapter.dialect === 'sqlite') {
-      await db.exec('pragma foreign_keys = on')
-    }
-  },
-  async down({ schema }) {
-    await schema.dropTable(users, { ifExists: true })
-  },
-})
+`20260228090000_create_users/down.sql`:
+
+```sql
+drop index if exists users_email_idx;
+drop table if exists users;
 ```
 
-### Runner Script Example
+### Multi-Statement Driver Configuration
 
-In `app/db/migrate.ts`:
+The runner sends each migration to the database as a single multi-statement script. Make sure the underlying driver accepts multiple statements:
 
-```ts
-import path from 'node:path'
-import { Pool } from 'pg'
-import { createPostgresDatabaseAdapter } from 'remix/data-table-postgres'
-import { createMigrationRunner } from 'remix/data-table/migrations'
-import { loadMigrations } from 'remix/data-table/migrations/node'
+- `better-sqlite3`: works out of the box (`db.exec`).
+- `pg`: works out of the box when no parameter array is passed.
+- `mysql2`: requires `multipleStatements: true` on the connection/pool.
 
-let directionArg = process.argv[2] ?? 'up'
-let direction = directionArg === 'down' ? 'down' : 'up'
-let to = process.argv[3]
+```ts
+import { createMysqlDatabase } from 'remix/data-table/mysql'
 
-let pool = new Pool({ connectionString: process.env.DATABASE_URL })
-let adapter = createPostgresDatabaseAdapter(pool)
-let migrations = await loadMigrations(path.resolve('app/db/migrations'))
-let runner = createMigrationRunner(adapter, migrations)
+let db = createMysqlDatabase({
+  uri: process.env.DATABASE_URL,
+  multipleStatements: true,
+})
+```
 
-try {
-  let result = direction === 'up' ? await runner.up({ to }) : await runner.down({ to })
-  console.log(direction + ' complete', {
-    applied: result.applied.map((entry) => entry.id),
-    reverted: result.reverted.map((entry) => entry.id),
-  })
-} finally {
-  await pool.end()
+### Database Command Configuration
+
+Configure `remix db` statically in `remix.json`. Connection secrets are read from the named
+environment variable at command runtime, and paths are resolved relative to `remix.json`:
+
+```jsonc
+{
+  "$schema": "https://remix.run/schemas/remix.json",
+  "db": {
+    "adapter": {
+      "type": "postgres",
+      "connectionString": { "env": "DATABASE_URL" },
+    },
+    "migrations": {
+      "directory": "./db/migrations",
+      "journalTable": "app_migrations",
+    },
+    "seed": "./db/seed.sql",
+  },
 }
 ```
 
-Use `journalTable` if you want a custom migrations journal table name:
+Application runtime setup remains application-owned. It does not need to expose any special
+exports for the CLI.
 
-```ts
-let runner = createMigrationRunner(adapter, migrations, {
-  journalTable: 'app_migrations',
-})
-```
-
-Run it with your runtime, for example:
+Run lifecycle commands through the Remix CLI:
 
 ```sh
-node ./app/db/migrate.ts up
-node ./app/db/migrate.ts up 20260301113000
-node ./app/db/migrate.ts down
-node ./app/db/migrate.ts down 20260228090000
+remix db status
+remix db migrate
+remix db migrate --to 20260301113000_add_user_status
+remix db seed
+remix db reset
+remix db wipe
 ```
 
-Use `step` when you want bounded rollforward/rollback behavior instead of a target id:
+`--to` accepts a bare migration id (`20260301113000`) or the full directory name (`20260301113000_add_user_status`).
+
+`remix db status` reports applied migrations whose files are no longer present as `missing`. If the journal table does not exist, it reports every migration as pending without creating the table. Forward migration runs stop before executing SQL when an applied journal entry is missing from the current migration set. Rollbacks skip those orphaned journal entries so migrations that are still present can be reverted.
+
+`wipe` and `reset` are destructive. They require a config-backed database so it can close, recreate, and reconnect to the configured database.
+
+### Programmatic Migrations
+
+Load migrations and pass the resolved collection directly to the database:
 
 ```ts
-await runner.up({ step: 1 })
-await runner.down({ step: 1 })
-```
+import { loadMigrations } from 'remix/data-table/migrations/node'
 
-`to` and `step` are mutually exclusive. Use one or the other for a given run.
+let migrations = await loadMigrations('./db/migrations')
+await db.migrate(migrations)
+```
 
-Use `dryRun` to compile and inspect the SQL plan without applying migrations:
+`Database.migrate()` supports forward and backward directions, a target or step bound, dry runs,
+and a custom journal table:
 
 ```ts
-let dryRunResult = await runner.up({ dryRun: true })
-console.log(dryRunResult.sql)
+await db.migrate(migrations)
+await db.migrate(migrations, { to: '20260301113000_add_user_status' })
+await db.migrate(migrations, { step: 1 })
+await db.migrate(migrations, { direction: 'down' })
+await db.migrate(migrations, { direction: 'down', to: '20260301113000' })
+await db.migrate(migrations, { direction: 'down', step: 1 })
+await db.migrate(migrations, { journalTable: 'app_migrations' })
+
+let plan = await db.migrate(migrations, { dryRun: true })
+for (let script of plan.sql) console.log(script)
 ```
 
-When migration transactions are enabled, migration-time `schema.createTable(...)`, `db.exec(...)`,
-query-builder data operations, and `schema.hasTable(...)` / `schema.hasColumn(...)` all run in the same
-adapter transaction context.
+`to` and `step` are mutually exclusive. Omit `journalTable` to use `data_table_migrations`.
 
-You can also pass a pre-built SQL statement into `schema.plan(...)` when authoring migrations:
+Database drivers with migration locking run the complete migration and journal lifecycle through the
+connection that owns the lock. This keeps advisory locks correctly paired when the driver uses a
+connection pool, including pools configured with a single connection.
+
+Read status separately, or rebuild a database with migrations and an optional seed. A seed is a
+function that receives the database; `loadSeed()` builds one from a SQL file:
 
 ```ts
-import { sql } from 'remix/data-table'
+import { loadSeed } from 'remix/data-table/migrations/node'
+
+let seed = await loadSeed('./db/seed.sql')
 
-await schema.plan(sql`update users set status = ${'active'} where status is null`)
+let status = await db.migrationStatus(migrations, { journalTable: 'app_migrations' })
+await db.reset({ migrations })
+await db.reset({ migrations, seed })
+await db.reset({ migrations, seed, journalTable: 'app_migrations' })
 ```
 
-You can run lightweight schema checks inside a migration with `schema.hasTable(...)` and
-`schema.hasColumn(...)` when you need defensive conditional behavior. Methods that take a table name
-accept either a string (`'app.users'`) or a `table(...)` object.
+When a lifecycle command is the last thing a process does, close database-owned connections so
+the process can exit:
 
-In `dryRun` mode, introspection methods still check the live database state. They do not simulate
-tables/columns from pending operations in the current dry-run plan.
+```ts
+await db.close()
+```
 
-For key-oriented migration APIs, single-column and compound forms are both supported:
+### Transaction Modes
 
-```ts
-await schema.alterTable(users, (table) => {
-  table.addPrimaryKey('id')
-  table.addForeignKey('account_id', 'accounts', 'id')
-  table.addForeignKey(['tenant_id', 'account_id'], 'accounts', ['tenant_id', 'id'])
-})
+By default each migration is wrapped in a transaction when the database supports transactional DDL. Override per migration with a directive on the first non-blank line of `up.sql`:
+
+```sql
+-- data-table/transaction: none
+create index concurrently users_email_active_idx on users (email) where status = 'active';
 ```
 
-Constraint and index names are optional in migration APIs. When omitted, `data-table` generates
-deterministic names for primary keys, uniques, foreign keys, checks, and indexes.
+Supported modes:
+
+- `auto` (default): wrap when the database supports transactional DDL.
+- `required`: wrap; the runner throws if the database cannot support it.
+- `none`: never wrap. Use this for statements like postgres `CREATE INDEX CONCURRENTLY` that cannot run inside a transaction.
 
-This is useful when you want to:
+You can also set `transaction` directly on a `MigrationDescriptor` when registering migrations programmatically.
 
-- Review generated SQL in CI before deploying
-- Verify migration ordering and target/step selection
-- Audit dialect-specific SQL differences across adapters
+### Programmatic Registration
 
-For non-filesystem runtimes, register migrations manually:
+For non-filesystem runtimes, register migrations directly:
 
 ```ts
-import { createMigrationRegistry, createMigrationRunner } from 'remix/data-table/migrations'
-import createUsers from './db/migrations/20260228090000_create_users.ts'
+import { createMigrationRegistry } from 'remix/data-table/migrations'
 
 let registry = createMigrationRegistry()
-registry.register({ id: '20260228090000', name: 'create_users', migration: createUsers })
+registry.register({
+  id: '20260228090000',
+  name: 'create_users',
+  up: 'create table users (id serial primary key, email text not null);',
+  down: 'drop table users;',
+})
 
-// adapter from createPostgresDatabaseAdapter/createMysqlDatabaseAdapter/createSqliteDatabaseAdapter
-let runner = createMigrationRunner(adapter, registry)
-await runner.up()
+await db.migrate(registry)
 ```
 
 ## Raw SQL Escape Hatch
@@ -536,14 +558,120 @@ let result = await db.exec(sql`
 `)
 ```
 
-`sql` keeps values parameterized per adapter dialect, so you can avoid manual string concatenation.
+`sql` keeps values parameterized for the database dialect, so you can avoid manual string concatenation.
+
+## Custom Database Drivers
+
+Applications normally use one of the concrete SQLite, PostgreSQL, or MySQL factories. Integration
+packages can add another dialect by implementing `DatabaseDriver` and extending `Database`. This
+complete skeleton assumes the underlying client exposes the operations needed by the driver:
+
+```ts
+import {
+  Database,
+  type DatabaseDriver,
+  type DataManipulationRequest,
+  type DataManipulationResult,
+  type DatabaseOptions,
+  type TableRef,
+  type TransactionOptions,
+  type TransactionToken,
+} from 'remix/data-table'
+import type { AcmeClient } from 'acme-database'
+
+class AcmeDriver implements DatabaseDriver<'acme'> {
+  readonly dialect = 'acme'
+  readonly capabilities = {
+    returning: true,
+    savepoints: true,
+    upsert: true,
+    transactionalDdl: true,
+    migrationLock: false,
+  } as const
+
+  #client: AcmeClient
+
+  constructor(client: AcmeClient) {
+    this.#client = client
+  }
+
+  execute(request: DataManipulationRequest): Promise<DataManipulationResult> {
+    return this.#client.execute(request)
+  }
+
+  executeScript(sql: string, transaction?: TransactionToken): Promise<void> {
+    return this.#client.executeScript(sql, transaction)
+  }
+
+  beginTransaction(options?: TransactionOptions): Promise<TransactionToken> {
+    return this.#client.beginTransaction(options)
+  }
+
+  commitTransaction(transaction: TransactionToken): Promise<void> {
+    return this.#client.commitTransaction(transaction)
+  }
+
+  rollbackTransaction(transaction: TransactionToken): Promise<void> {
+    return this.#client.rollbackTransaction(transaction)
+  }
+
+  hasTable(table: TableRef, transaction?: TransactionToken): Promise<boolean> {
+    return this.#client.hasTable(table, transaction)
+  }
+
+  hasColumn(table: TableRef, column: string, transaction?: TransactionToken): Promise<boolean> {
+    return this.#client.hasColumn(table, column, transaction)
+  }
+
+  createSavepoint(transaction: TransactionToken, name: string): Promise<void> {
+    return this.#client.createSavepoint(transaction, name)
+  }
+
+  rollbackToSavepoint(transaction: TransactionToken, name: string): Promise<void> {
+    return this.#client.rollbackToSavepoint(transaction, name)
+  }
+
+  releaseSavepoint(transaction: TransactionToken, name: string): Promise<void> {
+    return this.#client.releaseSavepoint(transaction, name)
+  }
+
+  wipe(): Promise<void> {
+    return this.#client.wipe()
+  }
+
+  close(): void | Promise<void> {
+    return this.#client.close()
+  }
+}
+
+export class AcmeDatabase extends Database<'acme'> {
+  constructor(client: AcmeClient, options?: DatabaseOptions) {
+    super(new AcmeDriver(client), options)
+  }
+}
+```
+
+`Database` supplies queries, CRUD helpers, relations, transactions, and migrations. The private
+driver owns SQL execution and connection lifecycle. A driver provides:
+
+- `dialect` and an immutable `capabilities` object
+- `execute()` and `executeScript()`
+- `hasTable()`, `hasColumn()`, `wipe()`, and idempotent `close()`
+- transaction and savepoint lifecycle methods using opaque `TransactionToken` values
+
+Drivers whose capabilities report `migrationLock: true` also implement `withMigrationLock()` and
+run its callback with a `DatabaseDriver` bound to the connection that owns the lock.
+
+`Database`, `DatabaseDriver`, and the supporting driver protocol types are all exported directly
+from `remix/data-table`. Transaction callbacks receive a transaction-scoped `Database`, so custom
+subclass methods are intentionally unavailable inside the callback.
 
 ## Related Packages
 
 - [`data-schema`](https://github.com/remix-run/remix/tree/main/packages/data-schema) - Optional schema parsing you can use inside table-level `validate(...)` hooks
-- [`data-table-postgres`](https://github.com/remix-run/remix/tree/main/packages/data-table-postgres) - PostgreSQL adapter
-- [`data-table-mysql`](https://github.com/remix-run/remix/tree/main/packages/data-table-mysql) - MySQL adapter
-- [`data-table-sqlite`](https://github.com/remix-run/remix/tree/main/packages/data-table-sqlite) - SQLite adapter
+- [`data-table-postgres`](https://github.com/remix-run/remix/tree/main/packages/data-table-postgres) - PostgreSQL database integration
+- [`data-table-mysql`](https://github.com/remix-run/remix/tree/main/packages/data-table-mysql) - MySQL database integration
+- [`data-table-sqlite`](https://github.com/remix-run/remix/tree/main/packages/data-table-sqlite) - SQLite database integration
 
 ## License
 

package/dist/cli.d.ts

@@ -0,0 +1,54 @@
+import type { Database } from './lib/database.ts';
+import type { Migrations, Seed } from './lib/migrations.ts';
+interface DatabaseCommandOptions {
+    /** Database instance used by the command. */
+    db: Database;
+}
+/** Structured invocation options accepted by {@link runRemixDb}. */
+export type RunRemixDbOptions = (DatabaseCommandOptions & {
+    /** Applies pending migrations. */
+    command: 'migrate';
+    /** Migrations to apply. */
+    migrations: Migrations;
+    /**
+     * Stops after applying this migration. Accepts a bare migration id or
+     * the full `id_name` directory form.
+     */
+    to?: string;
+    /** Migration journal table. */
+    journalTable?: string;
+}) | (DatabaseCommandOptions & {
+    /** Wipes, migrates, and optionally seeds the database. */
+    command: 'reset';
+    /** Migrations to apply after wiping the database. */
+    migrations: Migrations;
+    /** Initializes database data after migrations finish. */
+    seed?: Seed;
+    /** Migration journal table. */
+    journalTable?: string;
+}) | (DatabaseCommandOptions & {
+    /** Runs the application's seed function. */
+    command: 'seed';
+    /** Initializes application database data. */
+    seed: Seed;
+}) | (DatabaseCommandOptions & {
+    /** Reports the status of known migrations. */
+    command: 'status';
+    /** Migrations to inspect. */
+    migrations: Migrations;
+    /** Migration journal table. */
+    journalTable?: string;
+}) | (DatabaseCommandOptions & {
+    /** Destructively recreates the configured database. */
+    command: 'wipe';
+});
+/**
+ * Runs a data-table database command from structured invocation options.
+ *
+ * @param options Database command and application database values.
+ * @returns The exit code the host CLI should use. Always resolves `0`;
+ * command failures throw.
+ */
+export declare function runRemixDb(options: RunRemixDbOptions): Promise<number>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAA;AAE3D,UAAU,sBAAsB;IAC9B,6CAA6C;IAC7C,EAAE,EAAE,QAAQ,CAAA;CACb;AAED,oEAAoE;AACpE,MAAM,MAAM,iBAAiB,GACzB,CAAC,sBAAsB,GAAG;IACxB,kCAAkC;IAClC,OAAO,EAAE,SAAS,CAAA;IAClB,2BAA2B;IAC3B,UAAU,EAAE,UAAU,CAAA;IACtB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAC,GACF,CAAC,sBAAsB,GAAG;IACxB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAA;IAChB,qDAAqD;IACrD,UAAU,EAAE,UAAU,CAAA;IACtB,yDAAyD;IACzD,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAC,GACF,CAAC,sBAAsB,GAAG;IACxB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,IAAI,EAAE,IAAI,CAAA;CACX,CAAC,GACF,CAAC,sBAAsB,GAAG;IACxB,8CAA8C;IAC9C,OAAO,EAAE,QAAQ,CAAA;IACjB,6BAA6B;IAC7B,UAAU,EAAE,UAAU,CAAA;IACtB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAC,GACF,CAAC,sBAAsB,GAAG;IACxB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAA;CAChB,CAAC,CAAA;AAEN;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4D5E"}

package/dist/cli.js

@@ -0,0 +1,53 @@
+/**
+ * Runs a data-table database command from structured invocation options.
+ *
+ * @param options Database command and application database values.
+ * @returns The exit code the host CLI should use. Always resolves `0`;
+ * command failures throw.
+ */
+export async function runRemixDb(options) {
+    if (options.command === 'migrate') {
+        let migrateOptions = options.to === undefined
+            ? { journalTable: options.journalTable }
+            : { to: options.to, journalTable: options.journalTable };
+        let result = await options.db.migrate(options.migrations, migrateOptions);
+        if (result.applied.length === 0) {
+            console.log('no pending migrations');
+        }
+        for (let entry of result.applied) {
+            console.log('applied ' + entry.id + '_' + entry.name);
+        }
+        return 0;
+    }
+    if (options.command === 'reset') {
+        await options.db.reset({
+            migrations: options.migrations,
+            seed: options.seed,
+            journalTable: options.journalTable,
+        });
+        console.log('database reset');
+        return 0;
+    }
+    if (options.command === 'seed') {
+        await options.seed(options.db);
+        console.log('database seeded');
+        return 0;
+    }
+    if (options.command === 'status') {
+        let entries = await options.db.migrationStatus(options.migrations, {
+            journalTable: options.journalTable,
+        });
+        for (let entry of entries) {
+            console.log(entry.id + ' ' + entry.name + ' ' + entry.status);
+        }
+        return 0;
+    }
+    if (options.command === 'wipe') {
+        await options.db.wipe();
+        return 0;
+    }
+    // Guard against unchecked command strings from plain-JS callers so an
+    // unknown command can never fall through to a destructive operation.
+    let command = options.command;
+    throw new Error('Unknown database command: ' + command);
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { AdapterCapabilityOverrides, AdapterCapabilities, DataManipulationRequest, DataMigrationRequest, AddCheckChange, AddCheckOperation, AddColumnChange, AddForeignKeyChange, AddForeignKeyOperation, AddPrimaryKeyChange, AddUniqueChange, AlterTableChange, AlterTableOperation, ChangeColumnChange, CheckConstraint, ColumnCheck, ColumnComputed, ColumnDefault, ColumnDefinition, ColumnTypeName, CountOperation, CreateIndexOperation, CreateTableOperation, DataMigrationResult, DataMigrationOperation, DataManipulationResult, DataManipulationOperation, DeleteOperation, DatabaseAdapter, DropCheckChange, DropCheckOperation, DropColumnChange, DropForeignKeyChange, DropForeignKeyOperation, DropIndexOperation, DropPrimaryKeyChange, DropTableOperation, DropUniqueChange, ExistsOperation, ForeignKeyAction, ForeignKeyConstraint, IndexDefinition, IndexMethod, InsertManyOperation, InsertOperation, JoinClause, JoinType, PrimaryKeyConstraint, RawOperation, RenameColumnChange, RenameIndexOperation, RenameTableOperation, ReturningSelection, SelectColumn, SelectOperation, SetTableCommentChange, TableRef, TransactionOptions, TransactionToken, UniqueConstraint, UpdateOperation, UpsertOperation, } from './lib/adapter.ts';
-export { DataTableAdapterError, DataTableConstraintError, DataTableError, DataTableQueryError, DataTableValidationError, } from './lib/errors.ts';
+export type { DatabaseCapabilities, DatabaseDriver, DataManipulationOperation, DataManipulationRequest, ColumnCheck, ColumnComputed, ColumnDefault, ColumnDefinition, ColumnTypeName, DataManipulationResult, ForeignKeyAction, IdentityOptions, TableRef, TransactionOptions, TransactionToken, } from './lib/driver.ts';
+export { DataTableDatabaseError, DataTableConstraintError, DataTableError, DataTableQueryError, DataTableValidationError, } from './lib/errors.ts';
 export type { AnyRelation, AnyColumn, AnyTable, BelongsToOptions, ColumnReference, ColumnReferenceForQualifiedName, HasManyOptions, HasManyThroughOptions, HasOneOptions, KeySelector, OrderByClause, OrderDirection, PrimaryKeyInput, Relation, RelationCardinality, RelationKind, RelationMapForTable, Table, TableAfterDelete, TableAfterDeleteContext, TableAfterRead, TableAfterReadContext, TableAfterReadResult, TableAfterWrite, TableAfterWriteContext, TableBeforeDelete, TableBeforeDeleteContext, TableBeforeDeleteResult, TableBeforeWrite, TableBeforeWriteContext, TableBeforeWriteResult, TableColumnInput, TableColumnName, TableColumns, TableLifecycleOperation, TableName, TablePrimaryKey, TableReference, TableRow, TableRowWith, TableColumnsDefinition, TableValidate, TableValidationContext, TableWriteOperation, TableValidationOperation, TableValidationResult, TimestampConfig, TimestampOptions, ValidationFailure, ValidationIssue, } from './lib/table.ts';
 export { belongsTo, columnMetadataKey, fail, getTableColumns, getTableColumnDefinitions, getTableBeforeDelete, getTableBeforeWrite, getTableAfterDelete, getTableAfterRead, getTableAfterWrite, getTableName, getTablePrimaryKey, getTableReference, getTableTimestamps, getTableValidator, hasMany, hasManyThrough, hasOne, table, tableMetadataKey, timestamps, } from './lib/table.ts';
 export type { ColumnNamespace } from './lib/column.ts';
@@ -8,8 +8,9 @@ export type { Predicate, WhereInput, WhereObject } from './lib/operators.ts';
 export { and, between, eq, gt, gte, ilike, inList, isNull, like, lt, lte, ne, notInList, notNull, or, } from './lib/operators.ts';
 export type { SqlStatement } from './lib/sql.ts';
 export { rawSql, sql } from './lib/sql.ts';
-export type { CountOptions, CreateManyResultOptions, CreateManyRowsOptions, CreateResultOptions, CreateRowOptions, DeleteManyOptions, FindManyOptions, FindOneOptions, OrderByInput, OrderByTuple, QueryColumnTypesForTable, QueryForTable, QueryTableInput, SingleTableColumn, SingleTableWhere, UpdateManyOptions, UpdateOptions, WriteResult, WriteRowResult, WriteRowsResult, } from './lib/database.ts';
-export { createDatabase, Database } from './lib/database.ts';
+export type { CountOptions, CreateManyResultOptions, CreateManyRowsOptions, CreateResultOptions, CreateRowOptions, DeleteManyOptions, DatabaseOptions, FindManyOptions, FindOneOptions, OrderByInput, OrderByTuple, QueryColumnTypesForTable, QueryForTable, QueryTableInput, SingleTableColumn, SingleTableWhere, UpdateManyOptions, UpdateOptions, WriteResult, WriteRowResult, WriteRowsResult, } from './lib/database.ts';
+export { Database } from './lib/database.ts';
+export type { DatabaseMigrateOptions, DatabaseMigrationStatusOptions, DatabaseResetOptions, MigrateResult, MigrationDescriptor, MigrationRegistry, Migrations, MigrationStatus, MigrationStatusEntry, Seed, } from './lib/migrations.ts';
 export type { AnyQuery } from './lib/query.ts';
 export { Query, query } from './lib/query.ts';
 //# 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":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}