Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
Loading...
Searching...
No Matches
orbit::orm::QueryBuilder< DBClient, ModelType > Class Template Reference

A lightweight, JSON-backed ORM Query Builder with bound parameters. More...

#include <QueryBuilder.hpp>

Public Member Functions

 QueryBuilder (std::shared_ptr< DBClient > db, const std::string &table)
 
QueryBuilder & where (const std::string &field, const std::string &op, const std::string &val)
 Adds a WHERE condition. val is bound as a parameter.
 
QueryBuilder & where (const Expr &expr)
 
QueryBuilder & order_by (const std::string &field, Order direction=Order::Asc)
 
QueryBuilder & limit (uint64_t n)
 Returns at most n rows.
 
QueryBuilder & offset (uint64_t n)
 Skips the first n rows (use with order_by() for stable pages).
 
QueryBuilder & all ()
 
QueryBuilder & primary_key (const std::string &column)
 The model's primary key column (default "id").
 
Statement insert_statement (const ModelType &model, bool returning=false) const
 The INSERT that insert_async() runs (create_async() adds RETURNING *). An unset primary key is left out.
 
Statement select_statement () const
 The SELECT that get_async() runs (placeholders as ?).
 
Statement count_statement () const
 The SELECT COUNT(*) that count_async() runs.
 
Statement update_statement (const nlohmann::json &changes) const
 The UPDATE that update_async() runs.
 
Statement delete_statement () const
 
QueryGetAwaiter< DBClient, ModelType > get_async ()
 Executes a SELECT query asynchronously and maps results to a vector of ModelType.
 
QueryCountAwaiter< DBClient > count_async ()
 Counts the matching rows.
 
QueryInsertAwaiter< DBClient, ModelType > update_async (const nlohmann::json &changes)
 Updates the matching rows; resumes with the number affected.
 
QueryInsertAwaiter< DBClient, ModelType > update_async (const ModelType &model)
 
QueryInsertAwaiter< DBClient, ModelType > remove_async ()
 Deletes the matching rows; resumes with the number affected.
 
QueryInsertAwaiter< DBClient, ModelType > insert_async (const ModelType &model)
 Executes an INSERT query for a model, binding every value.
 
QueryCreateAwaiter< DBClient, ModelType > create_async (const ModelType &model)
 Inserts model and resumes with the row as stored, including the generated primary key and column defaults.
 

Private Member Functions

void append_where (Statement &st) const
 
void require_condition (const char *what) const
 

Static Private Member Functions

static Statement finish (Statement st)
 

Private Attributes

std::shared_ptr< DBClient > db_
 
std::string table_
 
std::vector< Expr > wheres_
 
std::vector< std::string > orders_
 
std::optional< uint64_t > limit_
 
std::optional< uint64_t > offset_
 
bool all_rows_ = false
 
std::string primary_key_ = "id"
 

Detailed Description

template<typename DBClient, typename ModelType>
class orbit::orm::QueryBuilder< DBClient, ModelType >

A lightweight, JSON-backed ORM Query Builder with bound parameters.

Values are always bound, never spliced. Table and column names must be plain identifiers; SQL reserved words among them (user, order, ...) are quoted for the client's dialect.

Constructor & Destructor Documentation

◆ QueryBuilder()

template<typename DBClient , typename ModelType >
orbit::orm::QueryBuilder< DBClient, ModelType >::QueryBuilder ( std::shared_ptr< DBClient >  db,
const std::string &  table 
)
inline
Exceptions
std::invalid_argumentif table is not a plain identifier.

Member Function Documentation

◆ all()

template<typename DBClient , typename ModelType >
QueryBuilder & orbit::orm::QueryBuilder< DBClient, ModelType >::all ( )
inline

Allows update_async()/remove_async() without a WHERE condition, i.e. on every row. Without it they throw, so a forgotten where() cannot rewrite or empty a whole table.

◆ append_where()

template<typename DBClient , typename ModelType >
void orbit::orm::QueryBuilder< DBClient, ModelType >::append_where ( Statement &  st) const
inlineprivate

◆ count_async()

template<typename DBClient , typename ModelType >
QueryCountAwaiter< DBClient > orbit::orm::QueryBuilder< DBClient, ModelType >::count_async ( )
inline

Counts the matching rows.

◆ count_statement()

template<typename DBClient , typename ModelType >
Statement orbit::orm::QueryBuilder< DBClient, ModelType >::count_statement ( ) const
inline

The SELECT COUNT(*) that count_async() runs.

◆ create_async()

template<typename DBClient , typename ModelType >
QueryCreateAwaiter< DBClient, ModelType > orbit::orm::QueryBuilder< DBClient, ModelType >::create_async ( const ModelType &  model)
inline

Inserts model and resumes with the row as stored, including the generated primary key and column defaults.

Uses INSERT ... RETURNING *: PostgreSQL, and MariaDB 10.5 or later (MySQL Server has no RETURNING and reports an error).

Item created = co_await query_Item(db).create_async(Item{0, "widget", 3});
// created.id is the new key
Exceptions
DatabaseError(on co_await) if the INSERT fails.

◆ delete_statement()

template<typename DBClient , typename ModelType >
Statement orbit::orm::QueryBuilder< DBClient, ModelType >::delete_statement ( ) const
inline

The DELETE that remove_async() runs.

Exceptions
std::logic_errorwithout a WHERE condition unless all() was called.

◆ finish()

template<typename DBClient , typename ModelType >
static Statement orbit::orm::QueryBuilder< DBClient, ModelType >::finish ( Statement  st)
inlinestaticprivate

◆ get_async()

template<typename DBClient , typename ModelType >
QueryGetAwaiter< DBClient, ModelType > orbit::orm::QueryBuilder< DBClient, ModelType >::get_async ( )
inline

Executes a SELECT query asynchronously and maps results to a vector of ModelType.

◆ insert_async()

template<typename DBClient , typename ModelType >
QueryInsertAwaiter< DBClient, ModelType > orbit::orm::QueryBuilder< DBClient, ModelType >::insert_async ( const ModelType &  model)
inline

Executes an INSERT query for a model, binding every value.

Exceptions
std::invalid_argumentif a field name is not a plain identifier.

Inserts model; resumes with the number of rows inserted (1). An unset primary key (see primary_key()) is left for the database.

Exceptions
DatabaseError(on co_await) if the INSERT fails.

◆ insert_statement()

template<typename DBClient , typename ModelType >
Statement orbit::orm::QueryBuilder< DBClient, ModelType >::insert_statement ( const ModelType &  model,
bool  returning = false 
) const
inline

The INSERT that insert_async() runs (create_async() adds RETURNING *). An unset primary key is left out.

Exceptions
std::invalid_argumentif the model does not serialise to a JSON object with at least one column to insert.

◆ limit()

template<typename DBClient , typename ModelType >
QueryBuilder & orbit::orm::QueryBuilder< DBClient, ModelType >::limit ( uint64_t  n)
inline

Returns at most n rows.

◆ offset()

template<typename DBClient , typename ModelType >
QueryBuilder & orbit::orm::QueryBuilder< DBClient, ModelType >::offset ( uint64_t  n)
inline

Skips the first n rows (use with order_by() for stable pages).

◆ order_by()

template<typename DBClient , typename ModelType >
QueryBuilder & orbit::orm::QueryBuilder< DBClient, ModelType >::order_by ( const std::string &  field,
Order  direction = Order::Asc 
)
inline

Sorts the results; call again for further sort keys.

Exceptions
std::invalid_argumentif field is not a plain identifier.

◆ primary_key()

template<typename DBClient , typename ModelType >
QueryBuilder & orbit::orm::QueryBuilder< DBClient, ModelType >::primary_key ( const std::string &  column)
inline

The model's primary key column (default "id").

insert_async() and create_async() leave the key out when it is unset (null, 0 or an empty string) so the database generates it, and update_async(model) never rewrites it.

Exceptions
std::invalid_argumentif column is not a plain identifier.

◆ remove_async()

template<typename DBClient , typename ModelType >
QueryInsertAwaiter< DBClient, ModelType > orbit::orm::QueryBuilder< DBClient, ModelType >::remove_async ( )
inline

Deletes the matching rows; resumes with the number affected.

◆ require_condition()

template<typename DBClient , typename ModelType >
void orbit::orm::QueryBuilder< DBClient, ModelType >::require_condition ( const char *  what) const
inlineprivate

◆ select_statement()

template<typename DBClient , typename ModelType >
Statement orbit::orm::QueryBuilder< DBClient, ModelType >::select_statement ( ) const
inline

The SELECT that get_async() runs (placeholders as ?).

◆ update_async() [1/2]

template<typename DBClient , typename ModelType >
QueryInsertAwaiter< DBClient, ModelType > orbit::orm::QueryBuilder< DBClient, ModelType >::update_async ( const ModelType &  model)
inline

Updates the matching rows to the fields of model, except its primary key (a default-valued id would otherwise overwrite the key).

◆ update_async() [2/2]

template<typename DBClient , typename ModelType >
QueryInsertAwaiter< DBClient, ModelType > orbit::orm::QueryBuilder< DBClient, ModelType >::update_async ( const nlohmann::json &  changes)
inline

Updates the matching rows; resumes with the number affected.

co_await query_User(db).where(orm::Col("id") == 7).update_async({{"name", "Ada"}, {"active", true}});
A database column, allowing C++ operators to build parameterized SQL conditions.
Definition QueryBuilder.hpp:203

◆ update_statement()

template<typename DBClient , typename ModelType >
Statement orbit::orm::QueryBuilder< DBClient, ModelType >::update_statement ( const nlohmann::json &  changes) const
inline

The UPDATE that update_async() runs.

Parameters
changesA JSON object of column -> new value (null sets NULL).
Exceptions
std::invalid_argumentif changes is not a non-empty object or names an invalid column; std::logic_error without a WHERE condition unless all() was called.

◆ where() [1/2]

template<typename DBClient , typename ModelType >
QueryBuilder & orbit::orm::QueryBuilder< DBClient, ModelType >::where ( const Expr &  expr)
inline

◆ where() [2/2]

template<typename DBClient , typename ModelType >
QueryBuilder & orbit::orm::QueryBuilder< DBClient, ModelType >::where ( const std::string &  field,
const std::string &  op,
const std::string &  val 
)
inline

Adds a WHERE condition. val is bound as a parameter.

Exceptions
std::invalid_argumentfor an invalid field name or an operator other than =, !=, <>, <, <=, >, >=, [NOT] LIKE, [NOT] ILIKE.

Member Data Documentation

◆ all_rows_

template<typename DBClient , typename ModelType >
bool orbit::orm::QueryBuilder< DBClient, ModelType >::all_rows_ = false
private

◆ db_

template<typename DBClient , typename ModelType >
std::shared_ptr<DBClient> orbit::orm::QueryBuilder< DBClient, ModelType >::db_
private

◆ limit_

template<typename DBClient , typename ModelType >
std::optional<uint64_t> orbit::orm::QueryBuilder< DBClient, ModelType >::limit_
private

◆ offset_

template<typename DBClient , typename ModelType >
std::optional<uint64_t> orbit::orm::QueryBuilder< DBClient, ModelType >::offset_
private

◆ orders_

template<typename DBClient , typename ModelType >
std::vector<std::string> orbit::orm::QueryBuilder< DBClient, ModelType >::orders_
private

◆ primary_key_

template<typename DBClient , typename ModelType >
std::string orbit::orm::QueryBuilder< DBClient, ModelType >::primary_key_ = "id"
private

◆ table_

template<typename DBClient , typename ModelType >
std::string orbit::orm::QueryBuilder< DBClient, ModelType >::table_
private

◆ wheres_

template<typename DBClient , typename ModelType >
std::vector<Expr> orbit::orm::QueryBuilder< DBClient, ModelType >::wheres_
private

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