|
nothing | beginTransaction () |
| Manually grabs the transaction lock.
|
|
nothing | clearEventQueue () |
| Clears the queue object for DBI events on the datasource.
|
|
nothing | close () |
| Closes the connection to the database; if any actions are in progress on the database, the close call will block until the actions complete. If any errors are encountered, an exception is raised.
|
|
nothing | commit () |
| Commits the current transaction and releases the transaction lock.
|
|
| constructor (string driver, *string user, *string pass, *string db, *string encoding, *string host, *softint port, *hash< auto > options, *Qore::Thread::Queue queue, auto arg) |
| Creates the Datasource 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 Datasource 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 Datasource 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. holds the transaction lock), False if not.
|
|
*hash< auto > | describe (string sql,...) |
| Executes an SQL select statement on the server and returns a description of the result set as a hash.
|
|
| destructor () |
| Closes the datasource if it's open (if any operations are in progress, will block until the operations complete) and destroys the object.
|
|
auto | exec (string sql,...) |
| Grabs the transaction lock (if autocommit is disabled) 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) |
| Grabs the transaction lock (if autocommit is disabled) 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)
|
|
bool | getAutoCommit () |
| Returns the autocommit status for the object.
|
|
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 current connection.
|
|
*string | getDBEncoding () |
| Retrieves the database-specific charset set encoding for the current connection.
|
|
*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.
|
|
*string | getHostName () |
| Returns the hostname parameter as a string or NOTHING if none is set.
|
|
string | getOSCharset () |
| Returns the Qore character encoding name for the current connection as a string or "(unknown)" if none is set.
|
|
*string | getOSEncoding () |
| Returns the Qore character encoding name for the current connection 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.
|
|
int | getTransactionLockTimeout () |
| Retrieves the transaction lock timeout value as an integer in milliseconds.
|
|
*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, False if not.
|
|
nothing | open () |
| Opens a connection to the datasouce, using the connection parameters already set; an exception is thrown if any errors occur.
|
|
nothing | reset () |
| Closes and reopens the Datasource.
|
|
nothing | rollback () |
| Rolls the current transaction back and releases the transaction lock.
|
|
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)
|
|
*hash< 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)
|
|
nothing | setAutoCommit (bool ac=True) |
| Turns autocommit on or off for this object.
|
|
nothing | setDBCharset (string encoding) |
| Sets the database-specific character encoding name for the next connection to the server.
|
|
nothing | setDBEncoding (string encoding) |
| Sets the database-specific character encoding name for the next connection to the server.
|
|
nothing | setDBName (string db) |
| Sets the database name parameter for the time a connection to the server is established.
|
|
nothing | setEventQueue (Qore::Thread::Queue queue, auto arg) |
| Sets a queue object for DBI events on the datasource.
|
|
nothing | setHostName (string host) |
| Sets the hostname to use for the next connection to the server.
|
|
| setOption (string opt, auto val) |
| sets an option for the datasource
|
|
nothing | setPassword (string pass) |
| Sets the password parameter for the time a connection to the server is established.
|
|
nothing | setPort (softint port=0) |
| Sets the port number to use for the connection.
|
|
nothing | setTransactionLockTimeout (timeout timeout_ms=0) |
| Sets the transaction lock timeout value in milliseconds; set to 0 for no timeout.
|
|
nothing | setUserName (string user) |
| Sets the username parameter for the time a connection to the server is established.
|
|
int | transactionTid () |
| Returns the TID of the thread holding the transaction lock or -1 if it's not currently held.
|
|
auto | vexec (string sql, *softlist< auto > vargs) |
| Grabs the transaction lock (if autocommit is disabled) 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.
|
|
*hash< 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.
|
|
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.
|
|
| 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
|
|
This class provides the Qore interface to databases.
- Restrictions:
- Qore::PO_NO_DATABASE
- Overview
- This class provides the main direct interface to DBI drivers (along with the SQLStatement and DatasourcePool classes).
The Datasource class will attempt to load any DBI driver that is not currently loaded in the constructor. For connection pooling support, see the DatasourcePool class.
Datasource objects will implicitly call Datasource::open() if no connection has yet been established and a method is called requiring a connection to the database server. Therefore any method that requires communication with the database server can also throw any exception that the open method can throw.
Most Qore DBI drivers allow "select" queries to be executed through the Datasource::exec() method, and allow SQL commands (procedure calls, etc) to be executed through the Datasource::select() method, and some DBI drivers do not (depends on the underlying DB API). At any rate, the transaction lock is set when auto-commit is disabled and when the Datasource::exec() or Datasource::beginTransaction() methods are executed as documented above. Therefore executing a transaction relevant command through the Datasource::select() method while auto-commit mode is disabled and a transaction has not yet started will not result in the transaction lock being allocated to the current thread and therefore could cause transaction errors when sharing the Datasource object between multiple threads.
Only databases with an existing Qore DBI driver can be accessed through the Datasource class.
All Qore DBI drivers set new connections to use transaction isolation level "read committed"
.
The Datasource class provides high-level, per-connection locking on requests at a level above the DBI drivers to ensure that the communication between clients and servers is properly serialized.
Datasource objects also have a default character encoding; all requests to the server will be made in this encoding, and all responses will be returned in the given encoding. If no encoding is specifically given to the Datasource object, the Datasource object will use the Default Character Encoding.
- SQL Binding by Value and by Placeholder Overview
- All Datasource methods accepting SQL strings to execute understand a special syntax used in the query string to bind Qore data by value and to specify placeholders for output variables (for example, when executing a stored procedure or database function). Placeholder binding is DBI driver specific, but binding by value is supported with the same syntax in all drivers. Additionally, the
%d
numeric specifier is supported equally in all Qore DBI drivers.
Datasource Format Specifiers
Format Specification | Description |
%d | If any value other than NOTHING or NULL is given, then the value is converted to an integer and this value is substituted in the string at this position; if the value is NOTHING or NULL, then a literal "null" is substituted instead. |
%s | The argument is converted to a string and the string is inserted literally without any conversion or escape sequences in the string; this is useful for table or schema prefixes, etc |
%v | The argument is bound by value according to the DBI driver's implementation. |
- SQL Binding Details
- To bind Qore data values directly in a binary format in an SQL command, use
%v
in the command string, and include the value as an argument after the string. Binding by value allows the DBI driver to take care of formatting the data properly for use in the query with the database server. When binding by value, strings do not need to be quoted, date/time values do not need special formatting, binary objects (with BLOB columns, for example) can be used directly in queries, etc.
Here is an 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);
When using dynamic SQL, to insert a numeric value or a literal "null"
in a query, use %d
in the command string, and include the value as an argument after the string. If the value is NOTHING or NULL, a literal "null"
will be written to the string; otherwise the argument is converted to an arbitrary-precision number or integer value if necessary and written to the string. This is useful for working with DECIMAL
(NUMERIC
, NUMBER
) types in a database-independent way; for example PostgreSQL servers do not do type conversions to DECIMAL
types when a string, integer, or float is bound by value, therefore to ensure that integral decimal values can be used in a database-independent way (with "null"
substitution when no value is bound), a valid approach is to use the %d
code in the command string instead of %v
. However please note that %v
is normally preferred to keep the server-side statement cache a manageable size, in the previous example using the int(), float(), or number() functions to convert string values before binding with %v
may be better.
For binding placeholders for output variables, write a unique name in the string and prefix it with a colon (ex: ":code"
). In this case the method will return a hash of the output variables using the placeholder names as keys, but without the colon prefix. By default, a string type will be bound to the position. To bind other variable types to placeholder positions, include the type constant (see SQL Constants) as an argument after the command string. For BLOBs, use Binary, for CLOBs, use the string "clob" (constants will be provided in a future release). Not all DBI drivers require placeholder buffer specifications; see the documentation for the DBI driver in question for more information and examples regarding placeholder buffer specifications.
- Result Set Output Binding
- A result set can be returned in two ways depending on the placeholder buffer specification:
When using RESULTSET, the SQLStatement object created acquires the transaction lock even when used with a method that normally doesn't indicate that a transaction will be started such as select() or selectRows(), therefore the transaction lock must be released manually in such cases (just as with the normal usage of SQLStatement objects); see the following example for details.
- Result Set Output Binding Example
SQLStatement stmt = ds.select("begin open :rs for select * from my_table; end;", RESULTSET);
on_exit ds.rollback();
map process_row($1), stmt;
- Datasource Transaction Locks
- Datasource objects have an internal transaction lock which will be grabbed when the Datasource::exec(), Datasource::vexec() Datasource::execRaw(), or Datasource::beginTransaction() methods are executed and autocommit is not enabled. This enables a single datasource to be safely used for transaction management by several threads simultaneously. Note that an exception in a Datasource method that would acquire the lock (such as the Datasource::exec() method) when it's not already held, will have the effect that the transaction lock is not acquired.
Any thread attempting to do transaction-relevant actions on a Datasource with auto-commit disabled while a transaction is in progress by another thread will block until the thread currently executing a transaction executes the Datasource::commit() or Datasource::rollback() methods (or the Datasource is deleted, reset, or closed, in which case the lock is released and an exception is raised as well).
There is a timeout associated with the transaction lock; if a thread waits for the transaction lock for more than the timeout period, then an exception will be raised in the waiting thread. The timeout value can be read and changed with the Datasource::getTransactionLockTimeout() and Datasource::setTransactionLockTimeout() methods, respectively. The default transaction lock timeout value is 120 seconds.
Note that the SQLStatement class also grabs the transaction lock when executing if it is created using a Datasource object in the constructor; for more information see the SQLStatement class documentation.
- Thread Resource Handling
- The Datasource class manages the transaction lock as a thread resource; if the transaction is not released with a call to Datasource::commit() or Datasource::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 Datasource 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 Datasource 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