SQLite

SQLite is the default scaffold for new projects. It runs without external services and is great for local development, CLI tools, and fast integration tests.

Install

Add the driver package:

dependencies:
  ormed: ^0.1.0
  ormed_sqlite: ^0.1.0

Configure (ormed.yaml)

driver:
  type: sqlite
  options:
    database: database.sqlite   # relative to project root
    session:
      foreign_keys: true
      journal_mode: WAL
    init:
      - PRAGMA busy_timeout = 5000

Use in code (DataSource)

The recommended way is to use the generated createDataSource() helper, but you can also initialize it manually:

From Config

import 'package:ormed/ormed.dart';
import 'package:ormed_sqlite/ormed_sqlite.dart';

void main() async {
  ensureSqliteDriverRegistration();
  
  final config = loadOrmConfig();
  final ds = DataSource.fromConfig(config);
  await ds.init();
}

Manual

Future<DataSource> createSqliteDataSource() async {
  final dataSource = DataSource(
    DataSourceOptions(
      name: 'default',
      driver: SqliteDriverAdapter.file('database.sqlite'),
      entities: generatedOrmModelDefinitions,
    ),
  );
  await dataSource.init();
  return dataSource;
}

SQLite Migrations Helpers

Import the SQLite migrations entrypoint to use SQLite-specific column aliases:

import 'package:ormed_sqlite/migrations.dart';

Available helpers:

• blob() → BLOB (alias for binary())
• real() → REAL (alias for float())
• numeric() → NUMERIC (alias for decimal())

In-memory (tests)

DataSource createInMemorySqliteDataSource() {
  return DataSource(
    DataSourceOptions(
      name: 'test',
      driver: SqliteDriverAdapter.inMemory(),
      entities: generatedOrmModelDefinitions,
    ),
  );
}

Options

Option	Type	Default	Description
database	String	database.sqlite	Path to the .sqlite file (relative to project root or absolute).
path	String?	—	Alias for database used by some programmatic helpers.
memory	bool	false	When true, connects to an in-memory database (tests / ephemeral usage).
session	Map<String, Object?>	{}	Session pragmas applied via PRAGMA key = value.
init	List<String>	[]	SQL statements executed after connecting.

Notes

• The adapter automatically enables RETURNING support and schema inspection.
• Migrations and seeds are configured separately in ormed.yaml. See Getting Started → Configuration.
• For plan/previews/schema internals, see Drivers → Internals.

Extensions

Driver extensions let you register custom clause compilers for SQLite queries.

class SqliteCaseInsensitiveExtensions extends DriverExtension {
  const SqliteCaseInsensitiveExtensions();

  @override
  List<DriverExtensionHandler> get handlers => const [
        DriverExtensionHandler(
          kind: DriverExtensionKind.where,
          key: 'ci_equals',
          compile: _compileSqliteCaseInsensitive,
        ),
      ];
}

DriverExtensionFragment _compileSqliteCaseInsensitive(
  DriverExtensionContext context,
  Object? payload,
) {
  final data = payload as Map<String, Object?>;
  final column = context.grammar.wrapIdentifier(data['column'] as String);
  final placeholder = context.grammar.parameterPlaceholder();
  return DriverExtensionFragment(
    sql: 'LOWER(${context.tableIdentifier}.$column) = LOWER($placeholder)',
    bindings: [data['value']],
  );
}

Future<List<Map<String, Object?>>> searchDocumentsSqlite(
  DataSource dataSource,
  String query,
) {
  return dataSource.context
      .table('documents')
      .whereExtension('ci_equals', {'column': 'title', 'value': query})
      .rows();
}

Future<DataSource> createSqliteExtensionDataSource() async {
  final dataSource = DataSource(
    DataSourceOptions(
      name: 'docs-sqlite-extensions',
      driver: SqliteDriverAdapter(database: 'database.sqlite'),
      entities: generatedOrmModelDefinitions,
      driverExtensions: const [SqliteCaseInsensitiveExtensions()],
    ),
  );
  await dataSource.init();
  return dataSource;
}