Skip to main content

Drivers

Ormed ships first-party driver adapters for SQLite, PostgreSQL, MySQL/MariaDB, and Cloudflare D1. The optional ormed_drift package lets Ormed share an existing Drift executor, so you can keep Drift's typed database API and add Ormed queries or reactive watchers where they help.

Before you start: You completed Configuration; You understand model/query basics from Learn Ormed.

Drivers are distributed as separate packages (for example, ormed_sqlite). The core ormed package depends only on the DriverAdapter interface. Drift is an integration adapter rather than a driver: drift configuration block; start with Drift integration when your application already owns a Drift executor.

  • SQLite — zero‑dependency file or in-memory database, ideal for local development and fast tests.
  • PostgreSQL — full‑featured SQL with rich JSON, window functions, and robust migrations at scale.
  • MySQL / MariaDB — common production backend with ON DUPLICATE KEY UPDATE support and JSON columns.
  • Cloudflare D1 — remote SQLite-compatible runtime for serverless/edge deployments.
  • Drift integration — share a Drift executor with Ormed queries, migrations, and reactive watchers. SQLite/LibSQL works across Drift's supported hosts; Drift PostgreSQL is native/server-side.

You can use a driver in four ways:

  1. Direct database facade via SqliteDatabase.connect, PostgresDatabase.connect, MySqlDatabase.connect, or D1Database.connect — no code generation required
  2. Generated code-first config via lib/src/database/config.dart + datasource.dart
  3. YAML/config driven via ormed.yaml + DataSource.fromConfig(config)
  4. Programmatic via DataSourceOptions(driver: ...)

The direct helpers return OrmDatabase, which exposes raw SQL, schema plans, ad-hoc table queries, transactions, migrations, and the same interceptor pipeline used by generated connections. Start with Direct Database Access when a generated registry would be unnecessary ceremony.

Driver Selection Cheat Sheet​

  • Local dev + fast tests: SQLite
  • General production relational workloads: PostgreSQL
  • Existing MySQL/MariaDB estate: MySQL driver
  • Cloudflare edge/serverless with D1: D1 driver
  • Existing Drift application: ormed_drift shared-executor integration

Registration and Helpers​

  • Code-first scaffolds and driver helper extensions (*DataSourceOptions(...), *DataSourceOptionsFromEnv(...)) do not require manual registration calls.
  • ormed CLI commands auto-register official drivers for migration/seed/schema workflows.
  • DataSource.fromConfig(config) remains available for explicit YAML-driven runtimes.

Environment Variables​

Driver packages expose environment-based helpers where it makes sense:

  • ormed_sqlite: sqliteFileDataSourceOptions(...), sqliteInMemoryDataSourceOptions(...)
  • ormed_postgres: postgresDataSourceOptionsFromEnv(...)
  • ormed_mysql: mySqlDataSourceOptionsFromEnv(...), mariaDbDataSourceOptions(...)
  • ormed_d1: d1DataSourceOptionsFromEnv(...)
  • ormed_drift: construct DriftDriverAdapter around the executor your app already uses; connection settings stay with Drift.

SQLite typically reads a file path from app-level config (for scaffolded projects, usually DB_PATH in generated config.dart).

Env Variable Matrix​

DriverHelperCommon env vars
SQLitegenerated config.dartDB_PATH
PostgreSQLpostgresDataSourceOptionsFromEnv(...)DB_URL/DATABASE_URL, DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSLMODE, DB_TIMEZONE, DB_APP_NAME
MySQL / MariaDBmySqlDataSourceOptionsFromEnv(...)DB_URL/DATABASE_URL, DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSLMODE, DB_TIMEZONE, DB_CHARSET, DB_COLLATION, DB_SQL_MODE
D1d1DataSourceOptionsFromEnv(...)D1_ACCOUNT_ID/CF_ACCOUNT_ID/DB_D1_ACCOUNT_ID, D1_DATABASE_ID/DB_D1_DATABASE_ID, D1_API_TOKEN/D1_SECRET/DB_D1_API_TOKEN, plus optional D1_* retry/logging vars
Driftno Ormed env helperDrift owns the executor and its connection settings

Pick the driver that matches your runtime environment; you can keep the rest of your Ormed code identical and switch by changing generated options helpers (or active YAML connection) and the adapter behind them.

Verify Driver Setup​

After configuring a driver, run:

dart run ormed_cli:ormed migrate --pretend

Then run a simple query through your app bootstrap path to confirm runtime connectivity.

Driver internals​

If you are building tools, debugging query output, or implementing a custom adapter, see:

Read This Next​