MySQL / MariaDB

The MySQL adapter also supports MariaDB. Configure via URL or explicit fields; common alias keys are accepted.

Install

Add the driver package:

dependencies:
  ormed: ^0.1.0
  ormed_mysql: ^0.1.0

Configure (ormed.yaml)

URL

driver:
  type: mysql          # or mariadb
  options:
    url: mysql://root:secret@localhost:6605/orm_test
    charset: utf8mb4
    collation: utf8mb4_general_ci
    timezone: "+00:00"
    sqlMode: STRICT_ALL_TABLES
    timeoutMs: 10000
    session:
      sql_notes: 0
    init:
      - SET NAMES utf8mb4
      - SET time_zone = "+00:00"

Fields

driver:
  type: mysql          # or mariadb
  options:
    host: 127.0.0.1
    port: 3306
    database: orm_test
    username: root
    password: secret
    ssl: false
    charset: utf8mb4
    collation: utf8mb4_general_ci
    timezone: "+00:00"
    sqlMode: STRICT_ALL_TABLES
    timeoutMs: 10000

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_mysql/ormed_mysql.dart';

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

URL (Manual)

Future<DataSource> createMysqlDataSourceFromUrl() async {
  final dataSource = DataSource(
    DataSourceOptions(
      name: 'default',
      driver: MySqlDriverAdapter.fromUrl(
        'mysql://root:secret@localhost:3306/app',
      ),
      entities: generatedOrmModelDefinitions,
    ),
  );
  await dataSource.init();
  return dataSource;
}

Fields (Manual)

Future<DataSource> createMysqlDataSourceFromFields() async {
  final dataSource = DataSource(
    DataSourceOptions(
      name: 'default',
      driver: MySqlDriverAdapter.custom(
        config: DatabaseConfig(
          driver: 'mysql',
          options: const {
            'host': '127.0.0.1',
            'port': 3306,
            'database': 'app',
            'username': 'root',
            'password': 'secret',
            'charset': 'utf8mb4',
            'collation': 'utf8mb4_general_ci',
          },
        ),
      ),
      entities: generatedOrmModelDefinitions,
    ),
  );
  await dataSource.init();
  return dataSource;
}

Options

Option	Type	Default	Description
url	String?	—	Full connection string. Aliases: uri, dsn. When set, it becomes the primary source for host/port/database/user/password and can also read query params like charset, collation, timezone, sql_mode, timeoutMs, ssl, secure, and password.
host	String	127.0.0.1	Database host (ignored when url/uri/dsn is set).
port	int	3306	Database port (ignored when url/uri/dsn is set).
database	String	connection name or test	Database name (ignored when url/uri/dsn is set).
username	String	root	Database username (ignored when url/uri/dsn is set).
password	String?	—	Database password.
ssl	bool	false	Enable TLS (alias: secure). URL schemes mysqls/mariadbs and +ssl imply TLS.
timeoutMs	int (ms)	10000	Connect timeout in milliseconds (alias: connectTimeout).
charset	String	utf8mb4	Charset used for SET NAMES ....
collation	String?	utf8mb4_general_ci	Collation for the connection and SET NAMES ... COLLATE ....
timezone	String	+00:00	Session timezone applied via SET time_zone = ....
sqlMode	String?	—	Session SQL mode string (alias: sql_mode).
session	Map<String, Object?>	{}	Session variables applied via SET @@key = value.
init	List<String>	[]	SQL statements executed after connecting and applying charset/timezone/sqlMode.
schema	String?	—	Optional schema/database qualifier used when compiling fully-qualified table names.

Extensions

Driver extensions let you register custom clause compilers for MySQL/MariaDB without dropping down to raw SQL helpers.

class MySqlCaseInsensitiveExtensions extends DriverExtension {
  const MySqlCaseInsensitiveExtensions();

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

DriverExtensionFragment _compileMySqlCaseInsensitive(
  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?>>> searchDocumentsMySql(
  DataSource dataSource,
  String query,
) {
  return dataSource.context
      .table('documents')
      .whereExtension('ci_equals', {'column': 'title', 'value': query})
      .rows();
}

Future<DataSource> createMySqlExtensionDataSource() async {
  final dataSource = DataSource(
    DataSourceOptions(
      name: 'docs-mysql-extensions',
      driver: MySqlDriverAdapter.fromUrl(
        'mysql://root:secret@localhost:3306/app',
      ),
      entities: generatedOrmModelDefinitions,
      driverExtensions: const [MySqlCaseInsensitiveExtensions()],
    ),
  );
  await dataSource.init();
  return dataSource;
}

Data types

Ormed uses driver codecs to map some MySQL/MariaDB column types to richer Dart types when they appear as model fields.

Values

final uuid = UuidValue.fromString('00000000-0000-0000-0000-000000000000');
final amount = Decimal.parse('12.34');
final duration = const Duration(hours: 1, minutes: 2, seconds: 3);
final tags = <String>{'alpha', 'beta'};
final bits = MySqlBitString.parse('1010');
final geometry = MySqlGeometry.fromHex('000000000101000000000000000000F03F0000000000000040');
final payload = Uint8List.fromList([1, 2, 3, 4]);

Migration

class CreateMysqlBuiltinsTable extends Migration {
  const CreateMysqlBuiltinsTable();

  @override
  void up(SchemaBuilder schema) {
    schema.create('mysql_builtins', (table) {
      table.id();
      table.decimal('amount', precision: 18, scale: 6);
      table.column(
        'time_value',
        const ColumnType(ColumnTypeName.time, precision: 6),
      );
      table.uuid('uuid_value');
      table.set('tags', ['alpha', 'beta', 'gamma']);
      table
          .column('bit_value', const ColumnType.custom('BIT(4)'))
          .nullable();
      table.geometry('geom').nullable();
      table.binary('payload');
      table.json('document').nullable();
    });
  }

  @override
  void down(SchemaBuilder schema) {
    schema.drop('mysql_builtins', ifExists: true, cascade: true);
  }
}

Supported mappings

Column type	Dart type	Notes
DECIMAL / NUMERIC	Decimal	Preserves precision (avoid double when you need exact values).
TIME	Duration	Encoded as [-]HH:MM:SS[.ffffff].
UUID	UuidValue	Stored as CHAR(36) by default.
SET(...)	Set<String>	Encoded/decoded as the comma-separated value returned by MySQL.
BIT(n)	MySqlBitString	Use when you need bit-level data rather than booleans.
GEOMETRY	MySqlGeometry	Raw bytes wrapper; decode/encode without lossy conversions.
JSON	Map<String, Object?> / List<Object?>	Stored as JSON strings, decoded into Dart collections.
BLOB / BINARY	Uint8List	Binary data (no string coercion).

Notes

• Uses ON DUPLICATE KEY UPDATE for upserts and supports JSON columns on MySQL 8+/MariaDB 10.5+.
• Set driver.type: mariadb to target MariaDB specifically; the same options apply.
• Migrations and seeds are configured separately in ormed.yaml. See Getting Started → Configuration.
• For plan/previews/schema internals, see Drivers → Internals.