MigrationPlan.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include "../Api.hpp"
#include "../SqlColumnTypeDefinitions.hpp"
#include "../SqlDataBinder.hpp"
#include "../Utils.hpp"
 
#include <reflection-cpp/reflection.hpp>
 
#include <cstddef>
#include <cstdint>
#include <functional>
#include <map>
#include <set>
#include <string>
#include <string_view>
#include <variant>
#include <vector>
 
namespace Lightweight
{
 
class SqlQueryFormatter;
 
namespace detail
{
 
    template <typename T>
    struct SqlColumnTypeDefinitionOf
    {
        static_assert(AlwaysFalse<T>, "Unsupported type for SQL column definition.");
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<std::string>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Text {};
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<bool>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Bool {};
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<char>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Char { 1 };
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<SqlDate>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Date {};
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<SqlDateTime>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::DateTime {};
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<SqlTime>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Time {};
    };
 
    template <size_t Precision, size_t Scale>
    struct SqlColumnTypeDefinitionOf<SqlNumeric<Precision, Scale>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Decimal { .precision = Precision, .scale = Scale };
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<SqlGuid>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Guid {};
    };
 
    template <typename T>
        requires(detail::OneOf<T, int16_t, uint16_t>)
    struct SqlColumnTypeDefinitionOf<T>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Smallint {};
    };
 
    template <typename T>
        requires(detail::OneOf<T, int32_t, uint32_t>)
    struct SqlColumnTypeDefinitionOf<T>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Integer {};
    };
 
    template <typename T>
        requires(detail::OneOf<T, int64_t, uint64_t>)
    struct SqlColumnTypeDefinitionOf<T>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Bigint {};
    };
 
    template <typename T>
        requires(detail::OneOf<T, float, double>)
    struct SqlColumnTypeDefinitionOf<T>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Real {};
    };
 
    template <size_t N, typename CharT>
        requires(detail::OneOf<CharT, char>)
    struct SqlColumnTypeDefinitionOf<SqlFixedString<N, CharT, SqlFixedStringMode::VARIABLE_SIZE>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Varchar { N };
    };
 
    template <size_t N, typename CharT>
        requires(detail::OneOf<CharT, char16_t, char32_t, wchar_t>)
    struct SqlColumnTypeDefinitionOf<SqlFixedString<N, CharT, SqlFixedStringMode::VARIABLE_SIZE>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::NVarchar { N };
    };
 
    template <size_t N, typename CharT>
        requires(detail::OneOf<CharT, char>)
    struct SqlColumnTypeDefinitionOf<SqlFixedString<N, CharT, SqlFixedStringMode::FIXED_SIZE>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Char { N };
    };
 
    template <size_t N, typename CharT>
        requires(detail::OneOf<CharT, char16_t, char32_t, wchar_t>)
    struct SqlColumnTypeDefinitionOf<SqlFixedString<N, CharT, SqlFixedStringMode::FIXED_SIZE>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::NChar { N };
    };
 
    template <size_t N, typename CharT>
    struct SqlColumnTypeDefinitionOf<SqlFixedString<N, CharT, SqlFixedStringMode::FIXED_SIZE_RIGHT_TRIMMED>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Char { N };
    };
 
    template <size_t N, typename CharT>
        requires(detail::OneOf<CharT, char16_t, char32_t, wchar_t>)
    struct SqlColumnTypeDefinitionOf<SqlFixedString<N, CharT, SqlFixedStringMode::FIXED_SIZE_RIGHT_TRIMMED>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::NChar { N };
    };
 
    template <size_t N, typename CharT>
        requires(detail::OneOf<CharT, char>)
    struct SqlColumnTypeDefinitionOf<SqlDynamicString<N, CharT>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Varchar { N };
    };
 
    template <size_t N, typename CharT>
        requires(detail::OneOf<CharT, char8_t, char16_t, char32_t, wchar_t>)
    struct SqlColumnTypeDefinitionOf<SqlDynamicString<N, CharT>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::NVarchar { N };
    };
 
    template <typename T>
    struct SqlColumnTypeDefinitionOf<std::optional<T>>
    {
        static constexpr auto value = SqlColumnTypeDefinitionOf<T>::value;
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<SqlText>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Text {};
    };
 
    template <size_t N>
    struct SqlColumnTypeDefinitionOf<SqlDynamicBinary<N>>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::VarBinary { N };
    };
 
} // namespace detail
 
/// @brief Represents a SQL column type definition of T.
///
/// @ingroup QueryBuilder
template <typename T>
constexpr auto SqlColumnTypeDefinitionOf = detail::SqlColumnTypeDefinitionOf<T>::value;
 
/// @brief Represents a primary key type.
///
/// This enumeration represents the primary key type of a column.
///
/// @ingroup QueryBuilder
enum class SqlPrimaryKeyType : uint8_t
{
    NONE,
    MANUAL,
    AUTO_INCREMENT,
    GUID,
};
 
/// @brief Represents a foreign key reference definition.
///
/// @ingroup QueryBuilder
struct SqlForeignKeyReferenceDefinition
{
    /// The table name that the foreign key references.
    std::string tableName;
 
    /// The column name that the foreign key references.
    std::string columnName;
};
 
/// @brief Represents a SQL column declaration.
///
/// @ingroup QueryBuilder
struct SqlColumnDeclaration
{
    /// The name of the column.
    std::string name;
 
    /// The type of the column.
    SqlColumnTypeDefinition type;
 
    /// The primary key type of the column.
    SqlPrimaryKeyType primaryKey { SqlPrimaryKeyType::NONE };
 
    /// The foreign key reference definition of the column.
    std::optional<SqlForeignKeyReferenceDefinition> foreignKey {};
 
    /// Indicates if the column is required (non-nullable).
    bool required { false };
 
    /// Indicates if the column is unique.
    bool unique { false };
 
    /// The default value of the column.
    std::string defaultValue {};
 
    /// Indicates if the column is indexed.
    bool index { false };
 
    /// The 1-based index in the primary key (0 if not part of a specific order).
    uint16_t primaryKeyIndex { 0 };
};
 
/// @brief Represents a composite foreign key constraint.
///
/// @ingroup QueryBuilder
struct SqlCompositeForeignKeyConstraint
{
    /// The columns in the current table.
    std::vector<std::string> columns;
 
    /// The referenced table name.
    std::string referencedTableName;
 
    /// The referenced columns in the referenced table.
    std::vector<std::string> referencedColumns;
};
 
struct SqlCreateTablePlan
{
    std::string schemaName;
    std::string tableName;
    std::vector<SqlColumnDeclaration> columns;
    std::vector<SqlCompositeForeignKeyConstraint> foreignKeys;
    bool ifNotExists { false }; ///< If true, generates CREATE TABLE IF NOT EXISTS.
};
 
namespace SqlAlterTableCommands
{
 
    struct RenameTable
    {
        std::string_view newTableName;
    };
 
    struct AddColumn
    {
        std::string columnName;
        SqlColumnTypeDefinition columnType;
        SqlNullable nullable = SqlNullable::Null;
    };
 
    struct AlterColumn
    {
        std::string columnName;
        SqlColumnTypeDefinition columnType;
        SqlNullable nullable = SqlNullable::Null;
    };
 
    struct AddIndex
    {
        std::string_view columnName;
        bool unique = false;
    };
 
    struct RenameColumn
    {
        std::string_view oldColumnName;
        std::string_view newColumnName;
    };
 
    struct DropColumn
    {
        std::string_view columnName;
    };
 
    struct DropIndex
    {
        std::string_view columnName;
    };
 
    struct AddForeignKey
    {
        std::string columnName;
        SqlForeignKeyReferenceDefinition referencedColumn;
    };
 
    struct AddCompositeForeignKey
    {
        std::vector<std::string> columns;
        std::string referencedTableName;
        std::vector<std::string> referencedColumns;
    };
 
    struct DropForeignKey
    {
        std::string columnName;
    };
 
    /// Adds a column only if it does not already exist.
    struct AddColumnIfNotExists
    {
        /// The name of the column to add.
        std::string columnName;
        /// The type of the column to add.
        SqlColumnTypeDefinition columnType;
        /// Whether the column is nullable.
        SqlNullable nullable = SqlNullable::Null;
    };
 
    /// Drops a column only if it exists.
    struct DropColumnIfExists
    {
        /// The name of the column to drop.
        std::string columnName;
    };
 
    /// Drops an index only if it exists.
    struct DropIndexIfExists
    {
        /// The name of the column whose index to drop.
        std::string columnName;
    };
 
} // namespace SqlAlterTableCommands
 
/// @brief Represents a single SQL ALTER TABLE command.
///
/// @ingroup QueryBuilder
using SqlAlterTableCommand = std::variant<SqlAlterTableCommands::RenameTable,
                                          SqlAlterTableCommands::AddColumn,
                                          SqlAlterTableCommands::AddColumnIfNotExists,
                                          SqlAlterTableCommands::AlterColumn,
                                          SqlAlterTableCommands::AddIndex,
                                          SqlAlterTableCommands::RenameColumn,
                                          SqlAlterTableCommands::DropColumn,
                                          SqlAlterTableCommands::DropColumnIfExists,
                                          SqlAlterTableCommands::DropIndex,
                                          SqlAlterTableCommands::DropIndexIfExists,
                                          SqlAlterTableCommands::AddForeignKey,
                                          SqlAlterTableCommands::AddCompositeForeignKey,
                                          SqlAlterTableCommands::DropForeignKey>;
 
/// @brief Represents a SQL ALTER TABLE plan on a given table.
///
/// @ingroup QueryBuilder
struct SqlAlterTablePlan
{
    /// The schema name of the table to alter.
    std::string_view schemaName;
 
    /// The name of the table to alter.
    std::string_view tableName;
 
    /// The list of commands to execute on the table.
    std::vector<SqlAlterTableCommand> commands;
};
 
/// @brief Represents a SQL DROP TABLE plan.
///
/// @ingroup QueryBuilder
struct SqlDropTablePlan
{
    /// The schema name of the table to drop.
    std::string_view schemaName;
 
    /// The name of the table to drop.
    std::string_view tableName;
 
    /// If true, generates DROP TABLE IF EXISTS instead of DROP TABLE.
    bool ifExists { false };
 
    /// If true, drops all foreign key constraints referencing this table first.
    /// On PostgreSQL, uses CASCADE. On MS SQL, drops FK constraints explicitly.
    bool cascade { false };
};
 
/// @brief Represents a raw SQL plan.
///
/// @ingroup QueryBuilder
struct SqlRawSqlPlan
{
    /// The raw SQL to execute.
    std::string_view sql;
};
 
/// @brief Represents a SQL INSERT data plan for migrations.
///
/// This structure represents an INSERT statement for a migration plan.
///
/// @ingroup QueryBuilder
struct SqlInsertDataPlan
{
    /// The schema name of the table to insert into.
    std::string schemaName;
 
    /// The name of the table to insert into.
    std::string tableName;
 
    /// The columns and their values to insert.
    std::vector<std::pair<std::string, SqlVariant>> columns;
};
 
/// @brief Represents a SQL UPDATE data plan for migrations.
///
/// This structure represents an UPDATE statement for a migration plan.
///
/// @ingroup QueryBuilder
struct SqlUpdateDataPlan
{
    /// The schema name of the table to update.
    std::string schemaName;
 
    /// The name of the table to update.
    std::string tableName;
 
    /// The columns and their values to set.
    std::vector<std::pair<std::string, SqlVariant>> setColumns;
 
    /// @brief Column-to-expression assignments that cannot be represented as a literal value.
    ///
    /// Each entry is `(column name, raw SQL expression)`. The expression is emitted verbatim
    /// after `"col" = ` at SQL-rendering time — used for things like `set TARGET = SOURCE` or
    /// `set CTR = CTR + 1` where the RHS references another column or contains arithmetic.
    /// Entries here are appended to the SET clause after `setColumns`.
    std::vector<std::pair<std::string, std::string>> setExpressions;
 
    /// The column name for the WHERE clause.
    std::string whereColumn;
 
    /// The comparison operator for the WHERE clause (e.g., "=", "<>", etc.).
    std::string whereOp;
 
    /// The value for the WHERE clause.
    SqlVariant whereValue;
 
    /// @brief Pre-rendered WHERE-clause body (the text after `WHERE`), used when the
    /// condition cannot be expressed with the simple `(whereColumn op whereValue)`
    /// triple — e.g. composite `AND`/`OR`/`NOT`, `IS NULL`, `IN (subquery)`, or
    /// `EXISTS (subquery)`. When non-empty, this takes precedence over the
    /// structured triple at SQL-emission time.
    std::string whereExpression;
};
 
/// @brief Represents a SQL DELETE data plan for migrations.
///
/// This structure represents a DELETE statement for a migration plan.
///
/// @ingroup QueryBuilder
struct SqlDeleteDataPlan
{
    /// The schema name of the table to delete from.
    std::string schemaName;
 
    /// The name of the table to delete from.
    std::string tableName;
 
    /// The column name for the WHERE clause.
    std::string whereColumn;
 
    /// The comparison operator for the WHERE clause (e.g., "=", "<>", etc.).
    std::string whereOp;
 
    /// The value for the WHERE clause.
    SqlVariant whereValue;
 
    /// Pre-rendered WHERE-clause body. See `SqlUpdateDataPlan::whereExpression`.
    std::string whereExpression;
};
 
/// @brief Represents a SQL CREATE INDEX plan for migrations.
///
/// This structure represents a CREATE INDEX statement for a migration plan.
///
/// @ingroup QueryBuilder
struct SqlCreateIndexPlan
{
    /// The schema name of the table to create the index on.
    std::string schemaName;
 
    /// The name of the index to create.
    std::string indexName;
 
    /// The name of the table to create the index on.
    std::string tableName;
 
    /// The columns to include in the index.
    std::vector<std::string> columns;
 
    /// If true, creates a UNIQUE index.
    bool unique { false };
 
    /// If true, generates CREATE INDEX IF NOT EXISTS.
    bool ifNotExists { false };
};
 
// clang-format off
 
/// @brief Represents a single SQL migration plan element.
///
/// This variant represents a single SQL migration plan element.
///
/// @ingroup QueryBuilder
using SqlMigrationPlanElement = std::variant<
    SqlCreateTablePlan,
    SqlAlterTablePlan,
    SqlDropTablePlan,
    SqlCreateIndexPlan,
    SqlRawSqlPlan,
    SqlInsertDataPlan,
    SqlUpdateDataPlan,
    SqlDeleteDataPlan
>;
 
// clang-format on
 
/// @brief Canonical compat-flag name requesting LUpd-compatible client-side string
/// truncation. Kept with the consumer (`MigrationRenderContext`) so there is a single
/// source of truth; `Lightweight::Config::CompatFlagLupTruncate` aliases this value.
inline constexpr std::string_view CompatFlagLupTruncateName = "lup-truncate";
 
/// @brief Opt-in behavioural knobs that the `ToSql` migration-plan renderer honours.
///
/// When a profile declares a `compat:` flag (see `Lightweight::Config::CompatFlags`), dbtool
/// / dbtool-gui construct one of these and pass it alongside the formatter so migration
/// rendering can diverge from strict behaviour per-run.
///
/// The context is mutable across successive `ToSql` calls within the same migration run:
/// it accumulates a column-width cache populated from `CreateTable` / `AlterTable` steps as
/// they are rendered, so later `Insert` / `Update` steps can truncate oversize values
/// without a server round-trip.
///
/// Default-constructed instances are strict (no truncation, no logging); this is the shape
/// used by code paths that don't care about compat, so existing callers keep their
/// behaviour.
struct [[nodiscard]] MigrationRenderContext
{
    /// When true, string values in `Insert` / `Update` steps are truncated to the
    /// destination column's declared character width and the truncation is logged via
    /// `SqlLogger::OnWarning`. Mirrors LUpd's client-side clipping behaviour; see
    /// `Lightweight::Config::CompatFlagLupTruncate`.
    bool lupTruncate = false;
 
    /// Per-(schema, table, column) cache of declared character widths. Populated lazily
    /// from `SqlCreateTablePlan` / `SqlAlterTablePlan` as they are rendered; the key is
    /// (`schema`, `table`, `column`). A zero/absent entry means "no known width" and the
    /// truncation layer leaves the value alone.
    struct ColumnKey
    {
        std::string schema; ///< Schema label (empty for engines without schemas, e.g. SQLite).
        std::string table;  ///< Table name.
        std::string column; ///< Column name.
        /// Total ordering on (schema, table, column) — defaulted three-way comparison.
        auto operator<=>(ColumnKey const&) const = default;
    };
 
    /// @brief How a column's declared width is counted. The truncation layer must match
    /// the server's interpretation: a VARCHAR(100) on MSSQL holds 100 *bytes*, but an
    /// NVARCHAR(100) holds 100 *characters*. Truncating to 100 characters when the
    /// server budget is 100 bytes still overflows on multi-byte source data.
    enum class WidthUnit : uint8_t
    {
        Characters,
        Bytes,
    };
 
    struct ColumnWidth
    {
        std::size_t value { 0 };
        WidthUnit unit { WidthUnit::Characters };
    };
 
    /// Cache of declared character widths, populated lazily as plan elements render.
    std::map<ColumnKey, ColumnWidth> columnWidths;
 
    /// @brief Optional fallback that fetches column widths for a `(schema, table)` from
    /// the live database when the cache has no entry for it.
    ///
    /// The renderer calls this once per `(schema, table)` it can't satisfy from
    /// `columnWidths`. Implementations should issue a single `INFORMATION_SCHEMA.COLUMNS`
    /// (or equivalent) query and write every char/varchar column's declared width back
    /// into `columnWidths`. They may also write a sentinel (e.g. an empty entry) when the
    /// table doesn't exist, so the renderer doesn't keep retrying. Default-empty means
    /// "no fallback" — i.e. only widths declared by the same migration plan are
    /// considered.
    std::function<void(MigrationRenderContext&, std::string_view /*schema*/, std::string_view /*table*/)> widthLookup;
 
    /// @brief Tables for which the lookup has already been attempted, so we don't
    /// re-query for every INSERT against the same table.
    struct TableKey
    {
        std::string schema; ///< Schema label (empty when the engine reports none).
        std::string table;  ///< Table name.
        /// Total ordering on (schema, table) — defaulted three-way comparison.
        auto operator<=>(TableKey const&) const = default;
    };
    /// Tables for which `widthLookup` has already been called; prevents repeat queries.
    std::set<TableKey> lookupAttempted;
 
    /// @brief Identity of the migration currently being rendered. Set by
    /// `MigrationManager::ApplySingleMigration` before `ToSql` is called for each
    /// step so warnings (e.g. `lup-truncate`) can attribute themselves to the
    /// offending migration. Empty / zero when rendering happens outside a migration
    /// run (e.g. unit tests calling `ToSql` directly).
    std::string activeMigrationTitle;
    /// Timestamp of the migration currently being rendered (0 outside a migration run).
    std::uint64_t activeMigrationTimestamp = 0;
};
 
/// Formats the given SQL migration plan element as a list of SQL statements.
///
/// @param formatter The SQL query formatter to use.
/// @param element The SQL migration plan element to format.
///
/// @return A list of SQL statements.
///
/// @ingroup QueryBuilder
[[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> ToSql(SqlQueryFormatter const& formatter,
                                                             SqlMigrationPlanElement const& element);
 
/// @overload
/// Rendering variant that consults a `MigrationRenderContext` for compat flags
/// and column-width tracking. Updates `context` in place when the rendered step declares
/// new columns.
[[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> ToSql(SqlQueryFormatter const& formatter,
                                                             SqlMigrationPlanElement const& element,
                                                             MigrationRenderContext& context);
 
/// @brief Represents a SQL migration plan.
///
/// This structure represents a SQL migration plan that can be executed on a database.
///
/// @ingroup QueryBuilder
struct [[nodiscard]] SqlMigrationPlan
{
    /// The SQL query formatter to use.
    SqlQueryFormatter const& formatter;
    /// The migration plan steps.
    std::vector<SqlMigrationPlanElement> steps {};
 
    /// Converts the migration plan to a list of SQL statements.
    [[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> ToSql() const;
};
 
/// @brief Formats the given SQL migration plan as a list of SQL statements.
///
/// @param formatter The SQL query formatter to use.
/// @param plans The SQL migration plans to format.
///
/// @return A list of SQL statements.
///
/// @ingroup QueryBuilder
[[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> ToSql(SqlQueryFormatter const& formatter,
                                                             std::vector<SqlMigrationPlan> const& plans);
 
} // namespace Lightweight