#include <SqlMigration.hpp>

Classes
struct	PlanFoldingResult
	Snapshot of the schema the registered migrations intend to produce. More...

Public Types
using	MigrationList = std::list< MigrationBase const * >
	Type alias for a list of migration pointers.

using	ExecuteCallback = std::function< void(MigrationBase const &, size_t, size_t)>
	Callback type invoked during migration execution to report progress.

Public Member Functions
LIGHTWEIGHT_API void	AddMigration (MigrationBase const *migration)

LIGHTWEIGHT_API MigrationList const &	GetAllMigrations () const noexcept

LIGHTWEIGHT_API MigrationBase const *	GetMigration (MigrationTimestamp timestamp) const noexcept

LIGHTWEIGHT_API void	RemoveAllMigrations ()

LIGHTWEIGHT_API std::list< MigrationBase const * >	GetPending () const noexcept

LIGHTWEIGHT_API void	ApplySingleMigration (MigrationBase const &migration)

LIGHTWEIGHT_API void	RevertSingleMigration (MigrationBase const &migration)

LIGHTWEIGHT_API size_t	ApplyPendingMigrations (ExecuteCallback const &feedbackCallback={})

LIGHTWEIGHT_API void	CreateMigrationHistory ()
	Create the migration history table if it does not exist.

LIGHTWEIGHT_API std::vector< MigrationTimestamp >	GetAppliedMigrationIds () const

LIGHTWEIGHT_API DataMapper &	GetDataMapper ()
	Get the data mapper used for migrations.

LIGHTWEIGHT_API DataMapper &	GetDataMapper () const
	Get the data mapper used for migrations.

LIGHTWEIGHT_API void	CloseDataMapper ()

LIGHTWEIGHT_API SqlTransaction	Transaction ()

LIGHTWEIGHT_API std::vector< std::string >	PreviewMigration (MigrationBase const &migration) const

LIGHTWEIGHT_API std::vector< std::string >	PreviewPendingMigrations (ExecuteCallback const &feedbackCallback={}) const

LIGHTWEIGHT_API std::vector< ChecksumVerificationResult >	VerifyChecksums () const

LIGHTWEIGHT_API void	MarkMigrationAsApplied (MigrationBase const &migration)

LIGHTWEIGHT_API RevertResult	RevertToMigration (MigrationTimestamp target, ExecuteCallback const &feedbackCallback={})

LIGHTWEIGHT_API MigrationStatus	GetMigrationStatus () const

LIGHTWEIGHT_API void	ValidateDependencies () const

LIGHTWEIGHT_API void	RegisterRelease (std::string version, MigrationTimestamp highestTimestamp)

LIGHTWEIGHT_API void	RemoveAllReleases ()
	Remove all registered releases. Useful for resetting state in tests.

LIGHTWEIGHT_API std::vector< MigrationRelease > const &	GetAllReleases () const noexcept
	Get all registered releases, sorted ascending by `highestTimestamp`.

LIGHTWEIGHT_API MigrationRelease const *	FindReleaseByVersion (std::string_view version) const noexcept

LIGHTWEIGHT_API MigrationRelease const *	FindReleaseForTimestamp (MigrationTimestamp timestamp) const noexcept

LIGHTWEIGHT_API MigrationList	GetMigrationsForRelease (std::string_view version) const

LIGHTWEIGHT_API PlanFoldingResult	FoldRegisteredMigrations (SqlQueryFormatter const &formatter, std::optional< MigrationTimestamp > upToInclusive=std::nullopt) const
	Pure plan-walk that folds the effect of every registered migration.

Static Public Member Functions
static LIGHTWEIGHT_API MigrationManager &	GetInstance ()

Detailed Description

Main API to use for managing SQL migrations

This class is a singleton and can be accessed using the GetInstance() method.

Definition at line 107 of file SqlMigration.hpp.

Member Typedef Documentation

◆ MigrationList

using Lightweight::SqlMigration::MigrationManager::MigrationList = std::list<MigrationBase const*>

Type alias for a list of migration pointers.

Definition at line 111 of file SqlMigration.hpp.

◆ ExecuteCallback

using Lightweight::SqlMigration::MigrationManager::ExecuteCallback = std::function<void(MigrationBase const& , size_t , size_t )>

Callback type invoked during migration execution to report progress.

Definition at line 148 of file SqlMigration.hpp.

Member Function Documentation

◆ GetInstance()

static LIGHTWEIGHT_API MigrationManager & Lightweight::SqlMigration::MigrationManager::GetInstance ( )

static

Get the singleton instance of the migration manager.

Returns: Reference to the migration manager. Get the singleton instance of the migration manager.; Reference to the migration manager.

Referenced by Lightweight::SqlMigration::MigrationBase::MigrationBase().

◆ AddMigration()

LIGHTWEIGHT_API void Lightweight::SqlMigration::MigrationManager::AddMigration ( MigrationBase const * migration )

Add a migration to the manager.

Parameters

migration Pointer to the migration to add.

Referenced by Lightweight::SqlMigration::MigrationBase::MigrationBase().

◆ GetAllMigrations()

LIGHTWEIGHT_API MigrationList const & Lightweight::SqlMigration::MigrationManager::GetAllMigrations ( ) const

noexcept

Get all migrations that have been added to the manager.

Returns: List of migrations.

◆ GetMigration()

LIGHTWEIGHT_API MigrationBase const * Lightweight::SqlMigration::MigrationManager::GetMigration ( MigrationTimestamp timestamp ) const

noexcept

Get a migration by timestamp.

Parameters

timestamp Timestamp of the migration to get.

Returns: Pointer to the migration if found, nullptr otherwise.

◆ RemoveAllMigrations()

LIGHTWEIGHT_API void Lightweight::SqlMigration::MigrationManager::RemoveAllMigrations ( )

Remove all migrations from the manager.

This function is useful if the migration manager should be reset.

◆ GetPending()

LIGHTWEIGHT_API std::list< MigrationBase const * > Lightweight::SqlMigration::MigrationManager::GetPending ( ) const

noexcept

Get all migrations that have not been applied yet.

Returns: List of pending migrations.

◆ ApplySingleMigration()

LIGHTWEIGHT_API void Lightweight::SqlMigration::MigrationManager::ApplySingleMigration ( MigrationBase const & migration )

Apply a single migration from a migration object.

Parameters

migration Pointer to the migration to apply.

◆ RevertSingleMigration()

LIGHTWEIGHT_API void Lightweight::SqlMigration::MigrationManager::RevertSingleMigration ( MigrationBase const & migration )

Revert a single migration from a migration object.

Parameters

migration Pointer to the migration to revert.

◆ ApplyPendingMigrations()

LIGHTWEIGHT_API size_t Lightweight::SqlMigration::MigrationManager::ApplyPendingMigrations ( ExecuteCallback const & feedbackCallback = {} )

Apply all migrations that have not been applied yet.

Parameters

feedbackCallback Callback to be called for each migration.

Returns: Number of applied migrations.

◆ GetAppliedMigrationIds()

LIGHTWEIGHT_API std::vector< MigrationTimestamp > Lightweight::SqlMigration::MigrationManager::GetAppliedMigrationIds ( ) const

Get all applied migration IDs.

Returns: Vector of applied migration IDs.

◆ GetDataMapper()

LIGHTWEIGHT_API DataMapper & Lightweight::SqlMigration::MigrationManager::GetDataMapper ( ) const

inline

Get the data mapper used for migrations.

Definition at line 179 of file SqlMigration.hpp.

References GetDataMapper().

◆ CloseDataMapper()

LIGHTWEIGHT_API void Lightweight::SqlMigration::MigrationManager::CloseDataMapper ( )

Close the data mapper.

This function is useful if explicitly closing the connection is desired before the migration manager is destroyed.

◆ Transaction()

LIGHTWEIGHT_API SqlTransaction Lightweight::SqlMigration::MigrationManager::Transaction ( )

Get a transaction for the data mapper.

Returns: Transaction.

◆ PreviewMigration()

LIGHTWEIGHT_API std::vector< std::string > Lightweight::SqlMigration::MigrationManager::PreviewMigration ( MigrationBase const & migration ) const

Preview SQL statements for a single migration without executing.

This is useful for dry-run mode to see what SQL would be executed.

Parameters

migration The migration to preview.

Returns: Vector of SQL statements that would be executed.

◆ PreviewPendingMigrations()

LIGHTWEIGHT_API std::vector< std::string > Lightweight::SqlMigration::MigrationManager::PreviewPendingMigrations ( ExecuteCallback const & feedbackCallback = {} ) const

Preview SQL statements for all pending migrations without executing.

This is useful for dry-run mode to see what SQL would be executed.

Parameters

feedbackCallback Optional callback to be called for each migration.

Returns: Vector of all SQL statements that would be executed.

◆ VerifyChecksums()

LIGHTWEIGHT_API std::vector< ChecksumVerificationResult > Lightweight::SqlMigration::MigrationManager::VerifyChecksums ( ) 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.

Returns: Vector of verification results for migrations with mismatched or missing checksums.

◆ MarkMigrationAsApplied()

LIGHTWEIGHT_API void Lightweight::SqlMigration::MigrationManager::MarkMigrationAsApplied ( MigrationBase const & migration )

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

Parameters

migration The migration to mark as applied.

Exceptions

std::runtime_error if the migration is already applied.

◆ RevertToMigration()

LIGHTWEIGHT_API RevertResult Lightweight::SqlMigration::MigrationManager::RevertToMigration	(	MigrationTimestamp	target,
		ExecuteCallback const &	feedbackCallback = `{}`
	)

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.

Parameters

target	Target timestamp to revert to. Migrations > target are reverted.
feedbackCallback	Optional callback for progress updates.

Returns: Result containing list of reverted timestamps or error information.

Note: Stops on first error. Previously reverted migrations in this call are NOT rolled back.

◆ GetMigrationStatus()

LIGHTWEIGHT_API MigrationStatus Lightweight::SqlMigration::MigrationManager::GetMigrationStatus ( ) const

Get a summary status of all migrations.

This method provides a quick overview of the migration state without needing to iterate through individual migrations.

Returns: Status struct with counts of applied, pending, and mismatched migrations.

◆ ValidateDependencies()

LIGHTWEIGHT_API void Lightweight::SqlMigration::MigrationManager::ValidateDependencies ( ) 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.

Exceptions

std::runtime_error if any dependency is unresolved or a cycle is found.

◆ RegisterRelease()

LIGHTWEIGHT_API void Lightweight::SqlMigration::MigrationManager::RegisterRelease	(	std::string	version,
		MigrationTimestamp	highestTimestamp
	)

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.

Parameters

version	Human-readable version, e.g. "6.7.0".
highestTimestamp	Highest migration timestamp (inclusive) that belongs to this release.

Exceptions

std::runtime_error on duplicate version or duplicate timestamp.

◆ FindReleaseByVersion()

LIGHTWEIGHT_API MigrationRelease const * Lightweight::SqlMigration::MigrationManager::FindReleaseByVersion ( std::string_view version ) const

noexcept

Find a release by exact version string match.

Returns: Pointer to the matching release, or nullptr if no release with that version is registered.

◆ FindReleaseForTimestamp()

LIGHTWEIGHT_API MigrationRelease const * Lightweight::SqlMigration::MigrationManager::FindReleaseForTimestamp ( MigrationTimestamp timestamp ) 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).

◆ GetMigrationsForRelease()

LIGHTWEIGHT_API MigrationList Lightweight::SqlMigration::MigrationManager::GetMigrationsForRelease ( std::string_view version ) const

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

Parameters

version The version string to look up.

Returns: Migrations in the release, ordered by timestamp. Empty if the version is unknown.

◆ FoldRegisteredMigrations()

LIGHTWEIGHT_API PlanFoldingResult Lightweight::SqlMigration::MigrationManager::FoldRegisteredMigrations	(	SqlQueryFormatter const &	formatter,
		std::optional< MigrationTimestamp >	upToInclusive = `std::nullopt`
	)		const

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.

Parameters

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.
upToInclusive	If set, fold only migrations with `timestamp <= upToInclusive`. If unset, fold all registered migrations.

Returns: The folded snapshot. Safe to call without a MigrationManager-attached data mapper.

The documentation for this class was generated from the following file:

Lightweight/SqlMigration.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ MigrationList

◆ ExecuteCallback

Member Function Documentation

◆ GetInstance()

◆ AddMigration()

◆ GetAllMigrations()

◆ GetMigration()

◆ RemoveAllMigrations()

◆ GetPending()

◆ ApplySingleMigration()

◆ RevertSingleMigration()

◆ ApplyPendingMigrations()

◆ GetAppliedMigrationIds()

◆ GetDataMapper()

◆ CloseDataMapper()

◆ Transaction()

◆ PreviewMigration()

◆ PreviewPendingMigrations()

◆ VerifyChecksums()

◆ MarkMigrationAsApplied()

◆ RevertToMigration()

◆ GetMigrationStatus()

◆ ValidateDependencies()

◆ RegisterRelease()

◆ FindReleaseByVersion()

◆ FindReleaseForTimestamp()

◆ GetMigrationsForRelease()

◆ FoldRegisteredMigrations()