Summary

Make remix.json the sole configuration contract for remix db. Repeatable database settings should be statically analyzable, explicit command-line input should remain authoritative, and the command should construct the configured database without discovering or inspecting application modules.

At the same time, simplify the programmatic database surface: runRemixDb() should consume resolved runtime values, while Database.migrate() should own the complete forward and rollback migration operation so callers do not need a separate public migration-runner factory.

remix.json + CLI flags
          ↓
normalized database command plan
          ↓
adapter + migrations + optional seed
          ↓
runRemixDb() → Database lifecycle APIs

Context and requirements

• remix.json must describe the database adapter and connection source, migration directory and journal table, and optional seed module using schema-validated static configuration.
• Built-in configuration must cover SQLite, PostgreSQL, and MySQL, with secrets referenced through environment-variable names rather than committed credentials.
• Custom adapters must use an explicitly configured module and database-factory export rather than module inspection.
• Database config paths must resolve relative to the selected config file; command-line path overrides must resolve relative to the invocation directory.
• remix db must work from a project subdirectory by finding the nearest remix.json, while an explicit global --config path remains authoritative.
• CLI flags must override overlapping remix.json values. Invocation-only controls such as --to and --force must not become persistent configuration defaults.
• Destructive CLI commands must continue requiring an explicit --force; programmatic runRemixDb() calls do not accept force because choosing the destructive command is already explicit authorization.
• The command executor must load migrations only for commands that use them and load seed code only for seed and reset.
• runRemixDb() must accept a discriminated command union containing resolved Database, Migrations, and Seed values rather than configuration paths or lazy module-discovery callbacks.
• Programmatic migration calls must support applying all pending migrations, targeting a migration, and selecting a journal table; reset calls must support migrations with an optional seed and journal table.
• Database.migrate() must support forward and backward directions, mutually exclusive to and step bounds, dry runs, and journal-table selection while continuing to return the migration result.
• Database.migrationStatus() remains the separate read operation for migration status.
• The public createMigrationRunner() and MigrationRunner surface should be removed; an internal runner may remain as the implementation behind Database.migrate() and Database.migrationStatus().
• This is a direct replacement with no fallback, deprecation window, compatibility behavior, migration warnings, or tests dedicated to a superseded application-module contract.
• Runtime application database setup remains application-owned and has no special CLI export contract.

Implementation plan

• Add schema-validated db configuration to remix.json for built-in adapters, environment-backed connections, migrations, seeds, and explicit custom database factories.
• Add database command option parsing and resolution that merges static configuration with authoritative CLI overrides and preserves destructive-command safety checks.
• Resolve the project/config root and all database paths consistently for default, subdirectory, and explicit --config invocations.
• Replace database module discovery with a normalized command plan and config-backed adapter construction.
• Load migration files and seed modules only for the commands that require them, with clear validation and runtime errors for missing or invalid configured exports.
• Redesign runRemixDb() around a discriminated union of resolved command values for migrate, reset, seed, status, and wipe.
• Fold migration direction, targets, steps, dry runs, and journal configuration into Database.migrate() and keep status on Database.migrationStatus().
• Remove the public migration-runner factory/types and keep any runner machinery implementation-only.
• Thread migration journal configuration consistently through migrate, status, and reset behavior.
• Update shell help and completion for all database flags and their command-specific availability.
• Replace database command and data-table coverage with tests of the new configuration, option precedence, adapter construction, command execution, lazy resource loading, custom factories, and migration APIs.
• Update demos and runtime setup to use explicit application-owned database and seed modules without CLI-specific exports.
• Update CLI, data-table, adapter, and aggregate Remix documentation and examples to describe only the new configuration and programmatic APIs.
• Add the required package change files for every affected published package and ensure generated aggregate exports remain synchronized.

Required gates

• pnpm run validate-package-meta passes.
• pnpm run lint and pnpm run format:check pass.
• Focused CLI, data-table, SQLite, PostgreSQL, and MySQL package tests, typechecks, and builds pass where affected.
• pnpm run test:changed and pnpm run typecheck:changed pass during development.
• Full pnpm test and pnpm run typecheck pass because this changes shared public APIs and cross-workspace CLI behavior.
• CLI help and shell completion expose only valid command-specific database options.
• Packed CLI, data-table, and aggregate Remix packages expose the intended new API and contain no removed public migration-runner export.