Classes and functions for SQL schema migrations. More...

Classes
struct	Lightweight::SqlMigration::MigrationTimestamp

class	Lightweight::SqlMigration::MigrationException

struct	Lightweight::SqlMigration::ChecksumVerificationResult

struct	Lightweight::SqlMigration::RevertResult

struct	Lightweight::SqlMigration::MigrationStatus

struct	Lightweight::SqlMigration::MigrationRelease

class	Lightweight::SqlMigration::MigrationManager

class	Lightweight::SqlMigration::MigrationBase

struct	Lightweight::SqlMigration::MigrationMetadata

Macros
#define	LIGHTWEIGHT_MIGRATION_PLUGIN()

#define	LIGHTWEIGHT_MIGRATION_PLUGIN_POSTINIT(connArg, mgrArg)

#define	LIGHTWEIGHT_MIGRATION_INSTANCE(timestamp) migration_##timestamp
	Represents the C++ migration object for a given timestamped migration.

#define	LIGHTWEIGHT_SQL_MIGRATION(timestamp, description)
	Creates a new migration.

#define	LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE(timestamp, description)
	Creates a new reversible migration whose `Down()` is defined out-of-line via LIGHTWEIGHT_SQL_MIGRATION_DOWN.

#define	LIGHTWEIGHT_SQL_MIGRATION_DOWN(timestamp) void Migration_##timestamp::Down(Lightweight::SqlMigrationQueryBuilder& plan) const
	Companion to LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE — defines the out-of-line `Down()` body.

#define	LIGHTWEIGHT_SQL_RELEASE(version, highestTimestamp)
	Associates a software release (version string) with the highest migration timestamp present at the time of that release.

Detailed Description

Classes and functions for SQL schema migrations.

Macro Definition Documentation

◆ LIGHTWEIGHT_MIGRATION_PLUGIN

#define LIGHTWEIGHT_MIGRATION_PLUGIN ( )

Value:

    /* NOLINTNEXTLINE(bugprone-macro-parentheses) */                                                     \
    extern "C" LIGHTWEIGHT_EXPORT Lightweight::SqlMigration::MigrationManager* AcquireMigrationManager() \
    {                                                                                                    \
        return &Lightweight::SqlMigration::MigrationManager::GetInstance();                              \
    }

Requires the user to call LIGHTWEIGHT_MIGRATION_PLUGIN() in exactly one CPP file of the migration plugin.

Definition at line 785 of file SqlMigration.hpp.

◆ LIGHTWEIGHT_MIGRATION_PLUGIN_POSTINIT

#define LIGHTWEIGHT_MIGRATION_PLUGIN_POSTINIT	(	connArg,
		mgrArg
	)

Value:

extern "C" LIGHTWEIGHT_EXPORT void LightweightMigrationPluginPostInit( \

Lightweight::SqlConnection&(connArg), Lightweight::SqlMigration::MigrationManager&(mgrArg))

Lightweight::SqlConnection

Represents a connection to a SQL database.

Definition SqlConnection.hpp:41

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.

Use as:

LIGHTWEIGHT_MIGRATION_PLUGIN_POSTINIT(connection, manager)
{
    MyPlugin::ImportLegacyVersions(manager, connection);
}

Definition at line 808 of file SqlMigration.hpp.

◆ LIGHTWEIGHT_MIGRATION_INSTANCE

#define LIGHTWEIGHT_MIGRATION_INSTANCE ( timestamp ) migration_##timestamp

Represents the C++ migration object for a given timestamped migration.

Parameters

timestamp Timestamp of the migration.

Definition at line 1074 of file SqlMigration.hpp.

◆ LIGHTWEIGHT_SQL_MIGRATION

#define LIGHTWEIGHT_SQL_MIGRATION	(	timestamp,
		description
	)

Value:

    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

Creates a new migration.

Parameters

timestamp	Timestamp of the migration.
description	Description of the migration.

Note: The migration will be registered with the migration manager automatically.

#include <Lightweight/SqlMigration.hpp>
 
LIGHTWEIGHT_SQL_MIGRATION(20260117234120, "Create table 'MyTable'")
{
    // Use 'plan' to define the migration steps, for example creating tables.
}

See also: Lightweight::SqlMigrationQueryBuilder

Definition at line 1094 of file SqlMigration.hpp.

◆ LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE

#define LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE	(	timestamp,
		description
	)

Value:

    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

Creates a new reversible migration whose Down() is defined out-of-line via 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.

Parameters

timestamp	Timestamp of the migration.
description	Description of the migration.

LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE(20260117234120, "Create table 'MyTable'")
{
    plan.CreateTable("MyTable").PrimaryKey("id", Integer());
}
 
LIGHTWEIGHT_SQL_MIGRATION_DOWN(20260117234120)
{
    plan.DropTable("MyTable");
}

Definition at line 1135 of file SqlMigration.hpp.

◆ LIGHTWEIGHT_SQL_MIGRATION_DOWN

#define LIGHTWEIGHT_SQL_MIGRATION_DOWN ( timestamp ) void Migration_##timestamp::Down(Lightweight::SqlMigrationQueryBuilder& plan) const

Companion to 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.

Parameters

timestamp Timestamp of the migration whose Down() body follows.

Definition at line 1165 of file SqlMigration.hpp.

◆ LIGHTWEIGHT_SQL_RELEASE

#define LIGHTWEIGHT_SQL_RELEASE	(	version,
		highestTimestamp
	)

Value:

    static ::Lightweight::SqlMigration::detail::ReleaseRegistrar _LIGHTWEIGHT_CONCATENATE_INNER(_lw_release_, __COUNTER__) \
    {                                                                                                                      \
        (version), ::Lightweight::SqlMigration::MigrationTimestamp                                                         \
        {                                                                                                                  \
            (highestTimestamp)                                                                                             \
        }                                                                                                                  \
    }

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.

Parameters

version	A string literal, e.g. `"6.7.0"`.
highestTimestamp	An unsigned integer literal matching the timestamp format used by migrations.

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);

Definition at line 1187 of file SqlMigration.hpp.

Classes

Macros

Detailed Description

Macro Definition Documentation

◆ LIGHTWEIGHT_MIGRATION_PLUGIN

◆ LIGHTWEIGHT_MIGRATION_PLUGIN_POSTINIT

◆ LIGHTWEIGHT_MIGRATION_INSTANCE

◆ LIGHTWEIGHT_SQL_MIGRATION

◆ LIGHTWEIGHT_SQL_MIGRATION_REVERSIBLE

◆ LIGHTWEIGHT_SQL_MIGRATION_DOWN

◆ LIGHTWEIGHT_SQL_RELEASE