SqlMigration.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "Api.hpp"
#include "DataMapper/DataMapper.hpp"
#include "SqlQuery/Migrate.hpp"
#include "SqlSchema.hpp"
#include "SqlTransaction.hpp"
 
#include <functional>
#include <list>
#include <map>
#include <optional>
#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;
    };
 
    /// 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;                           ///< Error message if failed
    };
 
    /// 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)`. 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;
    };
 
    /// 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 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.
        ///
        /// @return List of pending migrations.
        [[nodiscard]] LIGHTWEIGHT_API std::list<MigrationBase const*> GetPending() const noexcept;
 
        /// 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);
 
        /// 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 = {});
 
        /// Create the migration history table if it does not exist.
        LIGHTWEIGHT_API void CreateMigrationHistory();
 
        /// Get all applied migration IDs.
        ///
        /// @return Vector of applied migration IDs.
        [[nodiscard]] LIGHTWEIGHT_API std::vector<MigrationTimestamp> GetAppliedMigrationIds() const;
 
        /// Get the data mapper used for migrations.
        [[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();
 
        /// 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;
 
        /// 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;
 
        /// 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.
        /// @throws std::runtime_error on duplicate version or duplicate timestamp.
        LIGHTWEIGHT_API void RegisterRelease(std::string version, MigrationTimestamp highestTimestamp);
 
        /// 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;
 
        /// @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 `dbtool fold` to emit a
        /// self-contained baseline (`.cpp` plugin or `.sql`).
        struct PlanFoldingResult
        {
            /// Per-table state: ordered column declarations + per-table FK list.
            struct TableState
            {
                /// Ordered column declarations as they should appear in the emitted CREATE TABLE.
                std::vector<SqlColumnDeclaration> columns;
 
                /// Composite (multi-column) foreign keys declared on this table.
                std::vector<SqlCompositeForeignKeyConstraint> compositeForeignKeys;
 
                /// True when the original migration created the table with `IF NOT EXISTS`.
                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 to replay (INSERT/UPDATE/DELETE/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;
 
      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;
 
        MigrationList _migrations;
        std::vector<MigrationRelease> _releases;
        mutable DataMapper* _dataMapper { nullptr };
    };
 
/// 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();                              \
    }
 
    /// 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);
        }
 
        virtual ~MigrationBase() = default;
 
        /// 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 {};
        }
 
        /// 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 {};
    };
 
    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;
        }
 
      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}` with the singleton manager.
            ReleaseRegistrar(std::string version, MigrationTimestamp highestTimestamp)
            {
                MigrationManager::GetInstance().RegisterRelease(std::move(version), highestTimestamp);
            }
        };
    } // 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 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. `"6.7.0"`.
/// @param highestTimestamp An unsigned integer literal matching the timestamp format used by migrations.
///
/// @code
/// LIGHTWEIGHT_SQL_MIGRATION(20260101120000, "Initial schema") { ... }
/// LIGHTWEIGHT_SQL_RELEASE("6.6.0", 20260101120000);
///
/// LIGHTWEIGHT_SQL_MIGRATION(20260501120000, "Add orders table") { ... }
/// LIGHTWEIGHT_SQL_RELEASE("6.7.0", 20260501120000);
/// @endcode
///
/// @ingroup SqlMigration
#define LIGHTWEIGHT_SQL_RELEASE(version, highestTimestamp)                                                                 \
    static ::Lightweight::SqlMigration::detail::ReleaseRegistrar _LIGHTWEIGHT_CONCATENATE_INNER(_lw_release_, __COUNTER__) \
    {                                                                                                                      \
        (version), ::Lightweight::SqlMigration::MigrationTimestamp                                                         \
        {                                                                                                                  \
            (highestTimestamp)                                                                                             \
        }                                                                                                                  \
    }