Skip to main content

Experimental — Generate migrations from models

Warning: This feature is experimental. Review and test generated SQL before using in production. Warning: This feature is not supported for sqlite.

The generate:migrations command inspects your live database schema and your registered models, computes a diff, and writes a migration file containing SQL statements to reconcile them.

Usage​

npx hysteria generate:migrations \
  --datasource ./database/index.ts \
  --tsconfig ./tsconfig.json \
  --migration-path ./database/migrations \
  --name add_user_fields \
  --dry

Options​

  • -d, --datasource [path] — Path to a file exporting a default sql instance. Required.
  • -c, --tsconfig [tsconfigPath] — Path to tsconfig.json to load TypeScript files. Defaults to ./tsconfig.json.
  • -m, --migration-path [path] — Output directory for migration files. Defaults to ./database/migrations.
  • -n, --name [name] — Base name for the migration. A millisecond timestamp is prefixed automatically.
  • -j, --javascript — Generate a JavaScript migration file instead of TypeScript.
  • -f, --dry — Does not create a migration file but only outputs sql statements.

Behavior​

  • If no differences are detected, the command logs: No new changes detected between database schema and models metadata and exits with code 0.
  • On differences, a file named like <timestamp>(_auto_generated_migration|{name}).(ts|js) is created with this.schema.rawQuery(...) statements for the detected changes.
  • The output directory is created if it does not exist.

Destructive operations (drops)​

  • The generator may emit drops for foreign keys, indexes, unique constraints, and columns when required to align with the models.
  • Tables are never auto-dropped. If you need to remove a table, write a manual migration to drop it. This avoids accidental data loss and to never delete ad hoc tables that are not part of the models.

Caveats​

  • Always review generated SQL. Some databases/drivers normalize types (e.g., floating precision, text families), which may affect diffs.
  • Run the generated migration in a safe environment first. Back up your database and test rollbacks as needed.
  • Ensure the sql instance passed via --datasource is fully configured for the target environment and registers your models.
  • SQLite has some limitations due to its limited alter table capabilities and it's not recommended to use this feature with sqlite
  • Crucial or complex operations should be done manually, this is intended as a tool to help you generate the SQL statements for your migrations in a standard way but it's not suggested to use it as a full replacement for manual migrations.

Using @column for Schema Metadata​

To make your model's intended database schema explicit and help the migration generator produce accurate diffs, use the @column decorator on your model properties. This decorator lets you specify database metadata such as default values and nullable status directly on your model fields.

!! Columns without the type option will be ignored for auto-generated migrations !!

Example:

@column({ type: "varchar", default: "active", nullable: false })
declare status: string;

@column({ type: "text", nullable: true })
declare description: string | null;

This metadata is used by the migration generator to compare your model definitions with the live database schema and generate the correct SQL statements for changes.