4.17. SQL::DatasourcePool Class

Note: This class is not available with the PO_NO_DATABASE parse option.

The DatasourcePool class provides transparent per-thread, per-transaction Datasource connection pooling.

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.

4.17.1. DatasourcePool Connection Allocations

The following methods allocate a persistent connection to the calling thread: DatasourcePool::exec(), DatasourcePool::vexec(), and 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(), or DatasourcePool::beginTransaction().

Table 4.788. DatasourcePool Method Overview

Method

Except?

Description

DatasourcePool::constructor()

Y

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

DatasourcePool::destructor()

Y

Destroys the object.

DatasourcePool::copy()

Y

Throws an exception; currently DatasourcePool objects may not be copied.

DatasourcePool::commit()

Y

Commits the transaction and releases the connection to the pool.

DatasourcePool::rollback()

Y

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

DatasourcePool::exec()

Y

Executes SQL code on the DB connection and dedicates a connection to the calling thread.

DatasourcePool::vexec()

Y

Executes SQL code on the DB connection, taking a list for all bind arguments. Dedicates a connection to the calling thread.

DatasourcePool::select()

Y

Executes a select statement on the server and returns the results in a hash (column names) of lists (rows).

DatasourcePool::vselect()

Y

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

DatasourcePool::selectRow()

Y

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

DatasourcePool::vselectRow()

Y

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.

DatasourcePool::selectRows()

Y

Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values).

DatasourcePool::vselectRows()

Y

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.

DatasourcePool::beginTransaction()

Y

Manually allocates a persistent connection to the calling thread.

DatasourcePool::getUserName()

N

Returns the username parameter.

DatasourcePool::getPassword()

N

Returns the password parameter.

DatasourcePool::getDBName()

N

Returns the dbname parameter.

DatasourcePool::getDBCharset()

N

Returns the DBI driver specific charset name for the current connection.

DatasourcePool::getOSCharset()

N

Returns the Qore charset name for the current connection.

DatasourcePool::getHostName()

N

Returns the hostname parameter.

DatasourcePool::getPort()

N

Returns the port parameter.

DatasourcePool::getDriverName()

N

Returns the name of the database driver used for this object.

DatasourcePool::getServerVersion()

Y

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

DatasourcePool::getClientVersion()

N

Returns the driver-specific client library version data. Not implemented by all drivers.


4.17.2. DatasourcePool::constructor()

Synopsis

Creates a DatasourcePool object. The constructor requires the database driver name as the first argument, and normally the dbname. The port number is supplied as the final parameter because support for the port number as a connection parameter was added after this class was already present in Qore.

Usage
new DatasourcePool(driver_name, [username], [password], [dbname], [charset_name], [hostname], [min], [max], [port])
Example
# open a Datasource pool to a PostgreSQL database, username="user", password="pass", dbname="database"
# use "utf8" for the character encoding for the connection, hostname="localhost", port=5432
# minimum 5 connections (opened immediately), with a maximum of 20
$pool = new DatasourcePool(DSPGSQL, "user", "pass", "database", "utf8", "localhost", 5, 20, 5432);

Table 4.789. Arguments for DatasourcePool::constructor()

Argument

Type

Description

driver_name

String

The name of the DBI driver for the DatasourcePool. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver.

[username]

String

The user name for the new connection.

[password]

String

The password for the new connection.

[dbname]

String

The database name for the new connection.

[charset_name]

String

The database-specific name of the character encoding to use for the new connection. 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.

[hostname]

String

The host name for the new connection (not used by some DBI drivers).

[min]

Integer

The minimum number of connections to open immediately (default=5).

[max]

Integer

The maximum number of connections to open (default=20).

[port]

Integer

The port number to use for the connection.


Table 4.790. Return Values for DatasourcePool::constructor()

Return Type

Description

Object

The DatasourcePool object created


Table 4.791. Exceptions Thrown by DatasourcePool::constructor()

err

desc

DATASOURCEPOOL-PARAM-EEROR

Missing DBI driver identifier as first argument, negative number of connections specified, or max < min.

DATASOURCEPOOL-UNSUPPORTED-DATABASE

Could not load a driver for the database identified.


4.17.3. DatasourcePool::destructor()

Synopsis

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

Usage
delete lvalue
Example
delete $pool;

Table 4.792. Exceptions Thrown by DatasourcePool::destructor()

err

desc

DATASOURCEPOOL-ERROR

The destructor was called while a transaction was still in progress.


4.17.4. DatasourcePool::copy()

Synopsis

Thows an exception; DatasourcePool objects cannot be copied at the moment.

4.17.5. DatasourcePool::beginTransaction()

Synopsis

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 vselect*, etc).

Usage
DatasourcePool::beginTransaction()
Example
$pool.beginTransaction();

Table 4.793. Arguments for DatasourcePool::beginTransaction()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.794. Return Values for DatasourcePool::beginTransaction()

Return Type

Description

n/a

This method return no value.


4.17.6. DatasourcePool::commit()

Synopsis

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

Usage
DatasourcePool::commit()
Example
$pool.commit();

Table 4.795. Arguments for DatasourcePool::commit()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.796. Return Values for DatasourcePool::commit()

Return Type

Description

Integer

0 for success, -1 for not open.


Table 4.797. Exceptions Thrown by DatasourcePool::commit()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.7. DatasourcePool::rollback()

Synopsis

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

Usage
DatasourcePool::rollback()
Example
$pool.rollback();

Table 4.798. Arguments for DatasourcePool::rollback()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.799. Return Values for DatasourcePool::rollback()

Return Type

Description

Integer

0 for success, -1 for failure (driver-specific).


Table 4.800. Exceptions Thrown by DatasourcePool::rollback()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.8. DatasourcePool::exec()

Synopsis

Allocates a persistent connection to the calling thread, 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 takes a special syntax for binding values and placeholders; see the Datasource::exec() method for more information.

Usage
DatasourcePool::exec(sql_command, [arg1, ...])
Example
$rows = $pool.exec("insert into table (varchar_col, timestamp_col, blob_col, numeric_col) values (%v, %v, %v, %d)", $string, now(), $binary, 100);

Table 4.801. Arguments for DatasourcePool::exec()

Argument

Type

Description

sql_command

String

The SQL command to execute on the server.

[arg1, ...]

Any

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.


Table 4.802. Return Values for DatasourcePool::exec()

Return Type

Description

Integer or Hash

For commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, a row count is returned.


Table 4.803. Exceptions Thrown by DatasourcePool::exec()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.9. DatasourcePool::vexec()

Synopsis

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

This method allocates a persistent connection from the pool to the calling thread.

Usage
DatasourcePool::vexec(sql_command, [list])
Example
$rows = $pool.vexec("insert into example_table value (%v, %v, %v)", $arg_list);

Table 4.804. Arguments for DatasourcePool::vexec()

Argument

Type

Description

sql_command

String

The SQL command to execute on the server.

[list]

List

Include any values to be bound (using %v in the command string) or placeholder specifications (using :<key_name> in the command string) in a single list in order after the command string.


Table 4.805. Return Values for DatasourcePool::vexec()

Return Type

Description

Integer or Hash

For commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, a row count is returned.


Table 4.806. Exceptions Thrown by DatasourcePool::vexec()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.10. DatasourcePool::select()

Synopsis

Executes an SQL select statement on the server and returns the result as a hash (column names) of lists (rows). See Datasource::select() for more information.

Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), or DatasourcePool::beginTransaction().

Usage
DatasourcePool::select(select_statement, [arg1, ...])
Example
# bind a string and a date/time value by value in a query
$query = $pool.select("select * from table where varchar_column = %v and timestamp_column > %v", $string, 2007-10-11T15:31:26.289);

Table 4.807. Arguments for DatasourcePool::select()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[arg1, ...]

Any

Arguments to bind by value in %v positions in the SQL string.


Table 4.808. Return Values for DatasourcePool::select()

Return Type

Description

Hash

Returns a hash (the keys are the column names) of lists (each hash key's value is a list giving the row data).


Table 4.809. Exceptions Thrown by DatasourcePool::select()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.11. DatasourcePool::vselect()

Synopsis

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

Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), or DatasourcePool::beginTransaction().

Usage
DatasourcePool::vselect(select_statement, [list])
Example
$query = $pool.vselect("select * from example_table where id = %v and name = %v", $arg_list);

Table 4.810. Arguments for DatasourcePool::vselect()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[arg1, ...]

List

A list of arguments to bind by value in %v positions in the SQL string.


Table 4.811. Return Values for DatasourcePool::vselect()

Return Type

Description

Hash

Returns a hash (the keys are the column names) of lists (each hash key's value is a list giving the row data).


Table 4.812. Exceptions Thrown by DatasourcePool::vselect()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.12. DatasourcePool::selectRow()

Synopsis

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 all but the first row are discarded. For a similar method taking a list for all bind arguments, see DatasourcePool::vselectRow().

This method also accepts all bind parameters (%d, %v, etc) as documented in Datasource Binding.

Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), or DatasourcePool::beginTransaction().

Usage
DatasourcePool::selectRow(select_statement, [arg1, ...])
Example
$list = $pool.selectRow("select * from example_table");

Table 4.813. Arguments for DatasourcePool::selectRow()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[arg1, ...]

Any

Arguments to bind by value in %v positions in the SQL string.


Table 4.814. Return Values for DatasourcePool::selectRow()

Return Type

Description

Hash or NOTHING

Returns a hash (column values) of the first row, NOTHING if no rows are returned.


Table 4.815. Exceptions Thrown by DatasourcePool::selectRow()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.13. DatasourcePool::vselectRow()

Synopsis

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

Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), or DatasourcePool::beginTransaction().

Usage
DatasourcePool::vselectRow(select_statement, [list])
Example
$list = $pool.vselectRow("select * from example_table where id = %v and name = %v", $arg_list);

Table 4.816. Arguments for DatasourcePool::vselectRow()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[list]

List

A list of arguments to bind by value in %v positions in the SQL string.


Table 4.817. Return Values for DatasourcePool::vselectRow()

Return Type

Description

Hash or NOTHING

Returns a hash of the first row (column values). If no rows are returned by the query, then NOTHING is returned.


4.17.14. DatasourcePool::selectRows()

Synopsis

Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values). This format is not as 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, etc) as documented in Datasource Binding.

Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), or DatasourcePool::beginTransaction().

Usage
DatasourcePool::selectRows(select_statement, [arg1, ...])
Example
$list = $pool.selectRows("select * from example_table");

Table 4.818. Arguments for DatasourcePool::selectRows()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[arg1, ...]

Any

Arguments to bind by value in %v positions in the SQL string.


Table 4.819. Return Values for DatasourcePool::selectRows()

Return Type

Description

List

Returns a list (the rows returned) of hashes (column values).


Table 4.820. Exceptions Thrown by DatasourcePool::selectRows()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.15. DatasourcePool::vselectRows()

Synopsis

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

Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), or DatasourcePool::beginTransaction().

Usage
DatasourcePool::vselectRows(select_statement, [list])
Example
$list = $pool.vselectRows("select * from example_table where id = %v and name = %v", $arg_list);

Table 4.821. Arguments for DatasourcePool::vselectRows()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[list]

List

A list of arguments to bind by value in %v positions in the SQL string.


Table 4.822. Return Values for DatasourcePool::vselectRows()

Return Type

Description

List

Returns a list (the rows returned) of hashes (column values).


Table 4.823. Exceptions Thrown by DatasourcePool::vselectRows()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.17.16. DatasourcePool::getUserName()

Synopsis

Retrieves the username parameter for all connections in this pool.

Usage
DatasourcePool::getUserName()
Example
$str = $pool.getUserName();

Table 4.824. Arguments for DatasourcePool::getUserName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.825. Return Values for DatasourcePool::getUserName()

Return Type

Description

String

The username connection parameter.


4.17.17. DatasourcePool::getPassword()

Synopsis

Retrieves the password connection parameter.

Usage
DatasourcePool::getPassword()
Example
$str = $pool.getPassword();

Table 4.826. Arguments for DatasourcePool::getPassword()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.827. Return Values for DatasourcePool::getPassword()

Return Type

Description

String

Retrieves the password connection parameter.


4.17.18. DatasourcePool::getDBName()

Synopsis

Retrieves the dbname connection parameter.

Usage
DatasourcePool::getDBName()
Example
$str = $pool.getDBName();

Table 4.828. Arguments for DatasourcePool::getDBName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.829. Return Values for DatasourcePool::getDBName()

Return Type

Description

String

Retrieves the password connection parameter.


4.17.19. DatasourcePool::getDBCharset()

Synopsis

Retrieves the database-specific charset set encoding for the current connection.

Usage
DatasourcePool::getDBCharset()
Example
$str = $pool.getDBCharset();

Table 4.830. Arguments for DatasourcePool::getDBCharset()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.831. Return Values for DatasourcePool::getDBCharset()

Return Type

Description

String

Retrieves the database-specific charset set encoding for the current connection.


4.17.20. DatasourcePool::getOSCharset()

Synopsis

Retrieves the Qore charset set encoding for the current connection.

Usage
DatasourcePool::getOSCharset()
Example
$str = $pool.getOSCharset();

Table 4.832. Arguments for DatasourcePool::getOSCharset()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.833. Return Values for DatasourcePool::getOSCharset()

Return Type

Description

String

Retrieves the Qore charset set encoding for the current connection.


4.17.21. DatasourcePool::getHostName()

Synopsis

Retrieves the hostname connection parameter.

Usage
DatasourcePool::getHostName()
Example
$str = $pool.getHostName();

Table 4.834. Arguments for DatasourcePool::getHostName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.835. Return Values for DatasourcePool::getHostName()

Return Type

Description

String

Retrieves the hostname connection parameter.


4.17.22. DatasourcePool::getPort()

Synopsis

Retrieves the port connection parameter.

Usage
DatasourcePool::getPort()
Example
$port = $db.getPort();

Table 4.836. Arguments for DatasourcePool::getPort()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.837. Return Values for DatasourcePool::getPort()

Return Type

Description

Integer or NOTHING

Retrieves the port connection parameter or no value if no port is set.


4.17.23. DatasourcePool::getDriverName()

Synopsis

Returns the name of the DBI driver used for this object.

Usage
DatasourcePool::getDriverName()
Example
$name = $pool.getDriverName();

Table 4.838. Arguments for DatasourcePool::getDriverName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.839. Return Values for DatasourcePool::getDriverName()

Return Type

Description

String

The name of the database driver used for this object.


4.17.24. DatasourcePool::getServerVersion()

Synopsis

Retrieves the driver-specific server version information for the current connection.

Usage
DatasourcePool::getServerVersion()
Example
$data = $pool.getServerVersion();

Table 4.840. Arguments for DatasourcePool::getServerVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.841. Return Values for DatasourcePool::getServerVersion()

Return Type

Description

Driver-Specific

See the documentation for the DBI driver used for the connection.


4.17.25. DatasourcePool::getClientVersion()

Synopsis

Retrieves the driver-specific client library version information. Not implemented for all drivers.

Usage
DatasourcePool::getClientVersion()
Example
$data = $pool.getClientVersion();

Table 4.842. Arguments for DatasourcePool::getClientVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.843. Return Values for DatasourcePool::getClientVersion()

Return Type

Description

Driver-Specific

See the documentation for the DBI driver used for the connection.