Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
Loading...
Searching...
No Matches
orbit::database::PostgresClient Class Reference

An asynchronous PostgreSQL client using libpq and a network Proactor. More...

#include <PostgresClient.hpp>

Inheritance diagram for orbit::database::PostgresClient:
Collaboration diagram for orbit::database::PostgresClient:

Public Member Functions

 PostgresClient (network::Proactor *proactor, const std::string &conninfo)
 Constructs a new PostgresClient.
 
 ~PostgresClient ()
 
void connect (std::function< void(bool success)> callback)
 Connects to the PostgreSQL database asynchronously. Called on a connected client, it drops that connection first (as reconnect()).
 
void query (const std::string &sql, std::function< void(const ResultSet &res)> callback)
 Executes a query asynchronously.
 
void query (const std::string &sql, const std::vector< std::optional< std::string > > &params, std::function< void(const ResultSet &res)> callback)
 Executes a statement with $1, $2, ... placeholders bound to params (text format; std::nullopt binds SQL NULL). Values are sent separately from the SQL text, so they cannot change the statement.
 
void execute (const std::string &sql, const std::vector< std::optional< std::string > > &params, std::function< void(const ResultSet &res)> callback)
 Like the parameterized query(), but prepares sql once per connection and reuses the plan on later calls with the same SQL.
 
void begin (std::function< void(const ResultSet &res)> callback)
 Starts a transaction (BEGIN).
 
void commit (std::function< void(const ResultSet &res)> callback)
 
void rollback (std::function< void(const ResultSet &res)> callback)
 Rolls back the current transaction (ROLLBACK).
 
bool in_transaction () const
 True inside a transaction block (including one that has failed).
 
void set_statement_timeout (std::chrono::milliseconds timeout)
 Server-side limit on each statement's run time; zero = none.
 
bool is_healthy () const
 True if connected and libpq reports the connection usable.
 
void reconnect (std::function< void(bool success)> callback)
 Drops the current connection (if any) and connects again.
 
void set_max_prepared_statements (size_t n)
 
size_t max_prepared_statements () const
 
size_t prepared_statement_count () const
 

Private Member Functions

void handle_connect (std::function< void(bool)> callback)
 
void handle_query (std::function< void(const ResultSet &)> callback)
 
void finish_connect (std::function< void(bool)> callback)
 
void close_connection ()
 

Private Attributes

network::Proactor * proactor_
 
std::string conninfo_
 
PGconn * conn_ {nullptr}
 
bool connected_ {false}
 
std::chrono::milliseconds statement_timeout_ {0}
 
std::unordered_map< std::string, std::string > prepared_
 
size_t next_statement_ = 0
 
size_t max_prepared_ = 256
 

Detailed Description

An asynchronous PostgreSQL client using libpq and a network Proactor.

Constructor & Destructor Documentation

◆ PostgresClient()

orbit::database::PostgresClient::PostgresClient ( network::Proactor *  proactor,
const std::string &  conninfo 
)

Constructs a new PostgresClient.

Parameters
proactorThe network Proactor to use for async events.
conninfoThe connection string for the PostgreSQL database.

◆ ~PostgresClient()

orbit::database::PostgresClient::~PostgresClient ( )

Member Function Documentation

◆ begin()

void orbit::database::PostgresClient::begin ( std::function< void(const ResultSet &res)>  callback)

Starts a transaction (BEGIN).

◆ close_connection()

void orbit::database::PostgresClient::close_connection ( )
private

◆ commit()

void orbit::database::PostgresClient::commit ( std::function< void(const ResultSet &res)>  callback)

Commits the current transaction (COMMIT). A transaction that hit an error is rolled back by the server instead, and the result is a failure.

◆ connect()

void orbit::database::PostgresClient::connect ( std::function< void(bool success)>  callback)

Connects to the PostgreSQL database asynchronously. Called on a connected client, it drops that connection first (as reconnect()).

Parameters
callbackA callback invoked with a boolean indicating success or failure.

◆ execute()

void orbit::database::PostgresClient::execute ( const std::string &  sql,
const std::vector< std::optional< std::string > > &  params,
std::function< void(const ResultSet &res)>  callback 
)

Like the parameterized query(), but prepares sql once per connection and reuses the plan on later calls with the same SQL.

Up to max_prepared_statements() statements are cached per connection; beyond that, statements run unprepared. The cache is cleared when the connection is re-established.

◆ finish_connect()

void orbit::database::PostgresClient::finish_connect ( std::function< void(bool)>  callback)
private

◆ handle_connect()

void orbit::database::PostgresClient::handle_connect ( std::function< void(bool)>  callback)
private

◆ handle_query()

void orbit::database::PostgresClient::handle_query ( std::function< void(const ResultSet &)>  callback)
private

◆ in_transaction()

bool orbit::database::PostgresClient::in_transaction ( ) const

True inside a transaction block (including one that has failed).

◆ is_healthy()

bool orbit::database::PostgresClient::is_healthy ( ) const

True if connected and libpq reports the connection usable.

◆ max_prepared_statements()

size_t orbit::database::PostgresClient::max_prepared_statements ( ) const
inline

◆ prepared_statement_count()

size_t orbit::database::PostgresClient::prepared_statement_count ( ) const
inline

◆ query() [1/2]

void orbit::database::PostgresClient::query ( const std::string &  sql,
const std::vector< std::optional< std::string > > &  params,
std::function< void(const ResultSet &res)>  callback 
)

Executes a statement with $1, $2, ... placeholders bound to params (text format; std::nullopt binds SQL NULL). Values are sent separately from the SQL text, so they cannot change the statement.

◆ query() [2/2]

void orbit::database::PostgresClient::query ( const std::string &  sql,
std::function< void(const ResultSet &res)>  callback 
)

Executes a query asynchronously.

Parameters
sqlThe SQL query string.
callbackA callback invoked with the query result upon completion.

◆ reconnect()

void orbit::database::PostgresClient::reconnect ( std::function< void(bool success)>  callback)

Drops the current connection (if any) and connects again.

◆ rollback()

void orbit::database::PostgresClient::rollback ( std::function< void(const ResultSet &res)>  callback)

Rolls back the current transaction (ROLLBACK).

◆ set_max_prepared_statements()

void orbit::database::PostgresClient::set_max_prepared_statements ( size_t  n)
inline

◆ set_statement_timeout()

void orbit::database::PostgresClient::set_statement_timeout ( std::chrono::milliseconds  timeout)
inline

Server-side limit on each statement's run time; zero = none.

Applied when the connection is established (call it before connect() or reconnect()). A statement over the limit fails with "canceling statement due to statement timeout". For an unreachable server, add libpq's connect_timeout / keepalives / tcp_user_timeout to conninfo.

Member Data Documentation

◆ conn_

PGconn* orbit::database::PostgresClient::conn_ {nullptr}
private

◆ connected_

bool orbit::database::PostgresClient::connected_ {false}
private

◆ conninfo_

std::string orbit::database::PostgresClient::conninfo_
private

◆ max_prepared_

size_t orbit::database::PostgresClient::max_prepared_ = 256
private

◆ next_statement_

size_t orbit::database::PostgresClient::next_statement_ = 0
private

◆ prepared_

std::unordered_map<std::string, std::string> orbit::database::PostgresClient::prepared_
private

◆ proactor_

network::Proactor* orbit::database::PostgresClient::proactor_
private

◆ statement_timeout_

std::chrono::milliseconds orbit::database::PostgresClient::statement_timeout_ {0}
private

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