CLI commands

The package ships two executables. Run them from your package root.

Command	What it does
dart run gisila_orm:generate	Parses every schema file, writes Dart models and SQL, and writes an incremental migration when the schema changed.
dart run gisila_orm:migrate	Applies, rolls back, lists or diffs migrations against a database.

generate

dart run gisila_orm:generate [--allow-destructive]
dart run gisila_orm:generate --build-runner [build_runner flags] [--no-delete]

When to use: after every schema edit. Commit everything it writes.

What it does

1. Finds every *.gisila.yaml / *.gisila.yml under lib/, test/ and example/ (skipping .gisila/).

2. Merges them into one schema and validates it. Any error prints diagnostics and exits with code 1.

3. Writes the Dart and full-schema SQL bundle:

   Schema files	Output
   One	<stem>.gisila.g.dart, <stem>.gisila.up.sql, <stem>.gisila.down.sql beside the YAML
   Several	lib/models/schema.gisila.g.dart, .up.sql, .down.sql (created if missing; the files’ common parent when there’s no lib/)

4. Maintains incremental migrations in a migrations/ directory next to that output (for example lib/models/migrations/):

   Situation	Result
   No migration of your own exists yet in that directory or under lib/	Writes <millis>_initial_schema.up.sql / .down.sql (the schema as of the last snapshot, or the current schema on the first run).
   No snapshot yet (.gisila/schema_snapshots/project.gisila.yaml)	Writes the snapshot and stops.
   Snapshot differs from the current schema	Writes <millis>_auto_project_changes.up.sql / .down.sql from the diff, then updates the snapshot.
   No change	Updates the snapshot.

If the diff would lose data (dropped table, column or enum, or a narrowing type change), nothing is written, the snapshot stays as it was, the changes are printed and the command exits with code 1. Re-run with --allow-destructive once you’ve checked them.

Commit the .gisila/ snapshot. Without it, the next run on another machine starts a fresh snapshot instead of diffing.

Flags

Flag	Description
--allow-destructive	Write the incremental migration even if it can lose data.
--build-runner	Run dart run build_runner build instead (single-file packages only). Adds --delete-conflicting-outputs unless you pass --no-delete. Other flags are passed through.

Exit codes

Code	Meaning
0	Success.
1	Schema validation failed, the migration was refused as destructive, or code generation failed.

migrate

dart run gisila_orm:migrate up     [--dir <path>] [--config <yaml>]
dart run gisila_orm:migrate down   [--dir <path>] [--config <yaml>] [--steps N]
dart run gisila_orm:migrate status [--dir <path>] [--config <yaml>]
dart run gisila_orm:migrate diff   --old <path> --new <path> --name <slug> [--out <dir>] [--allow-destructive]

When to use: in development after generate, and in deployment before the new version of your app starts.

Connection

up, down and status load the connection with DatabaseConfig.fromEnvironment: DATABASE_URL (and DB_CONNECTIONS / DB_<NAME>_URL) win over the YAML file. If neither DATABASE_URL nor the config file exists, the command exits with code 64. Migrations run on the default connection.

Commands

Command	Description
up	Applies every pending migration found under --dir as one batch. Prints Nothing to apply. Database is up to date. or the applied ids.
down	Rolls back the last --steps batches.
status	Prints Discovered: N, applied: M and one [x] / [ ] line per migration, noting files edited after they were applied.
diff	Compares two schema files and writes a migration pair with SchemaDiffer. Doesn’t connect to a database.

up and down hold an advisory lock, so two deploys migrating the same database at once run one after the other. up refuses to run when an applied migration file was edited (exit code 1).

Flags

Flag	Applies to	Default	Description
--dir <path>	up, down, status	lib	Directory searched recursively for *.up.sql / *.down.sql.
--config <yaml>	up, down, status	database.yaml	YAML config, used for anything the environment doesn’t set.
--steps <n>	down	1	Number of batches to roll back.
--old <path>	diff	– (required)	Previous schema file.
--new <path>	diff	– (required)	New schema file.
--name <slug>	diff	– (required)	Name appended to the timestamp.
--out <dir>	diff	lib/migrations	Output directory.
--allow-destructive	diff	off	Write the migration even if it can lose data.

Exit codes

Code	Meaning
0	Success (including “nothing to do”).
1	An applied migration was edited, or diff refused a destructive change.
64	Bad usage: unknown command, missing diff flags, or no connection configured.

Other failures (a migration’s SQL errors, an unreachable database) end the process with the uncaught exception.

Examples

# Local development, using database.yaml
dart run gisila_orm:generate
dart run gisila_orm:migrate up

# Deployment
export DATABASE_URL='postgres://app:secret@db.internal:5432/blog?sslmode=verify-full'
dart run gisila_orm:migrate up

# Undo the last two batches
dart run gisila_orm:migrate down --steps 2

# Write a migration from two schema versions
dart run gisila_orm:migrate diff --old schema_v1.gisila.yaml --new lib/models/blog.gisila.yaml \
  --name add_slug --out lib/models/migrations

Library functions behind generate

package:gisila_orm/generators/project_codegen.dart exposes the same steps for custom tooling:

Symbol	Description
Future<List<File>> discoverSchemaFiles(Directory root)	Schema files under lib/, test/, example/, sorted.
Future<ProjectCodegenResult> generateProjectSchema(Directory root)	Steps 1-3 above. The result has schema, sourceFiles, outputDir, stem, dartFile, upSqlFile, downSqlFile and isMultiFile.
Future<String?> generateProjectIncrementalMigration(Directory root, {SchemaDefinition? schema, Directory? migrationsDir, bool allowDestructive = false})	Step 4. Returns the migration name written, or null.
projectSchemaRoots	['lib', 'test', 'example'].
projectSnapshotRelativePath	.gisila/schema_snapshots/project.gisila.yaml.
initialMigrationName	initial_schema.

See also: Run migrations, The codegen pipeline, build.yaml options.