Configuration

Ormed defaults to code-first runtime configuration generated in lib/src/database/config.dart.
ormed.yaml remains supported for CLI workflows and explicit connection blocks.

Prerequisites

• You completed Installation
• You ran ormed init from Quick Start or Adopt Existing Project

What You’ll Learn

• How generated config.dart selects one or many runtime connections
• When to introduce ormed.yaml and multi-connection blocks
• How environment variables are resolved in code and YAML

Step Outcome

By the end of this page, you should have:

• A clear config mode choice (code-first vs ormed.yaml)
• Connection definitions matching your runtime and CLI needs
• Environment interpolation working in your local/dev setup

Pick A Config Mode First

Use case	Recommended mode
App runtime in Dart code, fastest onboarding	Code-first (config.dart)
Explicit per-connection CLI blocks, YAML-driven workflows	ormed.yaml
Multi-connection runtime in code	Code-first + generated helpers
Multi-connection CLI targeting	ormed.yaml with connections

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.

Runtime Configuration (Default)

ormed init generates runtime datasource options in code:

const String defaultDataSourceConnection = 'default';

/// Connections baked into this generated scaffold.
const List<String> generatedDataSourceConnections = <String>['default'];

DataSourceOptions buildDataSourceOptions({String? connection}) {
  final env = OrmedEnvironment.fromDirectory(Directory.current);
  final registry = bootstrapOrm();
  final selectedConnection = (connection ?? defaultDataSourceConnection).trim();
  switch (selectedConnection) {
    case 'default':
      final path = env.string(
        'DB_PATH',
        fallback: 'database/ormed_examples.sqlite',
      );
      return registry.sqliteFileDataSourceOptions(path: path, name: 'default');
    default:
      throw ArgumentError.value(
        selectedConnection,
        'connection',
        'Unknown generated datasource connection. Expected one of: default',
      );
  }
}

Map<String, DataSourceOptions> buildAllDataSourceOptions() {
  final options = <String, DataSourceOptions>{};
  for (final connection in generatedDataSourceConnections) {
    options[connection] = buildDataSourceOptions(connection: connection);
  }
  return options;
}

This gives you:

• defaultDataSourceConnection
• generatedDataSourceConnections
• buildDataSourceOptions({String? connection})
• buildAllDataSourceOptions()
• Per-connection helpers such as buildDefaultDataSourceOptions()

Use these helpers directly from app bootstrap. You do not need to manually assemble driver adapters for normal cases.

Optional ormed.yaml (CLI / explicit connection blocks)

Single connection

CLI commands read these top-level blocks as a 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

seeds is optional unless you run ormed seed / ormed migrate --seed.

Multiple connections

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, d1, 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)

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

• 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. Scaffold it with ormed init --only=seeders (or create the first seeder with ormed make:seeder) before running the entrypoint directly:

  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 / D1.

Environment Variables

You can use environment variables in both code-first and YAML configurations.

• In code-first mode, use OrmedEnvironment helpers in config.dart.
• In YAML mode, ${VAR} resolves from process environment and ${VAR:-fallback} uses a fallback.

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

Set environment variables:

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

.env support: .env files are loaded and interpolated by OrmedEnvironment, and YAML interpolation remains supported for ormed.yaml.

Verify Configuration

Code-first runtime check:

dart run lib/main.dart

YAML/CLI check:

dart run ormed_cli:ormed migrate --connection primary

Programmatic Configuration

You can also configure Ormed programmatically. The recommended approach is generated code-first helpers.

Generated (recommended)

Use generated datasource/config helpers directly:

import 'package:ormed/ormed.dart';
import 'src/database/datasource.dart';

void main() async {
  final ds = createDataSource();
  await ds.init();
}

From ormed.yaml

If you prefer explicit YAML-driven runtime boot:

import 'package:ormed/ormed.dart';
import 'src/database/config.dart';

void main() async {
  final config = loadOrmConfig();
  final options = buildDataSourceOptions();
  final ds = DataSource.fromConfig(config, registry: options.registry);
  await ds.init();
}

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

• Defining Models — design your schema model layer
• Drivers — pick runtime-specific connection behavior
• Migrations — connect config to schema rollout
• CLI Commands — operational command reference

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:migration produces). The migration registry can still contain both styles.