@deterministic-code/migraters 0.0.2 → 0.0.3

package/README.md

@@ -1 +1,149 @@
-Migrate executables for deterministic-code.
+# Migraters
+
+Migraters tracks SQL changes during development and applies them upstream as the project evolves. As a codebase grows in complexity and team size, keeping those changes tracked and in sync becomes harder. Migraters is built for that.
+
+The typical workflow is:
+
+* On development, create one or more migration files, test them, and run migrate up.
+* On deploy, those scripts are copied to production and migrate up is run again, so the upstream database matches development.
+
+The same migrate commands and a consistent API are available in multiple programming languages and across many datasource dialects.
+
+## Install
+
+### Install from npm
+
+```shell
+npm install @deterministic-code/migraters
+npx migrate-init --language typescript --dialect sqlite --dialect postgres
+```
+
+### Install skill
+
+Agent skill for Claude or Cursor: [skill/SKILL.md](skill/SKILL.md).
+
+```shell
+npx skills add https://github.com/deterministic-code/migraters/tree/main/skill -g -a cursor -a claude-code -y --copy
+```
+
+## Skill Prompts
+
+Natural-language prompts the [skill](skill/SKILL.md) maps straight to CLI commands:
+
+| Prompt | Runs |
+| --- | --- |
+| Install migraters for sqlite and postgres | `npm install` → `npx migrate-init --language typescript --dialect sqlite --dialect postgres` |
+| Add driver oracle | `npx migrate-init --language <language>` with prior dialects **plus** `oracle` |
+| Create a new migrate | `npx migrate-create` |
+| migrate up | `npx migrate-up` |
+| migrate down | `npx migrate-down` |
+
+`npx migrate-init` replaces the language and dialect set, so “add driver” means re-run init with the same `--language`, the previously enabled dialects, and the new one (for example `npx migrate-init --language typescript --dialect sqlite --dialect postgres --dialect oracle` after a sqlite+postgres install). Flag details are under [Commands](#commands).
+
+## Quick example
+
+`user.sql`:
+
+```sql
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  email TEXT NOT NULL
+);
+```
+
+```shell
+npx migrate-init --language typescript --dialect sqlite
+npx migrate-setup --provider sqlite --connection ./app.sqlite
+npx migrate-create --provider sqlite --name add_users
+cat user.sql > sql/sqlite/migrations/0001_add_users_up.sql
+npx migrate-up --provider sqlite --connection ./app.sqlite
+```
+
+## Commands
+
+### init
+
+Selects the programming language and dialects this tree will compile and install. `migrate-init` is project setup, not an `IMigrater` method, and it does not take `--connection`. `--language` is required (`typescript`, `csharp`, or `rust`). Repeat `--dialect` once per provider (aliases from [`cli.yaml`](cli.yaml) apply: `pg`, `mssql`, `ora`, and the rest). Re-running replaces the previous language and dialect set. `--all` restores every dialect. Init installs that language’s driver dependencies and builds `migrate-setup`, `migrate-up`, `migrate-down`, and `migrate-create`. Later commands dispatch to those binaries.
+
+```shell
+npx migrate-init --language typescript --dialect sqlite --dialect postgres
+npx migrate-init --language csharp --dialect sqlite
+npx migrate-init --language rust --dialect sqlite
+```
+
+`migrate-init` attaches only the selected dialect packages and builds those binaries. TypeScript installs `@deterministic-code/migraters-<dialect>` (one driver each). C# writes `ProjectReference`s to `Dialects/<Name>/Migrate*.csproj` (each project owns one NuGet driver). Rust still enables Cargo features until its pool is split the same way. A clone does not ship or build the full dialect matrix.
+
+### setup
+
+Creates the `migrates` and `migrate_logs` tables and the migrations directory. Idempotent.
+
+```shell
+npx migrate-setup --provider <sqlite|postgres|mysql|sqlserver|oracle> --connection <url> [--migrations-path <dir>] [--and-up] [--create-database]
+```
+
+`--create-database` creates the database named in `--connection` if it does not exist. `--and-up` runs `migrate-up` immediately after setup. Default migrations directory is `./sql/<dialect>/migrations`.
+
+### up
+
+Applies every pending migration, each in its own transaction.
+
+```shell
+npx migrate-up --provider <…> --connection <url> [--migrations-path <dir>] [--migrations-root <dir>] [--one]
+```
+
+`--migrations-root` looks under `<root>/<dialect>/migrations` and defaults to `sql`. It is ignored when `--migrations-path` is set. `--one` applies only the next pending migration. A whole-line `GO` (sqlcmd-style) splits a file into batches; each batch is executed separately.
+
+### down
+
+Rolls back the most recently applied migration, one step. Type `confirm` at the prompt, or pass `--confirm`.
+
+```shell
+npx migrate-down --provider <…> --connection <url> [--migrations-path <dir>] [--migrations-root <dir>] [--confirm]
+```
+
+### create
+
+Writes the next `<NNNN>_<name>_up.sql` and `<NNNN>_<name>_down.sql` pair. The name must match `^[a-z][a-z0-9_]*$`.
+
+```shell
+npx migrate-create --provider <…> --name <snake_case_slug> [--migrations-path <dir>]
+```
+
+## API
+
+The four `IMigrater` verbs are one contract in every language: argv in [`cli.yaml`](cli.yaml), `IMigrater` in [`api.yaml`](api.yaml). Each language implements that interface. Catalog insert and delete stay inside `up` and `down`. `migrate-init` lives only in [`cli.yaml`](cli.yaml).
+
+| Verb | TypeScript [`IMigrater`](typescript/src/abstractions/migrater.ts) | Rust [`IMigrater`](rust/src/migrater.rs) | C# [`IMigrater`](csharp/Abstractions/IMigrater.cs) |
+|---|---|---|---|
+| setup | `setup` | `setup` | `Setup` |
+| up | `up` | `up` | `Up` |
+| down | `down` | `down` | `Down` |
+| create | `create` | `create` | `Create` |
+
+## Language support
+
+| Datasource | C# | Rust | TypeScript |
+|---|---|---|---|
+| sqlite | yes | yes | yes |
+| postgres | yes | yes | yes |
+| mysql | yes | yes | yes |
+| sqlserver | yes | yes | yes |
+| oracle | yes | yes | yes |
+
+## Providers
+
+`sqlite`, `postgres`, `mysql`, `sqlserver`, and `oracle`.
+
+When `--connection` is omitted, the runner reads the first set environment variable for that dialect:
+
+| Provider | Environment variables |
+|---|---|
+| sqlite | `SQLITE_PATH`, `DB_PATH` |
+| postgres | `PG_CONNECTION_STRING`, `DATABASE_URL` |
+| mysql | `MYSQL_URL`, `DATABASE_URL` |
+| sqlserver | `MSSQL_URL`, `DATABASE_URL` |
+| oracle | `ORACLE_CONNECT_STRING`, `DATABASE_URL` |
+
+## Specification
+
+Shared argv, flags, aliases, exit codes, and command behavior live in [`cli.yaml`](cli.yaml). `IMigrater` (`setup`, `up`, `down`, `create`) lives in [`api.yaml`](api.yaml). `migrate-init` is CLI-only. SQL spelling stays a provider detail.

package/bundle.yaml

@@ -23,43 +23,38 @@ languages:
     dialects:
       sqlite:
         files:
-          - typescript/src/dialects/sqlite-dialect.ts
+          - typescript/dialects/sqlite/**
           - shared/templates/sql/sqlite/**
         apk: sqlite
         packages:
           - name: better-sqlite3
-            version: "^13.0.3"
             installScripts: true
       postgres:
         files:
-          - typescript/src/dialects/postgres-dialect.ts
+          - typescript/dialects/postgres/**
           - shared/templates/sql/postgres/**
         apk: postgresql-client
         packages:
           - name: pg
-            version: "^8.13.0"
       mysql:
         files:
-          - typescript/src/dialects/mysql-dialect.ts
+          - typescript/dialects/mysql/**
           - shared/templates/sql/mysql/**
         apk: mysql-client
         packages:
           - name: mysql2
-            version: "^3.22.2"
       sqlserver:
         files:
-          - typescript/src/dialects/sqlserver-dialect.ts
+          - typescript/dialects/sqlserver/**
           - shared/templates/sql/sqlserver/**
         packages:
           - name: mssql
-            version: "^12.5.0"
       oracle:
         files:
-          - typescript/src/dialects/oracle-dialect.ts
+          - typescript/dialects/oracle/**
           - shared/templates/sql/oracle/**
         packages:
           - name: oracledb
-            version: "^6.10.0"
     commands:
       setup: migrate-setup --provider {{provider}}
       up: migrate-up --provider {{provider}} --migrate-path {{migrationsPath}}
@@ -100,6 +95,7 @@ languages:
       - rust/Cargo.toml
       - rust/rustfmt.toml
       - rust/src/**/*.rs
+      - rust/api/**
       - rust/init/**
       - shared/templates/help/**
       - shared/templates/messages/**
@@ -108,32 +104,27 @@ languages:
     dialects:
       sqlite:
         files:
-          - rust/src/dialects/sqlite.rs
+          - rust/dialects/sqlite/**
           - shared/templates/sql/sqlite/**
         apk: sqlite
-        feature: sqlite
       postgres:
         files:
-          - rust/src/dialects/postgres.rs
+          - rust/dialects/postgres/**
           - shared/templates/sql/postgres/**
         apk: postgresql-client
-        feature: postgres
       mysql:
         files:
-          - rust/src/dialects/mysql.rs
+          - rust/dialects/mysql/**
           - shared/templates/sql/mysql/**
         apk: mysql-client
-        feature: mysql
       sqlserver:
         files:
-          - rust/src/dialects/sqlserver.rs
+          - rust/dialects/sqlserver/**
           - shared/templates/sql/sqlserver/**
-        feature: sqlserver
       oracle:
         files:
-          - rust/src/dialects/oracle.rs
+          - rust/dialects/oracle/**
           - shared/templates/sql/oracle/**
-        feature: oracle
     commands:
       setup: migrate-setup --provider {{provider}}
       up: migrate-up --provider {{provider}} --migrate-path {{migrationsPath}}
@@ -176,6 +167,7 @@ languages:
     common:
       - csharp/**/*.cs
       - csharp/MigrateRunner.csproj
+      - csharp/MigrateRunner.Core.csproj
       - csharp/MigrateInit/MigrateInit.csproj
       - csharp/GlobalUsings.cs
       - csharp/.csharpierrc.json
@@ -191,7 +183,7 @@ languages:
     dialects:
       sqlite:
         files:
-          - csharp/Dialects/SqliteDialect.cs
+          - csharp/Dialects/Sqlite/**
           - shared/templates/sql/sqlite/**
         apk: sqlite
         packages:
@@ -199,15 +191,15 @@ languages:
             version: "9.0.0"
       postgres:
         files:
-          - csharp/Dialects/PostgresDialect.cs
+          - csharp/Dialects/Postgres/**
           - shared/templates/sql/postgres/**
         apk: postgresql-client
         packages:
           - name: Npgsql
-            version: "9.0.1"
+            version: "9.0.2"
       mysql:
         files:
-          - csharp/Dialects/MysqlDialect.cs
+          - csharp/Dialects/Mysql/**
           - shared/templates/sql/mysql/**
         apk: mysql-client
         packages:
@@ -215,18 +207,18 @@ languages:
             version: "2.4.0"
       sqlserver:
         files:
-          - csharp/Dialects/SqlServerDialect.cs
+          - csharp/Dialects/SqlServer/**
           - shared/templates/sql/sqlserver/**
         packages:
           - name: Microsoft.Data.SqlClient
-            version: "6.0.1"
+            version: "6.0.2"
       oracle:
         files:
-          - csharp/Dialects/OracleDialect.cs
+          - csharp/Dialects/Oracle/**
           - shared/templates/sql/oracle/**
         packages:
           - name: Oracle.ManagedDataAccess.Core
-            version: "23.7.0"
+            version: "23.9.1"
     commands:
       setup: migrate-setup --provider {{provider}}
       up: migrate-up --provider {{provider}} --migrate-path {{migrationsPath}}

package/cli.yaml

@@ -14,6 +14,11 @@ providers:
   - sqlserver
   - oracle
 
+languages:
+  - typescript
+  - csharp
+  - rust
+
 # Lookup: lowercase, strip spaces/underscores/hyphens, then match a provider or alias.
 provider_aliases:
   sqlite3: sqlite
@@ -69,14 +74,19 @@ connection_environment:
 commands:
   - verb: init
     summary: |
-      Selects the dialects this tree will compile and install. Repeat --dialect
-      once per provider. Re-running replaces the previous set. --all restores
+      Selects the programming language and dialects this tree will compile and
+      install. --language is required. Repeat --dialect once per provider.
+      Re-running replaces the previous language and dialect set. --all restores
       every dialect. Does not take --connection.
     examples: |
-      {{command}} --dialect sqlite --dialect postgres
-      {{command}} --dialect oracle
-      {{command}} --all
+      {{command}} --language typescript --dialect sqlite --dialect postgres
+      {{command}} --language csharp --dialect sqlite
+      {{command}} --language rust --all
     args:
+      - flag: --language
+        placeholder: languages
+        required: true
+        help: "Programming language runner to install and build. typescript, csharp, or rust."
       - flag: --dialect
         placeholder: providers
         required: false
@@ -92,6 +102,9 @@ commands:
       and the migrations directory (mkdir -p). Idempotent — re-running against an
       already-setup database is a no-op. For sqlite, also mkdir -p of the parent
       directory of --connection so a fresh-tree path like ./.test/foo.sqlite works.
+      Pass --create-database to create the database named in --connection if it
+      does not exist (postgres, mysql, sqlserver). sqlite creates the file on
+      connect. oracle uses the existing service.
     examples: |
       # sqlite — bare path or sqlite:// URL; both create a file on disk.
       {{command}} --provider sqlite --connection ./app.sqlite
@@ -130,6 +143,9 @@ commands:
       - flag: --and-up
         required: false
         help: "After setup, immediately invoke migrate-up so the chain is applied in one step."
+      - flag: --create-database
+        required: false
+        help: "Create the database named in --connection if it does not exist."
 
   - verb: up
     show_connection_env: true
@@ -186,9 +202,8 @@ commands:
   - verb: down
     show_connection_env: true
     summary: |
-      Rolls back the MOST RECENTLY applied migration (one step). DESTRUCTIVE: prints a
-      random 4-letter uppercase token on stderr and refuses to proceed unless the
-      operator types it back on stdin (or passes --confirm <TOKEN> matching it).
+      Rolls back the MOST RECENTLY applied migration (one step). DESTRUCTIVE: refuses
+      to proceed unless the operator types confirm on stdin, or passes --confirm.
     examples: |
       # sqlite — bare path or sqlite:// URL.
       {{command}} --provider sqlite --connection ./app.sqlite
@@ -230,11 +245,8 @@ commands:
           Root prefix; the script then looks at <migrations-root>/<dialect>/migrations.
           Defaults to 'sql'. Ignored when --migrations-path is also set.
       - flag: --confirm
-        placeholder: TOKEN
         required: false
-        help: |
-          Skip the interactive prompt. The TOKEN must match the value
-          printed on stderr at runtime — there is no fixed bypass value.
+        help: Skip the interactive prompt.
 
   - verb: create
     summary: |

package/csharp/Abstractions/IConnectionResolver.cs

@@ -0,0 +1,6 @@
+namespace Deterministic.MigrateRunner;
+
+internal interface IConnectionResolver
+{
+    string? FromEnvironment(ISqlDialect dialect);
+}

package/csharp/Abstractions/IMigrateCommand.cs

@@ -0,0 +1,7 @@
+namespace Deterministic.MigrateRunner;
+
+internal interface IMigrateCommand
+{
+    string Name { get; }
+    Task<int> RunAsync(string[] args);
+}

package/csharp/Abstractions/IMigrater.cs

@@ -0,0 +1,20 @@
+namespace Deterministic.MigrateRunner;
+
+internal sealed record SetupArg(string Connection, string MigrationsPath);
+
+internal sealed record UpArg(string Connection, string MigrationsPath, bool One = false);
+
+internal sealed record DownArg(string Connection, string MigrationsPath);
+
+internal sealed record CreateArg(string Name, string MigrationsPath);
+
+internal sealed record CreateResponse(string UpName, string DownName);
+
+internal interface IMigrater
+{
+    string Name { get; }
+    Task Setup(SetupArg args);
+    Task<IReadOnlyList<string>> Up(UpArg args);
+    Task<string?> Down(DownArg args);
+    Task<CreateResponse> Create(CreateArg args);
+}

package/csharp/Abstractions/ISqlDialect.cs

@@ -0,0 +1,23 @@
+namespace Deterministic.MigrateRunner;
+
+public interface ISqlDialect
+{
+    string Name { get; }
+    IReadOnlyList<string> ConnectionEnvironmentVariables { get; }
+    string MigratesDdl { get; }
+    string MigrateLogsDdl { get; }
+    string SelectAppliedChecksumSql { get; }
+    string InsertAppliedSql { get; }
+    string DeleteAppliedSql { get; }
+    bool UseTransaction { get; }
+    string NowExpr { get; }
+    string LimitClause(int n);
+    string QuoteIdent(string ident);
+    string Placeholder(string name);
+    string NormalizeConnectionString(string connection);
+    DbConnection CreateConnection(string connectionString);
+    string? PrerequisiteError(string connection);
+    void PrepareSetup(string connection);
+    void AddParameter(DbCommand command, string name, object value);
+    Task CreateDatabaseIfMissingAsync(string connection);
+}

package/csharp/Abstractions/ISqlDialectFactory.cs

@@ -0,0 +1,7 @@
+namespace Deterministic.MigrateRunner;
+
+internal interface ISqlDialectFactory
+{
+    bool TryGet(string name, out ISqlDialect dialect);
+    IReadOnlyList<ISqlDialect> All();
+}

package/csharp/Abstractions/SqlDialect.cs

@@ -0,0 +1,78 @@
+namespace Deterministic.MigrateRunner;
+
+public sealed class SqlDialect : ISqlDialect
+{
+    private readonly Func<string, string> _normalize;
+    private readonly Func<string, DbConnection> _createConnection;
+    private readonly Action<DbCommand, string, object> _addParameter;
+    private readonly Func<string, string> _quoteIdent;
+    private readonly Func<string, string> _placeholder;
+    private readonly Func<string, string?>? _prerequisiteError;
+    private readonly Action<string>? _prepareSetup;
+    private readonly Func<string, Task>? _createDatabase;
+    private readonly Func<int, string> _limitClause;
+
+    public SqlDialect(
+        string name,
+        IReadOnlyList<string> connectionEnvironmentVariables,
+        bool useTransaction,
+        Func<string, string> normalizeConnectionString,
+        Func<string, DbConnection> createConnection,
+        Action<DbCommand, string, object> addParameter,
+        Func<string, string> quoteIdent,
+        Func<string, string> placeholder,
+        Func<string, string?>? prerequisiteError = null,
+        Action<string>? prepareSetup = null,
+        Func<string, Task>? createDatabase = null,
+        string nowExpr = "CURRENT_TIMESTAMP",
+        Func<int, string>? limitClause = null
+    )
+    {
+        Name = name;
+        ConnectionEnvironmentVariables = connectionEnvironmentVariables;
+        UseTransaction = useTransaction;
+        NowExpr = nowExpr;
+        _normalize = normalizeConnectionString;
+        _createConnection = createConnection;
+        _addParameter = addParameter;
+        _quoteIdent = quoteIdent;
+        _placeholder = placeholder;
+        _prerequisiteError = prerequisiteError;
+        _prepareSetup = prepareSetup;
+        _createDatabase = createDatabase;
+        _limitClause = limitClause ?? (n => $"LIMIT {n}");
+    }
+
+    public string Name { get; }
+    public IReadOnlyList<string> ConnectionEnvironmentVariables { get; }
+    public bool UseTransaction { get; }
+    public string NowExpr { get; }
+    public string MigratesDdl => SqlTemplates.Read(Name, "migrates");
+    public string MigrateLogsDdl => SqlTemplates.Read(Name, "migrate_logs");
+    public string SelectAppliedChecksumSql =>
+        $"SELECT {_quoteIdent("name")} AS name, {_quoteIdent("checksum")} AS checksum FROM {_quoteIdent("migrates")}";
+    public string InsertAppliedSql =>
+        $"INSERT INTO {_quoteIdent("migrates")} ({_quoteIdent("name")}, {_quoteIdent("checksum")}) VALUES ({_placeholder("p1")}, {_placeholder("p2")})";
+    public string DeleteAppliedSql =>
+        $"DELETE FROM {_quoteIdent("migrates")} WHERE {_quoteIdent("name")} = {_placeholder("p1")}";
+
+    public string LimitClause(int n) => _limitClause(n);
+    public string QuoteIdent(string ident) => _quoteIdent(ident);
+    public string Placeholder(string name) => _placeholder(name);
+    public string NormalizeConnectionString(string connection) => _normalize(connection);
+    public DbConnection CreateConnection(string connectionString) => _createConnection(connectionString);
+    public void AddParameter(DbCommand command, string name, object value) =>
+        _addParameter(command, name, value);
+    public string? PrerequisiteError(string connection) => _prerequisiteError?.Invoke(connection);
+    public void PrepareSetup(string connection) => _prepareSetup?.Invoke(connection);
+    public Task CreateDatabaseIfMissingAsync(string connection) =>
+        _createDatabase?.Invoke(connection) ?? Task.CompletedTask;
+
+    public static void Bind(DbCommand command, string parameterName, object value)
+    {
+        var p = command.CreateParameter();
+        p.ParameterName = parameterName;
+        p.Value = value;
+        command.Parameters.Add(p);
+    }
+}

package/csharp/Abstractions/SqlDialectFactory.cs

@@ -0,0 +1,24 @@
+namespace Deterministic.MigrateRunner;
+
+internal sealed class SqlDialectFactory(IEnumerable<ISqlDialect> dialects) : ISqlDialectFactory
+{
+    private readonly ISqlDialect[] _all =
+    [
+        .. CliSpec.Providers.Select(name => dialects.FirstOrDefault(d => d.Name == name)).OfType<ISqlDialect>(),
+    ];
+    private readonly IReadOnlyDictionary<string, ISqlDialect> _byName = dialects.ToDictionary(
+        d => d.Name,
+        StringComparer.Ordinal
+    );
+
+    public IReadOnlyList<ISqlDialect> All() => _all;
+
+    public bool TryGet(string name, out ISqlDialect dialect)
+    {
+        var key = MigrateCli.NormalizeProvider(name);
+        if (key is not null && _byName.TryGetValue(key, out dialect!))
+            return true;
+        dialect = null!;
+        return false;
+    }
+}

package/csharp/Dialects/Mysql/MigrateMysql.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <RootNamespace>Deterministic.MigrateRunner</RootNamespace>
+    <AssemblyName>MigrateMysql</AssemblyName>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\MigrateRunner.Core.csproj" />
+    <PackageReference Include="MySqlConnector" Version="2.4.0" />
+  </ItemGroup>
+</Project>

package/csharp/Dialects/Mysql/MysqlCreateDatabase.cs

@@ -0,0 +1,21 @@
+using MySqlConnector;
+
+namespace Deterministic.MigrateRunner;
+
+internal static class MysqlCreateDatabase
+{
+    public static async Task IfMissingAsync(string connection)
+    {
+        var normalized = MysqlDialect.Instance.NormalizeConnectionString(connection);
+        var b = new MySqlConnectionStringBuilder(normalized);
+        if (string.IsNullOrEmpty(b.Database))
+            return;
+        var name = b.Database;
+        b.Database = "";
+        await using var conn = new MySqlConnection(b.ConnectionString);
+        await conn.OpenAsync().ConfigureAwait(false);
+        await using var cmd = conn.CreateCommand();
+        cmd.CommandText = $"CREATE DATABASE IF NOT EXISTS `{name.Replace("`", "``")}`";
+        await cmd.ExecuteNonQueryAsync().ConfigureAwait(false);
+    }
+}

package/csharp/Dialects/Mysql/MysqlDialect.cs

@@ -0,0 +1,44 @@
+using MySqlConnector;
+
+namespace Deterministic.MigrateRunner;
+
+public static class MysqlDialect
+{
+    // MySQL DDL auto-commits, so wrapping apply + catalog write gives no atomicity.
+    public static readonly ISqlDialect Instance = new SqlDialect(
+        "mysql",
+        ["MYSQL_URL", "DATABASE_URL"],
+        useTransaction: false,
+        NormalizeConnection,
+        s => new MySqlConnection(s),
+        (cmd, n, v) => SqlDialect.Bind(cmd, $"@{n}", v),
+        ident => $"`{ident}`",
+        name => $"@{name}",
+        createDatabase: MysqlCreateDatabase.IfMissingAsync
+    );
+
+    private static string NormalizeConnection(string connection)
+    {
+        if (ConnectionStringUrl.TryUri(connection, "mysql") is not { } url)
+            return connection;
+        var uri = new Uri(url);
+        var b = new MySqlConnectionStringBuilder
+        {
+            Server = uri.Host,
+            Port = (uint)(uri.Port > 0 ? uri.Port : 3306),
+        };
+        ConnectionStringUrl.ApplyUriParts(
+            uri,
+            (u, p) =>
+            {
+                if (u is not null)
+                    b.UserID = u;
+                if (p is not null)
+                    b.Password = p;
+            },
+            db => b.Database = db,
+            (k, v) => b[k] = v
+        );
+        return b.ConnectionString;
+    }
+}