#include <ozo/connection.h>

Description

Database connection concept.

Connection concept represents a minimum set of attributes and functions that are required by the library to execute operations on a database. Connection should provide:

the native PostgreSQL connection handle from libpq,
an executor to perform IO-related operation (according to the current version of Boost.Asio it should be boost::asio::io_context::executor_type object),
an additional error context to provide context-depended information for errors,
IO functions that are necessary to perform operations.

Concrete models

ozo::connection, ozo::pooled_connection, ozo::transaction

Definition

Any wrapper object, which may be unwrapped to the underlying Connection model via ozo::unwrap_connection is valid Connection model.

Connection c is an object of type C for which these next requirements are valid:

Expression	Type	Description
as_const(c).native_handle()	`C::native_handle_type`	Should return native handle type of PostgreSQL connection. In the current implementation it should be `PGconn*` type. Shall not throw an exception.
as_const(c).oid_map()	`C::oid_map_type`	Should return a const reference on `OidMap` which is used by the library for custom types introspection for the connection IO. Shall not throw an exception.
as_const(c).get_error_context()	`C::error_context_type`	Should return a const reference on an additional error context is related to at least the last error. In the current implementation, the type supported is `std::string`. Shall not throw an exception.
c.set_error_context(error_context_type)^[1] c.set_error_context()^[2]		Should set^[1] or reset^[2] additional error context.
as_const(c).get_executor()	`C::executor_type`	Should provide an executor object that is useful for IO-related operations, like timer and so on. In the current implementation `boost::asio::io_context::executor_type` is only applicable. Shall not throw an exception.
c.async_wait_write(WaitHandler)		Should asynchronously wait for write ready state of the connection socket.
c.async_wait_read(WaitHandler)		Should asynchronously wait for read ready state of the connection socket.
c.close()	`error_code`	Should close connection socket and cancel all IO operation on the connection (like `async_wait_write`, `async_wait_read`). Shall not throw an exception.
c.cancel()		Should cancel all IO operation on the connection (like `async_wait_write`, `async_wait_read`). Should not throw an exception.
c.is_bad()	bool	Should return `false` for the established connection that can perform operations. Shall not throw an exception.
c.is_open()	bool	Should return `true` for the object with valid native connection handle attached. Shall not throw an exception.
bool(as_const(c))	bool	Should return `true` for the established connection that can perform operations. Should return `false` at least if `c.is_bad()` returns `true`. Shall not throw an exception.
ozo::get_connection(c, t, Handler)		Should reset the additional error context. This behaviour is performed in default implementation of `ozo::get_connection()` via `c.set_error_context()` call.
ozo::is_connection<C>	`std::true_type`	The template `ozo::is_connection` should be specialized for the connection type via inheritance from `std::true_type`.

Where:

Handler is callable with template <typename Connection> void(ozo::error_code, Connection&&) signature,
WaitHandler is callable with void(ozo::error_code, int = 0) signature,
t is a TimeConstraint model object,
as_const() is std::as_const().

See also: ozo::get_connection(), ozo::is_connection