Diff coverage report for

//

//

// Copyright (c) 2026 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2026 Vinnie Falco (vinnie.falco@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0.

// Distributed under the Boost Software License, Version 1.0.

// https://www.boost.org/LICENSE_1_0.txt

// https://www.boost.org/LICENSE_1_0.txt

//

//

#ifndef BOOST_HTTP_DB_SCHEMA_HPP

#ifndef BOOST_HTTP_DB_SCHEMA_HPP

#define BOOST_HTTP_DB_SCHEMA_HPP

#define BOOST_HTTP_DB_SCHEMA_HPP

#include <cstdint>

#include <cstdint>

#include <tuple>

#include <tuple>

#include <type_traits>

#include <type_traits>

#include <string_view>

#include <string_view>

namespace boost {

namespace boost {

namespace http {

namespace http {

namespace db {

namespace db {

/** Bitwise flags describing column properties.

/** Bitwise flags describing column properties.

    Accumulated on a @ref field_t descriptor via

    Accumulated on a @ref field_t descriptor via

    builder-style member functions.

    builder-style member functions.

*/

*/

enum field_flags : unsigned

enum field_flags : unsigned

{

{

    flag_none           = 0,

    flag_none           = 0,

    flag_primary_key    = 1 << 0,

    flag_primary_key    = 1 << 0,

    flag_auto_increment = 1 << 1,

    flag_auto_increment = 1 << 1,

    flag_not_null       = 1 << 2,

    flag_not_null       = 1 << 2,

    flag_unique         = 1 << 3,

    flag_unique         = 1 << 3,

    flag_indexed        = 1 << 4

    flag_indexed        = 1 << 4

};

};

/** Describe a single column mapped to a struct member.

/** Describe a single column mapped to a struct member.

    The member pointer is stored as a data member so

    The member pointer is stored as a data member so

    that the natural syntax works without requiring

    that the natural syntax works without requiring

    angle brackets. The entire schema description is

    angle brackets. The entire schema description is

    constexpr and available at compile time.

    constexpr and available at compile time.

    @par Example

    @par Example

    @code

    @code

    field("id", &user::id).primary_key().auto_increment()

    field("id", &user::id).primary_key().auto_increment()

    field("email", &user::email).not_null().unique()

    field("email", &user::email).not_null().unique()

    @endcode

    @endcode

    @tparam T Member value type (e.g. `std::string`).

    @tparam T Member value type (e.g. `std::string`).

    @tparam C Containing class type (e.g. `user`).

    @tparam C Containing class type (e.g. `user`).

    @see field, embed_t, has_one_t

    @see field, embed_t, has_one_t

*/

*/

template <typename T, typename C>

template <typename T, typename C>

struct field_t

struct field_t

{

{

    using value_type = T;

    using value_type = T;

    using class_type = C;

    using class_type = C;

    std::string_view name;

    std::string_view name;

    T C::* pointer;

    T C::* pointer;

    unsigned flags = flag_none;

    unsigned flags = flag_none;

    /// Mark this column as the primary key.

    /// Mark this column as the primary key.

    constexpr field_t& primary_key()    { flags |= flag_primary_key;    return *this; }

    constexpr field_t& primary_key()    { flags |= flag_primary_key;    return *this; }

    /// Mark this column as auto-incrementing.

    /// Mark this column as auto-incrementing.

    constexpr field_t& auto_increment() { flags |= flag_auto_increment; return *this; }

    constexpr field_t& auto_increment() { flags |= flag_auto_increment; return *this; }

    /// Mark this column as NOT NULL.

    /// Mark this column as NOT NULL.

    constexpr field_t& not_null()       { flags |= flag_not_null;       return *this; }

    constexpr field_t& not_null()       { flags |= flag_not_null;       return *this; }

    /// Mark this column as UNIQUE.

    /// Mark this column as UNIQUE.

    constexpr field_t& unique()         { flags |= flag_unique;         return *this; }

    constexpr field_t& unique()         { flags |= flag_unique;         return *this; }

    /// Mark this column as indexed.

    /// Mark this column as indexed.

    constexpr field_t& indexed()        { flags |= flag_indexed;        return *this; }

    constexpr field_t& indexed()        { flags |= flag_indexed;        return *this; }

    /// Return true if this column is a primary key.

    /// Return true if this column is a primary key.

    /// Return true if this column is auto-incrementing.

    /// Return true if this column is auto-incrementing.

    /// Return true if this column is NOT NULL.

    /// Return true if this column is NOT NULL.

    /// Return true if this column is UNIQUE.

    /// Return true if this column is UNIQUE.

    /// Return true if this column is indexed.

    /// Return true if this column is indexed.

    /// Return the member value from an object.

    /// Return the member value from an object.

    {

    {

    }

    }

    /// Set the member value on an object.

    /// Set the member value on an object.

    {

    {

    /// Set the member value on an object by move.

    /// Set the member value on an object by move.

    {

    {

};

};

/** Create a field descriptor for a member pointer.

/** Create a field descriptor for a member pointer.

    Deduces `T` and `C` from the member pointer so

    Deduces `T` and `C` from the member pointer so

    template arguments are never needed at the call site.

    template arguments are never needed at the call site.

    @par Example

    @par Example

    @code

    @code

    field("email", &user::email)

    field("email", &user::email)

    field("id", &user::id).primary_key().auto_increment()

    field("id", &user::id).primary_key().auto_increment()

    @endcode

    @endcode

    @param name Column name in the database table.

    @param name Column name in the database table.

    @param ptr  Pointer to the mapped data member.

    @param ptr  Pointer to the mapped data member.

    @return A @ref field_t descriptor for the member.

    @return A @ref field_t descriptor for the member.

    @see field_t

    @see field_t

*/

*/

template <typename T, typename C>

template <typename T, typename C>

constexpr auto field(std::string_view name, T C::* ptr)

constexpr auto field(std::string_view name, T C::* ptr)

    -> field_t<T, C>

    -> field_t<T, C>

{

{

    return { name, ptr };

    return { name, ptr };

}

}

/** Describe a nested struct flattened into the parent table.

/** Describe a nested struct flattened into the parent table.

    The nested type must provide its own `tag_invoke`

    The nested type must provide its own `tag_invoke`

    overloads for @ref fields_t. A prefix is prepended

    overloads for @ref fields_t. A prefix is prepended

    to each nested column name to avoid collisions.

    to each nested column name to avoid collisions.

    @par Example

    @par Example

    @code

    @code

    // If user::addr is an address with field "street",

    // If user::addr is an address with field "street",

    // the resulting column is "addr_street".

    // the resulting column is "addr_street".

    embed("addr_", &user::addr)

    embed("addr_", &user::addr)

    @endcode

    @endcode

    @tparam T Nested struct type.

    @tparam T Nested struct type.

    @tparam C Containing class type.

    @tparam C Containing class type.

    @see embed, field_t

    @see embed, field_t

*/

*/

template <typename T, typename C>

template <typename T, typename C>

struct embed_t

struct embed_t

{

{

    using value_type = T;

    using value_type = T;

    using class_type = C;

    using class_type = C;

    std::string_view prefix;

    std::string_view prefix;

    T C::* pointer;

    T C::* pointer;

    /// Return the nested struct from an object.

    /// Return the nested struct from an object.

    {

    {

    }

    }

    /// Set the nested struct on an object.

    /// Set the nested struct on an object.

    {

    {

    /// Set the nested struct on an object by move.

    /// Set the nested struct on an object by move.

    {

    {

};

};

/** Create an embedded field descriptor for a nested struct.

/** Create an embedded field descriptor for a nested struct.

    @param prefix String prepended to nested column names.

    @param prefix String prepended to nested column names.

    @param ptr    Pointer to the nested data member.

    @param ptr    Pointer to the nested data member.

    @return An @ref embed_t descriptor.

    @return An @ref embed_t descriptor.

    @see embed_t

    @see embed_t

*/

*/

template <typename T, typename C>

template <typename T, typename C>

constexpr auto embed(std::string_view prefix, T C::* ptr)

constexpr auto embed(std::string_view prefix, T C::* ptr)

    -> embed_t<T, C>

    -> embed_t<T, C>

{

{

    return { prefix, ptr };

    return { prefix, ptr };

}

}

/** Describe a one-to-one relationship to another table.

/** Describe a one-to-one relationship to another table.

    The referenced type must provide its own

    The referenced type must provide its own

    `tag_invoke` overloads for @ref table_name_t

    `tag_invoke` overloads for @ref table_name_t

    and @ref fields_t.

    and @ref fields_t.

    @par Example

    @par Example

    @code

    @code

    has_one("address_id", &user::addr)

    has_one("address_id", &user::addr)

    @endcode

    @endcode

    @tparam T Referenced struct type.

    @tparam T Referenced struct type.

    @tparam C Containing class type.

    @tparam C Containing class type.

    @see has_one, has_many_t

    @see has_one, has_many_t

*/

*/

template <typename T, typename C>

template <typename T, typename C>

struct has_one_t

struct has_one_t

{

{

    using value_type = T;

    using value_type = T;

    using class_type = C;

    using class_type = C;

    std::string_view foreign_key;

    std::string_view foreign_key;

    T C::* pointer;

    T C::* pointer;

    /// Return the related object from the parent.

    /// Return the related object from the parent.

    {

    {

    }

    }

    /// Set the related object on the parent.

    /// Set the related object on the parent.

    {

    {

    /// Set the related object on the parent by move.

    /// Set the related object on the parent by move.

    {

    {

};

};

/** Create a one-to-one relationship descriptor.

/** Create a one-to-one relationship descriptor.

    @param foreign_key Column name of the foreign key.

    @param foreign_key Column name of the foreign key.

    @param ptr         Pointer to the related data member.

    @param ptr         Pointer to the related data member.

    @return A @ref has_one_t descriptor.

    @return A @ref has_one_t descriptor.

    @see has_one_t

    @see has_one_t

*/

*/

template <typename T, typename C>

template <typename T, typename C>

constexpr auto has_one(std::string_view foreign_key, T C::* ptr)

constexpr auto has_one(std::string_view foreign_key, T C::* ptr)

    -> has_one_t<T, C>

    -> has_one_t<T, C>

{

{

    return { foreign_key, ptr };

    return { foreign_key, ptr };

}

}

/** Describe a one-to-many relationship.

/** Describe a one-to-many relationship.

    The child type has a member acting as the foreign

    The child type has a member acting as the foreign

    key pointing back to the parent's primary key.

    key pointing back to the parent's primary key.

    The child's foreign key member pointer is stored

    The child's foreign key member pointer is stored

    so the library can build the appropriate JOIN or

    so the library can build the appropriate JOIN or

    subquery.

    subquery.

    @par Example

    @par Example

    @code

    @code

    has_many(&user::posts, &post::user_id)

    has_many(&user::posts, &post::user_id)

    @endcode

    @endcode

    @tparam Collection Container type in the parent

    @tparam Collection Container type in the parent

        (e.g. `std::vector< post >`).

        (e.g. `std::vector< post >`).

    @tparam Parent     Parent class type.

    @tparam Parent     Parent class type.

    @tparam FK         Foreign key value type in the child.

    @tparam FK         Foreign key value type in the child.

    @tparam Child      Child class type.

    @tparam Child      Child class type.

    @see has_many, has_one_t

    @see has_many, has_one_t

*/

*/

template <typename Collection, typename Parent, typename FK, typename Child>

template <typename Collection, typename Parent, typename FK, typename Child>

struct has_many_t

struct has_many_t

{

{

    using collection_type = Collection;

    using collection_type = Collection;

    using parent_type     = Parent;

    using parent_type     = Parent;

    using child_type      = Child;

    using child_type      = Child;

    using fk_value_type   = FK;

    using fk_value_type   = FK;

    Collection Parent::* pointer;

    Collection Parent::* pointer;

    FK Child::* foreign_key;

    FK Child::* foreign_key;

};

};

/** Create a one-to-many relationship descriptor.

/** Create a one-to-many relationship descriptor.

    @param ptr Pointer to the collection member in the parent.

    @param ptr Pointer to the collection member in the parent.

    @param fk  Pointer to the foreign key member in the child.

    @param fk  Pointer to the foreign key member in the child.

    @return A @ref has_many_t descriptor.

    @return A @ref has_many_t descriptor.

    @see has_many_t

    @see has_many_t

*/

*/

template <

template <

    typename Collection, typename Parent,

    typename Collection, typename Parent,

    typename FK, typename Child>

    typename FK, typename Child>

constexpr auto has_many(

constexpr auto has_many(

    Collection Parent::* ptr,

    Collection Parent::* ptr,

    FK Child::* fk)

    FK Child::* fk)

    -> has_many_t<Collection, Parent, FK, Child>

    -> has_many_t<Collection, Parent, FK, Child>

{

{

    return { ptr, fk };

    return { ptr, fk };

}

}

/** Tag type for retrieving the table name of a mapped type.

/** Tag type for retrieving the table name of a mapped type.

    Customize via `tag_invoke`:

    Customize via `tag_invoke`:

    @par Example

    @par Example

    @code

    @code

    constexpr auto tag_invoke(

    constexpr auto tag_invoke(

        db::table_name_t, user const&)

        db::table_name_t, user const&)

    {

    {

        return "users";

        return "users";

    }

    }

    @endcode

    @endcode

    @see fields_t, HasMapping

    @see fields_t, HasMapping

*/

*/

struct table_name_t

struct table_name_t

{

{

    template <typename T>

    template <typename T>

    {

    {

    }

    }

};

};

/** Tag type for retrieving the field descriptors of a mapped type.

/** Tag type for retrieving the field descriptors of a mapped type.

    Customize via `tag_invoke`:

    Customize via `tag_invoke`:

    @par Example

    @par Example

    @code

    @code

    constexpr auto tag_invoke(

    constexpr auto tag_invoke(

        db::fields_t, user const&)

        db::fields_t, user const&)

    {

    {

        return std::tuple(

        return std::tuple(

            db::field("id", &user::id)

            db::field("id", &user::id)

                .primary_key().auto_increment(),

                .primary_key().auto_increment(),

            db::field("email", &user::email)

            db::field("email", &user::email)

                .not_null().unique(),

                .not_null().unique(),

            db::field("name", &user::name));

            db::field("name", &user::name));

    }

    }

    @endcode

    @endcode

    @see table_name_t, HasMapping

    @see table_name_t, HasMapping

*/

*/

struct fields_t

struct fields_t

{

{

    template <typename T>

    template <typename T>

    constexpr auto operator()(T const& v) const

    constexpr auto operator()(T const& v) const

    {

    {

        return tag_invoke(*this, v);

        return tag_invoke(*this, v);

    }

    }

};

};

/// Customization point object for @ref table_name_t.

/// Customization point object for @ref table_name_t.

inline constexpr table_name_t table_name{};

inline constexpr table_name_t table_name{};

/// Customization point object for @ref fields_t.

/// Customization point object for @ref fields_t.

inline constexpr fields_t     fields{};

inline constexpr fields_t     fields{};

/** Concept for types with a complete schema mapping.

/** Concept for types with a complete schema mapping.

    A conforming type must provide `tag_invoke`

    A conforming type must provide `tag_invoke`

    overloads for both @ref table_name_t and

    overloads for both @ref table_name_t and

    @ref fields_t.

    @ref fields_t.

    @par Syntactic Requirements

    @par Syntactic Requirements

    @li `tag_invoke( table_name, v )` is convertible

    @li `tag_invoke( table_name, v )` is convertible

        to `std::string_view`.

        to `std::string_view`.

    @li `tag_invoke( fields, v )` is a valid expression.

    @li `tag_invoke( fields, v )` is a valid expression.

    @tparam T The type to check for a schema mapping.

    @tparam T The type to check for a schema mapping.

    @see table_name_t, fields_t

    @see table_name_t, fields_t

*/

*/

template <typename T>

template <typename T>

concept HasMapping = requires(T const& v)

concept HasMapping = requires(T const& v)

{

{

    { tag_invoke(table_name, v) } -> std::convertible_to<std::string_view>;

    { tag_invoke(table_name, v) } -> std::convertible_to<std::string_view>;

    { tag_invoke(fields,     v) };

    { tag_invoke(fields,     v) };

};

};

namespace detail {

namespace detail {

template <typename Tuple, typename F, std::size_t... Is>

template <typename Tuple, typename F, std::size_t... Is>

    Tuple const& t, F&& f, std::index_sequence<Is...>)

    Tuple const& t, F&& f, std::index_sequence<Is...>)

{

{

} // namespace detail

} // namespace detail

/** Invoke a callable for each field in a mapped type.

/** Invoke a callable for each field in a mapped type.

    @param f Callable invoked as `f( field_descriptor )`

    @param f Callable invoked as `f( field_descriptor )`

        for every field in `T`'s mapping.

        for every field in `T`'s mapping.

    @tparam T A type satisfying @ref HasMapping.

    @tparam T A type satisfying @ref HasMapping.

    @see field_count

    @see field_count

*/

*/

template <HasMapping T, typename F>

template <HasMapping T, typename F>

{

{

        fs,

        fs,

        static_cast<F&&>(f),

        static_cast<F&&>(f),

        std::make_index_sequence<

        std::make_index_sequence<

            std::tuple_size_v<decltype(fs)>>{});

            std::tuple_size_v<decltype(fs)>>{});

/** Return the number of fields in a mapped type.

/** Return the number of fields in a mapped type.

    @tparam T A type satisfying @ref HasMapping.

    @tparam T A type satisfying @ref HasMapping.

    @return The compile-time field count.

    @return The compile-time field count.

    @see for_each_field

    @see for_each_field

*/

*/

template <HasMapping T>

template <HasMapping T>

constexpr std::size_t field_count()

constexpr std::size_t field_count()

{

{

    constexpr auto fs = tag_invoke(fields, T{});

    constexpr auto fs = tag_invoke(fields, T{});

    return std::tuple_size_v<decltype(fs)>;

    return std::tuple_size_v<decltype(fs)>;

}

}

} // namespace db

} // namespace db

} // namespace http

} // namespace http

} // namespace boost

} // namespace boost

#endif

#endif