Configuration

Ormed uses ormed.yaml for CLI + runtime configuration. Two shapes are supported: a single top-level connection (scaffold default) or a connections: map for multi-db setups.

Snippet context

• YAML blocks show CLI/runtime config.
• Dart snippets show only the relevant registry/setup pieces; full app bootstrapping is covered in Quick Start.

Connection Shape

Single (default)

CLI commands read these top-level blocks as the single active connection.

Create ormed.yaml in your project root:

driver:
  type: sqlite
  options:
    database: database.sqlite
migrations:
  directory: lib/src/database/migrations
  registry: lib/src/database/migrations.dart
  ledger_table: orm_migrations
  schema_dump: database/schema.sql
seeds:
  directory: lib/src/database/seeders
  registry: lib/src/database/seeders.dart

Multiple

Use this shape for multi-tenant or multi-environment setups. Target a specific connection with --connection <name>.

default_connection: primary

connections:
  primary:
    driver:
      type: sqlite
      options:
        database: data/app.sqlite
    migrations:
      directory: lib/src/database/migrations
      registry: lib/src/database/migrations.dart
      ledger_table: orm_migrations
    seeds:
      directory: lib/src/database/seeders
      registry: lib/src/database/seeders.dart

  analytics:
    driver:
      type: postgres
      options:
        url: ${ANALYTICS_URL}
    migrations:
      directory: lib/src/database/migrations/analytics
      registry: lib/src/database/analytics_migrations.dart

Configuration Blocks (what each section means)

default_connection

The default database connection to use when --connection is not specified.

default_connection: primary

connections

Named database connections. Each connection has its own driver, migrations, and seed configuration.

connections:
  primary:
    driver:
      type: sqlite  # sqlite, postgres, mysql, mariadb
      options:
        database: database.sqlite
    
    # Migrations configuration
    migrations:
      directory: lib/src/database/migrations
      registry: lib/src/database/migrations.dart
      ledger_table: _orm_migrations
      schema_dump: database/schema.sql
    
    # Seeders configuration (optional)
    seeds:
      directory: lib/src/database/seeders
      registry: lib/src/database/seeders.dart

Registry Files (Why They Matter)

Both migrations.registry and seeds.registry are standalone Dart entrypoints. The CLI shells out to these files, so keep their paths accurate in ormed.yaml.

• Migrations registry (migrations.registry): exports buildMigrations() and a small main that supports flags like --dump-json/--plan-json for schema previews. You can run it directly:

  dart run lib/src/database/migrations.dart --dump-json

• Seeds registry (seeds.registry): lists SeederRegistrations and exposes main for ormed seed / ormed migrate --seed. You can execute it without the CLI wrapper:

  dart run lib/src/database/seeders.dart

If you relocate these files, update the registry paths so the CLI can find and execute them.

Driver-specific options live on the dedicated pages: Drivers → SQLite / PostgreSQL / MySQL.

Environment Variables

You can use environment variables in your configuration. ${VAR} resolves from the current process environment; ${VAR:-fallback} uses fallback when unset.

connections:
  production:
    driver:
      type: postgres
      options:
        url: ${DATABASE_URL}
        sslmode: ${DB_SSLMODE:-disable}

Set the environment variable:

export DATABASE_URL="postgres://user:pass@db.example.com:5432/myapp"
dart run ormed migrate:apply --connection production

.env support: if a .env file sits next to ormed.yaml, it is loaded automatically (merged with platform environment). Useful for local secrets without exporting them.

Programmatic Configuration

You can also configure Ormed programmatically. The recommended approach is to use the generated registry.

Generated (recommended)

Future<void> programmaticConfig() async {
  // Create driver (SQLite in-memory for fast tests / examples)
  final driver = SqliteDriverAdapter.inMemory();

  // Use the generated registry helper (includes all models)
  final registry = bootstrapOrm();

  // Create data source
  final dataSource = DataSource(
    DataSourceOptions(
      name: 'primary',
      driver: driver,
      entities: registry.definitions.values.toList(),
    ),
  );

  await dataSource.init();
  // Use the data source...
}

Manual (advanced)

If you prefer manual control, you can still register models individually:

void manualRegistration() {
  final registry = ModelRegistry()
    ..register(UserOrmDefinition.definition)
    ..register(PostOrmDefinition.definition)
    ..registerTypeAlias<User>(UserOrmDefinition.definition);
}

Next Steps

• Drivers — choose and configure your target database
• Defining Models — create your first models
• CLI Commands — learn all available CLI commands
• Migrations — set up database migrations

Migration authoring format

The CLI can scaffold migrations as either:

• Dart migrations (default)
• SQL folder migrations (up.sql / down.sql)

To change the default authoring format for the active connection:

migrations:
  format: sql # dart | sql

This only affects generation defaults (what ormed make produces). The migration registry can still contain both styles.