Main API for mapping records to and from the database using high level C++ syntax. More...

#include <DataMapper.hpp>

Public Member Functions
	DataMapper ()
	Constructs a new data mapper, using the default connection.

	DataMapper (SqlConnection &&connection)
	Constructs a new data mapper, using the given connection.

	DataMapper (std::optional< SqlConnectionString > connectionString)
	Constructs a new data mapper, using the given connection string.

	DataMapper (DataMapper const &)=delete

	DataMapper (DataMapper &&) noexcept=default

DataMapper &	operator= (DataMapper const &)=delete

DataMapper &	operator= (DataMapper &&) noexcept=default

SqlConnection const &	Connection () const noexcept
	Returns the connection reference used by this data mapper.

SqlConnection &	Connection () noexcept
	Returns the mutable connection reference used by this data mapper.

template<typename Record >
std::vector< std::string >	CreateTableString (SqlServerType serverType)
	Constructs a string list of SQL queries to create the table for the given record type.

template<typename FirstRecord , typename... MoreRecords>
std::vector< std::string >	CreateTablesString (SqlServerType serverType)
	Constructs a string list of SQL queries to create the tables for the given record types.

template<typename Record >
void	CreateTable ()
	Creates the table for the given record type.

template<typename FirstRecord , typename... MoreRecords>
void	CreateTables ()
	Creates the tables for the given record types.

template<typename Record >
RecordPrimaryKeyType< Record >	Create (Record &record)
	Creates a new record in the database.

template<typename Record >
RecordPrimaryKeyType< Record >	CreateExplicit (Record const &record)
	Creates a new record in the database.

template<typename Record , typename... PrimaryKeyTypes>
std::optional< Record >	QuerySingle (PrimaryKeyTypes &&... primaryKeys)
	Queries a single record (based on primary key) from the database.

template<typename Record , typename... PrimaryKeyTypes>
std::optional< Record >	QuerySingleWithoutRelationAutoLoading (PrimaryKeyTypes &&... primaryKeys)
	Queries a single record (based on primary key) from the database without auto-loading relations.

template<typename Record , typename... InputParameters>
std::vector< Record >	Query (SqlSelectQueryBuilder::ComposedQuery const &selectQuery, InputParameters &&... inputParameters)
	Queries multiple records from the database, based on the given query.

template<typename Record , typename... InputParameters>
std::vector< Record >	Query (std::string_view sqlQueryString, InputParameters &&... inputParameters)

template<typename ElementMask , typename Record , typename... InputParameters>
std::vector< Record >	Query (SqlSelectQueryBuilder::ComposedQuery const &selectQuery, InputParameters &&... inputParameters)

template<typename Record , DataMapperOptions QueryOptions = {}>
SqlAllFieldsQueryBuilder< Record, QueryOptions >	Query ()

SqlQueryBuilder	Query ()

template<typename Record >
void	Update (Record &record)
	Updates the record in the database.

template<typename Record >
std::size_t	Delete (Record const &record)
	Deletes the record from the database.

SqlQueryBuilder	FromTable (std::string_view tableName)
	Constructs an SQL query builder for the given table name.

template<typename Record >
bool	IsModified (Record const &record) const noexcept
	Checks if the record has any modified fields.

template<typename Record >
void	ClearModifiedState (Record &record) noexcept
	Clears the modified state of the record.

template<typename Record >
void	LoadRelations (Record &record)
	Loads all direct relations to this record.

template<typename Record >
void	ConfigureRelationAutoLoading (Record &record)

template<typename T >
std::optional< T >	Execute (std::string_view sqlQueryString)

template<typename Record , typename... InputParameters>
LIGHTWEIGHT_FORCE_INLINE std::vector< Record >	Query (SqlSelectQueryBuilder::ComposedQuery const &selectQuery, InputParameters &&... inputParameters)

template<typename Record , typename ValueType >
LIGHTWEIGHT_FORCE_INLINE void	SetId (Record &record, ValueType &&id)

template<typename Record , size_t InitialOffset>
LIGHTWEIGHT_FORCE_INLINE Record &	BindOutputColumns (Record &record)

template<typename ElementMask , typename Record , size_t InitialOffset>
LIGHTWEIGHT_FORCE_INLINE Record &	BindOutputColumns (Record &record)

Static Public Member Functions
static LIGHTWEIGHT_API DataMapper &	AcquireThreadLocal ()
	Acquires a thread-local DataMapper instance that is safe for reuse within that thread.

template<typename Record >
static std::string	Inspect (Record const &record)
	Constructs a human readable string representation of the given record.

Detailed Description

Main API for mapping records to and from the database using high level C++ syntax.

A DataMapper instances operates on a single SQL connection and provides methods to create, read, update and delete records in the database.

See also: Field, BelongsTo, HasMany, HasManyThrough, HasOneThrough

struct Person
{
   Field<SqlGuid, PrimaryKey::AutoAssign> id;
   Field<SqlAnsiString<30>> name;
   Field<SqlAnsiString<40>> email;
};
 
auto dm = DataMapper {};
 
// Create a new person record
auto person = Person { .id = SqlGuid::Create(), .name = "John Doe", .email = "johnt@doe.com" };
 
// Create the record in the database and set the primary key on the record
auto const personId = dm.Create(person);
 
// Query the person record from the database
auto const queriedPerson = dm.Query<Person>(personId)
                             .Where(FieldNameOf<&Person::id>, "=", personId)
                             .First();
 
if (queriedPerson.has_value())
    std::println("Queried Person: {}", DataMapper::Inspect(queriedPerson.value()));
 
// Update the person record in the database
person.email = "alt@doe.com";
dm.Update(person);
 
// Delete the person record from the database
dm.Delete(person);

Definition at line 88 of file DataMapper.hpp.

Constructor & Destructor Documentation

◆ DataMapper() [1/3]

Lightweight::DataMapper::DataMapper ( )

inline

Constructs a new data mapper, using the default connection.

Definition at line 95 of file DataMapper.hpp.

◆ DataMapper() [2/3]

Lightweight::DataMapper::DataMapper ( SqlConnection && connection )

inlineexplicit

Constructs a new data mapper, using the given connection.

Definition at line 102 of file DataMapper.hpp.

◆ DataMapper() [3/3]

Lightweight::DataMapper::DataMapper ( std::optional< SqlConnectionString > connectionString )

inlineexplicit

Constructs a new data mapper, using the given connection string.

Definition at line 109 of file DataMapper.hpp.

Member Function Documentation

◆ Connection() [1/2]

SqlConnection const & Lightweight::DataMapper::Connection ( ) const

inlinenoexcept

Returns the connection reference used by this data mapper.

Definition at line 122 of file DataMapper.hpp.

◆ Connection() [2/2]

SqlConnection & Lightweight::DataMapper::Connection ( )

inlinenoexcept

Returns the mutable connection reference used by this data mapper.

Definition at line 128 of file DataMapper.hpp.

◆ Inspect()

template<typename Record >

std::string Lightweight::DataMapper::Inspect ( Record const & record )

static

Constructs a human readable string representation of the given record.

Definition at line 1077 of file DataMapper.hpp.

◆ CreateTableString()

template<typename Record >

std::vector< std::string > Lightweight::DataMapper::CreateTableString ( SqlServerType serverType )

Constructs a string list of SQL queries to create the table for the given record type.

Definition at line 1118 of file DataMapper.hpp.

References Lightweight::SqlMigrationQueryBuilder::CreateTable(), Lightweight::SqlQueryFormatter::Get(), Lightweight::SqlQueryBuilder::Migration(), and Lightweight::SqlForeignKeyReferenceDefinition::tableName.

◆ CreateTablesString()

template<typename FirstRecord , typename... MoreRecords>

std::vector< std::string > Lightweight::DataMapper::CreateTablesString ( SqlServerType serverType )

Constructs a string list of SQL queries to create the tables for the given record types.

Definition at line 1207 of file DataMapper.hpp.

◆ CreateTable()

template<typename Record >

void Lightweight::DataMapper::CreateTable ( )

Creates the table for the given record type.

Definition at line 1219 of file DataMapper.hpp.

References Lightweight::SqlStatement::ExecuteDirect(), and Lightweight::SqlConnection::ServerType().

◆ CreateTables()

template<typename FirstRecord , typename... MoreRecords>

void Lightweight::DataMapper::CreateTables ( )

Creates the tables for the given record types.

Definition at line 1229 of file DataMapper.hpp.

◆ Create()

template<typename Record >

RecordPrimaryKeyType< Record > Lightweight::DataMapper::Create ( Record & record )

Creates a new record in the database.

The record is inserted into the database and the primary key is set on this record.

Returns: The primary key of the newly created record.

Definition at line 1310 of file DataMapper.hpp.

References ClearModifiedState(), ConfigureRelationAutoLoading(), Lightweight::SqlGuid::Create(), CreateExplicit(), Lightweight::GetPrimaryKeyField(), and Lightweight::SqlStatement::LastInsertId().

◆ CreateExplicit()

template<typename Record >

RecordPrimaryKeyType< Record > Lightweight::DataMapper::CreateExplicit ( Record const & record )

Creates a new record in the database.

Note: This is a variation of the Create() method and does not update the record's primary key.

Returns: The primary key of the newly created record.

Definition at line 1236 of file DataMapper.hpp.

References Lightweight::SqlStatement::Execute(), Lightweight::SqlQueryBuilder::Insert(), Lightweight::SqlStatement::LastInsertId(), Lightweight::SqlStatement::Prepare(), and Lightweight::SqlConnection::Query().

Referenced by Create().

◆ QuerySingle()

template<typename Record , typename... PrimaryKeyTypes>

std::optional< Record > Lightweight::DataMapper::QuerySingle ( PrimaryKeyTypes &&... primaryKeys )

Queries a single record (based on primary key) from the database.

The primary key(s) are used to identify the record to load. If the record is not found, std::nullopt is returned.

Definition at line 1555 of file DataMapper.hpp.

References ConfigureRelationAutoLoading().

◆ QuerySingleWithoutRelationAutoLoading()

template<typename Record , typename... PrimaryKeyTypes>

std::optional< Record > Lightweight::DataMapper::QuerySingleWithoutRelationAutoLoading ( PrimaryKeyTypes &&... primaryKeys )

Queries a single record (based on primary key) from the database without auto-loading relations.

The primary key(s) are used to identify the record to load.

Main goal of this function is to load record without relationships to decrease compilation time and work around some limitations of template instantiation depth on MSVC compiler.

Definition at line 1527 of file DataMapper.hpp.

References Lightweight::SqlStatement::Connection(), Lightweight::SqlStatement::Execute(), Lightweight::SqlStatement::GetResultCursor(), Lightweight::SqlStatement::Prepare(), Lightweight::SqlConnection::Query(), Lightweight::SqlQueryBuilder::Select(), and Lightweight::SqlConnection::ServerType().

◆ Query() [1/5]

template<typename Record , typename... InputParameters>

std::vector< Record > Lightweight::DataMapper::Query	(	std::string_view	sqlQueryString,
		InputParameters &&...	inputParameters
	)

Queries multiple records from the database, based on the given query.

Parameters

sqlQueryString	The SQL query string to execute.
inputParameters	The input parameters for the query to be bound before executing.

Returns: A vector of records of the given type that were found via the query.

example:

struct Person
{
    int id;
    std::string name;
    std::string email;
    std::string phone;
    std::string address;
    std::string city;
    std::string country;
};
 
void example(DataMapper& dm)
{
    auto const sqlQueryString = R"(SELECT * FROM "Person" WHERE "city" = ? AND "country" = ?)";
    auto const records = dm.Query<Person>(sqlQueryString, "Berlin", "Germany");
    for (auto const& record: records)
    {
        std::println("Person: {}", DataMapper::Inspect(record));
    }
}

Definition at line 1594 of file DataMapper.hpp.

References ConfigureRelationAutoLoading(), Lightweight::SqlStatement::Connection(), Lightweight::SqlStatement::Execute(), Lightweight::SqlStatement::FetchRow(), Lightweight::SqlStatement::GetColumn(), Lightweight::SqlStatement::GetResultCursor(), Lightweight::SqlStatement::NumColumnsAffected(), Lightweight::SqlStatement::Prepare(), and Lightweight::SqlConnection::ServerType().

◆ Query() [2/5]

template<typename ElementMask , typename Record , typename... InputParameters>

std::vector< Record > Lightweight::DataMapper::Query	(	SqlSelectQueryBuilder::ComposedQuery const &	selectQuery,
		InputParameters &&...	inputParameters
	)

Queries records from the database, based on the given query and can be used to retrieve only part of the record by specifying the ElementMask.

example:

struct Person
{
   int id;
   std::string name;
   std::string email;
   std::string phone;
   std::string address;
   std::string city;
   std::string country;
};
 
auto infos = dm.Query<SqlElements<1,5>(RecordTableName<Person>.Fields({"name"sv, "city"sv}));
 
for(auto const& info : infos)
{
   // only info.name and info.city are loaded
}

Definition at line 1727 of file DataMapper.hpp.

References ConfigureRelationAutoLoading(), Lightweight::SqlStatement::Connection(), Lightweight::SqlStatement::Execute(), Lightweight::SqlStatement::GetResultCursor(), Lightweight::SqlStatement::Prepare(), and Lightweight::SqlConnection::ServerType().

◆ Query() [3/5]

template<typename Record , DataMapperOptions QueryOptions = {}>

SqlAllFieldsQueryBuilder< Record, QueryOptions > Lightweight::DataMapper::Query ( )

inline

Queries records of different types from the database, based on the given query. User can constructed query that selects columns from the multiple tables this function is used to get result of the query

example:

    struct JointA{};
    struct JointB{};
    struct JointC{};
   
    // the following query will construct statement to fetch all elements of JointA and JointC types
    auto dm = DataMapper {};
    auto const query = dm.FromTable(RecordTableName<JoinTestA>)
                         .Select()
                         .Fields<JointA, JointC>()
                         .InnerJoin<&JointB::a_id, &JointA::id>()
                         .InnerJoin<&JointC::id, &JointB::c_id>()
                         .All();
    auto const records = dm.Query<JointA, JointC>(query);
    for(const auto [elementA, elementC] : records)
    {
      // do something with elementA and elementC
    }
template <typename First, typename Second, typename... Rest, DataMapperOptions QueryOptions = {}>
    requires DataMapperRecord<First> && DataMapperRecord<Second> && DataMapperRecords<Rest...>
std::vector<std::tuple<First, Second, Rest...>> Query(SqlSelectQueryBuilder::ComposedQuery const& selectQuery);
 
    Queries records of different types from the database, based on the given query.
template <typename FirstRecord, typename NextRecord, DataMapperOptions QueryOptions = {}>
    requires DataMapperRecord<FirstRecord> && DataMapperRecord<NextRecord>
SqlAllFieldsQueryBuilder<std::tuple<FirstRecord, NextRecord>, QueryOptions> Query()
{
    std::string fields;
 
    auto const emplaceRecordsFrom = [&fields]<typename Record>() {
        Reflection::EnumerateMembers<Record>([&fields]<size_t I, typename Field>() {
            if (!fields.empty())
                fields += ", ";
            fields += std::format(R"("{}"."{}")", RecordTableName<Record>, FieldNameAt<I, Record>);
        });
    };
 
    emplaceRecordsFrom.template operator()<FirstRecord>();
    emplaceRecordsFrom.template operator()<NextRecord>();
 
    return SqlAllFieldsQueryBuilder<std::tuple<FirstRecord, NextRecord>, QueryOptions>(*this, std::move(fields));
}
 
    Queries records of given Record type.
   
    The query builder can be used to further refine the query.
    The query builder will execute the query when a method like All(), First(n), etc. is called.
   
    @returns A query builder for the given Record type.
   
    @code
    auto const records = dm.Query<Person>()
                           .Where(FieldNameOf<&Person::is_active>, "=", true)
                           .All();

Definition at line 311 of file DataMapper.hpp.

◆ Query() [4/5]

SqlQueryBuilder Lightweight::DataMapper::Query ( )

inline

Returns a SqlQueryBuilder using the default query formatter. This can be used to build custom queries separately from the DataMapper. and execute them via the DataMapper's Query() methods that SqlSelectQueryBuilder

Definition at line 330 of file DataMapper.hpp.

References Lightweight::SqlConnection::QueryFormatter().

◆ Update()

template<typename Record >

void Lightweight::DataMapper::Update ( Record & record )

Updates the record in the database.

Definition at line 1409 of file DataMapper.hpp.

References ClearModifiedState(), Lightweight::SqlStatement::Execute(), Lightweight::SqlStatement::Prepare(), Lightweight::SqlConnection::Query(), and Lightweight::SqlQueryBuilder::Update().

◆ Delete()

template<typename Record >

std::size_t Lightweight::DataMapper::Delete ( Record const & record )

Deletes the record from the database.

Definition at line 1479 of file DataMapper.hpp.

References Lightweight::SqlQueryBuilder::Delete(), Lightweight::SqlStatement::Execute(), Lightweight::SqlStatement::NumRowsAffected(), Lightweight::SqlStatement::Prepare(), and Lightweight::SqlConnection::Query().

◆ FromTable()

SqlQueryBuilder Lightweight::DataMapper::FromTable ( std::string_view tableName )

inline

Constructs an SQL query builder for the given table name.

Definition at line 344 of file DataMapper.hpp.

References Lightweight::SqlConnection::Query().

◆ IsModified()

template<typename Record >

bool Lightweight::DataMapper::IsModified ( Record const & record ) const

noexcept

Checks if the record has any modified fields.

Definition at line 1381 of file DataMapper.hpp.

◆ ClearModifiedState()

template<typename Record >

void Lightweight::DataMapper::ClearModifiedState ( Record & record )

noexcept

Clears the modified state of the record.

Definition at line 1766 of file DataMapper.hpp.

Referenced by Create(), and Update().

◆ LoadRelations()

template<typename Record >

void Lightweight::DataMapper::LoadRelations ( Record & record )

Loads all direct relations to this record.

Definition at line 2012 of file DataMapper.hpp.

◆ ConfigureRelationAutoLoading()

template<typename Record >

void Lightweight::DataMapper::ConfigureRelationAutoLoading ( Record & record )

Configures the auto loading of relations for the given record.

This means, that no explicit loading of relations is required. The relations are automatically loaded when accessed.

Definition at line 2158 of file DataMapper.hpp.

References AcquireThreadLocal(), Lightweight::SqlStatement::CloseCursor(), ConfigureRelationAutoLoading(), Lightweight::SqlStatement::Execute(), Lightweight::SqlStatement::FetchRow(), Lightweight::SqlStatement::GetColumn(), Lightweight::SqlStatement::Prepare(), Lightweight::HasOneThrough< OtherTable, ThroughTable >::SetAutoLoader(), Lightweight::HasMany< OtherRecord >::SetAutoLoader(), and Lightweight::HasManyThrough< ReferencedRecordT, ThroughRecordT >::SetAutoLoader().

Referenced by ConfigureRelationAutoLoading(), Create(), Query(), Query(), and QuerySingle().

◆ Execute()

template<typename T >

std::optional< T > Lightweight::DataMapper::Execute ( std::string_view sqlQueryString )

Helper function that allow to execute query directly via data mapper and get scalar result without need to create SqlStatement manually

Parameters

sqlQueryString The SQL query string to execute.

Definition at line 2296 of file DataMapper.hpp.

References Lightweight::SqlStatement::ExecuteDirectScalar().

◆ Query() [5/5]

template<typename Record , typename... InputParameters>

LIGHTWEIGHT_FORCE_INLINE std::vector< Record > Lightweight::DataMapper::Query	(	SqlSelectQueryBuilder::ComposedQuery const &	selectQuery,
		InputParameters &&...	inputParameters
	)

inline

Definition at line 1585 of file DataMapper.hpp.

◆ SetId()

template<typename Record , typename ValueType >

LIGHTWEIGHT_FORCE_INLINE void Lightweight::DataMapper::SetId	(	Record &	record,
		ValueType &&	id
	)

inline

Definition at line 2063 of file DataMapper.hpp.

◆ BindOutputColumns() [1/2]

template<typename Record , size_t InitialOffset>

LIGHTWEIGHT_FORCE_INLINE Record & Lightweight::DataMapper::BindOutputColumns ( Record & record )

inline

Definition at line 2096 of file DataMapper.hpp.

◆ BindOutputColumns() [2/2]

template<typename ElementMask , typename Record , size_t InitialOffset>

LIGHTWEIGHT_FORCE_INLINE Record & Lightweight::DataMapper::BindOutputColumns ( Record & record )

inline

Definition at line 2111 of file DataMapper.hpp.

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

Lightweight/DataMapper/DataMapper.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DataMapper() [1/3]

◆ DataMapper() [2/3]

◆ DataMapper() [3/3]

Member Function Documentation

◆ Connection() [1/2]

◆ Connection() [2/2]

◆ Inspect()

◆ CreateTableString()

◆ CreateTablesString()

◆ CreateTable()

◆ CreateTables()

◆ Create()

◆ CreateExplicit()

◆ QuerySingle()

◆ QuerySingleWithoutRelationAutoLoading()

◆ Query() [1/5]

◆ Query() [2/5]

◆ Query() [3/5]

◆ Query() [4/5]

◆ Update()

◆ Delete()

◆ FromTable()

◆ IsModified()

◆ ClearModifiedState()

◆ LoadRelations()

◆ ConfigureRelationAutoLoading()

◆ Execute()

◆ Query() [5/5]

◆ SetId()

◆ BindOutputColumns() [1/2]

◆ BindOutputColumns() [2/2]