llm.txthome

Migrations

Lucent uses schema-diff migrations derived from your collection definitions.

That makes migrations convenient, but you should treat them as an operator workflow, not magic.

What Lucent Does

Lucent can:

  • create missing system tables
  • create new collection tables
  • add new columns
  • rename columns when previousName is used
  • create indexes and constraints derived from field config
  • optionally drop orphaned columns and tables when dropOrphaned: true

What Lucent Does Not Do Yet

Lucent does not currently provide:

  • rollback support
  • custom JS/TS migration functions
  • first-class data migrations

Treat migrations as forward-only unless your deployment process provides its own database rollback strategy.

Automatic Migrations

When Lucent boots, it runs migrations before serving requests.

That is convenient in development, but for production deployments you should know exactly what will run.

Manual Migrations

Apply migrations:

lucent migrate

Preview them first:

lucent migrate --dry-run

The dry run returns planned steps without applying DDL.

Configuration

export default defineLucentConfig({
  migration: {
    warnings: "development",
    dropOrphaned: false,
  },
});

warnings

  • "development": show orphan warnings only outside production
  • "always": always show warnings
  • "never": suppress warnings

dropOrphaned

When true, Lucent will drop columns and tables that still exist in the database but no longer exist in config.

This is destructive. Keep it disabled unless you have reviewed the change and have a rollback plan outside Lucent.

Migration Result

Programmatic migration runs return:

{
  success: boolean;
  dryRun: boolean;
  applied: string[];
  planned: string[];
  statements: string[];
  warnings: string[];
  errors: string[];
}

Interpretation:

  • applied: human-readable steps that were actually executed
  • planned: human-readable steps that would run in a dry run
  • statements: raw DDL/queries generated for the migration plan
  • warnings: operator warnings, mainly around orphaned objects
  1. Run lucent migrate --dry-run
  2. Review warnings and destructive config such as dropOrphaned
  3. Take or verify a database backup
  4. Run lucent migrate
  5. Start or restart the app

Supported Adapters

  • PostgreSQL
  • SurrealDB

PostgreSQL is the primary production path. If you depend on SurrealDB-specific behavior, test it explicitly in your own deployment flow.