SqlMigration.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "Api.hpp"
#include "DataMapper/DataMapper.hpp"
#include "ProgressTask.hpp"
#include "SqlError.hpp"
#include "SqlQuery/Migrate.hpp"
#include "SqlQuery/MigrationPlan.hpp"
#include "SqlSchema.hpp"
#include "SqlTransaction.hpp"
 
#include <cstddef>
#include <cstdint>
#include <exception>
#include <expected>
#include <format>
#include <functional>
#include <list>
#include <map>
#include <memory>
#include <optional>
#include <set>
#include <span>
#include <stdexcept>
#include <string>
#include <string_view>
#include <vector>
 
namespace Lightweight
{
 
class SqlConnection;
 
/// @defgroup SqlMigration SQL Migration
/// @brief Classes and functions for SQL schema migrations.
 
namespace SqlMigration
{
    class MigrationBase;
 
    /// Represents a unique timestamp of a migration.
    ///
    /// This struct is used to identify migrations and is used as a key in the migration history table.
    ///
    /// Note, a recommended format for the timestamp is a human readable format like YYYYMMDDHHMMSS
    ///
    /// @code
    /// MigrationTimestamp { 2026'01'17'00'31'20 };
    /// @endcode
    ///
    /// @ingroup SqlMigration
    struct MigrationTimestamp
    {
        /// The numeric timestamp value identifying the migration.
        uint64_t value {};
 
        /// Three-way comparison operator.
        constexpr std::weak_ordering operator<=>(MigrationTimestamp const& other) const noexcept = default;
    };
 
    /// Exception thrown when applying or reverting a single migration fails.
    ///
    /// Carries structured diagnostic context so callers (CLI, GUI) can render
    /// the *which migration*, *which step*, *which SQL statement* and the
    /// underlying driver error as separate fields instead of parsing one
    /// opaque message string.
    ///
    /// @ingroup SqlMigration
    class MigrationException: public SqlException
    {
      public:
        /// Whether the failure happened while applying (Up) or reverting (Down).
        enum class Operation : std::uint8_t
        {
            Apply,
            Revert,
        };
 
        /// Constructs a migration exception that wraps a driver error with
        /// the migration identity and the exact SQL statement that failed.
        ///
        /// @param operation Whether the failure happened during apply or revert.
        /// @param timestamp The migration that failed.
        /// @param title Human-readable migration title.
        /// @param stepIndex Zero-based step index inside the migration plan.
        /// @param failedSql The SQL statement that produced the driver error.
        /// @param driverError The ODBC-level error info as received from the driver.
        LIGHTWEIGHT_API MigrationException(Operation operation,
                                           MigrationTimestamp timestamp,
                                           std::string title,
                                           std::size_t stepIndex,
                                           std::string failedSql,
                                           SqlErrorInfo driverError);
 
        /// Whether the failure occurred while applying or reverting.
        [[nodiscard]] Operation GetOperation() const noexcept
        {
            return _operation;
        }
        /// Timestamp of the failing migration.
        [[nodiscard]] MigrationTimestamp GetMigrationTimestamp() const noexcept
        {
            return _timestamp;
        }
        /// Human-readable title of the failing migration.
        [[nodiscard]] std::string const& GetMigrationTitle() const noexcept
        {
            return _title;
        }
        /// Zero-based step index inside the plan of the failing migration.
        [[nodiscard]] std::size_t GetStepIndex() const noexcept
        {
            return _stepIndex;
        }
        /// The exact SQL statement that the driver rejected.
        [[nodiscard]] std::string const& GetFailedSql() const noexcept
        {
            return _failedSql;
        }
        /// Raw driver error message, without the migration context prefix that
        /// `what()` and `info().message` decorate it with.
        [[nodiscard]] std::string const& GetDriverMessage() const noexcept
        {
            return _driverMessage;
        }
 
      private:
        Operation _operation;
        MigrationTimestamp _timestamp;
        std::string _title;
        std::size_t _stepIndex;
        std::string _failedSql;
        std::string _driverMessage;
    };
 
    /// Result of verifying a migration's checksum.
    ///
    /// @ingroup SqlMigration
    struct ChecksumVerificationResult
    {
        MigrationTimestamp timestamp; ///< The timestamp of the verified migration.
        std::string_view title;       ///< The title of the verified migration.
        std::string storedChecksum;   ///< The checksum stored in the database.
        std::string computedChecksum; ///< The checksum computed from the current migration definition.
        bool matches;                 ///< Whether the stored and computed checksums match.
    };
 
    /// Result of reverting multiple migrations.
    ///
    /// @ingroup SqlMigration
    struct RevertResult
    {
        std::vector<MigrationTimestamp> revertedTimestamps; ///< Successfully reverted migrations
        std::optional<MigrationTimestamp> failedAt;         ///< Migration that failed, if any
        std::string errorMessage;                           ///< Short error message if failed (driver message only)
 
        /// Title of the migration that failed (if any). Empty when no failure or
        /// when the failure happened before the migration could be located.
        std::string failedTitle;
 
        /// Zero-based step index inside the failed migration's plan. Meaningful
        /// only when `failedAt` is set and the failure came from a driver error
        /// (not from e.g. a missing registered migration).
        std::size_t failedStepIndex {};
 
        /// The exact SQL statement that failed, if available. Empty when the
        /// failure happened outside of SQL execution (e.g. missing Down()
        /// implementation, unregistered migration).
        std::string failedSql;
 
        /// SQLSTATE diagnostic code from the driver, if available.
        std::string sqlState;
 
        /// Native driver error code, if available.
        SQLINTEGER nativeErrorCode {};
    };
 
    /// Status summary of migrations.
    ///
    /// @ingroup SqlMigration
    struct MigrationStatus
    {
        size_t appliedCount {};        ///< Number of migrations that have been applied
        size_t pendingCount {};        ///< Number of migrations waiting to be applied
        size_t mismatchCount {};       ///< Number of applied migrations with checksum mismatches
        size_t unknownAppliedCount {}; ///< Number of applied migrations not found in registered list
        size_t totalRegistered {};     ///< Total number of registered migrations
    };
 
    /// Associates a software release with the highest migration timestamp present at release time.
    ///
    /// Releases are declared in source (typically a migration plugin) via
    /// `LIGHTWEIGHT_SQL_RELEASE(version, highestTimestamp[, options])`. They let tools answer questions like
    /// "which migrations belong to release 6.7.0?" or "roll back everything applied after 6.7.0".
    ///
    /// The `highestTimestamp` is an inclusive upper bound: a migration `M` belongs to the release
    /// iff `prev_release_ts < M.timestamp <= highestTimestamp`, where `prev_release_ts` is the
    /// previous release's timestamp (or 0 if there is none).
    ///
    /// @ingroup SqlMigration
    struct MigrationRelease
    {
        /// Human-readable version string, e.g. "6.7.0".
        std::string version;
        /// Highest migration timestamp contained in this release (inclusive).
        MigrationTimestamp highestTimestamp;
        /// Whether every migration of this release requires a backup of the database taken after its
        /// last migration (see `MigrationManager::BackupRequirementFor`).
        bool requiresBackup = false;
    };
 
    /// Options of a release declared with `LIGHTWEIGHT_SQL_RELEASE`.
    ///
    /// @ingroup SqlMigration
    struct MigrationReleaseOptions
    {
        /// Shorthand for "every migration of the release requires a backup".
        bool requiresBackup = false;
    };
 
    /// What a `schema_backups` record documents.
    ///
    /// @ingroup SqlMigration
    enum class BackupRecordKind : std::uint8_t
    {
        Backup,  ///< A verified backup archive was written; stored as `backup`.
        Restore, ///< A backup archive was restored into the database; stored as `restore`.
        /// A migrating run went ahead without a backup because the user explicitly waived it; stored as
        /// `waived`. Never satisfies a requirement.
        Waived,
    };
 
    /// Name of the table that holds the backup records.
    ///
    /// @ingroup SqlMigration
    inline constexpr std::string_view BackupRecordTableName = "schema_backups";
 
    /// The SHA-256 of an empty `schema_migrations` history (the digest of no rows).
    ///
    /// @ingroup SqlMigration
    inline constexpr std::string_view EmptyMigrationHistoryDigest =
        "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
 
    /// The migration history physically recorded in `schema_migrations`, as read from the database.
    ///
    /// @ingroup SqlMigration
    struct MigrationHistoryState
    {
        /// Highest applied version; empty when none is recorded. For messages.
        std::optional<MigrationTimestamp> lastAppliedMigration;
        /// The latest `applied_at` over all recorded migrations; empty when none carries a time. Informational.
        std::optional<SqlDateTime> lastAppliedAt;
        /// SHA-256, lowercase hex, of the whole physical history: one line `<version>|<applied_at>` per row,
        /// sorted by version, `applied_at` as milliseconds since the Unix epoch (empty when null). Any
        /// applied, re-applied, rolled back or re-stamped migration changes it.
        std::string digest = std::string { EmptyMigrationHistoryDigest };
    };
 
    /// One row of the `schema_backups` table.
    ///
    /// @ingroup SqlMigration
    struct BackupRecord
    {
        /// Assigned by the database; the newest record has the highest.
        std::uint64_t id = 0;
        /// UTC, informational: for a backup when it started reading the database, for a restore when it
        /// finished. It plays no part in `BackupRecordCovers`.
        SqlDateTime createdAt;
        /// UTF-8, without its directory.
        std::string archiveFileName;
        /// SHA-256 of the archive file, lowercase hex.
        std::string archiveSha256;
        /// The history the backup saw, from `ReadMigrationHistoryState`. Read it before the backup reads
        /// any data (for a restore: after it finished). A record is built only from a state read from the
        /// database, never from a clock. Stored: `lastAppliedMigration` and `digest`.
        MigrationHistoryState observedState;
        /// The tool that wrote the record, e.g. `dbtool 1.2.3`.
        std::string toolVersion;
        /// What the record documents.
        BackupRecordKind kind = BackupRecordKind::Backup;
    };
 
    /// Whether the work a command will run needs a backup, and whether a recorded one satisfies it.
    ///
    /// @ingroup SqlMigration
    struct BackupRequirement
    {
        /// Whether anything demands a backup.
        bool required = false;
        /// What demands it: `release <version>`, `migration <timestamp> "<title>"` and `step "<title>"`, in that order.
        std::vector<std::string> reasons;
        /// Whether nothing is required or the newest backup or restore record covers the database's current state.
        bool satisfied = true;
        /// The newest `backup` or `restore` record; `waived` records are skipped.
        std::optional<BackupRecord> lastBackup;
    };
 
    /// Reads the migration history from `schema_migrations`.
    ///
    /// Physical rows only; the virtual-applied overlay does not count.
    ///
    /// @param dataMapper The migration connection's mapper.
    /// @return The state; empty when the table is missing. Other errors throw.
    /// @ingroup SqlMigration
    [[nodiscard]] LIGHTWEIGHT_API MigrationHistoryState ReadMigrationHistoryState(DataMapper& dataMapper);
 
    /// Reads the newest `backup` or `restore` record, by id; `waived` records are skipped.
    ///
    /// @param dataMapper The migration connection's mapper.
    /// @return The record; empty when there is none or the table is missing. Other errors throw.
    /// @ingroup SqlMigration
    [[nodiscard]] LIGHTWEIGHT_API std::optional<BackupRecord> ReadLatestBackupRecord(DataMapper& dataMapper);
 
    /// Appends a record to `schema_backups`, creating the table when it is missing.
    ///
    /// @param dataMapper The migration connection's mapper.
    /// @param record The record to store; its `id` is ignored.
    /// @return The record with the id the database assigned, or the database error.
    /// @ingroup SqlMigration
    [[nodiscard]] LIGHTWEIGHT_API std::expected<BackupRecord, SqlErrorInfo> WriteBackupRecord(DataMapper& dataMapper,
                                                                                              BackupRecord record);
 
    /// Whether @p record covers the database state @p state.
    ///
    /// Only a `backup` or `restore` record can cover, and it does when it saw exactly the current migration
    /// history: its `observedState.digest` equals the state's. Any migration applied, re-applied, rolled
    /// back or re-stamped since changes the digest. Only values read from the database are compared, so
    /// `createdAt` and the clocks of the hosts involved play no part. Any other kind covers nothing.
    ///
    /// @param record The record to test.
    /// @param state The current migration state.
    /// @ingroup SqlMigration
    [[nodiscard]] LIGHTWEIGHT_API bool BackupRecordCovers(BackupRecord const& record,
                                                          MigrationHistoryState const& state) noexcept;
 
    /// Whether @p schema is a schema name `MigrationManager::SetDefaultSchema` accepts: `[A-Za-z0-9_]+`.
    ///
    /// @param schema The name to check.
    /// @return False for an empty name and for any other character.
    /// @ingroup SqlMigration
    [[nodiscard]] LIGHTWEIGHT_API bool IsValidSchemaName(std::string_view schema) noexcept;
 
    /// The failure of one unit of `MigrationManager::UnicodeUpgradeTables`, which was rolled back.
    ///
    /// `info()` keeps the SQLSTATE and native error code of the cause; its message names the unit,
    /// its tables and what the units before it committed, followed by the cause's message.
    ///
    /// @ingroup SqlMigration
    class UnicodeUpgradeUnitError final: public SqlException
    {
      public:
        /// @param info       The cause's error info, its message already prefixed with the unit's.
        /// @param unitNumber The failed unit, counted from 1.
        /// @param unitCount  The number of units of the upgrade.
        UnicodeUpgradeUnitError(SqlErrorInfo info, std::size_t unitNumber, std::size_t unitCount):
            SqlException(std::move(info)),
            _unitNumber { unitNumber },
            _unitCount { unitCount }
        {
        }
 
        /// The failed unit, counted from 1; the units before it are committed.
        [[nodiscard]] std::size_t UnitNumber() const noexcept
        {
            return _unitNumber;
        }
 
        /// The number of units of the upgrade.
        [[nodiscard]] std::size_t UnitCount() const noexcept
        {
            return _unitCount;
        }
 
      private:
        std::size_t _unitNumber;
        std::size_t _unitCount;
    };
 
    class MigrationManager;
 
    /// Whether an operation changes the database or only reports what it would change.
    ///
    /// @ingroup SqlMigration
    enum class ExecutionMode : std::uint8_t
    {
        Execute, ///< Carry the operation out.
        DryRun,  ///< Report the plan and change nothing.
    };
 
    /// Options of a pre-migrate step.
    ///
    /// @ingroup SqlMigration
    struct PreMigrateStepOptions
    {
        /// Whether this run of the step demands a backup of the database taken after its last
        /// migration (see `MigrationManager::BackupRequirementFor`), e.g. "the dry-run plan is not
        /// empty". Evaluated on the migration connection before the run; empty means never. Hosts call it
        /// on every requirement check and from any thread (a worker, or a GUI's own), so keep it cheap.
        std::function<bool(SqlConnection&, MigrationManager&)> requiresBackup;
    };
 
    /// Work a plugin runs before the first pending migration of `migrate`, `apply` and `migrate-to-release`.
    ///
    /// The first parameter is the migration connection, on which the host holds the migration lock
    /// unless it opted out of locking; then the host's manager, the step's own task and the execution
    /// mode, in which a dry run makes the step report its plan and change nothing.
    ///
    /// @ingroup SqlMigration
    using PreMigrateStep = std::function<void(SqlConnection&, MigrationManager&, ProgressTask&, ExecutionMode)>;
 
    /// A registered pre-migrate step, without its code.
    ///
    /// @ingroup SqlMigration
    struct PreMigrateStepInfo
    {
        std::string title;                      ///< The step's title, as its task shows it.
        bool declaresBackupRequirement = false; ///< Whether the step has a `requiresBackup` predicate.
    };
 
    /// How `MigrationManager::RunPreMigrateSteps` ended.
    ///
    /// @ingroup SqlMigration
    enum class PreMigrateStepsOutcome : std::uint8_t
    {
        Completed, ///< Every step ran; the migrations may follow.
        Cancelled, ///< The task asked to cancel; the caller applies no migration.
    };
 
    /// A pre-migrate step threw; the command stops and applies no migration.
    ///
    /// @ingroup SqlMigration
    class PreMigrateStepError final: public std::runtime_error
    {
      public:
        /// @param stepTitle The failed step.
        /// @param cause What the step threw.
        PreMigrateStepError(std::string stepTitle, std::string_view cause):
            std::runtime_error(std::format("Pre-migrate step \"{}\" failed: {}", stepTitle, cause)),
            _stepTitle { std::move(stepTitle) }
        {
        }
 
        /// @return The title of the step that failed.
        [[nodiscard]] std::string const& StepTitle() const noexcept
        {
            return _stepTitle;
        }
 
      private:
        std::string _stepTitle;
    };
 
    /// Main API to use for managing SQL migrations
    ///
    /// This class is a singleton and can be accessed using the GetInstance() method.
    ///
    /// @ingroup SqlMigration
    class MigrationManager
    {
      public:
        /// Type alias for a list of migration pointers.
        using MigrationList = std::list<MigrationBase const*>;
 
        /// Get the singleton instance of the migration manager.
        ///
        /// @return Reference to the migration manager.
        /// Get the singleton instance of the migration manager.
        ///
        /// @return Reference to the migration manager.
        LIGHTWEIGHT_API static MigrationManager& GetInstance();
 
        /// Add a migration to the manager.
        ///
        /// @param migration Pointer to the migration to add.
        LIGHTWEIGHT_API void AddMigration(MigrationBase const* migration);
 
        /// Get all migrations that have been added to the manager.
        ///
        /// @return List of migrations.
        [[nodiscard]] LIGHTWEIGHT_API MigrationList const& GetAllMigrations() const noexcept;
 
        /// Get a migration by timestamp.
        ///
        /// @param timestamp Timestamp of the migration to get.
        /// @return Pointer to the migration if found, nullptr otherwise.
        [[nodiscard]] LIGHTWEIGHT_API MigrationBase const* GetMigration(MigrationTimestamp timestamp) const noexcept;
 
        /// Remove a single migration from the manager.
        ///
        /// Called by @c MigrationBase's destructor so a migration that goes out of scope does not
        /// leave a dangling pointer behind. Removing a migration that was never added is a no-op.
        ///
        /// @param migration Pointer to the migration to remove.
        LIGHTWEIGHT_API void RemoveMigration(MigrationBase const* migration) noexcept;
 
        /// Remove all migrations from the manager.
        ///
        /// This function is useful if the migration manager should be reset.
        LIGHTWEIGHT_API void RemoveAllMigrations();
 
        /// Get all migrations that have not been applied yet.
        ///
        /// A dependency cycle does not throw: the list then falls back to timestamp order, and the error
        /// surfaces again from ApplyPendingMigrations() / ValidateDependencies().
        ///
        /// @return List of pending migrations.
        /// @throws std::runtime_error Reading the applied migrations failed in a way other than the
        ///         table being absent (e.g. an unexpected NULL in `schema_migrations`).
        [[nodiscard]] LIGHTWEIGHT_API std::list<MigrationBase const*> GetPending() const;
 
        /// Callback type invoked during migration execution to report progress.
        using ExecuteCallback =
            std::function<void(MigrationBase const& /*migration*/, size_t /*current*/, size_t /*total*/)>;
 
        /// Apply a single migration from a migration object.
        ///
        /// @param migration Pointer to the migration to apply.
        LIGHTWEIGHT_API void ApplySingleMigration(MigrationBase const& migration);
 
        /// @brief Variant of `ApplySingleMigration` that threads a caller-owned render
        /// context through to `ToSql`. Use this from loops over multiple migrations so
        /// the column-width cache (and other per-run compat state) accumulates across
        /// the sequence.
        LIGHTWEIGHT_API void ApplySingleMigration(MigrationBase const& migration, MigrationRenderContext& context);
 
        /// Revert a single migration from a migration object.
        ///
        /// @param migration Pointer to the migration to revert.
        LIGHTWEIGHT_API void RevertSingleMigration(MigrationBase const& migration);
 
        /// Apply all migrations that have not been applied yet.
        ///
        /// @param feedbackCallback Callback to be called for each migration.
        /// @return Number of applied migrations.
        LIGHTWEIGHT_API size_t ApplyPendingMigrations(ExecuteCallback const& feedbackCallback = {});
 
        /// Apply pending migrations whose timestamp is <= `targetInclusive`.
        ///
        /// Honors dependency-respecting topological order, just like
        /// `ApplyPendingMigrations`, and threads a single render context across
        /// the run so column-width state from earlier CREATE TABLEs is visible
        /// to later compat-aware INSERT/UPDATE rendering.
        ///
        /// If a pending migration with `ts <= target` declares a dependency on
        /// a migration whose timestamp is `> target` (i.e. excluded by the
        /// bound) and is not already applied, this throws — partial states
        /// that violate dependencies are refused up front.
        ///
        /// @param targetInclusive Highest timestamp to apply (inclusive).
        /// @param feedbackCallback Callback to be called for each migration.
        /// @return Number of applied migrations (may be zero if already past `targetInclusive`).
        /// @throws std::runtime_error if a dependency would cross the boundary.
        LIGHTWEIGHT_API size_t ApplyPendingMigrationsUpTo(MigrationTimestamp targetInclusive,
                                                          ExecuteCallback const& feedbackCallback = {});
 
        /// Create the migration history table if it does not exist.
        LIGHTWEIGHT_API void CreateMigrationHistory();
 
        /// @brief Sets the default schema applied to migration connections.
        ///
        /// When non-empty, installs a chained `SqlConnection::SetPostConnectedHook`
        /// that executes the formatter's `SetDefaultSchemaStatement(schema)`
        /// (e.g. `SET search_path TO "<schema>", public` on PostgreSQL) for
        /// every new connection. SQL Server and SQLite have no portable
        /// session-level "default schema" command — for SQL Server, the
        /// connecting login's server-side `DEFAULT_SCHEMA` is what determines
        /// where unqualified DDL/DML lands.
        ///
        /// `schema` is validated against a `[A-Za-z0-9_]` whitelist; rejecting
        /// invalid input by throwing a `std::invalid_argument`. Passing an
        /// empty string clears any previously installed schema hook.
        ///
        /// Calling this **after** a connection has already been opened on the
        /// current thread does not retroactively apply the schema — the hook
        /// fires on subsequent `SqlConnection::Connect` calls. For dbtool and
        /// the GUI this is invoked before the first connection.
        ///
        /// @param schema The default schema to use. Empty disables.
        LIGHTWEIGHT_API void SetDefaultSchema(std::string schema);
 
        /// @brief Returns the default schema currently installed on the manager
        /// (empty when unset).
        [[nodiscard]] LIGHTWEIGHT_API std::string_view DefaultSchema() const noexcept;
 
        /// Get all applied migration IDs.
        ///
        /// Returns the union of timestamps physically present in `schema_migrations`
        /// and the in-memory "virtual applied" overlay (see `AddVirtualAppliedMigrations`),
        /// sorted ascending and deduplicated. The accessor never creates the
        /// `schema_migrations` table — when the table does not exist the database
        /// half of the union is the empty set, so a pure-overlay state is fully
        /// observable here without any side effects.
        ///
        /// @return Vector of applied migration IDs (database rows ∪ overlay).
        [[nodiscard]] LIGHTWEIGHT_API std::vector<MigrationTimestamp> GetAppliedMigrationIds() const;
 
        /// Contribute "virtual" applied migration IDs that participate in every
        /// `GetAppliedMigrationIds()` read but are not persisted to
        /// `schema_migrations` until the manager actually performs a write
        /// (`ApplySingleMigration`, `MarkMigrationAsApplied`, or
        /// `RevertSingleMigration`). Designed for plugin post-init hooks that
        /// need to bridge a foreign version-tracking table (e.g. the legacy
        /// `LASTRADA_PROPERTIES NR=4` row) into the modern applied-set view
        /// without paying for table creation on read-only commands like
        /// `status` or `list-applied`.
        ///
        /// The input is merged into an internal sorted, deduplicated vector;
        /// passing the same timestamp twice is a no-op.
        ///
        /// @param timestamps Timestamps to add to the overlay.
        LIGHTWEIGHT_API void AddVirtualAppliedMigrations(std::span<MigrationTimestamp const> timestamps);
 
        /// Drop every entry from the in-memory virtual-applied overlay. Intended
        /// for test setup/teardown and for callers that want to re-derive the
        /// overlay from scratch (e.g. a `dbtool-gui` reconnect against a
        /// different profile). Has no effect on `schema_migrations` rows.
        LIGHTWEIGHT_API void ClearVirtualAppliedMigrations();
 
        /// Optional sink for informational status messages emitted by plugin
        /// hooks (e.g. the "Transitioning from LASTRADA_PROPERTIES …" banner).
        /// `dbtool` installs a sink that prints to `stdout` to preserve the
        /// historical CLI output; `dbtool-gui` installs a sink that routes
        /// through its `LogInfo` channel so the banner shows up in the
        /// activity log instead of going to a hidden stream.
        using LogSink = std::function<void(std::string_view)>;
 
        /// Install a log sink. Pass `{}` to clear.
        ///
        /// @param sink Callable invoked once per status message.
        LIGHTWEIGHT_API void SetLogSink(LogSink sink);
 
        /// Emit a status message via the installed sink. No-op when no sink is
        /// installed — silent by default keeps the library suitable for use in
        /// embedded contexts that have no obvious output stream.
        ///
        /// @param message The message to deliver.
        LIGHTWEIGHT_API void Log(std::string_view message) const;
 
        /// @brief Number of rows `Insert(...).IfNotExists(...)` steps skipped because a row
        /// with the same key values already existed, counted over the manager's lifetime.
        ///
        /// Each skip is also reported through @ref Log as one line of the form
        /// `Skipped existing row: <timestamp> <table> (<key>=<value>, ...)`. Both happen once the
        /// migration has committed, so a migration that fails and rolls back reports no skips.
        /// Callers that need the count of one run take the difference before and after it.
        [[nodiscard]] LIGHTWEIGHT_API std::size_t SkippedExistingRowCount() const noexcept;
 
        /// Registers a step that `migrate`, `apply` and `migrate-to-release` run, in registration order,
        /// before their first pending migration (also when none is pending). Plugins register steps
        /// from their post-init hook; a step is code of that plugin, so hosts call
        /// `RemoveAllPreMigrateSteps` before running post-init hooks again and before unloading it.
        ///
        /// @param title The step's title, unique among the steps.
        /// @param options The step's options.
        /// @param step The step's code.
        /// @throws std::invalid_argument when @p step is empty or a step titled @p title exists.
        LIGHTWEIGHT_API void AddPreMigrateStep(std::string title, PreMigrateStepOptions options, PreMigrateStep step);
 
        /// @return The registered pre-migrate steps, in registration order.
        [[nodiscard]] LIGHTWEIGHT_API std::vector<PreMigrateStepInfo> GetPreMigrateSteps() const;
 
        /// Removes every pre-migrate step.
        LIGHTWEIGHT_API void RemoveAllPreMigrateSteps() noexcept;
 
        /// Runs the pre-migrate steps in registration order, each under a sub-task of @p parent named
        /// like the step, on the migration connection. The caller holds the migration lock (unless it
        /// opted out of locking) and calls this before applying the first pending migration. Status and
        /// read-only commands never call it. Cancellation is checked before and after each step.
        ///
        /// @param parent The task the steps' tasks open under.
        /// @param mode Whether the steps only report their plan.
        /// @return `Cancelled` when @p parent asked to cancel; the caller then applies no migration.
        /// @throws PreMigrateStepError when a step throws, also something other than a `std::exception`
        ///         ("unknown exception"); the steps after it do not run.
        [[nodiscard]] LIGHTWEIGHT_API PreMigrateStepsOutcome RunPreMigrateSteps(ProgressTask& parent, ExecutionMode mode);
 
        /// Get the data mapper used for migrations.
        ///
        /// Owned by the manager and connected with the default connection string on first use. When
        /// the application replaces the default (@ref SqlConnection::SetDefaultConnectionString), the
        /// next call reconnects the same instance - the reference stays valid - to the new default.
        /// A call from a copy of the library that never had a default set (a plugin that links
        /// Lightweight statically, calling into the host's manager from a hook) keeps the mapper as it is.
        ///
        /// @return The migration data mapper.
        /// @throws SqlException Connecting failed.
        [[nodiscard]] LIGHTWEIGHT_API DataMapper& GetDataMapper();
 
        /// Get the data mapper used for migrations.
        [[nodiscard]] LIGHTWEIGHT_API DataMapper& GetDataMapper() const
        {
            return const_cast<MigrationManager*>(this)->GetDataMapper();
        }
 
        /// Close the data mapper.
        ///
        /// This function is useful if explicitly closing the connection is desired before
        /// the migration manager is destroyed.
        LIGHTWEIGHT_API void CloseDataMapper();
 
        /// @brief Per-migration compat policy.
        ///
        /// Given a migration about to be applied (or previewed), returns the set of compat
        /// flags that should be active while rendering it. Plugins that ship legacy
        /// migrations use this to scope compat behaviour to their own timestamp range
        /// (e.g. a plugin enables `lup-truncate` for migrations predating a given
        /// release). Unset means "strict for every migration".
        using CompatPolicy = std::function<std::set<std::string>(MigrationBase const&)>;
 
        /// @brief Installs a per-migration compat policy. Pass `{}` to clear.
        ///
        /// Typically called once from a plugin's static initializer. Replaces any policy
        /// previously installed — composition is the caller's responsibility for now.
        /// A policy from a plugin is code in that plugin's library: a host must clear it
        /// before it unloads the plugin, as dbtool's `Tools::UnloadPlugins` does.
        LIGHTWEIGHT_API void SetCompatPolicy(CompatPolicy policy);
 
        /// @brief Returns a view of the installed policy so it can be propagated across
        /// managers (plugin → central). Empty callable if no policy was installed.
        [[nodiscard]] LIGHTWEIGHT_API CompatPolicy const& GetCompatPolicy() const noexcept;
 
        /// @brief Composes an additional policy with the currently installed one. If no
        /// policy is installed, the argument becomes the policy as-is; otherwise both
        /// policies are consulted and their flag sets unioned per migration.
        LIGHTWEIGHT_API void ComposeCompatPolicy(CompatPolicy policy);
 
        /// @brief Returns the compat flags the current policy assigns to `migration`, or
        /// an empty set if no policy is installed.
        [[nodiscard]] LIGHTWEIGHT_API std::set<std::string> CompatFlagsFor(MigrationBase const& migration) const;
 
        /// Get a transaction for the data mapper.
        ///
        /// @return Transaction.
        LIGHTWEIGHT_API SqlTransaction Transaction();
 
        /// Preview SQL statements for a single migration without executing.
        ///
        /// This is useful for dry-run mode to see what SQL would be executed.
        ///
        /// @param migration The migration to preview.
        /// @return Vector of SQL statements that would be executed.
        [[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> PreviewMigration(MigrationBase const& migration) const;
 
        /// @brief Variant of `PreviewMigration` that threads a caller-owned render
        /// context so the column-width cache accumulates across a sequence of preview
        /// calls. Used by `PreviewPendingMigrations` to render compat-aware dry runs.
        [[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> PreviewMigrationWithContext(
            MigrationBase const& migration, MigrationRenderContext& context) const;
 
        /// @brief One row in the `RewriteChecksumsResult.entries` list.
        struct ChecksumRewriteEntry
        {
            MigrationTimestamp timestamp; ///< The migration whose stored checksum was rewritten.
            std::string_view title;       ///< Title of the registered migration (or "(Unknown Migration)").
            std::string oldChecksum;      ///< Stored checksum before the rewrite. Empty if there was none.
            std::string newChecksum;      ///< Stored checksum after the rewrite.
        };
 
        /// @brief Result of a `RewriteChecksums` call.
        struct RewriteChecksumsResult
        {
            std::vector<ChecksumRewriteEntry> entries; ///< One entry per rewritten or would-be-rewritten row.
            std::vector<MigrationTimestamp>
                unregisteredTimestamps; ///< Applied rows whose migration is no longer registered.
            bool wasDryRun = false;     ///< True if the call ran in dry-run mode.
        };
 
        /// @brief Snapshot of the schema the registered migrations *intend* to produce.
        ///
        /// Pure plan-walk — never executes SQL, never opens a connection. Folds the
        /// effects of every registered migration (up to an optional cut-off timestamp)
        /// into a per-table view of "the final shape" plus a chronological list of
        /// data steps and surviving indexes/releases. Used by:
        ///
        ///   - `HardReset` to know which tables the migrations would have created
        ///   - `UnicodeUpgradeTables` to know which char/varchar columns the migrations
        ///     now declare wide
        ///
        /// Both are pure operations — `FoldRegisteredMigrations` itself never
        /// executes a single statement. See `FoldRegisteredMigrations` for the API.
        struct PlanFoldingResult
        {
            /// Per-table state: ordered column declarations + per-table FK list.
            struct TableState
            {
                /// Ordered column declarations as they would be emitted in CREATE TABLE.
                std::vector<SqlColumnDeclaration> columns;
                /// Composite foreign keys declared on this table (single-column FKs are
                /// carried inline on the corresponding `SqlColumnDeclaration::foreignKey`).
                std::vector<SqlCompositeForeignKeyConstraint> compositeForeignKeys;
                /// Whether the original CREATE TABLE used IF NOT EXISTS (carried through
                /// to emitters so they can replay it verbatim).
                bool ifNotExists = false;
            };
 
            /// (schema, table) → folded `TableState`. Insertion order is *not* preserved by
            /// `std::map` — for emission order use `creationOrder` below.
            std::map<SqlSchema::FullyQualifiedTableName, TableState> tables;
 
            /// Tables in *creation* order (first-time-seen). Reverse for safe DROP ordering
            /// when tearing the schema down.
            std::vector<SqlSchema::FullyQualifiedTableName> creationOrder;
 
            /// Indexes that survive folding (created on tables still present at end).
            std::vector<SqlCreateIndexPlan> indexes;
 
            /// One data step (INSERT/UPDATE/DELETE/RawSql) tagged with its source migration.
            struct DataStep
            {
                /// Timestamp of the migration that contributed this data step.
                MigrationTimestamp sourceTimestamp;
                /// Title of the migration that contributed this data step.
                std::string sourceTitle;
                /// The plan element itself (INSERT, UPDATE, DELETE, or RawSql).
                SqlMigrationPlanElement element;
            };
 
            /// Data steps in chronological order. **No coalescing** — the fold replays
            /// every data step verbatim, exactly as if migrations were applied in order.
            std::vector<DataStep> dataSteps;
 
            /// Releases declared via `LIGHTWEIGHT_SQL_RELEASE` that fall within the fold range.
            std::vector<MigrationRelease> releases;
 
            /// Migrations that contributed to the fold (timestamp + title). Used by emitters
            /// to write a header comment explaining what was collapsed.
            std::vector<std::pair<MigrationTimestamp, std::string>> foldedMigrations;
        };
 
        /// @brief Pure plan-walk that folds the effect of every registered migration.
        ///
        /// Visits each migration's `Up()` plan in timestamp order (or up to
        /// `upToInclusive` if provided) and accumulates the cumulative end-state into a
        /// `PlanFoldingResult`. **Never** executes SQL or touches a database connection
        /// — the supplied formatter is only used to build the in-memory plan elements.
        ///
        /// @param formatter Formatter used by the migration query builder while walking
        ///                  each migration's `Up()`. Any standard formatter works; the
        ///                  walk inspects plan element shapes, not rendered SQL.
        /// @param upToInclusive If set, fold only migrations with `timestamp <= upToInclusive`.
        ///                     If unset, fold all registered migrations.
        ///
        /// @return The folded snapshot. Safe to call without a `MigrationManager`-attached
        ///         data mapper.
        [[nodiscard]] LIGHTWEIGHT_API PlanFoldingResult FoldRegisteredMigrations(
            SqlQueryFormatter const& formatter, std::optional<MigrationTimestamp> upToInclusive = std::nullopt) const;
 
        /// @brief Result of a `HardReset` call.
        struct HardResetResult
        {
            /// True when the populating call was a dry-run; the result describes the
            /// would-be plan and no DDL was issued.
            bool wasDryRun = false;
            /// Tables the registered migrations *would* have created and were also present
            /// in the live DB — these were dropped (or would be dropped on a real run).
            std::vector<SqlSchema::FullyQualifiedTableName> droppedTables;
            /// Tables registered migrations declare but that aren't in the live DB —
            /// nothing to do for these. Reported for visibility only.
            std::vector<SqlSchema::FullyQualifiedTableName> absentTables;
            /// Tables in the live DB the registered migrations don't know about — left
            /// alone (user-owned). Reported prominently so operators notice.
            std::vector<SqlSchema::FullyQualifiedTableName> preservedTables;
            /// Whether the `schema_migrations` table itself was dropped (always true on a
            /// real run, false on dry-run).
            bool schemaMigrationsDropped = false;
            /// Whether `schema_backups` exists and was dropped (or, in a dry run, would be), with every
            /// backup, restore and waived record in it.
            bool schemaBackupsDropped = false;
        };
 
        /// @brief Drops every table the registered migrations would create (incl.
        /// `schema_migrations`), preserving any user-created tables.
        ///
        /// Folds all registered migrations to compute the migration-owned set, intersects
        /// with the live schema (via `SqlSchema::ReadAllTables`), then drops the matching
        /// live tables in **reverse** creation order with `cascade=true ifExists=true`. The
        /// `schema_migrations` table is dropped explicitly because it's created outside the
        /// registered-migrations stream.
        ///
        /// Tables present in the live DB but not in the migration plan are left alone and
        /// reported under `preservedTables` so operators can spot them.
        ///
        /// Also drops `schema_backups`: its records describe backups of the migration state being discarded.
        ///
        /// @param mode `ExecutionMode::DryRun` returns the would-be plan without writing anything.
        [[nodiscard]] LIGHTWEIGHT_API HardResetResult HardReset(ExecutionMode mode = ExecutionMode::Execute);
 
        /// @brief One column upgrade entry in `UnicodeUpgradeResult`.
        struct ColumnUpgradeEntry
        {
            /// Fully-qualified name of the table that owns the column.
            SqlSchema::FullyQualifiedTableName table;
            /// Name of the column being upgraded.
            std::string column;
            /// Live byte-counted type the column currently has.
            SqlColumnTypeDefinition liveType;
            /// Char-counted type the migrations now declare for this column.
            SqlColumnTypeDefinition intendedType;
            /// Whether the column is nullable (preserved across the type rewrite).
            bool nullable = true;
            /// Empty for a column the migrations declare wide. Otherwise the column is upgraded only
            /// because a foreign key joins it to an upgraded column, named here as `table.column`,
            /// or as `schema.table.column` when the upgrade spans several schemas.
            std::string joinedByForeignKeyTo {};
        };
 
        /// @brief Result of an `UnicodeUpgradeTables` call.
        struct UnicodeUpgradeResult
        {
            /// True when the populating call was a dry-run; the result describes the
            /// would-be diff and no DDL was issued.
            bool wasDryRun = false;
            /// Columns whose live type drifted from the intended type and were upgraded
            /// (or would be on a real run).
            std::vector<ColumnUpgradeEntry> columns;
            /// Foreign keys that had to be dropped + re-added to upgrade their
            /// participating columns. Reported so operators see the FK churn.
            std::vector<SqlCompositeForeignKeyConstraint> rebuiltForeignKeys;
            /// SQL Server: every object that depends on an upgraded column — keys, unique,
            /// foreign-key, default and check constraints, indexes, statistics — and is
            /// dropped and recreated under its original name around the type change.
            std::vector<std::string> rebuiltObjects;
            /// The tables in the order they are upgraded, grouped into units: the tables a
            /// foreign key joins through an upgraded column share one unit, and each unit is
            /// upgraded and committed in a transaction of its own.
            std::vector<std::vector<SqlSchema::FullyQualifiedTableName>> units;
            /// True when the call stopped after a committed unit because its progress task asked to cancel;
            /// a later call continues with the next unit.
            bool wasCancelled = false;
            /// Units this call committed: all of `units` unless it was cancelled, 0 for a dry run. A failing call
            /// throws and returns no result.
            std::size_t committedUnitCount = 0;
        };
 
        /// @brief Rewrites legacy `VARCHAR/CHAR` columns to `NVARCHAR/NCHAR` where the
        /// registered migrations now declare wide types.
        ///
        /// Compares the folded plan's intended column types against `SqlSchema::ReadAllTables`
        /// output; an upgrade is triggered iff intended is `NVarchar`/`NChar` AND live is
        /// `Varchar`/`Char` with the same `size`. Foreign keys that touch any upgrade column
        /// are dropped before the alter and re-added afterwards; SQL Server and PostgreSQL read
        /// them from the catalog and recreate them under their own names with their own
        /// definitions (referenced schema, actions), whoever created them. Cross-backend; SQLite
        /// uses the in-tree `RebuildSqliteTable` recipe under the hood.
        ///
        /// Declared names match live ones without regard to case where the dialect's identifiers
        /// are case-insensitive (`SqlQueryFormatter::IdentifiersAreCaseInsensitive`).
        ///
        /// The live tables of every schema are read. A declared table resolves to the schema its
        /// migration names; else to the first schema holding that name in the connection's name
        /// resolution order (SQL Server: the user's default schema, then `dbo`; PostgreSQL: the
        /// search path); else to the only schema holding it. Each column is altered, and its
        /// dependents found, in the schema it was resolved to. When several schemas hold a declared
        /// name, none of them is in that order and one has a column to widen, the call throws
        /// `std::runtime_error` naming them.
        ///
        /// Where a foreign key needs both sides to share one text type (SQL Server), every column
        /// a foreign key joins to an upgraded column is upgraded too, declared or not, and reported
        /// with `ColumnUpgradeEntry::joinedByForeignKeyTo` set. Such a column must have the same narrow
        /// type and size and must not be declared with another type; otherwise the call throws
        /// `std::runtime_error` naming it, in a dry run too, before anything has changed.
        ///
        /// Each unit (see `UnicodeUpgradeResult::units`) runs in a transaction of its own and is
        /// committed before the next one starts; the log sink reports each committed unit. Under
        /// the simple recovery model, or while log backups run, the transaction log then only has
        /// to hold one unit, so the largest unit sets its peak. A failing unit is rolled back and
        /// stops the call with `UnicodeUpgradeUnitError`, which names it and says how many units
        /// were committed before it. A later call continues where this one stopped, as the plan is
        /// computed from the live schema.
        ///
        /// A unit that fails is reported as failed on its tasks (the failing table's, the unit's and the
        /// overall one) before the call throws.
        ///
        /// @param mode `ExecutionMode::DryRun` returns the would-be diff without writing anything and
        ///        reports only the plan to @p progress.
        /// @param progress Receives planning, an overall task weighted by the tables' row counts (SQL
        ///        Server: `sys.partitions`; PostgreSQL: `pg_class.reltuples`; otherwise
        ///        `COUNT(*)`), one task per unit and per table; null reports nothing. Cancellation is
        ///        checked after each committed unit except the last; see `UnicodeUpgradeResult::wasCancelled`.
        [[nodiscard]] LIGHTWEIGHT_API UnicodeUpgradeResult UnicodeUpgradeTables(ExecutionMode mode = ExecutionMode::Execute,
                                                                                ProgressTask* progress = nullptr);
 
        /// @brief Re-stamps `schema_migrations.checksum` rows that have drifted.
        ///
        /// Applied migrations whose stored checksum no longer matches the current
        /// `MigrationBase::ComputeChecksum` output are updated in-place. Migrations that
        /// match are left alone. Rows that reference a migration which is no longer
        /// registered (e.g. removed from the codebase) are surfaced via
        /// `RewriteChecksumsResult.unregisteredTimestamps` and *not* touched.
        ///
        /// This is a recovery tool used when a regen of generated migrations changes
        /// their byte-level shape but not their logical effect — running it without
        /// understanding *why* the checksum drifted would defeat the integrity check.
        ///
        /// @param dryRun When true, returns the would-be diff without writing anything.
        [[nodiscard]] LIGHTWEIGHT_API RewriteChecksumsResult RewriteChecksums(bool dryRun = false);
 
        /// Preview SQL statements for all pending migrations without executing.
        ///
        /// This is useful for dry-run mode to see what SQL would be executed.
        ///
        /// @param feedbackCallback Optional callback to be called for each migration.
        /// @return Vector of all SQL statements that would be executed.
        [[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> PreviewPendingMigrations(
            ExecuteCallback const& feedbackCallback = {}) const;
 
        /// Preview SQL for pending migrations whose timestamp is <= `targetInclusive`.
        ///
        /// Bounded counterpart of `PreviewPendingMigrations`. Same dependency
        /// rules as `ApplyPendingMigrationsUpTo`: if any included migration
        /// depends on an excluded pending migration, this throws.
        ///
        /// @param targetInclusive Highest timestamp to preview (inclusive).
        /// @param feedbackCallback Optional callback to be called for each migration.
        /// @return Vector of all SQL statements that would be executed.
        /// @throws std::runtime_error if a dependency would cross the boundary.
        [[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> PreviewPendingMigrationsUpTo(
            MigrationTimestamp targetInclusive, ExecuteCallback const& feedbackCallback = {}) const;
 
        /// Verify checksums of all applied migrations.
        ///
        /// Compares the stored checksums in the database with the computed checksums
        /// of the current migration definitions. This helps detect if migrations
        /// have been modified after they were applied.
        ///
        /// @return Vector of verification results for migrations with mismatched or missing checksums.
        [[nodiscard]] LIGHTWEIGHT_API std::vector<ChecksumVerificationResult> VerifyChecksums() const;
 
        /// Mark a migration as applied without executing its Up() method.
        ///
        /// This is useful for:
        /// - Baseline migrations when setting up an existing database
        /// - Marking migrations that were applied manually or through other means
        /// - Skipping migrations that are not applicable to a specific environment
        ///
        /// @param migration The migration to mark as applied.
        /// @throws std::runtime_error if the migration is already applied.
        LIGHTWEIGHT_API void MarkMigrationAsApplied(MigrationBase const& migration);
 
        /// Revert all migrations applied after the target timestamp.
        ///
        /// This method reverts migrations in reverse chronological order,
        /// rolling back from the most recent to just after the target.
        /// The target migration itself is NOT reverted.
        ///
        /// @param target Target timestamp to revert to. Migrations > target are reverted.
        /// @param feedbackCallback Optional callback for progress updates.
        /// @return Result containing list of reverted timestamps or error information.
        /// @note Stops on first error. Previously reverted migrations in this call are NOT rolled back.
        [[nodiscard]] LIGHTWEIGHT_API RevertResult RevertToMigration(MigrationTimestamp target,
                                                                     ExecuteCallback const& feedbackCallback = {});
 
        /// Get a summary status of all migrations.
        ///
        /// This method provides a quick overview of the migration state without
        /// needing to iterate through individual migrations.
        ///
        /// @return Status struct with counts of applied, pending, and mismatched migrations.
        [[nodiscard]] LIGHTWEIGHT_API MigrationStatus GetMigrationStatus() const;
 
        /// Validate that all registered migrations have satisfiable dependencies.
        ///
        /// For each pending migration, verifies that every declared dependency is either
        /// already applied or itself pending (so it will be applied first due to topological
        /// ordering). Also detects cycles among pending migrations.
        ///
        /// @throws std::runtime_error if any dependency is unresolved or a cycle is found.
        LIGHTWEIGHT_API void ValidateDependencies() const;
 
        /// Register a release marker for a software version.
        ///
        /// Typically called from `LIGHTWEIGHT_SQL_RELEASE(version, timestamp)` at static init time.
        /// Releases are ordered by `highestTimestamp`; two releases may not share the same
        /// `highestTimestamp`, and the same version string may not be registered twice.
        ///
        /// @param version Human-readable version, e.g. "6.7.0".
        /// @param highestTimestamp Highest migration timestamp (inclusive) that belongs to this release.
        /// @param options Release options, e.g. `{ .requiresBackup = true }`.
        /// @throws std::runtime_error on duplicate version or duplicate timestamp.
        LIGHTWEIGHT_API void RegisterRelease(std::string version,
                                             MigrationTimestamp highestTimestamp,
                                             MigrationReleaseOptions options = {});
 
        /// Remove all registered releases. Useful for resetting state in tests.
        LIGHTWEIGHT_API void RemoveAllReleases();
 
        /// Get all registered releases, sorted ascending by `highestTimestamp`.
        [[nodiscard]] LIGHTWEIGHT_API std::vector<MigrationRelease> const& GetAllReleases() const noexcept;
 
        /// Find a release by exact version string match.
        ///
        /// @return Pointer to the matching release, or nullptr if no release with that version is registered.
        [[nodiscard]] LIGHTWEIGHT_API MigrationRelease const* FindReleaseByVersion(std::string_view version) const noexcept;
 
        /// Find the release whose timestamp range contains `timestamp`.
        ///
        /// Returns the release with the smallest `highestTimestamp` that is `>= timestamp`.
        /// Returns nullptr if `timestamp` is greater than every registered release's highestTimestamp
        /// (i.e., the migration is post-all-releases / unreleased).
        [[nodiscard]] LIGHTWEIGHT_API MigrationRelease const* FindReleaseForTimestamp(
            MigrationTimestamp timestamp) const noexcept;
 
        /// Get all registered migrations belonging to a given release.
        ///
        /// A migration `M` belongs to release `R` iff
        /// `prev_release_ts < M.timestamp <= R.highestTimestamp`, where `prev_release_ts` is the
        /// previous release's timestamp (or 0 if `R` is the first release).
        ///
        /// @param version The version string to look up.
        /// @return Migrations in the release, ordered by timestamp. Empty if the version is unknown.
        [[nodiscard]] LIGHTWEIGHT_API MigrationList GetMigrationsForRelease(std::string_view version) const;
 
        /// Whether the work a command will run needs a backup first, and whether one exists.
        ///
        /// Only that work counts: a migration of @p toRun demands a backup when it `RequiresBackup()` or
        /// its release declares `requiresBackup`, and a registered pre-migrate step when its
        /// `requiresBackup` predicate returns true (evaluated here, on the migration connection). Pass
        /// all pending migrations for `migrate`, the pending ones up to the release for
        /// `migrate-to-release`, the named one for `apply`. Only when something demands a backup are
        /// `schema_backups` and `schema_migrations` read: the newest `backup` or `restore` record must
        /// cover the database's current state (see `BackupRecordCovers`).
        ///
        /// @param toRun The migrations the command will run.
        /// @return The requirement; `required` is false when nothing demands a backup.
        /// @throws whatever a step's predicate throws.
        [[nodiscard]] LIGHTWEIGHT_API BackupRequirement BackupRequirementFor(std::span<MigrationTimestamp const> toRun);
 
      private:
        /// Return the pending list in dependency-respecting order.
        ///
        /// Dependencies among pending migrations are resolved via topological sort.
        /// Migrations with no dependency between them keep timestamp order.
        /// Throws on missing deps or cycles.
        [[nodiscard]] MigrationList TopoSortPending(MigrationList pending,
                                                    std::vector<MigrationTimestamp> const& applied) const;
 
        /// @brief Builds a fresh, policy-agnostic render context. The per-migration
        /// compat knobs are layered on by `ApplySingleMigration` / `PreviewMigrationWithContext`
        /// before rendering a given migration's steps.
        [[nodiscard]] static MigrationRenderContext MakeRenderContext();
 
        /// @brief Materialises any pending virtual-applied entries as real rows
        /// in `schema_migrations`. Creates the history table if necessary, then
        /// inserts one row per overlay entry that maps to a registered
        /// migration and is not yet present in the table. Clears the overlay on
        /// success. Called as the first action of every write path so the
        /// physical table only exists when there is at least one row to put in
        /// it.
        void PersistVirtualAppliedMigrations();
 
        /// @brief Counts the rows a committed migration's `IfNotExists` inserts skipped and logs
        /// each of @p skippedRows via @ref Log.
        void ReportSkippedRows(std::vector<std::string> const& skippedRows);
 
        /// A registered pre-migrate step with its code.
        struct RegisteredPreMigrateStep
        {
            std::string title;
            PreMigrateStepOptions options;
            PreMigrateStep run;
        };
 
        MigrationList _migrations;
        std::vector<MigrationRelease> _releases;
        std::unique_ptr<DataMapper> _dataMapper;
        /// The @ref SqlConnection::DefaultConnectionStringGeneration @c _dataMapper was connected under.
        std::uint32_t _dataMapperGeneration {};
        CompatPolicy _compatPolicy;
        std::string _defaultSchema; ///< Default schema applied to migration connections, empty when unset.
 
        /// @brief In-memory overlay of applied migration timestamps that are
        /// not (yet) persisted to `schema_migrations`. Populated by plugin
        /// post-init hooks via `AddVirtualAppliedMigrations`; drained into the
        /// table by `PersistVirtualAppliedMigrations` whenever the manager
        /// transitions from a read-only state into actually writing. Always
        /// kept sorted ascending and deduplicated.
        std::vector<MigrationTimestamp> _virtualAppliedIds;
 
        LogSink _logSink; ///< Optional status-message sink. Empty by default.
 
        std::size_t _skippedExistingRowCount {}; ///< Rows skipped by `IfNotExists` inserts so far.
 
        /// Registered pre-migrate steps, in registration order.
        std::vector<RegisteredPreMigrateStep> _preMigrateSteps;
    };
 
/// Requires the user to call LIGHTWEIGHT_MIGRATION_PLUGIN() in exactly one CPP file of the migration plugin.
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_MIGRATION_PLUGIN()                                                                   \
    /* NOLINTNEXTLINE(bugprone-macro-parentheses) */                                                     \
    extern "C" LIGHTWEIGHT_EXPORT Lightweight::SqlMigration::MigrationManager* AcquireMigrationManager() \
    {                                                                                                    \
        return &Lightweight::SqlMigration::MigrationManager::GetInstance();                              \
    }
 
/// Defines the non-throwing exported C entry point @p entryPoint of a plugin hook, which runs the
/// body that follows the macro as @p body and hands the message of an exception it throws to the
/// host's error sink, returning false; no exception crosses the shared-library boundary. Use
/// `LIGHTWEIGHT_MIGRATION_PLUGIN_POSTINIT` or `LIGHTWEIGHT_MIGRATION_PLUGIN_POSTMIGRATE` instead.
#define LIGHTWEIGHT_DETAIL_MIGRATION_PLUGIN_HOOK(entryPoint, body, connArg, mgrArg)                           \
    static void body(Lightweight::SqlConnection&, Lightweight::SqlMigration::MigrationManager&);              \
    extern "C" LIGHTWEIGHT_EXPORT bool entryPoint(Lightweight::SqlConnection& connection,                     \
                                                  Lightweight::SqlMigration::MigrationManager& manager,       \
                                                  Lightweight::SqlMigration::PluginHookErrorSink reportError, \
                                                  void* errorContext) noexcept                                \
    {                                                                                                         \
        try                                                                                                   \
        {                                                                                                     \
            body(connection, manager);                                                                        \
            return true;                                                                                      \
        }                                                                                                     \
        catch (std::exception const& exception)                                                               \
        {                                                                                                     \
            if (reportError != nullptr)                                                                       \
                reportError(errorContext, exception.what());                                                  \
        }                                                                                                     \
        catch (...)                                                                                           \
        {                                                                                                     \
            if (reportError != nullptr)                                                                       \
                reportError(errorContext, "unknown exception");                                               \
        }                                                                                                     \
        return false;                                                                                         \
    }                                                                                                         \
    static void body(Lightweight::SqlConnection&(connArg), Lightweight::SqlMigration::MigrationManager&(mgrArg))
 
/// Optional hook executed once per plugin by dbtool, after migration history has been
/// created and an active connection is available on the central manager. Plugins use
/// this to perform one-shot bridging work that needs both a live `SqlConnection` and
/// the merged `MigrationManager` — for example, importing legacy version tracking
/// from a custom table into `schema_migrations`.
///
/// A hook body that throws is reported by the host and does not stop it. The macro exports the
/// non-throwing C entry point `LightweightMigrationPluginPostInitReported`, which catches the
/// exception and hands its message to the host, so no exception crosses the shared-library
/// boundary, whatever exception model the plugin uses. Hosts skip, with a warning, a plugin that
/// exports only the earlier `LightweightMigrationPluginPostInit`; rebuild such a plugin.
///
/// Use as:
///
/// @code
/// LIGHTWEIGHT_MIGRATION_PLUGIN_POSTINIT(connection, manager)
/// {
///     MyPlugin::ImportLegacyVersions(manager, connection);
/// }
/// @endcode
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_MIGRATION_PLUGIN_POSTINIT(connArg, mgrArg) \
    LIGHTWEIGHT_DETAIL_MIGRATION_PLUGIN_HOOK(                  \
        LightweightMigrationPluginPostInitReported, LightweightMigrationPluginPostInitBody, connArg, mgrArg)
 
/// Optional hook executed once per plugin by dbtool and dbtool-gui after a successful
/// `migrate`, `migrate-to-release` or `apply`, including runs where nothing was pending.
/// It runs on the migration connection while the migration lock is still held (unless the
/// caller opted out of locking, as with `dbtool --no-lock`), and never for dry runs,
/// read-only commands or a failed migration. Plugins use it for work that
/// needs the migrated schema, such as seeding reference data.
///
/// A hook body that throws makes the command fail; the migrations it ran after stay applied.
/// The macro exports a non-throwing C entry point that catches the exception and hands its
/// message to the host, so no exception crosses the shared-library boundary.
///
/// Use as:
///
/// @code
/// LIGHTWEIGHT_MIGRATION_PLUGIN_POSTMIGRATE(connection, manager)
/// {
///     MyPlugin::SeedReferenceData(connection);
/// }
/// @endcode
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_MIGRATION_PLUGIN_POSTMIGRATE(connArg, mgrArg) \
    LIGHTWEIGHT_DETAIL_MIGRATION_PLUGIN_HOOK(                     \
        LightweightMigrationPluginPostMigrate, LightweightMigrationPluginPostMigrateBody, connArg, mgrArg)
 
    /// Host-supplied sink that a plugin's post-init or post-migrate entry point reports a failure
    /// message to. The entry point skips the report when the host passes a null sink.
    /// @param context The opaque context the host passed alongside the sink.
    /// @param message The failure message, only valid for the duration of the call. May be null
    ///                (an exception whose `what()` returns null), so the sink must handle that.
    using PluginHookErrorSink = void (*)(void* context, char const* message) noexcept;
 
    /// The sink of the post-migrate entry point; see `PluginHookErrorSink`.
    using PostMigrateErrorSink = PluginHookErrorSink;
 
    /// Represents a single unique SQL migration.
    ///
    /// @ingroup SqlMigration
    class MigrationBase
    {
      public:
        /// Default copy constructor.
        MigrationBase(MigrationBase const&) = default;
        MigrationBase(MigrationBase&&) = delete;
        /// Default copy assignment operator.
        MigrationBase& operator=(MigrationBase const&) = default;
        MigrationBase& operator=(MigrationBase&&) = delete;
        /// Constructs a migration with the given timestamp and title.
        MigrationBase(MigrationTimestamp timestamp, std::string_view title):
            _timestamp { timestamp },
            _title { title }
        {
            MigrationManager::GetInstance().AddMigration(this);
        }
 
        /// Unregisters this migration from the singleton manager the constructor registered it with.
        ///
        /// Registration is a side effect of construction, so deregistration has to be one of
        /// destruction: otherwise the manager keeps a pointer to a dead object, and its
        /// duplicate-timestamp lookup dereferences it. A later migration reusing that storage is then
        /// reported as a duplicate of itself.
        virtual ~MigrationBase()
        {
            MigrationManager::GetInstance().RemoveMigration(this);
        }
 
        /// Apply the migration.
        ///
        /// @param plan Query builder to use for building the migration plan.
        virtual void Up(SqlMigrationQueryBuilder& plan) const = 0;
 
        /// Revert the migration.
        ///
        /// @param plan Query builder to use for building the migration plan.
        virtual void Down(SqlMigrationQueryBuilder& plan) const
        {
            (void) plan;
        }
 
        /// Check if this migration has a Down() implementation for rollback.
        ///
        /// This method determines whether the migration can be safely reverted.
        /// The default implementation returns false. Derived classes that implement
        /// Down() should override this to return true.
        ///
        /// @return true if Down() is implemented and can revert this migration.
        [[nodiscard]] virtual bool HasDownImplementation() const noexcept
        {
            return false;
        }
 
        /// Get the timestamps of migrations that this migration depends on.
        ///
        /// Dependencies are enforced at apply time: each declared dependency must be
        /// registered and applied (or pending in the same run, in dependency order)
        /// before this migration will run. The default implementation returns no
        /// dependencies, preserving timestamp-ordered apply behavior.
        ///
        /// @return Vector of dependency timestamps. Empty if this migration has none.
        [[nodiscard]] virtual std::vector<MigrationTimestamp> GetDependencies() const
        {
            return {};
        }
 
        /// Get the author of the migration, if any.
        ///
        /// @return Author string, empty if not set.
        [[nodiscard]] virtual std::string_view GetAuthor() const noexcept
        {
            return {};
        }
 
        /// Get the long-form description of the migration, if any.
        ///
        /// This is a multi-line description in addition to the short title.
        ///
        /// @return Description string, empty if not set.
        [[nodiscard]] virtual std::string_view GetDescription() const noexcept
        {
            return {};
        }
 
        /// Whether running this migration requires a backup of the database taken after its last
        /// migration (see `MigrationManager::BackupRequirementFor`). A release's `requiresBackup` adds
        /// the same demand for all of its migrations.
        ///
        /// @return False unless overridden.
        [[nodiscard]] virtual bool RequiresBackup() const noexcept
        {
            return false;
        }
 
        /// Get the timestamp of the migration.
        ///
        /// @return Timestamp of the migration.
        [[nodiscard]] MigrationTimestamp GetTimestamp() const noexcept
        {
            return _timestamp;
        }
 
        /// Get the title of the migration.
        ///
        /// @return Title of the migration.
        [[nodiscard]] std::string_view GetTitle() const noexcept
        {
            return _title;
        }
 
        /// Compute SHA-256 checksum of migration's Up() SQL statements.
        ///
        /// The checksum is computed from the SQL statements that would be executed
        /// by this migration. This allows detecting if a migration has been modified
        /// after it was applied.
        ///
        /// @param formatter The SQL query formatter to use for generating SQL.
        /// @return SHA-256 hex string (64 characters).
        [[nodiscard]] LIGHTWEIGHT_API std::string ComputeChecksum(SqlQueryFormatter const& formatter) const;
 
      private:
        MigrationTimestamp _timestamp;
        std::string_view _title;
    };
 
    /// Represents a single unique SQL migration.
    ///
    /// This class is a convenience class that can be used to create a migration.
    ///
    /// @ingroup SqlMigration
    /// Optional metadata attached to a Migration at construction time.
    ///
    /// All fields are optional. Unset fields behave as if the feature
    /// were not used (e.g. empty dependencies preserves timestamp order).
    ///
    /// @ingroup SqlMigration
    struct MigrationMetadata
    {
        /// Migrations that must be applied before this one.
        std::vector<MigrationTimestamp> dependencies {};
        /// Author of the migration. Recorded in schema_migrations when the migration is applied.
        std::string_view author {};
        /// Long-form description. Recorded in schema_migrations when the migration is applied.
        std::string_view description {};
        /// Whether running the migration requires a backup; see `MigrationBase::RequiresBackup`.
        bool requiresBackup = false;
    };
 
    template <uint64_t TsValue>
    class Migration: public MigrationBase
    {
      public:
        /// The migration's timestamp, available at compile time from the type itself.
        ///
        /// Exposed so @ref TimestampOf can extract the timestamp without
        /// having to repeat the literal at every use site (e.g. in dependency lists).
        static constexpr MigrationTimestamp TimeStamp { TsValue };
 
        /// Create a new migration.
        ///
        /// @param title Title of the migration.
        /// @param up Function to apply the migration.
        /// @param down Function to revert the migration (optional).
        Migration(std::string_view title,
                  std::function<void(SqlMigrationQueryBuilder&)> const& up,
                  std::function<void(SqlMigrationQueryBuilder&)> const& down = {}):
            MigrationBase(TimeStamp, title),
            _up { up },
            _down { down }
        {
        }
 
        /// Create a new migration with optional metadata (dependencies, author, description).
        ///
        /// @param title Title of the migration.
        /// @param metadata Optional metadata including dependencies, author, and description.
        /// @param up Function to apply the migration.
        /// @param down Function to revert the migration (optional).
        Migration(std::string_view title,
                  MigrationMetadata metadata,
                  std::function<void(SqlMigrationQueryBuilder&)> const& up,
                  std::function<void(SqlMigrationQueryBuilder&)> const& down = {}):
            MigrationBase(TimeStamp, title),
            _up { up },
            _down { down },
            _metadata { std::move(metadata) }
        {
        }
 
        /// Apply the migration.
        ///
        /// @param builder Query builder to use for building the migration plan.
        void Up(SqlMigrationQueryBuilder& builder) const override
        {
            _up(builder);
        }
 
        /// Revert the migration.
        ///
        /// @param builder Query builder to use for building the migration plan.
        void Down(SqlMigrationQueryBuilder& builder) const override
        {
            if (_down)
                _down(builder);
        }
 
        /// Check if this migration has a Down() implementation.
        ///
        /// @return true if a down function was provided.
        [[nodiscard]] bool HasDownImplementation() const noexcept override
        {
            return static_cast<bool>(_down);
        }
 
        /// Get the declared dependencies for this migration.
        [[nodiscard]] std::vector<MigrationTimestamp> GetDependencies() const override
        {
            return _metadata.dependencies;
        }
 
        /// Get the author of this migration.
        [[nodiscard]] std::string_view GetAuthor() const noexcept override
        {
            return _metadata.author;
        }
 
        /// Get the long-form description of this migration.
        [[nodiscard]] std::string_view GetDescription() const noexcept override
        {
            return _metadata.description;
        }
 
        /// Whether running this migration requires a backup; see `MigrationBase::RequiresBackup`.
        [[nodiscard]] bool RequiresBackup() const noexcept override
        {
            return _metadata.requiresBackup;
        }
 
      private:
        std::function<void(SqlMigrationQueryBuilder&)> _up;
        std::function<void(SqlMigrationQueryBuilder&)> _down;
        MigrationMetadata _metadata {};
    };
 
    /// Extracts the @ref MigrationTimestamp from a migration type that exposes a static
    /// constexpr `TimeStamp` member.
    ///
    /// Works with both the class template @ref Migration and the struct generated by the
    /// @ref LIGHTWEIGHT_SQL_MIGRATION macro. Use via `decltype`:
    ///
    /// @code
    /// auto migrationA = SqlMigration::Migration<202601010001>("dep base", [](auto&){ ... });
    /// auto tsA = TimestampOf<decltype(migrationA)>; // MigrationTimestamp { 202601010001 }
    /// @endcode
    ///
    /// @tparam T A migration type exposing `static constexpr MigrationTimestamp TimeStamp`.
    template <typename T>
    inline constexpr MigrationTimestamp TimestampOf = T::TimeStamp;
 
    namespace detail
    {
        /// RAII registrar used by `LIGHTWEIGHT_SQL_RELEASE` to register a release with the
        /// migration manager at static-initialization time. Not intended for direct use.
        ///
        /// @ingroup SqlMigration
        struct ReleaseRegistrar
        {
            /// Registers `{version, highestTimestamp, options}` with the singleton manager.
            ReleaseRegistrar(std::string version, MigrationTimestamp highestTimestamp, MigrationReleaseOptions options = {})
            {
                MigrationManager::GetInstance().RegisterRelease(std::move(version), highestTimestamp, options);
            }
 
            /// Registers `{version, highestTimestamp, options}` with the singleton manager.
            ReleaseRegistrar(std::string version, std::uint64_t highestTimestamp, MigrationReleaseOptions options = {})
            {
                MigrationManager::GetInstance().RegisterRelease(
                    std::move(version), MigrationTimestamp { highestTimestamp }, options);
            }
        };
    } // namespace detail
 
} // namespace SqlMigration
 
} // namespace Lightweight
 
#define _LIGHTWEIGHT_CONCATENATE(s1, s2)       s1##s2
#define _LIGHTWEIGHT_CONCATENATE_INNER(s1, s2) _LIGHTWEIGHT_CONCATENATE(s1, s2)
 
/// @brief Represents the C++ migration object for a given timestamped migration.
/// @param timestamp Timestamp of the migration.
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_MIGRATION_INSTANCE(timestamp) migration_##timestamp
 
/// @brief Creates a new migration.
/// @param timestamp Timestamp of the migration.
/// @param description Description of the migration.
///
/// @note The migration will be registered with the migration manager automatically.
///
/// @code
/// #include <Lightweight/SqlMigration.hpp>
///
/// LIGHTWEIGHT_SQL_MIGRATION(20260117234120, "Create table 'MyTable'")
/// {
///     // Use 'plan' to define the migration steps, for example creating tables.
/// }
/// @endcode
///
/// @see Lightweight::SqlMigrationQueryBuilder
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_SQL_MIGRATION(timestamp, description)                                                              \
    struct Migration_##timestamp: public Lightweight::SqlMigration::MigrationBase                                      \
    {                                                                                                                  \
        /** The migration's timestamp, exposed so @ref TimestampOf can extract it from the type. */                    \
        static constexpr Lightweight::SqlMigration::MigrationTimestamp TimeStamp { static_cast<uint64_t>(timestamp) }; \
        explicit Migration_##timestamp():                                                                              \
            Lightweight::SqlMigration::MigrationBase(TimeStamp, description)                                           \
        {                                                                                                              \
        }                                                                                                              \
                                                                                                                       \
        void Up(Lightweight::SqlMigrationQueryBuilder& plan) const override;                                           \
        void Down(Lightweight::SqlMigrationQueryBuilder& /*plan*/) const override {}                                   \
    };                                                                                                                 \
                                                                                                                       \
    static Migration_##timestamp _LIGHTWEIGHT_CONCATENATE(migration_, timestamp);                                      \
                                                                                                                       \
    void Migration_##timestamp::Up(Lightweight::SqlMigrationQueryBuilder& plan) const
 
/// @brief Creates a new reversible migration whose `Down()` is defined out-of-line
/// via @ref LIGHTWEIGHT_SQL_MIGRATION_DOWN.
///
/// Use this variant when the migration needs to be reversible. Follow the macro with
/// the `Up()` body, then later use `LIGHTWEIGHT_SQL_MIGRATION_DOWN(timestamp) { ... }`
/// to provide the `Down()` body.
///
/// @param timestamp Timestamp of the migration.
/// @param description Description of the migration.
///
/// @code
/// LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE(20260117234120, "Create table 'MyTable'")
/// {
///     plan.CreateTable("MyTable").PrimaryKey("id", Integer());
/// }
///
/// LIGHTWEIGHT_SQL_MIGRATION_DOWN(20260117234120)
/// {
///     plan.DropTable("MyTable");
/// }
/// @endcode
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE(timestamp, description)                                              \
    struct Migration_##timestamp: public Lightweight::SqlMigration::MigrationBase                                 \
    {                                                                                                             \
        explicit Migration_##timestamp():                                                                         \
            Lightweight::SqlMigration::MigrationBase(Lightweight::SqlMigration::MigrationTimestamp { timestamp }, \
                                                     description)                                                 \
        {                                                                                                         \
        }                                                                                                         \
                                                                                                                  \
        void Up(Lightweight::SqlMigrationQueryBuilder& plan) const override;                                      \
        void Down(Lightweight::SqlMigrationQueryBuilder& plan) const override;                                    \
                                                                                                                  \
        [[nodiscard]] bool HasDownImplementation() const noexcept override                                        \
        {                                                                                                         \
            return true;                                                                                          \
        }                                                                                                         \
    };                                                                                                            \
                                                                                                                  \
    static Migration_##timestamp _LIGHTWEIGHT_CONCATENATE(migration_, timestamp);                                 \
                                                                                                                  \
    void Migration_##timestamp::Up(Lightweight::SqlMigrationQueryBuilder& plan) const
 
/// @brief Companion to @ref LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE — defines the out-of-line `Down()` body.
///
/// Must be used in the same translation unit and follow the matching
/// `LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE(timestamp, ...)` declaration.
///
/// @param timestamp Timestamp of the migration whose Down() body follows.
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_SQL_MIGRATION_DOWN(timestamp) \
    void Migration_##timestamp::Down(Lightweight::SqlMigrationQueryBuilder& plan) const
 
/// @brief Associates a software release (version string) with the highest migration timestamp
/// present at the time of that release.
///
/// Declare one `LIGHTWEIGHT_SQL_RELEASE` per cut release, alongside the migrations that belong to it.
/// The macro registers with the migration manager at static-initialization time. Multiple releases
/// may coexist in the same translation unit.
///
/// @param version A string literal, e.g. `"2.0.0"`.
/// @param ... The highest migration timestamp of the release, optionally followed by its
///            `MigrationReleaseOptions`, e.g. `{ .requiresBackup = true }`.
///
/// @code
/// LIGHTWEIGHT_SQL_RELEASE("1.0.0", 20260101120000);
/// LIGHTWEIGHT_SQL_RELEASE("2.0.0", 20260501120000, { .requiresBackup = true });
/// @endcode
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_SQL_RELEASE(version, ...)                                                                              \
    static ::Lightweight::SqlMigration::detail::ReleaseRegistrar _LIGHTWEIGHT_CONCATENATE_INNER(_lw_release_, __COUNTER__) \
    {                                                                                                                      \
        (version), __VA_ARGS__                                                                                             \
    }