migration_runner.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2021-2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "migration_record.h"
 
#include <kcenon/common/patterns/result.h>
 
#include <functional>
#include <memory>
#include <string>
#include <string_view>
#include <vector>
 
// Forward declaration for pacs_database_adapter
#ifdef PACS_WITH_DATABASE_SYSTEM
namespace kcenon::pacs::storage {
class pacs_database_adapter;
}
#endif
 
// Forward declaration of SQLite handle
struct sqlite3;
 
namespace kcenon::pacs::storage {
 
using VoidResult = kcenon::common::VoidResult;
 
using migration_function = std::function<VoidResult(sqlite3* db)>;
 
#ifdef PACS_WITH_DATABASE_SYSTEM
using adapter_migration_function =
    std::function<VoidResult(pacs_database_adapter&)>;
#endif
 
class migration_runner {
public:
    migration_runner();
 
    ~migration_runner() = default;
 
    // Non-copyable, non-movable (stateless service)
    migration_runner(const migration_runner&) = delete;
    auto operator=(const migration_runner&) -> migration_runner& = delete;
    migration_runner(migration_runner&&) = delete;
    auto operator=(migration_runner&&) -> migration_runner& = delete;
 
    // ========================================================================
    // Migration Operations
    // ========================================================================
 
    [[nodiscard]] auto run_migrations(sqlite3* db) -> VoidResult;
 
    [[nodiscard]] auto run_migrations_to(sqlite3* db, int target_version)
        -> VoidResult;
 
#ifdef PACS_WITH_DATABASE_SYSTEM
    // ========================================================================
    // Migration Operations (pacs_database_adapter)
    // ========================================================================
 
    [[nodiscard]] auto run_migrations(pacs_database_adapter& db) -> VoidResult;
 
    [[nodiscard]] auto run_migrations_to(pacs_database_adapter& db,
                                         int target_version) -> VoidResult;
 
    [[nodiscard]] auto get_current_version(pacs_database_adapter& db) const
        -> int;
 
    [[nodiscard]] auto needs_migration(pacs_database_adapter& db) const -> bool;
 
    [[nodiscard]] auto get_history(pacs_database_adapter& db) const
        -> std::vector<migration_record>;
#endif
 
    // ========================================================================
    // Version Information
    // ========================================================================
 
    [[nodiscard]] auto get_current_version(sqlite3* db) const -> int;
 
    [[nodiscard]] auto get_latest_version() const noexcept -> int;
 
    [[nodiscard]] auto needs_migration(sqlite3* db) const -> bool;
 
    // ========================================================================
    // Migration History
    // ========================================================================
 
    [[nodiscard]] auto get_history(sqlite3* db) const
        -> std::vector<migration_record>;
 
private:
    // ========================================================================
    // Internal Implementation
    // ========================================================================
 
    [[nodiscard]] auto ensure_schema_version_table(sqlite3* db) -> VoidResult;
 
    [[nodiscard]] auto apply_migration(sqlite3* db, int version) -> VoidResult;
 
    [[nodiscard]] auto record_migration(sqlite3* db, int version,
                                        std::string_view description)
        -> VoidResult;
 
    [[nodiscard]] auto execute_sql(sqlite3* db, std::string_view sql)
        -> VoidResult;
 
    // Migration implementations (SQLite)
    [[nodiscard]] auto migrate_v1(sqlite3* db) -> VoidResult;
    [[nodiscard]] auto migrate_v2(sqlite3* db) -> VoidResult;
    [[nodiscard]] auto migrate_v3(sqlite3* db) -> VoidResult;
    [[nodiscard]] auto migrate_v4(sqlite3* db) -> VoidResult;
    [[nodiscard]] auto migrate_v5(sqlite3* db) -> VoidResult;
    [[nodiscard]] auto migrate_v6(sqlite3* db) -> VoidResult;
    [[nodiscard]] auto migrate_v7(sqlite3* db) -> VoidResult;
    [[nodiscard]] auto migrate_v8(sqlite3* db) -> VoidResult;
    [[nodiscard]] auto migrate_v9(sqlite3* db) -> VoidResult;
 
#ifdef PACS_WITH_DATABASE_SYSTEM
    // ========================================================================
    // Internal Implementation (pacs_database_adapter)
    // ========================================================================
 
    [[nodiscard]] auto ensure_schema_version_table(pacs_database_adapter& db)
        -> VoidResult;
 
    [[nodiscard]] auto apply_migration(pacs_database_adapter& db, int version)
        -> VoidResult;
 
    [[nodiscard]] auto record_migration(pacs_database_adapter& db, int version,
                                        std::string_view description)
        -> VoidResult;
 
    [[nodiscard]] auto execute_sql(pacs_database_adapter& db,
                                   std::string_view sql) -> VoidResult;
 
    // Migration implementations (pacs_database_adapter)
    [[nodiscard]] auto migrate_v1(pacs_database_adapter& db) -> VoidResult;
    [[nodiscard]] auto migrate_v2(pacs_database_adapter& db) -> VoidResult;
    [[nodiscard]] auto migrate_v3(pacs_database_adapter& db) -> VoidResult;
    [[nodiscard]] auto migrate_v4(pacs_database_adapter& db) -> VoidResult;
    [[nodiscard]] auto migrate_v5(pacs_database_adapter& db) -> VoidResult;
    [[nodiscard]] auto migrate_v6(pacs_database_adapter& db) -> VoidResult;
    [[nodiscard]] auto migrate_v7(pacs_database_adapter& db) -> VoidResult;
    [[nodiscard]] auto migrate_v8(pacs_database_adapter& db) -> VoidResult;
    [[nodiscard]] auto migrate_v9(pacs_database_adapter& db) -> VoidResult;
 
    std::vector<std::pair<int, adapter_migration_function>> adapter_migrations_;
#endif
 
    static constexpr int LATEST_VERSION = 9;
 
    std::vector<std::pair<int, migration_function>> migrations_;
};
 
}  // namespace kcenon::pacs::storage