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 <optional>
#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 <>
    struct SqlColumnTypeDefinitionOf<float>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Real { .precision = 24 };
    };
 
    template <>
    struct SqlColumnTypeDefinitionOf<double>
    {
        static constexpr auto value = SqlColumnTypeDefinitions::Real { .precision = 53 };
    };
 
    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;
        /// The schema of the referenced table; empty means the schema of the altered table.
        std::string referencedSchemaName {};
    };
 
    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 Key columns that make the insert conditional, empty for a plain insert.
    ///
    /// When non-empty, the row is inserted only if no row with the same values in these
    /// columns exists yet (`INSERT ... SELECT ... WHERE NOT EXISTS (...)`). Each key column
    /// must be one of @ref columns and must not hold NULL; rendering throws otherwise.
    std::vector<std::string> keyColumns;
};
 
/// @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 };
 
    /// Pre-rendered predicate body of a partial (PostgreSQL / SQLite) or filtered
    /// (SQL Server) index, without the leading `WHERE`. Empty means the index covers
    /// every row. Emitted verbatim after the column list as `WHERE <expression>`; the
    /// caller is responsible for dialect-safe quoting. Mirrors
    /// `SqlUpdateDataPlan::whereExpression`.
    std::string whereExpression {};
};
 
// 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 Compat-flag name that lets a foreign-key column follow the narrow/wide text
/// kind of the column it references (`CHAR`<->`NCHAR`, `VARCHAR`<->`NVARCHAR`, same
/// length). Lets one migration apply to legacy databases whose referenced columns are
/// narrow and to fresh ones where they are wide. Only takes effect on DBMSes whose
/// formatter reports `DistinguishesNarrowAndWideText()` (SQL Server).
inline constexpr std::string_view CompatFlagFkMatchReferencedTextName = "fk-match-referenced-text";
 
/// @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;
 
    /// When true (and the formatter distinguishes narrow and wide text), a foreign-key
    /// column declared by a `CreateTable` / `AlterTable` step is rendered with the
    /// narrow/wide variant of the referenced column's actual type when the two differ
    /// only in that respect. See `CompatFlagFkMatchReferencedTextName`.
    bool fkMatchReferencedText = 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;
 
    /// Per-column text types (`Char` / `NChar` / `Varchar` / `NVarchar` only), from steps
    /// rendered so far and from `widthLookup`. Consulted by `fkMatchReferencedText`.
    std::map<ColumnKey, SqlColumnTypeDefinition> textColumnTypes;
 
    /// @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 A statement whose values are bound as parameters when it runs.
///
/// @ingroup QueryBuilder
struct SqlBoundStatement
{
    /// The statement text, with one `?` placeholder per parameter.
    std::string sql;
 
    /// The values bound to the placeholders, in order.
    std::vector<SqlVariant> parameters;
};
 
/// @brief Renders an `Insert(...).IfNotExists(...)` step for execution with bound parameters.
///
/// `MigrationManager` executes this form, binding the values, while checksums and previews
/// (`ToSql`) keep showing them as literals, so the checksum of a migration does not depend on how
/// its values reach the database. Callers that run `ToSql` output themselves (e.g.
/// `SqlStatement::MigrateDirect`) execute the literal form.
///
/// UTF-8 text is bound as UTF-16, so it is stored exactly as its literal rendering would store it.
/// A GUID, date, time or timestamp is bound as the text its literal quotes, so the server parses the
/// same text either way: a native time or timestamp would keep the fraction the literal drops, and
/// SQLite would store a timestamp in another text form that a key comparison never matches.
/// Other values are bound natively. Exact decimals (also at high scale), binary values and `bool`
/// store exactly as their literals; a `double` reaches the column as its binary value. That stores
/// the same as the literal for FLOAT/REAL columns and for DECIMAL columns of low scale, but it can
/// differ where the literal is parsed as a decimal: a DECIMAL column with more fractional digits
/// than the double holds exactly (e.g. DECIMAL(28,12) receives 123456.789011999994 rather than
/// 123456.789012000000), SQLite parsing some literals 1-2 ULP off the correctly rounded double the
/// bound value carries, and a double into a text column (SQLite stores 3.0 as "3.0" bound, "3" as a
/// literal). Exact decimals belong in `SqlNumeric` / `SqlDynamicNumeric`.
///
/// @param element The step to render.
/// @return The bound statement, or nothing when @p element is not an `IfNotExists` insert.
/// @throws std::invalid_argument A key column is not one of the insert's columns or holds NULL.
///
/// @ingroup QueryBuilder
[[nodiscard]] LIGHTWEIGHT_API std::optional<SqlBoundStatement> ToBoundSql(SqlMigrationPlanElement const& element);
 
/// @overload
/// Applies the value-level compat knobs of @p context (string truncation) like `ToSql` does. Callers
/// render the step with `ToSql(formatter, element, context)` first, which reports the truncation.
[[nodiscard]] LIGHTWEIGHT_API std::optional<SqlBoundStatement> ToBoundSql(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