Qore Programming Language Reference Manual: Qore::SQL::AbstractDatasource Class Reference

Qore Programming Language Reference Manual 0.8.11

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
Qore::SQL::AbstractDatasource Class Referenceabstract

This class defines an abstract interface for database access, inherited by both the Datasource and DatasourcePool classes. More...

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

## Public Member Functions
abstract nothing | beginTransaction ()
| Manually signals the start of transaction management on the AbstractDatasource. More...
abstract nothing | commit ()
| Commits the current transaction and releases any thread resources associated with the transaction. More...
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. More...
abstract any | 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) More...
abstract any | 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) More...
abstract any | getClientVersion ()
| Retrieves the driver-specific client library version information. More...
abstract hash | getConfigHash ()
| Returns a datasource hash describing the configuration of the current object. More...
abstract string | getConfigString ()
| Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource() More...
abstract string | getDBEncoding ()
| Retrieves the database-specific charset set encoding for the object. More...
abstract *string | getDBName ()
| Returns the database name parameter as a string or NOTHING if none is set. More...
abstract string | getDriverName ()
| Returns the name of the driver used for the object. More...
abstract *string | getHostName ()
| Returns the hostname parameter as a string or NOTHING if none is set. More...
abstract *string | getOSEncoding ()
| Returns the Qore character encoding name for the object as a string or NOTHING if none is set. More...
abstract *string | getPassword ()
| Returns the password parameter as a string or NOTHING if none is set. More...
abstract *int | getPort ()
| Gets the port number that will be used for the next connection to the server. More...
abstract any | getServerVersion ()
| Returns the driver-specific server version data for the current connection. More...
abstract *string | getUserName ()
| Returns the username parameter as a string or NOTHING if none is set. More...
abstract bool | inTransaction ()
| Returns True if a transaction is currently in progress. More...
abstract nothing | rollback ()
| Rolls the current transaction back and releases any thread resources associated with the transaction. More...
abstract any | 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) More...
abstract any | selectRow (string sql,...)
| Executes an SQL select statement on the server and returns the first row as a hash (the column values) More...
abstract any | selectRows (string sql,...)
| Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values) More...
abstract any | vexec (string sql, *softlist 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. More...
abstract any | vselect (string sql, *softlist 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. More...
abstract any | vselectRow (string sql, *softlist 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. More...
abstract any | vselectRows (string sql, *softlist 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. More...

## Detailed Description

This class defines an abstract interface for database access, inherited by both the Datasource and DatasourcePool classes.

Restrictions:
  Qore::PO_NO_DATABASE

## Member Function Documentation

abstract nothing Qore::SQL::AbstractDatasource::beginTransaction | ( |  | ) |
| pure virtual

Manually signals the start of transaction management on the AbstractDatasource.

This method should be called when the AbstractDatasource object will be shared between more than 1 thread, and a transaction will be started with a AbstractDatasource::select() method or the like.

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

Example:
  $db.beginTransaction();

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract nothing Qore::SQL::AbstractDatasource::commit | ( |  | ) |
| pure virtual

Commits the current transaction and releases any thread resources associated with the transaction.

Example:
  $db.commit();

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

bool Qore::SQL::AbstractDatasource::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.

Note
  - this is reimplemented as Datasource::currentThreadInTransaction() and DatasourcePool::currentThreadInTransaction()
  - this method was added as a non-abstract method in Qore 0.8.10 to avoid breaking existing subclasses of AbstractDatasource

Since
  Qore 0.8.10

abstract any Qore::SQL::AbstractDatasource::exec | ( | string | sql,
|  |  | ...
| ) |  |
| pure virtual

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)

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:
  my int $rows = $db.exec("insert into table (varchar_col, timestamp_col, blob_col, numeric_col) values (%v, %v, %v, %d)", $string, now(), $binary, 100);

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::execRaw | ( | string | sql | ) |
| pure virtual

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))");

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::getClientVersion | ( |  | ) |
| pure virtual

Retrieves the driver-specific client library version information.

Returns
  the driver-specific client library version information

Example:
  my any $ver = $db.getClientVersion();

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract hash Qore::SQL::AbstractDatasource::getConfigHash | ( |  | ) |
| pure virtual

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

Example:
  my hash $h = $ds.getConfigHash();

Returns
  a datasource hash describing the configuration of the current object

Since
  Qore 0.8.8

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract string Qore::SQL::AbstractDatasource::getConfigString | ( |  | ) |
| pure virtual

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

Example:
  my 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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract string Qore::SQL::AbstractDatasource::getDBEncoding | ( |  | ) |
| pure virtual

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

Returns
  the database-specific charset set encoding for the object

Example:
  my string $enc = $db.getDBEncoding();

See Also
  AbstractDatasource::getOSEncoding();

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract *string Qore::SQL::AbstractDatasource::getDBName | ( |  | ) |
| pure virtual

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

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract string Qore::SQL::AbstractDatasource::getDriverName | ( |  | ) |
| pure virtual

Returns the name of the driver used for the object.

Returns
  the name of the driver used for the object

Example:
  my string $driver = $db.getDriverName();

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract *string Qore::SQL::AbstractDatasource::getHostName | ( |  | ) |
| pure virtual

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

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract *string Qore::SQL::AbstractDatasource::getOSEncoding | ( |  | ) |
| pure virtual

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

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract *string Qore::SQL::AbstractDatasource::getPassword | ( |  | ) |
| pure virtual

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

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract *int Qore::SQL::AbstractDatasource::getPort | ( |  | ) |
| pure virtual

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

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::getServerVersion | ( |  | ) |
| pure virtual

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

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

Example:
  my any $ver = $db.getServerVersion();

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract *string Qore::SQL::AbstractDatasource::getUserName | ( |  | ) |
| pure virtual

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

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract bool Qore::SQL::AbstractDatasource::inTransaction | ( |  | ) |
| pure virtual

Returns True if a transaction is currently in progress.

Returns
  True if a transaction is currently in progress

Example:
  my bool $b = $db.inTransaction();

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract nothing Qore::SQL::AbstractDatasource::rollback | ( |  | ) |
| pure virtual

Rolls the current transaction back and releases any thread resources associated with the transaction.

Example:
  $db.rollback();

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::select | ( | string | sql,
|  |  | ...
| ) |  |
| pure virtual

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

The usual 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 AbstractDatasource::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 AbstractDatasource::selectRows().

To execute select statements that begin a transaction (such as `"select for update"`), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one 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)

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

Note
  This method returns all the data available immediately; to process query data piecewise, use the SQLStatement class

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::selectRow | ( | string | sql,
|  |  | ...
| ) |  |
| pure virtual

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 AbstractDatasource::vselectRow().

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

To execute select statements that begin a transaction (such as `"select for update"`), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one 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:
  my *hash $h = $db.selectRow("select * from example_table where id = 1");

Exceptions

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

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::selectRows | ( | string | sql,
|  |  | ...
| ) |  |
| pure virtual

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 AbstractDatasource::select() method, therefore for larger amounts of data, it is recommended to use AbstractDatasource::select(). The usual return value of this method can be iterated with the ListHashIterator class.

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

To execute select statements that begin a transaction (such as `"select for update"`), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one 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:
  my *list $list = $db.selectRows("select * from example_table");

See Also
  AbstractDatasource::select()

Note
  This method returns all the data available immediately; to process query data piecewise, use the SQLStatement class

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::vexec | ( | string | sql,
|  | *softlist | vargs
| ) |  |
| pure virtual

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.

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

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:
  my int $rows = $db.vexec("insert into example_table value (%v, %v, %v)", $arg_list);

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::vselect | ( | string | sql,
|  | *softlist | vargs
| ) |  |
| pure virtual

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 usual 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`, etc) as documented in Binding by Value and Placeholder

To execute select statements that begin a transaction (such as `"select for update"`), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one 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

Example:
  my *hash $query = $db.vselect("select * from example_table where id = %v and name = %v", $arg_list);

See Also
  AbstractDatasource::select()

Note
  This method returns all the data available immediately; to process query data piecewise, use the SQLStatement class

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::vselectRow | ( | string | sql,
|  | *softlist | vargs
| ) |  |
| pure virtual

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 AbstractDatasource::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`, etc) as documented in Binding by Value and Placeholder

To execute select statements that begin a transaction (such as `"select for update"`), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one 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:
  my *hash $h = $db.vselectRow("select * from example_table where id = %v and type = %v", $arg_list);

See Also
  AbstractDatasource::selectRow()

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.

abstract any Qore::SQL::AbstractDatasource::vselectRows | ( | string | sql,
|  | *softlist | vargs
| ) |  |
| pure virtual

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 AbstractDatasource::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 AbstractDatasource::select() method, therefore for larger amounts of data, it is recommended to use AbstractDatasource::select().

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

To execute select statements that begin a transaction (such as `"select for update"`), execute AbstractDatasource::beginTransaction() first to signal that a transaction is starting; this is particularly important when the object is shared among more than one thread.

Parameters

  sql | The SQL command to execute
  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:
  my *list $list = $db.vselectRows("select * from example_table where id = %v and type = %v", $arg_list);

See Also
  AbstractDatasource::selectRows()

Note
  This method returns all the data available immediately; to process query data piecewise, use the SQLStatement class

Implemented in Qore::SQL::Datasource, and Qore::SQL::DatasourcePool.