@deterministic-code/migraters 0.0.1 → 0.0.3

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;
+    }
+}

package/csharp/Dialects/Mysql/bin/Debug/net9.0/MigrateMysql.deps.json

@@ -0,0 +1,213 @@
+{
+  "runtimeTarget": {
+    "name": ".NETCoreApp,Version=v9.0",
+    "signature": ""
+  },
+  "compilationOptions": {},
+  "targets": {
+    ".NETCoreApp,Version=v9.0": {
+      "MigrateMysql/1.0.0": {
+        "dependencies": {
+          "MigrateCore": "1.0.0",
+          "MySqlConnector": "2.4.0",
+          "MigrateCore.Reference": "1.0.0.0"
+        },
+        "runtime": {
+          "MigrateMysql.dll": {}
+        }
+      },
+      "DotNetEnv/3.2.0": {
+        "dependencies": {
+          "Microsoft.Extensions.Configuration": "1.1.2",
+          "Microsoft.Extensions.Configuration.Abstractions": "1.1.2",
+          "Superpower": "3.0.0"
+        },
+        "runtime": {
+          "lib/netstandard2.0/DotNetEnv.dll": {
+            "assemblyVersion": "3.2.0.0",
+            "fileVersion": "3.2.0.0"
+          }
+        }
+      },
+      "Microsoft.Extensions.Configuration/1.1.2": {
+        "dependencies": {
+          "Microsoft.Extensions.Configuration.Abstractions": "1.1.2"
+        },
+        "runtime": {
+          "lib/netstandard1.1/Microsoft.Extensions.Configuration.dll": {
+            "assemblyVersion": "1.1.2.0",
+            "fileVersion": "1.1.2.30427"
+          }
+        }
+      },
+      "Microsoft.Extensions.Configuration.Abstractions/1.1.2": {
+        "dependencies": {
+          "Microsoft.Extensions.Primitives": "1.1.1"
+        },
+        "runtime": {
+          "lib/netstandard1.0/Microsoft.Extensions.Configuration.Abstractions.dll": {
+            "assemblyVersion": "1.1.2.0",
+            "fileVersion": "1.1.2.30427"
+          }
+        }
+      },
+      "Microsoft.Extensions.DependencyInjection/9.0.0": {
+        "dependencies": {
+          "Microsoft.Extensions.DependencyInjection.Abstractions": "9.0.0"
+        },
+        "runtime": {
+          "lib/net9.0/Microsoft.Extensions.DependencyInjection.dll": {
+            "assemblyVersion": "9.0.0.0",
+            "fileVersion": "9.0.24.52809"
+          }
+        }
+      },
+      "Microsoft.Extensions.DependencyInjection.Abstractions/9.0.0": {
+        "runtime": {
+          "lib/net9.0/Microsoft.Extensions.DependencyInjection.Abstractions.dll": {
+            "assemblyVersion": "9.0.0.0",
+            "fileVersion": "9.0.24.52809"
+          }
+        }
+      },
+      "Microsoft.Extensions.Logging.Abstractions/8.0.2": {
+        "dependencies": {
+          "Microsoft.Extensions.DependencyInjection.Abstractions": "9.0.0"
+        },
+        "runtime": {
+          "lib/net8.0/Microsoft.Extensions.Logging.Abstractions.dll": {
+            "assemblyVersion": "8.0.0.0",
+            "fileVersion": "8.0.1024.46610"
+          }
+        }
+      },
+      "Microsoft.Extensions.Primitives/1.1.1": {
+        "runtime": {
+          "lib/netstandard1.0/Microsoft.Extensions.Primitives.dll": {
+            "assemblyVersion": "1.1.1.0",
+            "fileVersion": "1.1.1.30427"
+          }
+        }
+      },
+      "MySqlConnector/2.4.0": {
+        "dependencies": {
+          "Microsoft.Extensions.DependencyInjection.Abstractions": "9.0.0",
+          "Microsoft.Extensions.Logging.Abstractions": "8.0.2"
+        },
+        "runtime": {
+          "lib/net9.0/MySqlConnector.dll": {
+            "assemblyVersion": "2.0.0.0",
+            "fileVersion": "2.4.0.0"
+          }
+        }
+      },
+      "Superpower/3.0.0": {
+        "runtime": {
+          "lib/net5.0/Superpower.dll": {
+            "assemblyVersion": "1.0.0.0",
+            "fileVersion": "3.0.0.0"
+          }
+        }
+      },
+      "MigrateCore/1.0.0": {
+        "dependencies": {
+          "DotNetEnv": "3.2.0",
+          "Microsoft.Extensions.DependencyInjection": "9.0.0"
+        },
+        "runtime": {
+          "MigrateCore.dll": {
+            "fileVersion": "0.0.0.0"
+          }
+        }
+      },
+      "MigrateCore.Reference/1.0.0.0": {
+        "runtime": {
+          "MigrateCore.dll": {
+            "assemblyVersion": "1.0.0.0",
+            "fileVersion": "1.0.0.0"
+          }
+        }
+      }
+    }
+  },
+  "libraries": {
+    "MigrateMysql/1.0.0": {
+      "type": "project",
+      "serviceable": false,
+      "sha512": ""
+    },
+    "DotNetEnv/3.2.0": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-2q+PD+aJcRW9QuRcIv4F8WbvEDxI6cwxzZJec2i45cBY4cAKCAoW4ZPkApJ7H82wr6Yfmxx/0kb1nLnRmZrGZA==",
+      "path": "dotnetenv/3.2.0",
+      "hashPath": "dotnetenv.3.2.0.nupkg.sha512"
+    },
+    "Microsoft.Extensions.Configuration/1.1.2": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-eK5BHx/pHLGGO/WDo7CS070MGgx3N7B/ORO/oKeS0qgCyv+ZAR47YWKXmG5aF+lIrAJd3uJjMTdTKgXTU2UDWw==",
+      "path": "microsoft.extensions.configuration/1.1.2",
+      "hashPath": "microsoft.extensions.configuration.1.1.2.nupkg.sha512"
+    },
+    "Microsoft.Extensions.Configuration.Abstractions/1.1.2": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-I1BRk2OCjOondHFc0flHFMxLTbsOPQdB0CxexkZOHcAD1oAWC2KcpxvmmQ07kLUcYKbtSdtvPkm7YPdw8bdJ9Q==",
+      "path": "microsoft.extensions.configuration.abstractions/1.1.2",
+      "hashPath": "microsoft.extensions.configuration.abstractions.1.1.2.nupkg.sha512"
+    },
+    "Microsoft.Extensions.DependencyInjection/9.0.0": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-MCPrg7v3QgNMr0vX4vzRXvkNGgLg8vKWX0nKCWUxu2uPyMsaRgiRc1tHBnbTcfJMhMKj2slE/j2M9oGkd25DNw==",
+      "path": "microsoft.extensions.dependencyinjection/9.0.0",
+      "hashPath": "microsoft.extensions.dependencyinjection.9.0.0.nupkg.sha512"
+    },
+    "Microsoft.Extensions.DependencyInjection.Abstractions/9.0.0": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-+6f2qv2a3dLwd5w6JanPIPs47CxRbnk+ZocMJUhv9NxP88VlOcJYZs9jY+MYSjxvady08bUZn6qgiNh7DadGgg==",
+      "path": "microsoft.extensions.dependencyinjection.abstractions/9.0.0",
+      "hashPath": "microsoft.extensions.dependencyinjection.abstractions.9.0.0.nupkg.sha512"
+    },
+    "Microsoft.Extensions.Logging.Abstractions/8.0.2": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-nroMDjS7hNBPtkZqVBbSiQaQjWRDxITI8Y7XnDs97rqG3EbzVTNLZQf7bIeUJcaHOV8bca47s1Uxq94+2oGdxA==",
+      "path": "microsoft.extensions.logging.abstractions/8.0.2",
+      "hashPath": "microsoft.extensions.logging.abstractions.8.0.2.nupkg.sha512"
+    },
+    "Microsoft.Extensions.Primitives/1.1.1": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-MrsHOyFpwT+LBzGWp/Oq3pV1Vku8FYE6hgO+2XR0WBRtoI9EaJcpRbtBabS7pXYrkIN1/LOXACpZ9Stqmbrs6A==",
+      "path": "microsoft.extensions.primitives/1.1.1",
+      "hashPath": "microsoft.extensions.primitives.1.1.1.nupkg.sha512"
+    },
+    "MySqlConnector/2.4.0": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-78M+gVOjbdZEDIyXQqcA7EYlCGS3tpbUELHvn6638A2w0pkPI625ixnzsa5staAd3N9/xFmPJtkKDYwsXpFi/w==",
+      "path": "mysqlconnector/2.4.0",
+      "hashPath": "mysqlconnector.2.4.0.nupkg.sha512"
+    },
+    "Superpower/3.0.0": {
+      "type": "package",
+      "serviceable": true,
+      "sha512": "sha512-bjKbAYWePooCAvPxQq+3KnmcLfRggMyRoXmtBMlmCG71bdwBHrO6rmRJ2DRIodg5aztNcxeZXBUVWT+H+MZUhw==",
+      "path": "superpower/3.0.0",
+      "hashPath": "superpower.3.0.0.nupkg.sha512"
+    },
+    "MigrateCore/1.0.0": {
+      "type": "project",
+      "serviceable": false,
+      "sha512": ""
+    },
+    "MigrateCore.Reference/1.0.0.0": {
+      "type": "reference",
+      "serviceable": false,
+      "sha512": ""
+    }
+  }
+}

package/csharp/Dialects/Mysql/bin/Debug/net9.0/cli.yaml

@@ -0,0 +1,276 @@
+# Source of truth for migrate command names, argv layout, and --help copy.
+# TypeScript, Rust, and C# parsers must match this file.
+# IMigrater (setup, up, down, create) lives in api.yaml. SQL spelling is a provider detail.
+# Help templates in shared/templates/help are generated:
+#   npm run generate:help
+# Usage line for each verb: `Usage: migrate-<verb> ` + args in order.
+
+command: migrate-{verb}
+
+providers:
+  - sqlite
+  - postgres
+  - mysql
+  - sqlserver
+  - oracle
+
+languages:
+  - typescript
+  - csharp
+  - rust
+
+# Lookup: lowercase, strip spaces/underscores/hyphens, then match a provider or alias.
+provider_aliases:
+  sqlite3: sqlite
+  mariadb: mysql
+  postgresql: postgres
+  pg: postgres
+  mssql: sqlserver
+  mssqlserver: sqlserver
+  ora: oracle
+
+exit_codes:
+  success: 0
+  usage: 2
+  runtime: 1
+
+help:
+  - -h
+  - --help
+
+help_stream: stderr
+
+# Canonical argv is `--flag value`. `--flag=value` is optional extra syntax.
+aliases:
+  --migrate-path: --migrations-path
+  --migrate-root: --migrations-root
+
+env_var_list_separator: " / "
+
+migrations:
+  path_flag: --migrations-path
+  root_flag: --migrations-root
+  root_default: sql
+  layout: "<root>/<provider>/migrations"
+  discovery: top_level_up_down_pairs
+  missing_directory: errors/migrate-path-not-dir
+
+create:
+  name_pattern: "^[a-z][a-z0-9_]*$"
+  sequence_digits: 4
+
+checksum:
+  algorithm: sha256
+  drift_bypass: MIGRATE_ALLOW_CHECKSUM_DRIFT
+
+# Documented when a command sets show_connection_env: true.
+connection_environment:
+  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]
+
+commands:
+  - verb: init
+    summary: |
+      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}} --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
+        help: "Dialect to enable. Repeat for each dialect. Aliases from this file apply."
+      - flag: --all
+        required: false
+        help: "Enable every dialect. Restores the committed full-provider set."
+
+  - verb: setup
+    show_connection_env: true
+    summary: |
+      Creates the bookkeeping tables (migrates, migrate_logs) for the chosen dialect
+      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
+      {{command}} --provider sqlite --connection sqlite:///absolute/path/app.sqlite
+
+      # postgres — URL or keyword form.
+      {{command}} --provider postgres --connection postgresql://user:pass@host:5432/dbname
+
+      # mysql — URL form.
+      {{command}} --provider mysql --connection mysql://user:pass@host:3306/dbname
+
+      # sqlserver / oracle — pass a driver-native connection string.
+      {{command}} --provider sqlserver --connection "Server=host;Database=dbname;User Id=user;Password=pass;"
+      {{command}} --provider oracle   --connection "user/pass@host:1521/service"
+
+      # env-var fallback when --connection is omitted:
+      SQLITE_PATH=./app.sqlite       {{command}} --provider sqlite
+      DATABASE_URL=postgresql://...  {{command}} --provider postgres
+      DATABASE_URL=mysql://...       {{command}} --provider mysql
+
+      # explicit in-memory sqlite:
+      {{command}} --provider sqlite --connection :memory:
+    args:
+      - flag: --provider
+        placeholder: providers
+        required: true
+        help: "Database dialect. Required."
+      - flag: --connection
+        placeholder: url
+        required: true
+        help: "Connection string. Required (or set the per-dialect env var below)."
+      - flag: --migrations-path
+        placeholder: dir
+        required: false
+        help: "Migrations directory (default: ./sql/<dialect>/migrations)."
+      - 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
+    summary: |
+      Applies ALL pending migrations in sequence, each in its own transaction.
+    examples: |
+      # sqlite — bare path or sqlite:// URL; both create a file on disk.
+      {{command}} --provider sqlite --connection ./app.sqlite
+      {{command}} --provider sqlite --connection sqlite:///absolute/path/app.sqlite
+
+      # postgres — URL or keyword form.
+      {{command}} --provider postgres --connection postgresql://user:pass@host:5432/dbname
+
+      # mysql — URL form.
+      {{command}} --provider mysql --connection mysql://user:pass@host:3306/dbname
+
+      # sqlserver / oracle — pass a driver-native connection string.
+      {{command}} --provider sqlserver --connection "Server=host;Database=dbname;User Id=user;Password=pass;"
+      {{command}} --provider oracle   --connection "user/pass@host:1521/service"
+
+      # env-var fallback when --connection is omitted:
+      SQLITE_PATH=./app.sqlite       {{command}} --provider sqlite
+      DATABASE_URL=postgresql://...  {{command}} --provider postgres
+
+      # custom migrations layout (default looks under sql/<dialect>/migrations):
+      {{command}} --provider sqlite --connection ./app.sqlite --migrations-path ./db/changes/sqlite
+      {{command}} --provider sqlite --connection ./app.sqlite --migrations-root ./db/changes
+
+      # one-shot: apply the next pending migration only, then exit.
+      {{command}} --provider sqlite --connection ./app.sqlite --one
+    args:
+      - flag: --provider
+        placeholder: providers
+        required: true
+        help: "Database dialect. Required."
+      - flag: --connection
+        placeholder: url
+        required: true
+        help: "Connection string. Required (or set the per-dialect env var below)."
+      - flag: --migrations-path
+        placeholder: dir
+        required: false
+        help: "Full path to the migrations directory (e.g. sql/sqlite/migrations)."
+      - flag: --migrations-root
+        placeholder: dir
+        required: false
+        help: |
+          Root prefix; the script then looks at <migrations-root>/<dialect>/migrations.
+          Defaults to 'sql'. Ignored when --migrations-path is also set.
+      - flag: --one
+        required: false
+        help: "Apply only the next pending migration, then exit. Default is to apply all pending migrations."
+
+  - verb: down
+    show_connection_env: true
+    summary: |
+      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
+      {{command}} --provider sqlite --connection sqlite:///absolute/path/app.sqlite
+
+      # postgres — URL or keyword form.
+      {{command}} --provider postgres --connection postgresql://user:pass@host:5432/dbname
+
+      # mysql — URL form.
+      {{command}} --provider mysql --connection mysql://user:pass@host:3306/dbname
+
+      # sqlserver / oracle — pass a driver-native connection string.
+      {{command}} --provider sqlserver --connection "Server=host;Database=dbname;User Id=user;Password=pass;"
+      {{command}} --provider oracle   --connection "user/pass@host:1521/service"
+
+      # env-var fallback when --connection is omitted:
+      SQLITE_PATH=./app.sqlite       {{command}} --provider sqlite
+      DATABASE_URL=postgresql://...  {{command}} --provider postgres
+
+      # custom migrations layout (default looks under sql/<dialect>/migrations):
+      {{command}} --provider sqlite --connection ./app.sqlite --migrations-path ./db/changes/sqlite
+    args:
+      - flag: --provider
+        placeholder: providers
+        required: true
+        help: "Database dialect. Required."
+      - flag: --connection
+        placeholder: url
+        required: true
+        help: "Connection string. Required (or set the per-dialect env var below)."
+      - flag: --migrations-path
+        placeholder: dir
+        required: false
+        help: "Full path to the migrations directory."
+      - flag: --migrations-root
+        placeholder: dir
+        required: false
+        help: |
+          Root prefix; the script then looks at <migrations-root>/<dialect>/migrations.
+          Defaults to 'sql'. Ignored when --migrations-path is also set.
+      - flag: --confirm
+        required: false
+        help: Skip the interactive prompt.
+
+  - verb: create
+    summary: |
+      Creates a new <NNNN>_<name>_up.sql + <NNNN>_<name>_down.sql pair scaffolded
+      with TODO placeholders. NNNN is one greater than the highest 1-4-digit
+      sequence prefix already present in the migrations directory (starts at 0001).
+      Legacy timestamp-prefixed filenames are ignored for numbering.
+    examples: |
+      {{command}} --provider sqlite --name add_users
+      {{command}} --provider postgres --name backfill_email_lower --migrations-path ./db/changes/postgres
+    args:
+      - flag: --provider
+        placeholder: providers
+        required: true
+        help: "Database dialect. Required."
+      - flag: --name
+        placeholder: snake_case_slug
+        required: true
+        help: |
+          snake_case slug for the new migration. Required. Must
+          match /^[a-z][a-z0-9_]*$/.
+      - flag: --migrations-path
+        placeholder: dir
+        required: false
+        help: |
+          Migrations directory (default: ./sql/<dialect>/migrations).
+          Created with mkdir -p if it does not exist.