OpenDBX::Conn(3)
π
OpenDBX::Conn(3) β the opendbx manual, part 1 π¦
okay bestie, this is the OpenDBX::Conn page from the opendbx manual and it is literally the βdatabase connection wrapper, but make it C++β page. Part 1 covers the class-level deets, the constructors/destructor, and the C-style bind(). No sign-off, more parts are coming. π«Ά
πΈ NAME πΈ
OpenDBX::Conn β encapsulates a connection to a database. Thatβs the whole vibe: one object wraps your DB connection. π
β¨ SYNOPSIS β¨
π Public Member Functions π
void bind (const char *database, const char *who='', const char
*cred='', odbxbind method=ODBX_BIND_SIMPLE) throw ( std::exception
)
void bind (const string &database, const string &who='', const string
&cred='', odbxbind method=ODBX_BIND_SIMPLE) throw ( std::exception
)
Conn () throw ()
Conn (const char *backend, const char *host='', const char *port='')
throw ( std::exception )
Conn (const Conn &ref) throw ()
Conn (const string &backend, const string &host='', const string
&port='') throw ( std::exception )
Stmt create (const char *sql, unsigned long size=0, Stmt::Type
type=Stmt::Simple) throw ( std::exception )
Stmt create (const string &sql, Stmt::Type type=Stmt::Simple) throw (
std::exception )
string & escape (const char *from, unsigned long fromlen, string &to)
throw ( std::exception )
string & escape (const string &from, string &to) throw ( std::exception
)
void finish () throw ( std::exception )
bool getCapability (odbxcap cap) throw ( std::exception )
void getOption (odbxopt option, void *value) throw ( std::exception )
Conn & operator= (const Conn &ref) throw ()
void setOption (odbxopt option, void *value) throw ( std::exception )
void unbind () throw ( std::exception )
~Conn () throw ()
and hereβs the group-chat translation of what each one does, bestie π
bind(C-style strings) β authenticates the user and selects the database using C-style string parameters.bind(C++ strings) β authenticates the user and selects the database using C++ style string parameters.Conn ()β the default constructor for newly created connection objects with no parameters.Conn(C-style strings) β creates a connection object using C-style string parameters.Conn(copy constructor) β copy constructor, obvi.Conn(C++ strings) β creates a connection object using C++ style string parameters.create(C-style buffer) β creates a statement object from a SQL text string using a C-style buffer.create(C++ string) β creates a statement object from a SQL text string using a C++ string.escape(C-style buffer) β escapes potentially dangerous characters in user input using a C-style buffer.escape(C++ string) β escapes potentially dangerous characters in user input using a C++ style string parameter.finish ()β cleans up the connection object.getCapabilityβ tests if the database driver module understands certain extensions.getOptionβ gets the value of a certain option provided by the database driver module.operator=β assigns a connection instance to another one.setOptionβ sets a certain option provided by the database driver module.unbind ()β releases the connection to the database and resets the authentication status.~Conn ()β destroys the connection instance if no other references exist.
π Detailed Description π
OpenDBX::Conn encapsulates a connection to a database. Thatβs it, thatβs the thesis. π
π Author
Norbert Sendetzky norbert@linuxnetworks.de
β Version
1.0
π Constructor & Destructor Documentation π
π¦ OpenDBX::Conn::Conn () π¦
The default constructor for newly created connection objects without parameters. It exists so programmers can use connection objects as member variables of other classes. They get initialized at construction time of the encapsulating object, back when no values for backend, host and port are available yet. π«Ά
You have to replace the created object later with a connection instance that got the necessary parameters via one of the other constructors. Calling one of the member functions on an instance created by the default constructor is not possible and will throw an exception. π
lowkey important: default-constructed object = placeholder only. Do not call member functions on it unless you want an exception.
Returns β Empty connection instance.
See also β Conn( const char*, const char*, const char* ), Conn( const string&, const string&, const string& ).
π«Ά OpenDBX::Conn::Conn (const char * backend, const char * host = '', const char * port = '')std::exception π«Ά
Creates a connection object using C style string parameters. It initializes a new connection using the parameters backend, host and port, but it does not open the connection to the database yet. This method allows C style strings as values for all parameters. Another constructor for C++ style strings is also available. It returns a new connection instance, which you can use to query options implemented by the driver or to create a statement. In case of an error, it throws an OpenDBX exception with error message, code and severity. π₯
The parameter backend is the name of the driver the OpenDBX library should use to connect to a database. The name must be one of the implemented and available drivers on the system and is case sensitive. All driver names are in lower case, e.g. "mysql".
Depending on the database driver, host can have different meanings. Normally, itβs the name or IP address of the server hosting the database server application. In case of serverless database implementations like SQLite, itβs the directory path where the database file is located. The path must contain the platform specific path separators like slash ("/") on Unix-like systems and backslash (\) on Windows systems. Also the path must end with the path separator like "/path/to/file/".
Furthermore port can be the number or name the database server application is listening to. If a name instead of the number is allowed depends on the database client library, but the number as string does always work. If an empty string is given, the default port of the database server application is used by the database client library.
Parameters
backendβ Name of the backend module to use.hostβ Name or IP address of the database server.portβ Name or number of the port used by the database server.
Returns β Connection instance.
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructor.OpenDBX::Exceptionβ If the underlying database library returns an error.
See also β Conn( const string&, const string&, const string& ).
π OpenDBX::Conn::Conn (const string & backend, const string & host = '', const string & port = '')std::exception π
Creates a connection object using C++ style string parameters. It initializes a new connection using the parameters backend, host and port, but it does not open the connection to the database yet. This method allows C++ style strings as values for all parameters. Another constructor for C style strings is also available. It returns a new connection instance, which you can use to query options implemented by the driver or to create a statement. In case of an error, it throws an OpenDBX exception with error message, code and severity. β¨
The parameter backend is the name of the driver the OpenDBX library should use to connect to a database. The name must be one of the implemented and available drivers on the system and is case sensitive. All driver names are in lower case, e.g. "mysql".
Depending on the database driver, host can have different meanings. Normally, itβs the name or IP address of the server hosting the database server application. In case of serverless database implementations like SQLite, itβs the directory path where the database file is located. The path must contain the platform specific path separators like slash ("/") on Unix-like systems and backslash (\) on Windows systems. Also the path must end with the path separator like "/path/to/file/".
Furthermore port can be the number or name the database server application is listening to. If a name instead of the number is allowed depends on the database client library, but the number as string does always work. If an empty string is given, the default port of the database server application is used by the database client library.
Parameters
backendβ Name of the backend module to use.hostβ Name or IP address of the database server.portβ Name or number of the port used by the database server.
Returns β Connection instance.
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructor.OpenDBX::Exceptionβ If the underlying database library returns an error.
See also β Conn( const char*, const char*, const char* ).
π§ OpenDBX::Conn::~Conn () π§
Destroys the connection instance if no other references exist. Each connection object uses a reference counter to remember if the connection is shared with other objects. If this isnβt the case, or if this object is the last one referencing the connection, the connection is closed and the allocated memory is freed. πβ¨
π OpenDBX::Conn::Conn (const Conn & ref) π
Copy constructor. Enables the transfer of the internal state of an object ref of the same type to this object. Both objects share the same database connection and the reference counter afterward. The reference counter is incremented each time an object is copied and will be decremented if it is destroyed. π«Ά
Parameters
refβ Original connection object instance.
π₯ Member Function Documentation π₯
π void OpenDBX::Conn::bind (const char * database, const char * who = '', const char * cred = '', odbxbind method = ODBX_BIND_SIMPLE)std::exception π
Authenticates the user and selects the database using C style string parameters. After initializing the object instance with one of the constructors that takes a backend, host and port string as parameter, itβs necessary to authenticate the user and select a database. Depending on the database client library, it also establishes the connection to the database server. This method accepts C style strings for the database name, the user name and the password. π
The first parameter, the name of the database, will be used to select the database all further commands are operating on. The database is the container for the tables, views, etc., which store the records and provide access to them.
Authentication is done in most cases by a combination of a user name and a password. If the user name is known by the database server and the supplied password matches with the stored one, the database server will allow the user to operate on the selected database and its tables, provided the user has permissions to read and/or modify the content.
The method parameter can be used to select different methods of authentication. At the moment, only simple authentication (ODBX_BIND_SIMPLE) with user name and password is available.
Parameters
databaseβ Name of the database managed by the database server.whoβ Name of the user account known by the database server.credβ Necessary credential which belongs to the user account.methodβ Method used for authentication.
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructor.OpenDBX::Exceptionβ If the underlying database library returns an error.
π«Ά void OpenDBX::Conn::bind (const string & database, const string & who = '', const string & cred = '', odbxbind method = ODBX_BIND_SIMPLE)std::exception
Okay so this is the log in and pick your database era π It takes C++ style string params and does the whole "authenticate the user, select the database" thing.
The way it works: after you've initialized the object instance with one of the constructors that takes a backend, host and port string as parameter, you have to authenticate the user and select a database. There's literally no skipping this step, bestie. Depending on the database client library, this call also establishes the connection to the database server. This method accepts C++ style strings for the database name, the user name and the password.
So β the first parameter, the name of the database, gets used to select the database that all further commands are operating on. And what even is a database here? It's the container for the tables, views, etc., which store the records and provide access to them. Iconic little nesting doll situation π
Authentication is done in most cases by a combination of a user name and a password. If the user name is known by the database server and the supplied password matches with the stored one, the database server will allow the user to operate on the selected database and its tables β provided the user has permissions to read and/or modify the content. No perms, no slay π₯
And the method parameter? That one can be used to select different methods of authentication. At the moment, only simple authentication (ODBX_BIND_SIMPLE) with user name and password is available. That's it, that's the whole menu π
Parameters
databaseβ Name of the database managed by the database serverwhoβ Name of the user account known by the database servercredβ Necessary credential which belongs to the user accountmethodβ Method used for authentication
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructorOpenDBX::Exceptionβ If the underlying database library returns an error
π¦ Stmt OpenDBX::Conn::create (const char * sql, unsigned long size = 0, Stmt::Type type = Stmt::Simple)std::exception
Making a statement object out of a SQL text string, but this overload takes a C style buffer β¨
This returns an instance of the Stmt class that contains the statement which gets sent to the database server later on. Rn, only simple statements are supported β those are sent to the database server for parsing, and they return the result after you call Stmt::execute(). Later on, prepared statements will also be possible, which are parsed by the database server when creating the object, and then only the parameters get sent to the database server on execution. That can speed up processing, especially if the statement is executed multiple times with different content for the parameters. Future-you is gonna be so grateful π§
The parameter named sql must contain the SQL text string that should be sent to the database server for execution. It have to be a C style buffer in this case (their words, but the vibe is clear π). For a reference of valid SQL statements, please have a look at the documentation of your database server β not my department, bestie.
The length of the statement, excluding the trailing "0" byte, should be given via the second parameter size. If the length of the statement is unknown, you can also supply zero (0) as the size value β which is also the default value if you hand over only one parameter. In that case, the length of the string is calculated internally by this function before the statement is given to the native database library. Very "we'll figure it out" of it π
Via the last parameter you can select how the statement should be treated internally by the OpenDBX and the native database library. Currently, only simple processing is available, which sends complete SQL statements β including its parameters β as string to the database server for parsing and execution. Later on, prepared statement handling will also be available, which parses the statements first and sends only the parameters to the server before execution. This parameter is also optional, so no pressure.
The returned object represents the given statement, which can be executed later on. Important though: the statement is only valid for the current connection, and as soon as the connection gets invalid or is closed, working with this object will throw an error. It's giving "situationship with your connection" π
Parameters
sqlβ SQL text string containing a valid statement understood by the database serversizeβ Size of the SQL text string in bytestypeβ Type of statement object that should be created
Returns
Statement instance bound to this connection
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructorOpenDBX::Exceptionβ If the underlying database library returns an error
See also
Stmt
π Stmt OpenDBX::Conn::create (const string & sql, Stmt::Type type = Stmt::Simple)std::exception
Same energy, but the C++ string glow-up π This one makes a statement object from a SQL text string using a C++ string, and returns an instance of the Stmt class containing the statement sent to the database server later on.
Currently, only simple statements are supported, which are sent to the database server for parsing and returning the result after calling Stmt::execute(). Later on, prepared statements will also be possible β parsed by the database server when creating the object, with only the parameters sent to the database server on execution. This can speed up processing especially if the statement is executed multiple times with different content for the parameters. Same future plans, just no size chaos β¨
The parameter named sql must contain the SQL text string that should be sent to the database server for execution. It have to be a C++ style string in this case. For a reference of valid SQL statements, please have a look at the documentation of your database server.
Via the last parameter type it can be selected how the statement should be treated internally by the OpenDBX and the native database library. Currently, only simple processing is available which sends complete SQL statements including its parameters as string to the database server for parsing and execution. Later on, also prepared statement handling will be available which parses the statements first and sends only the parameters to the server before execution. This parameter is also optional. Optional! Just like your Friday night plans πΈ
The returned object is representing the given statement, which can be executed later on. And again, the statement is only valid for the current connection, and as soon as the connection gets invalid or is closed, working with this object will throw an error. Not me warning you twice π
Parameters
sqlβ SQL text string containing a valid statement understood by the database servertypeβ Type of statement object that should be created
Returns
Statement instance bound to this connection
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructorOpenDBX::Exceptionβ If the underlying database library returns an error
See also
Stmt
π₯ string & OpenDBX::Conn::escape (const char * from, unsigned long fromlen, string & to)std::exception
Okay this one is actually important, so listen up bestie: escaping potentially dangerous characters in user input, using a C style buffer. For preventing SQL injection attacks β which can have desasterous effects β all text input that will be part of an SQL statement must be escaped. No cap, no shortcuts, no "it's probably fine" π
This does also apply to user content that is already stored in the database and should be copied to another record or stored again, as the escaping is removed before the database server writes the content to disk. Sneaky, right?
The first parameter must contain the character sequence that should be escaped as C style string. This string itself won't be modified by this method β it stays exactly as it was, unbothered, moisturised, in its lane π
The escaped string gets written to the third parameter named to, which have to be also an C++ style string. After transforming the input to an escaped string, the result may be more then twice the size of the original input β so plan your buffers accordingly, it grows π
The additional escape sequences aren't stored in the database column, so only the original string will be written to the disk. So it's big on the way in, normal on the way out.
A C++ reference of the third parameter containing the escaped string afterwards is also returned by this method, providing the possibility to write more elegant code. Chainable. Fancy. We love to see it β¨
Parameters
fromβ Input string with which may contain dangerous charactersfromlenβ Size of the input string to escape in bytestoβ String instance where the escaped characters should be written to
Returns
Reference to the second parameter containing the escaped characters
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructorOpenDBX::Exceptionβ If the underlying database library returns an error
π string & OpenDBX::Conn::escape (const string & from, string & to)std::exception
The C++ string twin of the one above, and it's giving same but comfier π«Ά Escapes potentially dangerous characters in user input using a C++ style string parameter β and for preventing SQL injection attacks which can have desasterous effects, all text input that will be part of an SQL statement must be escaped. This does also apply to user content that is already stored in the database and should be copied to another record or stored again, as the escaping is removed before the database server writes the content to disk. Yes I'm repeating it, because it MATTERS π
The first parameter must contain the character sequence that should be escaped, as a C++ style string. This string itself won't be modified by this method. Untouched. Pristine. Iconic.
The escaped string will be written to the third parameter named to, which have to be also a C++ style string. After transforming the input to an escaped string, the result may be more then twice the size of the original input. The additional escape sequences aren't stored in the database column, so only the original string will be written to the disk. Same deal as before β it's all just transportation βοΈ
A C++ reference of the second parameter containing the escaped string afterwards is also returned by this method too, providing the possibility to write more elegant code.
Parameters
fromβ Input string with which may contain dangerous characterstoβ String instance where the escaped characters should be written to
Returns
Reference to the second parameter containing the escaped characters
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructorOpenDBX::Exceptionβ If the underlying database library returns an error
π void OpenDBX::Conn::finish ()std::exception
Cleans up the connection object. That's it. Short queen behavior π It's the "closing the group chat for the night" of methods β nothing else to report.
Exceptions
std::invalid_argumentβ If the object was only initialized by the default constructorOpenDBX::Exceptionβ If the underlying database library returns an error
π¦ bool OpenDBX::Conn::getCapability (odbxcap cap) β throws std::exception
Okay so this one is your vibe check for the driver module: does it actually understand the fancy extensions or not? π
Context first, bestie: the OpenDBX library is built out of a basic set of functions that every driver has to implement, plus optional sets that add extra functionality on top. This method lets your app ask the driver β the one you picked with the first parameter of this object's constructor β whether it supports one or more of those optional sets. The available sets and their constants are:
ODBX_CAP_BASICβ the core function set that all backends are required to implement. It's literally everything you need to connect to the database server, send textual queries, process the simple results that come back, plus all the error handling functions. The whole starter pack. β¨ODBX_CAP_LOβ the function set for handling large objects, aka the stuff the basic functions can't reach into. Currently, Firebird/Interbase and Oracle require using the LOB functions. No cap, they just do. π«Ά
The basic set is basically the guarantee that every driver can handle connections, send statements, and retrieve results β it's supported by all drivers, so you usually don't even have to check it. (Check it anyway if you're feeling paranoid, we love a cautious queen.)
Some database client libraries don't hand you the content of large objects through the basic functions. Instead, Result::fieldValue() returns only a handle to the large object, and reading or modifying the content of that data object means calling additional methods. Sneaky but valid.
Parameters
capβ constant of the capability
Returns
True if supported, false if not. Simple as that. π
Exceptions
std::invalid_argumentβ if the object was only initialized by the default constructorOpenDBX::Exceptionβ if the underlying database library returns an error
πΈ void OpenDBX::Conn::getOption (odbxopt option, void * value) β throws std::exception
Gets the value of a certain option provided by the database driver module. Basically it asks the backend module "hey, what options do you actually implement, and what are their current values?" π
You can call this at every stage, and its main character purpose is finding out which features the backend module supports. Those features can be enabled with setOption() before the connection to the database server is established by calling bind() β order matters, bestie, do not skip the steps.
There are several option values defined as named constants in the opendbx/api.h header file. A few of them are purely informational, while most of the options can also be set to different values via setOption() to change how the backend module behaves. The options are:
ODBX_OPT_API_VERSIONβ the API version implemented by the backend. Returns a five digit number representing the API version of the backend module in the formXYYZZ, whereXis the major number,YYthe revision, andZZthe minor number of the API.ODBX_OPT_THREAD_SAFEβ whether it's safe to use this backend (and especially the native database client library) in an application that uses threads, where more than one thread opens database connections via the OpenDBX library.ODBX_OPT_TLSβ the database client library may support transmitting all data securely by encrypting the network traffic via SSL or TLS. Emphasis on may. πODBX_OPT_MULTI_STATEMENTSβ the database server may be able to support multiple SQL statements in one string sent to the database.ODBX_OPT_PAGED_RESULTSβ every database server and client library can transfer records row by row. Some of them can also transfer multiple rows, or even all at once, to minimize server load, network traffic and latency. The downside? Increased memory consumption. Trade-offs, always trade-offs. πODBX_OPT_COMPRESSβ support of compressed network traffic between database client and server. This can lead to higher throughput if the network is the bottleneck.ODBX_OPT_MODEβ some database servers support different modes of operation, e.g. modes for compliance to other SQL implementations or completely different query languages. Iconic, honestly.
The value parameter must be a pointer to an integer variable where the backend module will store the result for the supplied option. If it's not stated otherwise, the value assigned to this parameter will be of boolean nature and therefore is ODBX_ENABLE for a supported option or ODBX_DISABLE for an option which isn't supported.
Parameters
optionβ constant of the optionvalueβ pointer to memory where the result is stored
Exceptions
std::invalid_argumentβ if the object was only initialized by the default constructorOpenDBX::Exceptionβ if the underlying database library returns an error
π§ Conn & OpenDBX::Conn::operator= (const Conn & ref)
Assigns a connection instance to another one. It takes the internal state of an object ref of the same type and assigns it to this object. After that, both objects share the same database connection and the reference counter. π
The reference counter gets incremented every single time an object is copied, and will be decremented if it is destroyed. So the connection stays alive as long as somebody's still holding onto it. She's not leaving until the last one of you logs off, periodt.
Parameters
refβ connection instance
Returns
Connection reference of this instance
π₯ void OpenDBX::Conn::setOption (odbxopt option, void * value) β throws std::exception
Sets a certain option provided by the database driver module. It changes the value of the specified option in the backend module or in the native database client library. β¨
β οΈ Before trying to set an option, test it withgetOption()first to make sure the backend actually supports it. And heads up: almost all options need to be set before connecting to the database server usingbind()to have any effect at all.
There are several option values defined as named constants in the opendbx/api.h header file. The possible options are:
ODBX_OPT_TLSβ use encryption to transmit all data securely over the network via SSL or TLS. This option can be set toODBX_TLS_NEVER(the default value) to prevent encryption,ODBX_TLS_ALWAYSto enforce encryption and fail if it can't be used between the client library and the server, orODBX_TLS_TRYto use encryption if possible with the option to fall back to a connection which isn't encrypted.ODBX_OPT_MULTI_STATEMENTSβ enables the database server to accept multiple statements in one string to the database if the value ofvalueis set toODBX_ENABLE. Although, it might be possible to disable it by setting it toODBX_DISABLE.ODBX_OPT_PAGED_RESULTSβ every database server and client library can transfer records row by row, and some can also transfer multiple rows or even all at once to minimize server load, network traffic and latency. The downside of that is increased memory consumption. If paged results are supported by the backend, passing positive values will fetch the specified number of records at once from the database server. The value of zero ("0") is special here because it asks the backend module to retrieve all records at once. All of them. Every last one. πODBX_OPT_COMPRESSβ enable compressed network traffic between database client and server. This can maximize throughput if the network is the bottleneck. Pass an integer variable withODBX_ENABLEto enable compression or withODBX_DISABLEto disable it for this connection.ODBX_OPT_MODEβ some database servers support different modes of operation, e.g. modes for compliance to other SQL implementations or completely different query languages. For this one, the value must point to a zero terminated string.
If not stated otherwise, the type of the variable passed to the second parameter named value must be an integer pointer, and its value must be in the range specified by the option being changed.
Parameters
optionβ constant of the optionvalueβ pointer to memory which contains the new value
Exceptions
std::invalid_argumentβ if the object was only initialized by the default constructorOpenDBX::Exceptionβ if the underlying database library returns an error
π void OpenDBX::Conn::unbind () β throws std::exception
Releases the connection to the database and resets the authentication status. Logging off, cleaning up, leaving the group chat gracefully. π¦
Exceptions
std::invalid_argumentβ if the object was only initialized by the default constructorOpenDBX::Exceptionβ if the underlying database library returns an error
π Author
Generated automatically by Doxygen for opendbx from the source code. (Not a human, just a very diligent little robot doing its thing. Respect.) π€β¨
and that's a wrap on OpenDBX::Conn(3) bestie!! πβ¨ you read the whole thing, i'm so proud of you β go forth and talk to your databases responsibly π
π
this masterpiece is Version 1.4.6, born Fri Feb 6 2026 20:17:56 β like, timestamped and everything. slay. π
π¦ where this page comes from
- ubuntu resolute: libopendbx1-dev 1.4.6-18build2
- ubuntu stonking: libopendbx1-dev 1.4.6-18build2
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms