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

#include <DataMapper.hpp>

Inherits std::enable_shared_from_this< DataMapper >.

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

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

	DataMapper (SqlConnectionString connectionString, PrivateTag _)
	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... Records> requires DataMapperRecords<Records...>
std::vector< std::tuple< Records... > >	QueryToTuple (SqlSelectQueryBuilder::ComposedQuery const &selectQuery)

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 >
SqlAllFieldsQueryBuilder< Record >	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 Record , typename... InputParameters>
LIGHTWEIGHT_FORCE_INLINE std::vector< Record >	Query (SqlSelectQueryBuilder::ComposedQuery const &selectQuery, InputParameters &&... inputParameters)

template<typename FirstRecord , typename SecondRecord , typename... InputParameters> requires DataMapperRecord<FirstRecord> && DataMapperRecord<SecondRecord>
std::vector< std::tuple< FirstRecord, SecondRecord > >	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 std::shared_ptr< DataMapper >	Create ()
	Factory method to create a new data mapper with default connection.

static std::shared_ptr< DataMapper >	Create (SqlConnection &&connection)
	Factory method to create a new data mapper with given connection.

static std::shared_ptr< DataMapper >	Create (SqlConnectionString connectionString)
	Factory method to create a new data mapper with connection string.

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 ( PrivateTag _ )

inline

Constructs a new data mapper, using the default connection.

Definition at line 97 of file DataMapper.hpp.

◆ DataMapper() [2/3]

Lightweight::DataMapper::DataMapper	(	SqlConnection &&	connection,
		PrivateTag	_
	)

inlineexplicit

Constructs a new data mapper, using the given connection.

Definition at line 104 of file DataMapper.hpp.

◆ DataMapper() [3/3]

Lightweight::DataMapper::DataMapper	(	SqlConnectionString	connectionString,
		PrivateTag	_
	)

inlineexplicit

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

Definition at line 111 of file DataMapper.hpp.

Member Function Documentation

◆ Create() [1/4]

static std::shared_ptr< DataMapper > Lightweight::DataMapper::Create ( )

inlinestatic

Factory method to create a new data mapper with default connection.

Definition at line 118 of file DataMapper.hpp.

◆ Create() [2/4]

static std::shared_ptr< DataMapper > Lightweight::DataMapper::Create ( SqlConnection && connection )

inlinestatic

Factory method to create a new data mapper with given connection.

Definition at line 124 of file DataMapper.hpp.

◆ Create() [3/4]

static std::shared_ptr< DataMapper > Lightweight::DataMapper::Create ( SqlConnectionString connectionString )

inlinestatic

Factory method to create a new data mapper with connection string.

Definition at line 130 of file DataMapper.hpp.

◆ Connection() [1/2]

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

inlinenoexcept

Returns the connection reference used by this data mapper.

Definition at line 142 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 148 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 467 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 508 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 597 of file DataMapper.hpp.

◆ CreateTable()

template<typename Record >

void Lightweight::DataMapper::CreateTable ( )

Creates the table for the given record type.

Definition at line 609 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 619 of file DataMapper.hpp.

◆ Create() [4/4]

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 700 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 626 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 947 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 919 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().

◆ QueryToTuple()

template<typename... Records>
requires DataMapperRecords<Records...>

std::vector< std::tuple< Records... > > Lightweight::DataMapper::QueryToTuple ( SqlSelectQueryBuilder::ComposedQuery const & selectQuery )

Queries multiple records and returns them as a vector of std::tuple of the given record types. This can be used to query multiple record types in a single query.

example:

struct Person
{
  int id;
  std::string name;
  std::string email;
  std::string phone;
};
struct Address
{
  int id;
  std::string address;
  std::string city;
  std::string country;
};
void example(DataMapper& dm)
{
  auto const sqlQueryString = R"(SELECT p.*, a.* FROM "Person" p INNER JOIN "Address" a ON p.id = a.id WHERE p.city =
  Berlin AND a.country = Germany)";
  auto const records = dm.QueryToTuple<Person, Address>(sqlQueryString);
  for (auto const& [person, address] : records)
  {
    std::println("Person: {}", DataMapper::Inspect(person));
    std::println("Address: {}", DataMapper::Inspect(address));
  }
}

Definition at line 1039 of file DataMapper.hpp.

References ConfigureRelationAutoLoading(), Lightweight::SqlStatement::Connection(), Lightweight::SqlStatement::Execute(), Lightweight::SqlStatement::GetResultCursor(), Lightweight::SqlStatement::Prepare(), 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 986 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 1147 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 >

SqlAllFieldsQueryBuilder< Record > 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 uset to get result of the

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 FirstRecord, typename NextRecord, typename... InputParameters>
    requires DataMapperRecord<FirstRecord> && DataMapperRecord<NextRecord>
// TODO : need more generic one and we also have queryToTuple
std::vector<std::tuple<FirstRecord, NextRecord>> Query(SqlSelectQueryBuilder::ComposedQuery const& selectQuery,
                                                       InputParameters&&... inputParameters);
 
    Queries records of different types from the database, based on the given query.
template <typename FirstRecord, typename NextRecord>
    requires DataMapperRecord<FirstRecord> && DataMapperRecord<NextRecord>
// TODO : need more generic one and we also have queryToTuple
SqlAllFieldsQueryBuilder<std::tuple<FirstRecord, NextRecord>> 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>>(_stmt, 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 369 of file DataMapper.hpp.

◆ Update()

template<typename Record >

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

Updates the record in the database.

Definition at line 797 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 869 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 393 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 769 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 1186 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 1432 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 1578 of file DataMapper.hpp.

References Lightweight::SqlStatement::Prepare(), Lightweight::HasOneThrough< OtherTable, ThroughTable >::SetAutoLoader(), Lightweight::HasMany< OtherRecord >::SetAutoLoader(), and Lightweight::HasManyThrough< ReferencedRecordT, ThroughRecordT >::SetAutoLoader().

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

◆ Query() [4/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 977 of file DataMapper.hpp.

◆ Query() [5/5]

template<typename FirstRecord , typename SecondRecord , typename... InputParameters>
requires DataMapperRecord<FirstRecord> && DataMapperRecord<SecondRecord>

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

Definition at line 1116 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 1483 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 1516 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 1531 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

◆ Create() [1/4]

◆ Create() [2/4]

◆ Create() [3/4]

◆ Connection() [1/2]

◆ Connection() [2/2]

◆ Inspect()

◆ CreateTableString()

◆ CreateTablesString()

◆ CreateTable()

◆ CreateTables()

◆ Create() [4/4]

◆ CreateExplicit()

◆ QuerySingle()

◆ QuerySingleWithoutRelationAutoLoading()

◆ QueryToTuple()

◆ Query() [1/5]

◆ Query() [2/5]

◆ Query() [3/5]

◆ Update()

◆ Delete()

◆ FromTable()

◆ IsModified()

◆ ClearModifiedState()

◆ LoadRelations()

◆ ConfigureRelationAutoLoading()

◆ Query() [4/5]

◆ Query() [5/5]

◆ SetId()

◆ BindOutputColumns() [1/2]

◆ BindOutputColumns() [2/2]