| Qore Programming Language Reference Manual 2.2.0

Loading...
Searching...
No Matches
Public Member Functions | List of all members
Qore::SQL::DatasourcePool Class Reference

Provides transparent per-thread, per-transaction datasource connection pooling. More...

`#include <QC_DatasourcePool.dox.h>`

Inheritance diagram for Qore::SQL::DatasourcePool:
[legend]

## Public Member Functions
nothing | beginTransaction ()
| Manually allocates a persistent connection from the pool to the calling thread.
nothing | clearEventQueue ()
| Clears the queue object for DBI events on the pool.
| clearWarningCallback ()
| clears any connection delay warning callback from the object
nothing | commit ()
| Commits the current transaction and releases the connection to the pool.
| constructor (string driver, *string user, *string pass, *string db, *string encoding, *string host, softint min=3, softint max=10, softint port=0, *Qore::Thread::Queue queue, auto arg)
| Creates the DatasourcePool object; attempts to load a DBI driver if the driver is not already present in Qore.
| constructor (string desc, *Qore::Thread::Queue queue, auto arg)
| Creates a DatasourcePool object from a single string giving all parameters that can be parsed by parse_datasource()
| constructor (hash< auto > opts, *Qore::Thread::Queue queue, auto arg)
| Creates a DatasourcePool object from a hash argument giving parameters for the constructor.
| copy ()
| Creates a new Datasource object with the same driver as the original and copies of all the connection parameters.
bool | currentThreadInTransaction ()
| Returns True if the current thread is in a transaction (i.e. has a dedicated datasource allocation), False if not.
| destructor ()
| Throws an exception if any transactions are in progress and returns immediately; the object is destroyed after any in-progress requests are completed.
auto | exec (string sql,...)
| Allocates a persistent connection to the current thread from the pool (if one has not already been allocated) and executes an SQL command on the server and returns either the integer row count (for example, for updates, inserts, and deletes) or the data retrieved (for example, if a stored procedure is executed that returns values)
auto | execRaw (string sql)
| Allocates a persistent connection to the current thread from the pool (if one has not already been allocated) and executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values)
int | getCapabilities ()
| Returns an integer bitfield of DBI driver capabilities.
list< auto > | getCapabilityList ()
| Returns a list of strings giving the capabilities of the current DBI driver.
auto | getClientVersion ()
| Retrieves the driver-specific client library version information; this method may not be implemented for all drivers.
hash< auto > | getConfigHash ()
| Returns a datasource hash describing the configuration of the current object.
string | getConfigString ()
| Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource()
*string | getDBCharset ()
| Retrieves the database-specific charset set encoding for the object.
*string | getDBEncoding ()
| Retrieves the database-specific charset set encoding for the object.
*string | getDBName ()
| Returns the database name parameter as a string or NOTHING if none is set.
string | getDriverName ()
| Returns the name of the driver used for the object.
string | getDriverRealName ()
| Returns the real DB driver name if supported by the driver, otherwise the Qore driver name.
int | getErrorTimeout ()
| Returns the error timeout period for waiting for a connection to come free as an integer giving milliseconds; note that timeout values less than or equal to zero mean that requests for a connection will wait indefinitely.
*string | getHostName ()
| Returns the hostname parameter as a string or NOTHING if none is set.
int | getMaximum ()
| Returns the maximum number of connections in this object.
int | getMinimum ()
| Returns the minimum number of connections in this object.
string | getOSCharset ()
| Returns the Qore character encoding name for the object as a string or `"(unknown)"` if none is set.
*string | getOSEncoding ()
| Returns the Qore character encoding name for the object as a string or NOTHING if none is set.
auto | getOption (string opt)
| Returns the current value for the given option.
hash< auto > | getOptionHash ()
| returns the valid options for the driver associated with the Datasource with descriptions and current values for the current Datasource object
*string | getPassword ()
| Returns the password parameter as a string or NOTHING if none is set.
*int | getPort ()
| Gets the port number that will be used for the next connection to the server.
AbstractSQLStatement | getSQLStatement ()
| Returns an AbstractSQLStatement object based on the current database connection object.
auto | getServerVersion ()
| Returns the driver-specific server version data for the current connection.
*hash< auto > | getUsageInfo ()
| Returns a hash with usage information about the DatasourcePool object.
*string | getUserName ()
| Returns the username parameter as a string or NOTHING if none is set.
bool | inTransaction ()
| Returns True if a transaction is currently in progress (meaning in this case that a datasource form the pool is dedicated to the calling thread), False if not.
nothing | rollback ()
| Rolls back the current transaction and releases the connection to the pool.
auto | select (string sql,...)
| Executes an SQL select statement on the server and returns the result as a hash (column names) of lists (column values per row)
auto | selectRow (string sql,...)
| Executes an SQL select statement on the server and returns the first row as a hash (the column values)
auto | selectRows (string sql,...)
| Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values)
| setErrorTimeout (timeout ts)
| Sets the timeout period for waiting for a connection to come free; note that timeout values less than or equal to zero mean that requests for a connection will wait indefinitely.
nothing | setEventQueue (Qore::Thread::Queue queue, auto arg)
| Sets a queue object for DBI events on the pool.
| setWarningCallback (timeout ms, code callback, auto arg)
| sets a connection delay warning callback to be called any time the delay assigning a connection from the pool exceeds the given timeout in milliseconds
string | toString ()
| Returns a string with technical information about the object.
auto | vexec (string sql, *softlist< auto > vargs)
| Allocates a persistent connection to the current thread from the pool (if one has not already been allocated) and executes SQL code on the DB connection, taking a list for all bind arguments.
auto | vselect (string sql, *softlist< auto > vargs)
| Executes a select statement on the server and returns the results in a hash (column names) of lists (column values per row), taking a list for all bind arguments.
auto | vselectRow (string sql, *softlist< auto > vargs)
| Executes a select statement on the server and returns the first row as a hash (column names and values), taking a list for all bind arguments.
auto | vselectRows (string sql, *softlist< auto > vargs)
| Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values), taking a list for all bind arguments.
Public Member Functions inherited from Qore::SQL::AbstractDatasource
abstract nothing | beginTransaction ()
| Manually signals the start of transaction management on the AbstractDatasource.
abstract nothing | commit ()
| Commits the current transaction and releases any thread resources associated with the transaction.
bool | currentThreadInTransaction ()
| Should return True if the current thread is in a transaction with this object, must be re-implemented in subclasses to provide the desired functionality.
abstract auto | exec (string sql,...)
| Executes an SQL command on the server and returns either the integer row count (for example, for updates, inserts, and deletes) or the data retrieved (for example, if a stored procedure is executed that returns values)
abstract auto | execRaw (string sql)
| Executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values)
abstract auto | getClientVersion ()
| Retrieves the driver-specific client library version information.
abstract hash< auto > | getConfigHash ()
| Returns a datasource hash describing the configuration of the current object.
abstract string | getConfigString ()
| Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource()
abstract *string | getDBEncoding ()
| Retrieves the database-specific charset set encoding for the object.
abstract *string | getDBName ()
| Returns the database name parameter as a string or NOTHING if none is set.
abstract string | getDriverName ()
| Returns the name of the driver used for the object.
string | getDriverRealName ()
| Returns the real DB driver name if supported by the driver, otherwise the Qore driver name.
abstract *string | getHostName ()
| Returns the hostname parameter as a string or NOTHING if none is set.
abstract *string | getOSEncoding ()
| Returns the Qore character encoding name for the object as a string or NOTHING if none is set.
auto | getOption (string opt)
| Returns the current value for the given option.
hash< auto > | getOptionHash ()
| Returns the valid options for the driver associated with the AbstractDatasource with descriptions and current values for the current AbstractDatasource object.
abstract *string | getPassword ()
| Returns the password parameter as a string or NOTHING if none is set.
abstract *int | getPort ()
| Gets the port number that will be used for the next connection to the server.
AbstractSQLStatement | getSQLStatement ()
| Returns an AbstractSQLStatement object based on the current database connection object.
abstract auto | getServerVersion ()
| Returns the driver-specific server version data for the current connection.
abstract *string | getUserName ()
| Returns the username parameter as a string or NOTHING if none is set.
abstract bool | inTransaction ()
| Returns True if a transaction is currently in progress.
abstract nothing | rollback ()
| Rolls the current transaction back and releases any thread resources associated with the transaction.
abstract auto | select (string sql,...)
| Executes an SQL select statement on the server and (normally) returns the result as a hash (column names) of lists (column values per row)
abstract auto | selectRow (string sql,...)
| Executes an SQL select statement on the server and returns the first row as a hash (the column values)
abstract auto | selectRows (string sql,...)
| Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values)
abstract auto | vexec (string sql, *softlist< auto > vargs)
| Executes an SQL command on the server and returns either the integer row count (for example, for updates, inserts, and deletes) or the data retrieved (for example, if a stored procedure is executed that returns values), taking a list for all bind arguments.
abstract auto | vselect (string sql, *softlist< auto > vargs)
| Executes a select statement on the server and returns the results in a hash (column names) of lists (column values per row), taking a list for all bind arguments.
abstract auto | vselectRow (string sql, *softlist< auto > vargs)
| Executes a select statement on the server and returns the first row as a hash (column names and values), taking a list for all bind arguments.
abstract auto | vselectRows (string sql, *softlist< auto > vargs)
| Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values), taking a list for all bind arguments.
Public Member Functions inherited from Qore::Serializable
| constructor ()
| The constructor does not perform any action; this class is just used to mark a class as serializable by inheriting this class.
| copy ()
| The copy constructor does not perform any action; this class is just used to mark a class as serializable by inheriting this class.
| serialize (OutputStream stream, *int flags)
| converts the object to binary data representing the object
binary | serialize (*int flags)
| converts the object to binary data representing the object
hash< SerializationInfo > | serializeToData (*int flags)
| converts the object to a serialization hash representing the object

## Additional Inherited Members
Static Public Member Functions inherited from Qore::Serializable
static auto | deserialize (InputStream stream, *int flags)
| Deserializes data produced with serialize() and returns the value represented by the data.
static auto | deserialize (binary bin, *int flags)
| Deserializes data produced with serialize() and returns the value represented by the data.
static auto | deserialize (string bin, *int flags)
| Deserializes data produced with serialize() and returns the value represented by the data.
static auto | deserialize (hash< SerializationInfo > data, *int flags)
| Deserializes data produced with serializeToData() and returns the value represented by the data.
static hash< SerializationInfo > | deserializeToData (InputStream stream, *int flags)
| Deserializes data produced with serialize() and returns the value represented by the data.
static hash< SerializationInfo > | deserializeToData (binary bin, *int flags)
| Deserializes data produced with serialize() and returns the value represented by the data.
static | serialize (auto val, OutputStream stream, *int flags)
| serializes the data and writes the serialized data to the given output stream
static binary | serialize (auto val, *int flags)
| serializes the data and returns the serialized data as a binary object
static hash< SerializationInfo > | serializeToData (auto val, *int flags)
| converts the value to a serialization hash representing the value

## Detailed Description

Provides transparent per-thread, per-transaction datasource connection pooling.

Restrictions:
  Qore::PO_NO_DATABASE

Overview
  In most cases, the DatasourcePool class can be used as a drop-in replacement for the Datasource class with autocommit disabled; when a transaction begins, a datasource will be automatically assigned to the calling thread, and it will only be released when a commit or rollback is called on the object. If no datasource is available, the calling thread will block until a datasource comes available.
  Note that the same principles apply to SQL and database driver usage as with the Datasource class, see the Datasource class documentation for more information.
  The DatasourcePool class uses Qore's thread resource tracking infrastructure to raise an exception if a thread terminates while a connection is allocated to it. If Qore user code enters a transaction with a DatasourcePool object and the thread terminates without closing the transaction (via DatasourcePool::commit() or DatasourcePool::rollback()), an exception will automatically be raised, the transaction will be rolled back, and the Datasource connection will be freed to the pool.

DatasourcePool Connection Allocations
  The following methods allocate a persistent connection to the calling thread:
  - DatasourcePool::exec()
  - DatasourcePool::vexec()
  - DatasourcePool::execRaw()
  - DatasourcePool::beginTransaction()
  The connection is released to the pool when DatasourcePool::commit() or DatasourcePool::rollback() are called (or in the case the thread terminates, in which case an exception is raised as well).
  To begin a transaction with one of the select methods (for example, with `"select for update"`), call DatasourcePool::beginTransaction() first to manually dedicate a Datasource to the thread before calling the select method. Otherwise statements that should be in the same transaction may be executed in different connections.
  Executing a DatasourcePool method while not in a transaction is realized by allocating a temporary connection to the calling thread which is re-released when the method returns. No explicit commits are executed by the class, therefore it is an error to execute transaction-relevant commands without first calling DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), or DatasourcePool::beginTransaction().
  Note that the SQLStatement class also grabs allocates a persistent connection to the calling thread when executing if it is created using a DatasourcePool object in the constructor; when connections are returned to the pool, all SQLStatement objects using the allocated datasource are closed automatically; for more information see the SQLStatement class documentation.

Thread Resource Handling
  The DatasourcePool class manages connection allocations as a thread resource; if the connection is not released with a call to DatasourcePool::commit() or DatasourcePool::rollback() when the thread exits (or when Qore::throw_thread_resource_exceptions() or Qore::throw_thread_resource_exceptions_to_mark() is called), the transaction is rolled back automatically and a `DATASOURCE-TRANSACTION-EXCEPTION` exception is raised describing the situation.
  Being an builtin class, the DatasourcePool class does not inherit AbstractThreadResource explicitly as a part of the exported API, and the internal AbstractThreadResource::cleanup() method cannot be overridden or suppressed.

Data Serialization
  The DatasourcePool class supports data serialization; deserialization can fail if the database is not supported on or reachable from the target machine.

When deserializing, any datasource event queue is lost; only the connection information is propagated in the deserialized copy.

Note
  This class is not available with the PO_NO_DATABASE parse option

See also
  SqlUtil for a high level database-independent API

## Member Function Documentation

## ◆ beginTransaction()

nothing Qore::SQL::DatasourcePool::beginTransaction | ( |  | ) |

Manually allocates a persistent connection from the pool to the calling thread.

This method should be called when a transaction will be started with a DatasourcePool::select() method (or DatasourcePool::vselect(), etc).

This method does not make any communication with the server to start a transaction; it only allocates a persistent connection to the current thread in Qore.

To release the connection, call DatasourcePool::commit() or DatasourcePool::rollback()

Example:
  db.beginTransaction();

## ◆ clearEventQueue()

nothing Qore::SQL::DatasourcePool::clearEventQueue | ( |  | ) |

Clears the queue object for DBI events on the pool.

Since
  Qore 0.8.9

## ◆ clearWarningCallback()

Qore::SQL::DatasourcePool::clearWarningCallback | ( |  | ) |

clears any connection delay warning callback from the object

Example:
  ds.clearWarningCallback();

Since
  Qore 0.8.9

## ◆ commit()

nothing Qore::SQL::DatasourcePool::commit | ( |  | ) |

Commits the current transaction and releases the connection to the pool.

Example:
  db.commit();

## ◆ constructor() [1/3]

Qore::SQL::DatasourcePool::constructor | ( | hash< auto > | opts,
|  | *Qore::Thread::Queue | queue,
|  | auto | arg )

Creates a DatasourcePool object from a hash argument giving parameters for the constructor.

Parameters

  opts | a hash giving parameters for the new datasource with the following possible keys (the `"type"` key is mandatory, also usable with the output of the parse_datasource() function): `type:` (*string) The name of the database driver to use; this key is mandatory; if not present, an exception will be raised. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver (this string should be the name of the driver to be loaded) `user:` (*string) The user name for the new connection `pass:` (*string) The password for the new connection `db:` (*string) The database name for the new connection `charset:` (*string) The database-specific name of the character encoding to use for the new connection. Also see DatasourcePool::setDBCharset() for a method that allows this parameter to be set after the constructor. If no value is passed for this parameter, then the database character encoding corresponding to the default character encoding for the Qore process will be used instead. `host:` (*string) The host name for the new connection `port:` (softint) The port number for the new connection `options:` (hash) An optional hash having `"min"` and `"max"` keys giving the minimum and maximum number of connections in the pool, respectively; all other options will be passed to the database driver
  queue | An optional Queue object to receive datasource events; note that the Queue passed cannot have any maximum size set or a `QUEUE-ERROR` will be thrown; passing NOTHING will clear any event queue
  arg | an optional argument to be included in the `arg` key of datasource events

Example:
  Datasource db(("type": DSPGSQL, "user": "username", "pass": "password", "db": "database", "charset": "utf8", "host": "localhost", "port": 5432, "options": ("min": 3, "max": 10)));

Exceptions

  DATASOURCEPOOL-UNSUPPORTED-DATABASE | DBI driver cannot be loaded
  DATASOURCEPOOL-CONSTRUCTOR-ERROR | missing or invalid `"driver"` key, other key name not assigned to a string; `"port"` value is <= 0; invalid `"min"` or `"max"` keys
  DBI-OPTION-ERROR | unknown or unsupported option passed to driver

## ◆ constructor() [2/3]

Qore::SQL::DatasourcePool::constructor | ( | string | desc,
|  | *Qore::Thread::Queue | queue,
|  | auto | arg )

Creates a DatasourcePool object from a single string giving all parameters that can be parsed by parse_datasource()

Parameters

  desc | a datasource description string in the format that can be parsed by parse_datasource()
  queue | An optional Queue object to receive datasource events; note that the Queue passed cannot have any maximum size set or a `QUEUE-ERROR` will be thrown; passing NOTHING will clear any event queue
  arg | an optional argument to be included in the `arg` key of datasource events

Example:
  DatasourcePool ds("pgsql:user/pass@db01(utf8)%localhost:5432");

Exceptions

  DATASOURCE-UNSUPPORTED-DATABASE | DBI driver cannot be loaded
  DATASOURCE-CONSTRUCTOR-ERRO | missing required parameter for connection; port value is <= 0
  DBI-OPTION-ERROR | unknown or unsupported option passed to driver

Since
  Qore 0.8.6

## ◆ constructor() [3/3]

Qore::SQL::DatasourcePool::constructor | ( | string | driver,
|  | *string | user,
|  | *string | pass,
|  | *string | db,
|  | *string | encoding,
|  | *string | host,
|  | softint | min = 3,
|  | softint | max = 10,
|  | softint | port = 0,
|  | *Qore::Thread::Queue | queue,
|  | auto | arg )

Creates the DatasourcePool object; attempts to load a DBI driver if the driver is not already present in Qore.

Parameters

  driver | The name of the DBI driver for the Datasource. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver (this string should be the name of the driver to be loaded)
  user | The user name for the new connection. Also see Datasource::setUserName() for a method that allows this parameter to be set after the constructor.
  pass | The password for the new connection. Also see Datasource::setPassword() for a method that allows this parameter to be set after the constructor.
  db | The database name for the new connection. Also see Datasource::setDBName() for a method that allows this parameter to be set after the constructor.
  encoding | The database-specific name of the character encoding to use for the new connection. Also see Datasource::setDBCharset() for a method that allows this parameter to be set after the constructor. If no value is passed for this parameter, then the database character encoding corresponding to the default character encoding will be used instead.
  host | The host name for the new connection. Also see Datasource::setHostName() for a method that allows this parameter to be set after the constructor.
  min | The minimum number of connections in the pool (this number of connections is opened in the constructor)
  max | The maximum number of connections in the pool (not more than this number of connections will be opened)
  port | The port number for the new connection. Also see Datasource::setPort() for a method that allows this parameter to be set after the constructor.
  queue | An optional Queue object to receive datasource events; note that the Queue passed cannot have any maximum size set or a `QUEUE-ERROR` will be thrown; passing NOTHING will clear any event queue
  arg | an optional argument to be included in the `arg` key of datasource events

Example:
  DatasourcePool db(DSPGSQL, "user", "pass", "database", "utf8", "localhost", 3, 10, 5432);

Exceptions

  DATASOURCEPOOL-UNSUPPORTED-DATABASE | DBI driver cannot be found
  DATASOURCEPOOL-CONSTRUCTOR-ERROR | invalid min, max, or port argument
  DBI-OPTION-ERROR | unknown or unsupported option passed to driver

## ◆ copy()

Qore::SQL::DatasourcePool::copy | ( |  | ) |

Creates a new Datasource object with the same driver as the original and copies of all the connection parameters.

Example:
  DatasourcePool new_dsp = dsp.copy();

## ◆ currentThreadInTransaction()

bool Qore::SQL::DatasourcePool::currentThreadInTransaction | ( |  | ) |

Returns True if the current thread is in a transaction (i.e. has a dedicated datasource allocation), False if not.

Returns
  True if the current thread is in a transaction (i.e. has a dedicated datasource allocation), False if not

Code Flags:
  CONSTANT

Example:
  bool b = db.currentThreadInTransaction();

Since
  Qore 0.8.7

## ◆ destructor()

Qore::SQL::DatasourcePool::destructor | ( |  | ) |

Throws an exception if any transactions are in progress and returns immediately; the object is destroyed after any in-progress requests are completed.

Example:
  delete db;

Exceptions

  DATASOURCEPOOL-ERROR | The destructor was called while a transaction was still in progress

## ◆ exec()

auto Qore::SQL::DatasourcePool::exec | ( | string | sql,
|  |  | ... )

Allocates a persistent connection to the current thread from the pool (if one has not already been allocated) and executes an SQL command on the server and returns either the integer row count (for example, for updates, inserts, and deletes) or the data retrieved (for example, if a stored procedure is executed that returns values)

This method also accepts all bind parameters (`%d`, `%v`, `%s`, etc) as documented in Binding by Value and Placeholder

Parameters

  sql | The SQL command to execute on the server
  ... | Include any values to be bound (using `%v` in the command string) or placeholder specifications (using `:`key_name in the command string) in order after the command string

Returns
  The return value depends on the DBI driver; normally, for commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, normally an integer row count is returned. However, some DBI drivers also allow select statements to be executed through this interface, which would also return a hash (column names) of lists (values for each column).

Example:
  int rows = db.exec("insert into table (varchar_col, timestamp_col, blob_col, numeric_col) values (%v, %v, %v, %d)", string, now(), binary, 100);

Note
  see the documentation for the DBI driver being used for additional possible exceptions

## ◆ execRaw()

auto Qore::SQL::DatasourcePool::execRaw | ( | string | sql | ) |

Allocates a persistent connection to the current thread from the pool (if one has not already been allocated) and executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values)

This method does not do any variable binding, so it's useful for example for DDL statements etc

Warning:
  Using this method to execute pure dynamic SQL many times with different SQL strings (as opposed to using the same string and binding by value instead of dynamic SQL) can affect application performance by prohibiting the efficient usage of the DB server's statement cache. See DB server documentation for variable binding and the SQL statement cache for more information.

Parameters

  sql | The SQL command to execute on the server; this string will not be subjected to any transformations for variable binding

Returns
  The return value depends on the DBI driver; normally, for commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, normally an integer row count is returned. However, some DBI drivers also allow select statements to be executed through this interface, which would also return a hash (column names) of lists (values for each column).

Example:
  db.execRaw("create table my_tab (id number, some_text varchar2(30))");

Note
  see the documentation for the DBI driver being used for additional possible exceptions

## ◆ getCapabilities()

int Qore::SQL::DatasourcePool::getCapabilities | ( |  | ) |

Returns an integer bitfield of DBI driver capabilities.

Returns
  an integer bitfield of DBI driver capabilities; see DBI Capability Constants for the meaning of each bit

Code Flags:
  CONSTANT

Example:
  int caps = pool.getCapabilities();
  if (!(caps & DBI_CAP_TRANSACTION_MANAGEMENT))
  throw "DATASOURCE-ERROR", sprintf("DBI driver %y does not support transaction management", db.getDriverName());

Since
  Qore 0.8.12

## ◆ getCapabilityList()

list< auto > Qore::SQL::DatasourcePool::getCapabilityList | ( |  | ) |

Returns a list of strings giving the capabilities of the current DBI driver.

Returns
  a list of strings giving the capabilities of the current DBI driver

Code Flags:
  CONSTANT

Example:
  printf("driver %y has the following capabilities:\n", db.getDriverName());
  foreach string cap in (db.getCapabilityList())
  printf("- %s\n", cap);

Since
  Qore 0.8.12

## ◆ getClientVersion()

auto Qore::SQL::DatasourcePool::getClientVersion | ( |  | ) |

Retrieves the driver-specific client library version information; this method may not be implemented for all drivers.

Returns
  the driver-specific client library version information; this method may not be implemented for all drivers; see the DBI driver documentation for the return data type and format

Example:
  auto ver = db.getClientVersion();

Note
  see the documentation for the DBI driver being used for possible exceptions

## ◆ getConfigHash()

hash< auto > Qore::SQL::DatasourcePool::getConfigHash | ( |  | ) |

Returns a datasource hash describing the configuration of the current object.

Code Flags:
  CONSTANT

Example:
  hash<auto> h = ds.getConfigHash();

Returns
  a datasource hash describing the configuration of the current object

Since
  Qore 0.8.8

## ◆ getConfigString()

string Qore::SQL::DatasourcePool::getConfigString | ( |  | ) |

Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource()

Code Flags:
  CONSTANT

Example:
  string str = ds.getConfigString();

Returns
  a string giving the configuration of the current object in a format that can be parsed by parse_datasource()

Since
  Qore 0.8.8

## ◆ getDBCharset()

*string Qore::SQL::DatasourcePool::getDBCharset | ( |  | ) |

Retrieves the database-specific charset set encoding for the object.

A method synonym for DatasourcePool::getDBEncoding() kept for backwards-compatibility

Returns
  the database-specific charset set encoding for the object

Code Flags:
  CONSTANT

Example:
  *string enc = db.getDBCharset();

## ◆ getDBEncoding()

*string Qore::SQL::DatasourcePool::getDBEncoding | ( |  | ) |

Retrieves the database-specific charset set encoding for the object.

Returns
  the database-specific charset set encoding for the object

Code Flags:
  CONSTANT

Example:
  *string enc = db.getDBEncoding();

See also
  DatasourcePool::getOSEncoding()

## ◆ getDBName()

*string Qore::SQL::DatasourcePool::getDBName | ( |  | ) |

Returns the database name parameter as a string or NOTHING if none is set.

Returns
  the database name parameter as a string or NOTHING if none is set

Code Flags:
  CONSTANT

Example:
  *string db = db.getDBName();

## ◆ getDriverName()

string Qore::SQL::DatasourcePool::getDriverName | ( |  | ) |

Returns the name of the driver used for the object.

Returns
  the name of the driver used for the object

Code Flags:
  CONSTANT

Example:
  string driver = db.getDriverName();

See also
  getDriverRealName()

## ◆ getDriverRealName()

string Qore::SQL::DatasourcePool::getDriverRealName | ( |  | ) |

Returns the real DB driver name if supported by the driver, otherwise the Qore driver name.

Returns
  the real DB driver name if supported by the driver, otherwise the Qore driver name

Code Flags:
  RET_VALUE_ONLY

Example:
  string driver = db.getDriverRealName();

The return value will differ from getDriverName() in the case of "wrapper" drivers such as `odbc` or `jdbc`, where the generic Qore driver name is insufficient to identify the database server type.

In other cases, this method will return the same value as getDriverName()

See also
  getDriverRName()

Since
  Qore 1.14

## ◆ getErrorTimeout()

int Qore::SQL::DatasourcePool::getErrorTimeout | ( |  | ) |

Returns the error timeout period for waiting for a connection to come free as an integer giving milliseconds; note that timeout values less than or equal to zero mean that requests for a connection will wait indefinitely.

Code Flags:
  CONSTANT

Example:
  int ms = ds.getErrorTimeout();

Returns
  the error timeout period for waiting for a connection to come free as an integer giving milliseconds; note that timeout values less than or equal to zero mean that requests for a connection will wait indefinitely

Since
  Qore 0.8.9

## ◆ getHostName()

*string Qore::SQL::DatasourcePool::getHostName | ( |  | ) |

Returns the hostname parameter as a string or NOTHING if none is set.

Returns
  the hostname parameter as a string or NOTHING if none is set

Code Flags:
  CONSTANT

Example:
  *string host = db.getHostName();

## ◆ getMaximum()

int Qore::SQL::DatasourcePool::getMaximum | ( |  | ) |

Returns the maximum number of connections in this object.

Returns
  the maximum number of connections in this object

Code Flags:
  CONSTANT

Example:
  int max = db.getMaximum();

## ◆ getMinimum()

int Qore::SQL::DatasourcePool::getMinimum | ( |  | ) |

Returns the minimum number of connections in this object.

Returns
  the minimum number of connections in this object

Code Flags:
  CONSTANT

Example:
  int min = db.getMinimum();

## ◆ getOption()

auto Qore::SQL::DatasourcePool::getOption | ( | string | opt | ) |

Returns the current value for the given option.

Code Flags:
  RET_VALUE_ONLY

Parameters

  opt | the option to get

Exceptions

  DBI-OPTION-ERROR | unknown or unsupported option passed to driver

Since
  Qore 0.8.6

## ◆ getOptionHash()

hash< auto > Qore::SQL::DatasourcePool::getOptionHash | ( |  | ) |

returns the valid options for the driver associated with the Datasource with descriptions and current values for the current Datasource object

Code Flags:
  CONSTANT

Returns
  a hash where the keys are valid option names, and the values are hashes with the following keys:
  - `"desc"`: a string description of the option
  - `"type"`: a string giving the data type restriction for the option
  - `"value"`: the current value of the option

Since
  Qore 0.8.6

## ◆ getOSCharset()

string Qore::SQL::DatasourcePool::getOSCharset | ( |  | ) |

Returns the Qore character encoding name for the object as a string or `"(unknown)"` if none is set.

Returns
  the Qore character encoding name for the object as a string or `"(unknown)"` if none is set

Code Flags:
  CONSTANT

Example:
  string enc = db.getOSCharset();

See also
  DatasourcePool::getOSEncoding()

## ◆ getOSEncoding()

*string Qore::SQL::DatasourcePool::getOSEncoding | ( |  | ) |

Returns the Qore character encoding name for the object as a string or NOTHING if none is set.

Returns
  the Qore character encoding name for the object as a string or NOTHING if none is set

Code Flags:
  CONSTANT

Example:
  *string enc = db.getOSEncoding();

## ◆ getPassword()

*string Qore::SQL::DatasourcePool::getPassword | ( |  | ) |

Returns the password parameter as a string or NOTHING if none is set.

Returns
  the password parameter as a string or NOTHING if none is set

Code Flags:
  CONSTANT

Example:
  *string pass = db.getPassword();

## ◆ getPort()

*int Qore::SQL::DatasourcePool::getPort | ( |  | ) |

Gets the port number that will be used for the next connection to the server.

Invalid port numbers will cause an exception to be thrown when the connection is opened

Code Flags:
  CONSTANT

Example:
  *int port = db.getPort();

## ◆ getServerVersion()

auto Qore::SQL::DatasourcePool::getServerVersion | ( |  | ) |

Returns the driver-specific server version data for the current connection.

Returns
  the driver-specific server version data for the current connection; see the DBI driver documentation for the return data type and format

Example:
  auto ver = db.getServerVersion();

Note
  see the documentation for the DBI driver being used for additional possible exceptions

## ◆ getSQLStatement()

AbstractSQLStatement Qore::SQL::DatasourcePool::getSQLStatement | ( |  | ) |

Returns an AbstractSQLStatement object based on the current database connection object.

Example:
  AbstractSQLStatement stmt = ds.getSQLStatement();

Exceptions

  SQLSTATEMENT-ERROR | the DBI driver for the given object does not support the prepared statement API

Since
  Qore 0.9.0

## ◆ getUsageInfo()

*hash< auto > Qore::SQL::DatasourcePool::getUsageInfo | ( |  | ) |

Returns a hash with usage information about the DatasourcePool object.

Code Flags:
  CONSTANT

Example:
  hash<auto> h = ds.getUsageInfo();

Returns
  a hash with the following keys (note that the `callback`, `timeout`, and optionally `arg` keys are only set if a warning callback is set):
  - `callback:` the closure or call reference set as the warning callback
  - `timeout:` an integer giving the timeout threshold in milliseconds before the warning callback is executed
  - `arg:` an optional argument passed to the warning callback
  - `wait_max:` the maximum number of microseconds that threads have had to wait for a free connection
  - `stats_reqs:` the total number of requests for connections / transactions on this DatasourcePool
  - `stats_hits:` the total number of requests for connections / transactions on this DatasourcePool that did not have to wait for a connection

Note
  `wait_max` is reported in microseconds (1 ms = 1000 us) while the warning timeout has a resolution of milliseconds

Since
  Qore 0.8.9

## ◆ getUserName()

*string Qore::SQL::DatasourcePool::getUserName | ( |  | ) |

Returns the username parameter as a string or NOTHING if none is set.

Returns
  the username parameter as a string or NOTHING if none is set

Code Flags:
  CONSTANT

Example:
  *string user = db.getUserName();

## ◆ inTransaction()

bool Qore::SQL::DatasourcePool::inTransaction | ( |  | ) |

Returns True if a transaction is currently in progress (meaning in this case that a datasource form the pool is dedicated to the calling thread), False if not.

Returns
  True if a transaction is currently in progress (meaning in this case that a datasource form the pool is dedicated to the calling thread), False if not

Code Flags:
  CONSTANT

Example:
  bool b = db.inTransaction();

## ◆ rollback()

nothing Qore::SQL::DatasourcePool::rollback | ( |  | ) |

Rolls back the current transaction and releases the connection to the pool.

Example:
  db.rollback();

## ◆ select()

auto Qore::SQL::DatasourcePool::select | ( | string | sql,
|  |  | ... )

Executes an SQL select statement on the server and returns the result as a hash (column names) of lists (column values per row)

The return format of this method is suitable for use with context statements, for easy iteration and processing of query results. Alternatively, the HashListIterator class can be used to iterate the return value of this method.

Additionally, this format is a more efficient format than that returned by the Datasource::selectRows() method, because the column names are not repeated for each row returned. Therefore, for retrieving anything greater than small amounts of data, it is recommended to use this method instead of Datasource::selectRows().

This method also accepts all bind parameters (`%d`, `%v`, `%s`, etc) as documented in Binding by Value and Placeholder

This method does not retain the datasource connection for the current thread if one was not already allocated before this method is called, so to execute select statements that begin a transaction (such as `"select for update"`), execute DatasourcePool::beginTransaction() first to ensure that the connection is dedicated to the calling thread.

Parameters

  sql | The SQL command to execute on the server
  ... | Include any values to be bound (using `%v` in the command string) or placeholder specifications (using `:`key_name in the command string) in order after the command string

Returns
  This method returns a hash (the keys are the column names) of lists (the column data per row) when executed with an SQL select statement, however some DBI drivers allow any SQL to be executed through this method, in which case other data types can be returned (such as an integer for a row count or a hash for output parameters when executing a stored procedure). If no rows are found, a hash of column names assigned to empty lists is returned.

Example:
  # bind a string and a date/time value by value in a query
  hash query = db.select("select * from table where varchar_column = %v and timestamp_column > %v", string, 2007-10-11T15:31:26.289);
  if (query.firstValue())
  printf("got results\n");

Note
  - See the documentation for the DBI driver being used for additional possible exceptions
  - This method returns all the data available immediately; to process query data piecewise, use the SQLStatement class

See also
  - DatasourcePool::vselect()
  - <hash>::contextIterator()
  - context Statements

## ◆ selectRow()

auto Qore::SQL::DatasourcePool::selectRow | ( | string | sql,
|  |  | ... )

Executes an SQL select statement on the server and returns the first row as a hash (the column values)

If more than one row is returned, then it is treated as an error and a `DBI-SELECT-ROW-ERROR` is returned (however the DBI driver should raise its own exception here to avoid retrieving more than one row from the server). For a similar method taking a list for all bind arguments, see DatasourcePool::vselectRow().

This method also accepts all bind parameters (`%d`, `%v`, `%s`, etc) as documented in Binding by Value and Placeholder

This method does not retain the datasource connection for the current thread if one was not already allocated before this method is called, so to execute select statements that begin a transaction (such as `"select for update"`), execute DatasourcePool::beginTransaction() first to ensure that the connection is dedicated to the calling thread.

Parameters

  sql | The SQL command to execute on the server
  ... | Include any values to be bound (using `%v` in the command string) or placeholder specifications (using `:`key_name in the command string) in order after the command string

Returns
  This method normally returns a hash (the keys are the column names) of row data or NOTHING if no row is found for the query when executed with an SQL select statement, however some DBI drivers allow any SQL statement to be executed through this method (not only select statements), in this case other data types can be returned

Example:
  *hash<auto> h = db.selectRow("select * from example_table where id = 1");

Exceptions

  DBI-SELECT-ROW-ERROR | more than 1 row retrieved from the server

Note
  see the documentation for the DBI driver being used for additional possible exceptions

## ◆ selectRows()

auto Qore::SQL::DatasourcePool::selectRows | ( | string | sql,
|  |  | ... )

Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values)

The return format of this method is not as memory efficient as that returned by the DatasourcePool::select() method, therefore for larger amounts of data, it is recommended to use DatasourcePool::select().

The usual return value of this method can be iterated with the ListHashIterator class.

This method also accepts all bind parameters (`%d`, `%v`, `%s`, etc) as documented in Binding by Value and Placeholder

This method does not retain the datasource connection for the current thread if one was not already allocated before this method is called, so to execute select statements that begin a transaction (such as `"select for update"`), execute DatasourcePool::beginTransaction() first to ensure that the connection is dedicated to the calling thread.

Parameters

  sql | The SQL command to execute on the server
  ... | Include any values to be bound (using `%v` in the command string) or placeholder specifications (using `:`key_name in the command string) in order after the command string

Returns
  Normally returns a list (rows) of hash (where the keys are the column names of each row) or NOTHING if no rows are found for the query, however some DBI drivers allow any SQL statement to be executed through this method (not only select statements), in this case other data types can be returned

Example:
  *list<auto> list = db.selectRows("select * from example_table");

Note
  see the documentation for the DBI driver being used for additional possible exceptions

See also
  DatasourcePool::select()

## ◆ setErrorTimeout()

Qore::SQL::DatasourcePool::setErrorTimeout | ( | timeout | ts | ) |

Sets the timeout period for waiting for a connection to come free; note that timeout values less than or equal to zero mean that requests for a connection will wait indefinitely.

Example:
  ds.setErrorTimeout(30s);

Since
  Qore 0.8.9

## ◆ setEventQueue()

nothing Qore::SQL::DatasourcePool::setEventQueue | ( | Qore::Thread::Queue | queue,
|  | auto | arg )

Sets a queue object for DBI events on the pool.

Parameters

  queue | the Queue object to receive datasource events; note that the Queue passed cannot have any maximum size set or a `QUEUE-ERROR` will be thrown; passing NOTHING will clear any event queue
  arg | an argument to be included in the `arg` key of datasource events

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

Since
  Qore 0.8.9

## ◆ setWarningCallback()

Qore::SQL::DatasourcePool::setWarningCallback | ( | timeout | ms,
|  | code | callback,
|  | auto | arg )

sets a connection delay warning callback to be called any time the delay assigning a connection from the pool exceeds the given timeout in milliseconds

Example:
  code cb = sub (string dsstr, int us, int to) {
  printf("WARNING: datasource pool %y took %f ms (threshold %d ms) to assign a new connection\n", dsstr, us.toNumber() / 1000n, to);
  };
  ds.setWarningCallback(5s, cb);

Parameters

  ms | the period of time with a resolution of milliseconds after which the callback will be called if a connection cannot be allocated in the given time period
  callback | a closure or call reference taking three or four arguments: (string desc, int time, int warning_timeout[, any arg]) which will be passed a datasource description string for the pool, an integer giving the amount of time it took to acquire the connection in microseconds (divide by 1000 to get milliseconds), an integer giving the warning timeout threshold in milliseconds, and optionally the arg value passed to this method
  arg | an optional argument that will be passed to the warning callback

Note
  that the warning timeout has a resolution of milliseconds, but the actual wait time is reported in microseconds (1 ms = 1000 us)

Since
  Qore 0.8.9

## ◆ toString()

string Qore::SQL::DatasourcePool::toString | ( |  | ) |

Returns a string with technical information about the object.

Returns
  a string with technical information about the object

Code Flags:
  CONSTANT

Example:
  string str = db.toString();

## ◆ vexec()

auto Qore::SQL::DatasourcePool::vexec | ( | string | sql,
|  | *softlist< auto > | vargs )

Allocates a persistent connection to the current thread from the pool (if one has not already been allocated) and executes SQL code on the DB connection, taking a list for all bind arguments.

Same as DatasourcePool::exec() except takes an explicit list for bind arguments

This method also accepts all bind parameters (`%d`, `%v`, `%s`, etc) as documented in Binding by Value and Placeholder

Parameters

  sql | The SQL command to execute on the server
  vargs | Include any values to be bound (using `%v` in the command string) or placeholder specifications (using `:`key_name in the command string) in order after the command string

Returns
  The return value depends on the DBI driver; normally, for commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, normally an integer row count is returned. However, some DBI drivers also allow select statements to be executed through this interface, which would also return a hash (column names) of lists (values for each column).

Example:
  int rows = db.vexec("insert into example_table value (%v, %v, %v)", arg_list);

Note
  see the documentation for the DBI driver being used for additional possible exceptions

## ◆ vselect()

auto Qore::SQL::DatasourcePool::vselect | ( | string | sql,
|  | *softlist< auto > | vargs )

Executes a select statement on the server and returns the results in a hash (column names) of lists (column values per row), taking a list for all bind arguments.

The return format of this method is suitable for use with context statements, for easy iteration and processing of query results. Alternatively, the HashListIterator class can be used to iterate the return value of this method.

This method also accepts all bind parameters (`%d`, `%v`, `%s`, etc) as documented in Binding by Value and Placeholder

This method does not retain the datasource connection for the current thread if one was not already allocated before this method is called, so to execute select statements that begin a transaction (such as `"select for update"`), execute DatasourcePool::beginTransaction() first to ensure that the connection is dedicated to the calling thread.

Parameters

  sql | The SQL command to execute on the server
  vargs | Include any values to be bound (using `%v` in the command string) or placeholder specifications (using `:`key_name in the command string) in order after the command string

Returns
  Normally returns a hash (the keys are the column names) of list (each hash key's value is a list giving the row data), however some DBI drivers allow any SQL statement to be executed through this method (not only select statements), in this case other data types can be returned. If no rows are found, a hash of column names assigned to empty lists is returned.

Example:
  hash<auto> query = db.vselect("select * from example_table where id = %v and name = %v", arg_list);
  if (query.firstValue())
  printf("got results\n");

Note
  - See the documentation for the DBI driver being used for additional possible exceptions
  - This method returns all the data available immediately; to process query data piecewise, use the SQLStatement class

See also
  - DatasourcePool::select()
  - <hash>::contextIterator()
  - context Statements

## ◆ vselectRow()

auto Qore::SQL::DatasourcePool::vselectRow | ( | string | sql,
|  | *softlist< auto > | vargs )

Executes a select statement on the server and returns the first row as a hash (column names and values), taking a list for all bind arguments.

This method is the same as the DatasourcePool::selectRow() method, except this method takes a single argument after the SQL command giving the list of bind value parameters

This method also accepts all bind parameters (`%d`, `%v`, `%s`, etc) as documented in Binding by Value and Placeholder

This method does not retain the datasource connection for the current thread if one was not already allocated before this method is called, so to execute select statements that begin a transaction (such as `"select for update"`), execute DatasourcePool::beginTransaction() first to ensure that the connection is dedicated to the calling thread.

Parameters

  sql | The SQL command to execute on the server
  vargs | Include any values to be bound (using `%v` in the command string) or placeholder specifications (using `:`key_name in the command string) in order after the command string

Returns
  This method normally returns a hash (the keys are the column names) of row data or NOTHING if no row is found for the query when executed with an SQL select statement, however some DBI drivers allow any SQL statement to be executed through this method (not only select statements), in this case other data types can be returned

Example:
  *hash<auto> h = db.vselectRow("select * from example_table where id = %v and type = %v", arg_list);

Note
  see the documentation for the DBI driver being used for additional possible exceptions

See also
  DatasourcePool::selectRow()

## ◆ vselectRows()

auto Qore::SQL::DatasourcePool::vselectRows | ( | string | sql,
|  | *softlist< auto > | vargs )

Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values), taking a list for all bind arguments.

Same as the Datasource::selectRows() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.

The usual return value of this method can be iterated with the ListHashIterator class.

The return format of this method is not as memory efficient as that returned by the DatasourcePool::select() method, therefore for larger amounts of data, it is recommended to use DatasourcePool::select().

This method also accepts all bind parameters (`%d`, `%v`, `%s`, etc) as documented in Binding by Value and Placeholder

This method does not retain the datasource connection for the current thread if one was not already allocated before this method is called, so to execute select statements that begin a transaction (such as `"select for update"`), execute DatasourcePool::beginTransaction() first to ensure that the connection is dedicated to the calling thread.

Parameters

  sql | The SQL command to execute on the server
  vargs | Include any values to be bound (using `%v` in the command string) or placeholder specifications (using `:`key_name in the command string) in order after the command string

Returns
  Normally returns a list (rows) of hash (where the keys are the column names of each row) or NOTHING if no rows are found for the query, however some DBI drivers allow any SQL statement to be executed through this method (not only select statements), in this case other data types can be returned

Example:
  *list<auto> list = db.vselectRows("select * from example_table where id = %v and type = %v", arg_list);

Note
  see the documentation for the DBI driver being used for additional possible exceptions

See also
  DatasourcePool::selectRows()