ormed_mysql

MySQL and MariaDB driver adapter for the ormed ORM. Implements the DriverAdapter and SchemaDriver contracts, executing queries through package:mysql_client_plus.

Features

• MySQL 8.0+ and MariaDB 10.5+ support
• Full JSON column support
• Transaction support with nested savepoints
• Schema introspection and migration support
• SET, ENUM, and spatial type support
• Connection configuration mirroring Laravel's MySQL options

Installation

dependencies:
  ormed: ^0.2.0
  ormed_mysql: ^0.2.0

Quick Start

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

Future<void> main() async {
  final ds = createDataSource(connection: 'default');
  await ds.init();

  final rows = await ds.connection.driver.queryRaw('SELECT 1 AS ok');
  print(rows.first['ok']);

  await ds.dispose();
}

Generated apps should use ormed init scaffolding (lib/src/database/config.dart + datasource.dart) as the primary runtime entrypoint.

Low-level adapter usage

import 'package:ormed_mysql/ormed_mysql.dart';

Future<void> main() async {
  final adapter = MySqlDriverAdapter.fromUrl(
    'mysql://root:secret@localhost:3306/mydb',
  );
  await adapter.queryRaw('SELECT 1 AS ok');
  await adapter.close();
}

Adapter Constructors

// MySQL from URL
MySqlDriverAdapter.fromUrl('mysql://user:pass@host:port/database')

// MariaDB from URL
MariaDbDriverAdapter.fromUrl('mariadb://user:pass@host:port/database')

// With SSL
MySqlDriverAdapter.fromUrl('mysqls://user:pass@host:port/database')

// Local development (insecure)
MySqlDriverAdapter.insecureLocal(
  database: 'mydb',
  username: 'root',
  password: 'secret',
  port: 3306,
)

// Custom configuration
MySqlDriverAdapter.custom(config: DatabaseConfig(
  driver: 'mysql',
  options: {
    'host': 'localhost',
    'port': 3306,
    'database': 'mydb',
    'username': 'root',
    'password': 'secret',
    'ssl': true,
    'timeoutMs': 30000,
    'charset': 'utf8mb4',
    'collation': 'utf8mb4_unicode_ci',
    'timezone': '+00:00',
    'sqlMode': 'STRICT_TRANS_TABLES',
    'session': {'wait_timeout': 28800},
    'init': ['SET NAMES utf8mb4'],
  },
))

DataSource Helper Extensions

import 'dart:io';

import 'package:ormed/ormed.dart';
import 'package:ormed_mysql/ormed_mysql.dart';
import 'package:your_app/src/models/user.orm.dart';

Future<void> main() async {
  final env = OrmedEnvironment.fromDirectory(Directory.current);
  final registry = ModelRegistry()..register(UserOrmDefinition.definition);
  final ds = DataSource(
    registry.mySqlDataSourceOptionsFromEnv(
      name: 'default',
      environment: env.values,
    ),
  );
  await ds.init();

  final rows = await ds.connection.driver.queryRaw('SELECT 1 AS ok');
  print(rows.first['ok']);

  await ds.dispose();
}

Environment Variables

mySqlDataSourceOptionsFromEnv(...) recognizes:

• DB_URL or DATABASE_URL
• DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
• DB_SSLMODE, DB_TIMEZONE
• DB_CHARSET, DB_COLLATION, DB_SQL_MODE

Example .env:

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=mydb
DB_USER=root
DB_PASSWORD=secret
DB_SSLMODE=disable
DB_TIMEZONE=+00:00
DB_CHARSET=utf8mb4
DB_COLLATION=utf8mb4_unicode_ci
DB_SQL_MODE=STRICT_TRANS_TABLES

Driver Capabilities

Capability	Supported
Joins (inner, left, right, cross)	✅
Lateral joins	✅
Transactions with savepoints	✅
Schema introspection	✅
Raw SQL execution	✅
JSON operations	✅
Index hints	✅
FOR UPDATE / LOCK IN SHARE MODE	✅
Database management	✅
Foreign key constraints	✅

Note: MySQL doesn't support native RETURNING. Insert operations return lastInsertID instead.

Type Mappings

Dart Type	MySQL Type
bool	TINYINT(1)
int	INT / BIGINT
double	DOUBLE
Decimal	DECIMAL / NUMERIC
String	VARCHAR / TEXT
DateTime	DATETIME / TIMESTAMP
Duration	TIME
UuidValue	CHAR(36)
Set<String>	SET
MySqlBitString	BIT
MySqlGeometry	GEOMETRY / POINT / POLYGON
Uint8List	BLOB / BINARY
Map	JSON

MySQL-Specific Types

// Value classes for MySQL-specific types
import 'package:ormed_mysql/ormed_mysql.dart';

MySqlBitString   // BIT column values
MySqlGeometry    // Spatial/geometry values (WKB format)

Connection URL Schemes

Scheme	Description
mysql://	Standard MySQL connection
mariadb://	Standard MariaDB connection
mysqls://	MySQL with SSL
mariadbs://	MariaDB with SSL
mysql+ssl://	MySQL with SSL (alternative)

Query parameters: ?ssl=true, ?secure=true

Docker Setup

MariaDB (docker-compose.yml)

cd packages/ormed_mysql
MARIADB_ROOT_PASSWORD=secret docker compose up -d

export MARIADB_URL="mariadb://root:secret@localhost:6604/orm_test"
dart test packages/ormed_mysql

docker compose down -v

MySQL (docker-compose.mysql.yml)

cd packages/ormed_mysql
MYSQL_ROOT_PASSWORD=secret docker compose -f docker-compose.mysql.yml up -d

export MYSQL_URL="mysql://root:secret@localhost:6605/orm_test"
dart test packages/ormed_mysql/test/mysql_driver_shared_test.dart

docker compose -f docker-compose.mysql.yml down -v

JSON Operations

// Query JSON columns
final users = await ds.query<\$User>()
    .whereJson('settings', '$.theme', 'dark')
    .get();

// Uses MySQL JSON functions: JSON_EXTRACT, JSON_UNQUOTE, JSON_TYPE

Index Hints

// MySQL-specific index hints
final results = await adapter.queryRaw(
  'SELECT * FROM users USE INDEX (idx_email) WHERE email = ?',
  ['test@example.com'],
);

Upsert Operations

MySQL uses ON DUPLICATE KEY UPDATE:

await repo.upsert(
  \$UserInsertDto(email: 'test@example.com', name: 'Test'),
  uniqueBy: ['email'],
);

Related Packages

Package	Description
ormed	Core ORM library
ormed_sqlite	SQLite driver
ormed_postgres	PostgreSQL driver
ormed_cli	CLI tool for migrations