Skip to main content

Drivers

Ormed ships first-party driver adapters for SQLite, PostgreSQL, MySQL/MariaDB, and Cloudflare D1.

Prerequisites​

  • You completed Configuration
  • You understand model/query basics from Learn Ormed

What You’ll Learn​

  • Which driver fits each runtime and deployment profile
  • How helper-based driver setup differs from config-driven setup
  • Where driver-specific behavior and internals live in the docs

Step Outcome​

By the end of this page, you should know:

  • Which driver package to adopt for your runtime
  • Whether to bootstrap with code-first helpers or YAML config
  • Which env vars and docs sections matter for your chosen driver

Drivers are distributed as separate packages (e.g. ormed_sqlite). The core ormed package depends only on the DriverAdapter interface.

  • 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.

You can use a driver in three ways:

  1. Generated code-first config via lib/src/database/config.dart + datasource.dart
  2. YAML/config driven via ormed.yaml + DataSource.fromConfig(config)
  3. Programmatic via DataSourceOptions(driver: ...)

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

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(...)

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

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​