Dmitigr Pgfe  1.1beta
The modern C++ API to PostgreSQL
List of all members
Prepared_statement Class Referenceabstract

Represents a client-side pointer to a remote prepared statement. More...

#include <dmitigr/pgfe/prepared_statement.hpp>

Inheritance diagram for Prepared_statement:
Response Parameterizable Server_message Message

Public Member Functions

Read-only properties
virtual const std::string & name () const =0
 
virtual bool is_preparsed () const =0
 
virtual std::size_t maximum_parameter_count () const =0
 
virtual std::size_t maximum_data_size () const =0
 
Settings
virtual const Dataparameter (std::size_t index) const =0
 
virtual const Dataparameter (const std::string &name) const =0
 
virtual void set_parameter (std::size_t index, std::unique_ptr< Data > &&value)=0
 Binds the parameter of the specified index with the value of type Data. More...
 
virtual void set_parameter (const std::string &name, std::unique_ptr< Data > &&value)=0
 
virtual void set_parameter (std::size_t index, std::nullptr_t)=0
 Similar to set_parameter_no_copy(std::size_t, const Data*). More...
 
virtual void set_parameter (const std::string &name, std::nullptr_t)=0
 Similar to set_parameter_no_copy(const std::string&, const Data*). More...
 
template<typename T >
std::enable_if_t<!std::is_same_v< Data *, T > > set_parameter (std::size_t index, T &&value)
 
template<typename T >
std::enable_if_t<!std::is_same_v< Data *, T > > set_parameter (const std::string &name, T &&value)
 
virtual void set_parameter_no_copy (std::size_t index, const Data *data)=0
 Similar to set_parameter(std::size_t, std::unique_ptr<Data>&&) but binds the parameter of the specified index with a view to the data. More...
 
virtual void set_parameter_no_copy (const std::string &name, const Data *data)=0
 
template<typename ... Types>
void set_parameters (Types &&... values)
 Binds parameters by indexes in range [0, sizeof ... (values)). More...
 
virtual void set_result_format (Data_format format)=0
 Sets the data format for all fields of rows that will be produced during the execution. More...
 
virtual Data_format result_format () const =0
 
Connection-related
virtual void execute_async ()=0
 Submits a request to the server to execute this prepared statement. More...
 
virtual void execute ()=0
 Similar to execute_async() but also waits the Response. More...
 
virtual Connectionconnection ()=0
 
virtual const Connectionconnection () const =0
 
virtual void describe_async ()=0
 Similar to Connection::describe_prepared_statement_async(). More...
 
virtual void describe ()=0
 Similar to Connection::describe_prepared_statement(). More...
 
virtual bool is_described () const =0
 
virtual std::optional< std::uint_fast32_t > parameter_type_oid (std::size_t index) const =0
 
virtual std::optional< std::uint_fast32_t > parameter_type_oid (const std::string &name) const =0
 
virtual const Row_inforow_info () const =0
 
- Public Member Functions inherited from Parameterizable
virtual ~Parameterizable ()=default
 The destructor. More...
 
virtual std::size_t positional_parameter_count () const =0
 
virtual std::size_t named_parameter_count () const =0
 
virtual std::size_t parameter_count () const =0
 
virtual const std::string & parameter_name (std::size_t index) const =0
 
virtual std::optional< std::size_t > parameter_index (const std::string &name) const =0
 
virtual std::size_t parameter_index_throw (const std::string &name) const =0
 
virtual bool has_parameter (const std::string &name) const =0
 
virtual bool has_positional_parameters () const =0
 
virtual bool has_named_parameters () const =0
 
virtual bool has_parameters () const =0
 

Detailed Description

Represents a client-side pointer to a remote prepared statement.

Each prepared statement has its name. There is a special prepared statement with empty name - so called unnamed prepared statement. Although the unnamed prepared statements behave largely the same as named prepared statements, operations on them are optimized for the single use and deallocation, whereas operations on named prepared statements are optimized for multiple use.

Prepared statements can be allocated by using:

  1. one of Connection::prepare_statement() methods;
  2. a PREPARE SQL command.

In the first case a prepared statement should be deallocated via Connection::unprepare_statement(). The behaviour is undefined if such a prepared statement is deallocated by using DEALLOCATE SQL command directly.

In the second case the prepared statement can also be deallocated by using DEALLOCATE SQL command.

There are some special cases of the prepared statement deallocations:

Maximum allowable size of the data for binding with parameters of prepared statements depends on the server version. The runtime error will be thrown if the mentioned maximum exceeds.

See also
Connection::prepare_statement(), Connection::unprepare_statement(), Connection::prepared_statement().

Member Function Documentation

◆ connection() [1/2]

virtual Connection* connection ( )
pure virtual
Returns
The pointer to the instance of type Connection where this statement is prepared.

◆ connection() [2/2]

virtual const Connection* connection ( ) const
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ describe()

virtual void describe ( )
pure virtual

◆ describe_async()

virtual void describe_async ( )
pure virtual

◆ execute()

virtual void execute ( )
pure virtual

Similar to execute_async() but also waits the Response.

Responses
Similar to Connection::perform_async().
Requires
(connection()->is_ready_for_request()).
Exception safety guarantee
Basic.
See also
Connection::execute()

◆ execute_async()

virtual void execute_async ( )
pure virtual

Submits a request to the server to execute this prepared statement.

Responses
Similar to Connection::perform_async().
Requires
(connection()->is_ready_for_async_request())
Exception safety guarantee
Strong.

◆ is_described()

virtual bool is_described ( ) const
pure virtual
Returns
true if the information inferred by the server about this prepared statement is available, or false otherwise.
See also
describe(), parameter_type_oid(), row_info().

◆ is_preparsed()

virtual bool is_preparsed ( ) const
pure virtual
Returns
true if the information inferred by the client (Pgfe) about this prepared statement is available, or false otherwise.

◆ maximum_data_size()

virtual std::size_t maximum_data_size ( ) const
pure virtual
Returns
The maximum data size allowed.

◆ maximum_parameter_count()

virtual std::size_t maximum_parameter_count ( ) const
pure virtual
Returns
The maximum parameter count allowed.

◆ name()

virtual const std::string& name ( ) const
pure virtual
Returns
The name of prepared statement.
Remarks
The empty name denotes the unnamed prepared statement.

◆ parameter() [1/2]

virtual const Data* parameter ( std::size_t  index) const
pure virtual
Returns
The parameter value.
Requires
(index < parameter_count())

◆ parameter() [2/2]

virtual const Data* parameter ( const std::string &  name) const
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Requries
(has_parameter(name))
See also
has_parameter()

◆ parameter_type_oid() [1/2]

virtual std::optional<std::uint_fast32_t> parameter_type_oid ( std::size_t  index) const
pure virtual
Returns
The object identifier of the parameter type, or std::nullopt if (is_described() == false).
Requires
(index < parameter_count())

◆ parameter_type_oid() [2/2]

virtual std::optional<std::uint_fast32_t> parameter_type_oid ( const std::string &  name) const
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Requries
(has_parameter(name))
See also
parameter(), has_parameter()

◆ result_format()

virtual Data_format result_format ( ) const
pure virtual
Returns
The data format for all fields of response rows.
See also
Connection::result_format().

◆ row_info()

virtual const Row_info* row_info ( ) const
pure virtual
Returns
  • nullptr if (is_described() == false), or
  • nullptr if the execution will not provoke producing the rows, or
  • the Row_info that describes the rows which the server would produce.

◆ set_parameter() [1/6]

virtual void set_parameter ( std::size_t  index,
std::unique_ptr< Data > &&  value 
)
pure virtual

Binds the parameter of the specified index with the value of type Data.

Requires
Effects
(parameter_count() == index + 1) - if (! is_preparsed() && ! is_described() && parameter_count() >= index).
Exception safety guarantee
Basic.
See also
parameter()

◆ set_parameter() [2/6]

virtual void set_parameter ( const std::string &  name,
std::unique_ptr< Data > &&  value 
)
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Requries
(has_parameter(name))
See also
parameter(), has_parameter()

◆ set_parameter() [3/6]

virtual void set_parameter ( std::size_t  index,
std::nullptr_t   
)
pure virtual

Similar to set_parameter_no_copy(std::size_t, const Data*).

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ set_parameter() [4/6]

virtual void set_parameter ( const std::string &  name,
std::nullptr_t   
)
pure virtual

Similar to set_parameter_no_copy(const std::string&, const Data*).

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ set_parameter() [5/6]

std::enable_if_t<!std::is_same_v<Data*, T> > set_parameter ( std::size_t  index,
T &&  value 
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Similar to set_parameter(std::size_t, std::unique_ptr<Data>&&) but binds the parameter of the specified index with the value of type T, implicitly converted to the Data by using to_data().

Requires
The value must be convertible to the Data.

◆ set_parameter() [6/6]

std::enable_if_t<!std::is_same_v<Data*, T> > set_parameter ( const std::string &  name,
T &&  value 
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Requries
(has_parameter(name))
See also
has_parameter()

◆ set_parameter_no_copy() [1/2]

virtual void set_parameter_no_copy ( std::size_t  index,
const Data data 
)
pure virtual

Similar to set_parameter(std::size_t, std::unique_ptr<Data>&&) but binds the parameter of the specified index with a view to the data.

Exception safety guarantee
Strong.
Remarks
No deep copy is performed.
See also
parameter()

◆ set_parameter_no_copy() [2/2]

virtual void set_parameter_no_copy ( const std::string &  name,
const Data data 
)
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Requries
(has_parameter(name))
See also
parameter(), has_parameter()

◆ set_parameters()

void set_parameters ( Types &&...  values)
inline

Binds parameters by indexes in range [0, sizeof ... (values)).

In other words:

set_parameters(value1, value2, value3)

equivalently to

(set_parameter(0, value1), set_parameter(1, value1), set_parameter(2, value2))
Requires
  1. Each value of values must be Data-convertible.
  2. `((! is_preparsed() && ! is_described() && sizeof ... (Types) < maximum_parameter_count()) || sizeof ... (Types) < parameter_count())`
Exception safety guarantee
Basic.
See also
set_parameter()

◆ set_result_format()

virtual void set_result_format ( Data_format  format)
pure virtual

Sets the data format for all fields of rows that will be produced during the execution.

Exception safety guarantee
Strong.
See also
Connection::set_result_format().

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