@deterministic-code/migraters 0.0.1 → 0.0.3

package/csharp/Infrastructure/MigrateCli.cs

@@ -0,0 +1,159 @@
+namespace Deterministic.MigrateRunner;
+
+internal static class MigrateCli
+{
+    internal static readonly string[] Verbs = ["setup", "up", "down", "create"];
+
+    internal static string? VerbFromHost()
+    {
+        string?[] candidates = [Environment.ProcessPath, Environment.GetCommandLineArgs()[0]];
+        foreach (var raw in candidates)
+        {
+            if (string.IsNullOrEmpty(raw))
+                continue;
+            var name = Path.GetFileNameWithoutExtension(raw);
+            if (!name.StartsWith("migrate-", StringComparison.OrdinalIgnoreCase))
+                continue;
+            var verb = name["migrate-".Length..].ToLowerInvariant();
+            if (Verbs.Contains(verb))
+                return verb;
+        }
+        return null;
+    }
+
+    internal static string NormalizeVerb(string sub)
+    {
+        if (sub.StartsWith("migrate-", StringComparison.OrdinalIgnoreCase))
+            sub = sub["migrate-".Length..];
+        return sub.ToLowerInvariant();
+    }
+    internal static bool TryResolveProvider(
+        ISqlDialectFactory dialects,
+        IConnectionResolver connections,
+        string provider,
+        string? connection,
+        out ISqlDialect dialect,
+        out string resolvedConnection,
+        out string error
+    )
+    {
+        dialect = null!;
+        resolvedConnection = connection ?? string.Empty;
+        error = string.Empty;
+        if (!dialects.TryGet(provider, out dialect))
+            return Fail(
+                HelpTemplates.Message(
+                    "errors/unsupported-provider",
+                    new Dictionary<string, string> { ["provider"] = provider }
+                ),
+                out error
+            );
+        if (string.IsNullOrEmpty(resolvedConnection))
+            resolvedConnection = connections.FromEnvironment(dialect) ?? string.Empty;
+        if (string.IsNullOrEmpty(resolvedConnection))
+        {
+            return Fail(
+                HelpTemplates.Message(
+                    "errors/missing-connection",
+                    new Dictionary<string, string>
+                    {
+                        ["envVars"] = EnvVarsList(dialect.ConnectionEnvironmentVariables),
+                    }
+                ),
+                out error
+            );
+        }
+        return true;
+    }
+
+    internal static string MigratePath(string provider, string? migratePath, string? migrateRoot) =>
+        string.IsNullOrEmpty(migratePath) ? $"{migrateRoot ?? "sql"}/{provider}/migrations" : migratePath;
+
+    internal static bool TryTakeFlag(
+        string[] args,
+        ref int i,
+        string current,
+        string flag,
+        out string value
+    )
+    {
+        if (current == flag)
+        {
+            if (i + 1 >= args.Length)
+            {
+                value = string.Empty;
+                return false;
+            }
+            value = args[++i];
+            return true;
+        }
+        var eq = flag + "=";
+        if (!current.StartsWith(eq, StringComparison.Ordinal))
+        {
+            value = string.Empty;
+            return false;
+        }
+        value = current[eq.Length..];
+        return true;
+    }
+
+    internal static string? NormalizeProvider(string raw)
+    {
+        var key = CliSpec.StripKey(raw);
+        foreach (var provider in CliSpec.Providers)
+        {
+            if (CliSpec.StripKey(provider) == key)
+                return provider;
+        }
+        return CliSpec.ProviderAliases.TryGetValue(key, out var canonical) ? canonical : null;
+    }
+
+    internal static string EnvVarsList(IEnumerable<string> vars) =>
+        string.Join(CliSpec.EnvVarListSeparator, vars);
+
+    internal static bool MissingProvider(out string error)
+    {
+        error = HelpTemplates.Message("errors/missing-provider");
+        return false;
+    }
+
+    internal static bool MissingName(out string error)
+    {
+        error = HelpTemplates.Message("errors/missing-name");
+        return false;
+    }
+
+    internal static bool IsValueFlag(string arg)
+    {
+        ReadOnlySpan<string> flags =
+        [
+            "--provider",
+            "--connection",
+            "--migrations-path",
+            "--migrate-path",
+            "--migrations-root",
+            "--migrate-root",
+            "--name",
+        ];
+        foreach (var flag in flags)
+        {
+            if (arg == flag || arg.StartsWith(flag + "=", StringComparison.Ordinal))
+                return true;
+        }
+        return false;
+    }
+
+    internal static string ParseArgError(string arg, bool missingValue) =>
+        missingValue
+            ? HelpTemplates.Message(
+                "errors/missing-value-for-flag",
+                new Dictionary<string, string> { ["flag"] = arg }
+            )
+            : HelpTemplates.Message("errors/unknown-arg", new Dictionary<string, string> { ["arg"] = arg });
+
+    private static bool Fail(string message, out string error)
+    {
+        error = message;
+        return false;
+    }
+}

package/csharp/Infrastructure/MigrateLog.cs

@@ -0,0 +1,54 @@
+namespace Deterministic.MigrateRunner;
+
+internal static class MigrateLog
+{
+    public static async Task<long> InsertStartedAsync(
+        DbConnection conn,
+        ISqlDialect dialect,
+        string name,
+        string direction
+    )
+    {
+        var t = dialect.QuoteIdent("migrate_logs");
+        var insert =
+            $"INSERT INTO {t} ({dialect.QuoteIdent("migrate_name")}, {dialect.QuoteIdent("direction")}, {dialect.QuoteIdent("status")}) VALUES ({dialect.Placeholder("p1")}, {dialect.Placeholder("p2")}, 'started')";
+        await DbExecute.CatalogWriteAsync(conn, null, dialect, insert, ("p1", name), ("p2", direction))
+            .ConfigureAwait(false);
+
+        var select =
+            $"SELECT {dialect.QuoteIdent("id")} AS id FROM {t} WHERE {dialect.QuoteIdent("migrate_name")} = {dialect.Placeholder("p1")} AND {dialect.QuoteIdent("direction")} = {dialect.Placeholder("p2")} ORDER BY {dialect.QuoteIdent("id")} DESC {dialect.LimitClause(1)}";
+        using var cmd = conn.CreateCommand();
+        cmd.CommandText = select;
+        dialect.AddParameter(cmd, "p1", name);
+        dialect.AddParameter(cmd, "p2", direction);
+        var value = await cmd.ExecuteScalarAsync().ConfigureAwait(false);
+        return Convert.ToInt64(value, CultureInfo.InvariantCulture);
+    }
+
+    public static async Task UpdateAsync(
+        DbConnection conn,
+        ISqlDialect dialect,
+        long id,
+        string status,
+        long durationMs,
+        string? errorMessage
+    )
+    {
+        var t = dialect.QuoteIdent("migrate_logs");
+        var now = dialect.NowExpr;
+        var sql =
+            $"UPDATE {t} SET {dialect.QuoteIdent("status")} = {dialect.Placeholder("p1")}, {dialect.QuoteIdent("finished_at")} = {now}, {dialect.QuoteIdent("duration_ms")} = {dialect.Placeholder("p2")}, {dialect.QuoteIdent("error_message")} = {dialect.Placeholder("p3")}, {dialect.QuoteIdent("updated")} = {now} WHERE {dialect.QuoteIdent("id")} = {dialect.Placeholder("p4")}";
+        await DbExecute
+            .CatalogWriteAsync(
+                conn,
+                null,
+                dialect,
+                sql,
+                ("p1", status),
+                ("p2", durationMs),
+                ("p3", (object?)errorMessage ?? DBNull.Value),
+                ("p4", id)
+            )
+            .ConfigureAwait(false);
+    }
+}

package/csharp/Infrastructure/Migrater.cs

@@ -0,0 +1,157 @@
+namespace Deterministic.MigrateRunner;
+
+internal sealed class Migrater(ISqlDialect dialect) : IMigrater
+{
+    public string Name => dialect.Name;
+
+    public async Task Setup(SetupArg args)
+    {
+        dialect.PrepareSetup(args.Connection);
+        await using var conn = dialect.CreateConnection(dialect.NormalizeConnectionString(args.Connection));
+        await conn.OpenAsync().ConfigureAwait(false);
+        await DbExecute.NonQueryAsync(conn, null, dialect.MigratesDdl).ConfigureAwait(false);
+        await DbExecute.NonQueryAsync(conn, null, dialect.MigrateLogsDdl).ConfigureAwait(false);
+        Directory.CreateDirectory(args.MigrationsPath);
+    }
+
+    public async Task<IReadOnlyList<string>> Up(UpArg args)
+    {
+        await using var conn = dialect.CreateConnection(dialect.NormalizeConnectionString(args.Connection));
+        await conn.OpenAsync().ConfigureAwait(false);
+
+        var files = Migrations.OrderedUpFiles(args.MigrationsPath);
+        var applied = await Migrations.AppliedChecksumsAsync(conn, dialect.SelectAppliedChecksumSql).ConfigureAwait(false);
+        Migrations.AssertNoChecksumDrift(files, applied);
+        var names = new List<string>();
+        while (true)
+        {
+            var next = files.FirstOrDefault(f => !applied.ContainsKey(f.Name));
+            if (next is null)
+                return names;
+
+            var sql = await File.ReadAllTextAsync(next.UpPath).ConfigureAwait(false);
+            var checksum = Checksum.Hex(sql);
+            var logId = await MigrateLog.InsertStartedAsync(conn, dialect, next.Name, "up").ConfigureAwait(false);
+            var started = DateTime.UtcNow;
+            try
+            {
+                await DbExecute
+                    .ApplyStatementsAsync(
+                        conn,
+                        dialect,
+                        sql,
+                        tx =>
+                            DbExecute.CatalogWriteAsync(
+                                conn,
+                                tx,
+                                dialect,
+                                dialect.InsertAppliedSql,
+                                ("p1", next.Name),
+                                ("p2", checksum)
+                            )
+                    )
+                    .ConfigureAwait(false);
+                await MigrateLog
+                    .UpdateAsync(conn, dialect, logId, "success", (long)(DateTime.UtcNow - started).TotalMilliseconds, null)
+                    .ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                await MigrateLog
+                    .UpdateAsync(conn, dialect, logId, "error", (long)(DateTime.UtcNow - started).TotalMilliseconds, ex.Message)
+                    .ConfigureAwait(false);
+                throw;
+            }
+
+            applied[next.Name] = checksum;
+            names.Add(next.Name);
+            if (args.One)
+                return names;
+        }
+    }
+
+    public async Task<string?> Down(DownArg args)
+    {
+        await using var conn = dialect.CreateConnection(dialect.NormalizeConnectionString(args.Connection));
+        await conn.OpenAsync().ConfigureAwait(false);
+
+        var files = Migrations.OrderedUpFiles(args.MigrationsPath);
+        var applied = await Migrations.AppliedChecksumsAsync(conn, dialect.SelectAppliedChecksumSql).ConfigureAwait(false);
+        if (applied.Count == 0)
+            return null;
+        Migrations.AssertNoChecksumDrift(files, applied);
+        var last = files.LastOrDefault(f => applied.ContainsKey(f.Name));
+        if (last is null)
+            throw new InvalidOperationException(HelpTemplates.Message("errors/rollback-not-in-path"));
+
+        var path =
+            Migrations.DownPathFor(args.MigrationsPath, last.Name)
+            ?? throw new FileNotFoundException(
+                HelpTemplates.Message(
+                    "errors/rollback-no-down-sibling",
+                    new Dictionary<string, string> { ["name"] = last.Name }
+                )
+            );
+        var sql = await File.ReadAllTextAsync(path).ConfigureAwait(false);
+        var logId = await MigrateLog.InsertStartedAsync(conn, dialect, last.Name, "down").ConfigureAwait(false);
+        var started = DateTime.UtcNow;
+        try
+        {
+            await DbExecute
+                .ApplyStatementsAsync(
+                    conn,
+                    dialect,
+                    sql,
+                    tx =>
+                        DbExecute.CatalogWriteAsync(
+                            conn,
+                            tx,
+                            dialect,
+                            dialect.DeleteAppliedSql,
+                            ("p1", last.Name)
+                        )
+                )
+                .ConfigureAwait(false);
+            await MigrateLog
+                .UpdateAsync(conn, dialect, logId, "success", (long)(DateTime.UtcNow - started).TotalMilliseconds, null)
+                .ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            await MigrateLog
+                .UpdateAsync(conn, dialect, logId, "error", (long)(DateTime.UtcNow - started).TotalMilliseconds, ex.Message)
+                .ConfigureAwait(false);
+            throw;
+        }
+
+        return last.Name;
+    }
+
+    public Task<CreateResponse> Create(CreateArg args)
+    {
+        if (!Migrations.IsMigrationName(args.Name))
+            throw new InvalidOperationException(
+                HelpTemplates.Message("errors/invalid-name", new Dictionary<string, string> { ["name"] = args.Name })
+            );
+        Directory.CreateDirectory(args.MigrationsPath);
+        var prefix = NextSequenceFromDir(args.MigrationsPath).ToString("D4", CultureInfo.InvariantCulture);
+        var upName = $"{prefix}_{args.Name}_up.sql";
+        var downName = $"{prefix}_{args.Name}_down.sql";
+        File.WriteAllText(
+            Path.Combine(args.MigrationsPath, upName),
+            HelpTemplates.Scaffold("up", new Dictionary<string, string> { ["name"] = args.Name })
+        );
+        File.WriteAllText(
+            Path.Combine(args.MigrationsPath, downName),
+            HelpTemplates.Scaffold("down", new Dictionary<string, string> { ["name"] = args.Name })
+        );
+        return Task.FromResult(new CreateResponse(upName, downName));
+    }
+
+    private static int NextSequenceFromDir(string dir) =>
+        !Directory.Exists(dir)
+            ? 1
+            : Migrations.NextSequence(
+                Directory.EnumerateFiles(dir).Select(Path.GetFileName).OfType<string>()
+            );
+}

package/csharp/Infrastructure/Migrations.cs

@@ -0,0 +1,105 @@
+namespace Deterministic.MigrateRunner;
+
+internal sealed record MigrationFile(string Name, string UpPath);
+
+internal static class Migrations
+{
+    private static readonly Regex NameRe = new("^[a-z][a-z0-9_]*$", RegexOptions.Compiled);
+    private static readonly Regex SeqRe = new(@"^(\d{1,4})_.*_up\.sql$", RegexOptions.Compiled);
+
+    public static bool IsMigrationName(string name) => NameRe.IsMatch(name);
+
+    public static int NextSequence(IEnumerable<string> fileNames) =>
+        fileNames
+            .Select(f => SeqRe.Match(f))
+            .Where(m => m.Success)
+            .Select(m => int.Parse(m.Groups[1].Value, CultureInfo.InvariantCulture))
+            .DefaultIfEmpty(0)
+            .Max() + 1;
+
+    public static IReadOnlyList<MigrationFile> OrderedUpFiles(string migratePath)
+    {
+        if (!Directory.Exists(migratePath))
+            throw new DirectoryNotFoundException(
+                HelpTemplates.Message(
+                    "errors/migrate-path-not-dir",
+                    new Dictionary<string, string> { ["path"] = migratePath }
+                )
+            );
+        return Directory
+            .EnumerateFiles(migratePath)
+            .Where(p => Path.GetFileName(p).EndsWith("_up.sql", StringComparison.Ordinal))
+            .OrderBy(p => Path.GetFileName(p), StringComparer.Ordinal)
+            .Select(p =>
+            {
+                var file = Path.GetFileName(p);
+                return new MigrationFile(file[..^"_up.sql".Length], p);
+            })
+            .ToList();
+    }
+
+    public static string CatalogName(string stored) =>
+        stored.EndsWith("_up.sql", StringComparison.Ordinal) ? stored[..^"_up.sql".Length] : stored;
+
+    public static async Task<Dictionary<string, string?>> AppliedChecksumsAsync(
+        DbConnection conn,
+        string sql
+    )
+    {
+        var map = new Dictionary<string, string?>(StringComparer.Ordinal);
+        using var cmd = conn.CreateCommand();
+        cmd.CommandText = sql;
+        using var reader = await cmd.ExecuteReaderAsync().ConfigureAwait(false);
+        while (await reader.ReadAsync().ConfigureAwait(false))
+        {
+            var name = CatalogName(reader.GetString(0));
+            var checksum = reader.IsDBNull(1) ? null : reader.GetString(1);
+            map[name] = checksum;
+        }
+        return map;
+    }
+
+    public static void AssertNoChecksumDrift(
+        IReadOnlyList<MigrationFile> files,
+        IReadOnlyDictionary<string, string?> applied
+    )
+    {
+        if (Environment.GetEnvironmentVariable("MIGRATE_ALLOW_CHECKSUM_DRIFT") == "1")
+            return;
+        var lines = new List<string>();
+        foreach (var file in files)
+        {
+            if (!applied.TryGetValue(file.Name, out var stored) || stored is null)
+                continue;
+            var current = Checksum.Hex(File.ReadAllText(file.UpPath));
+            if (current == stored)
+                continue;
+            lines.Add(
+                HelpTemplates
+                    .Message(
+                        "checksum-drift-line",
+                        new Dictionary<string, string>
+                        {
+                            ["name"] = file.Name,
+                            ["stored"] = stored.Length <= 12 ? stored : stored[..12],
+                            ["current"] = current.Length <= 12 ? current : current[..12],
+                        }
+                    )
+                    .TrimEnd()
+            );
+        }
+        if (lines.Count == 0)
+            return;
+        throw new InvalidOperationException(
+            HelpTemplates
+                .Message("checksum-drift", new Dictionary<string, string> { ["lines"] = string.Join('\n', lines) })
+                .TrimEnd()
+        );
+    }
+
+    public static string? DownPathFor(string migratePath, string name)
+    {
+        var path = Path.Combine(migratePath, $"{name}_down.sql");
+        return File.Exists(path) ? path : null;
+    }
+}

package/csharp/Infrastructure/SqlTemplates.cs

@@ -0,0 +1,10 @@
+namespace Deterministic.MigrateRunner;
+
+internal static class SqlTemplates
+{
+    public static string Read(string dialect, string name) =>
+        File.ReadAllText(
+                Path.Combine(AppContext.BaseDirectory, "templates", "sql", dialect, $"{name}.sql")
+            )
+            .Trim();
+}

package/csharp/MigrateCreate.cs

@@ -0,0 +1,114 @@
+// Scaffolds a new <NNNN>_<name>_{up,down}.sql pair in the migrations directory. Numbering is max(1-4-digit prefix in dir)+1; legacy timestamp prefixes are ignored.
+
+namespace Deterministic.MigrateRunner;
+
+internal sealed class MigrateCreate(ISqlDialectFactory dialects) : IMigrateCommand
+{
+    private static readonly string HelpText = HelpTemplates.Read("create");
+
+    public string Name => "create";
+
+    public async Task<int> RunAsync(string[] args)
+    {
+        if (!TryParse(args, out var provider, out var name, out var migrationsPath, out var showHelp, out var error))
+            return showHelp ? WriteHelp() : Fail(error);
+
+        if (!dialects.TryGet(provider, out var dialect))
+            return Fail(
+                HelpTemplates.Message(
+                    "errors/unsupported-provider",
+                    new Dictionary<string, string> { ["provider"] = provider }
+                )
+            );
+
+        var dir = migrationsPath ?? $"./sql/{dialect.Name}/migrations";
+        try
+        {
+            var created = await new Migrater(dialect).Create(new CreateArg(name, dir)).ConfigureAwait(false);
+            Console.WriteLine(
+                HelpTemplates.Message("status/created", new Dictionary<string, string> { ["file"] = created.UpName })
+            );
+            Console.WriteLine(
+                HelpTemplates.Message("status/created", new Dictionary<string, string> { ["file"] = created.DownName })
+            );
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            return Fail($"migrate-create failed: {ex.Message}", 1);
+        }
+    }
+
+    private static bool TryParse(
+        string[] args,
+        out string provider,
+        out string name,
+        out string? migrationsPath,
+        out bool showHelp,
+        out string error
+    )
+    {
+        provider = string.Empty;
+        name = string.Empty;
+        migrationsPath = null;
+        showHelp = false;
+        error = string.Empty;
+
+        for (var i = 0; i < args.Length; i++)
+        {
+            var a = args[i];
+            if (a is "-h" or "--help")
+            {
+                showHelp = true;
+                return false;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--provider", out var takenProvider))
+            {
+                provider = takenProvider;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--name", out var takenName))
+            {
+                name = takenName;
+                continue;
+            }
+            if (MigrateCli.TryTakeFlag(args, ref i, a, "--migrations-path", out var takenPath)
+                || MigrateCli.TryTakeFlag(args, ref i, a, "--migrate-path", out takenPath))
+            {
+                migrationsPath = takenPath;
+                continue;
+            }
+
+            error = MigrateCli.ParseArgError(a, MigrateCli.IsValueFlag(a) && i + 1 >= args.Length);
+            return false;
+        }
+
+        if (string.IsNullOrEmpty(provider))
+            return MigrateCli.MissingProvider(out error);
+        if (string.IsNullOrEmpty(name))
+            return MigrateCli.MissingName(out error);
+        if (!Migrations.IsMigrationName(name))
+        {
+            error = HelpTemplates.Message(
+                "errors/invalid-name",
+                new Dictionary<string, string> { ["name"] = name }
+            );
+            return false;
+        }
+        return true;
+    }
+
+    private static int WriteHelp()
+    {
+        Console.Error.Write(HelpText);
+        return 0;
+    }
+
+    private static int Fail(string error, int code = 2)
+    {
+        Console.Error.WriteLine(error);
+        if (code == 2)
+            Console.Error.Write(HelpText);
+        return code;
+    }
+}