Qore::SQL::Datasource Class Reference

This class provides the Qore interface to databases. More...

#include <QC_Datasource.dox.h>

Inheritance diagram for Qore::SQL::Datasource:

Public Member Methods
nothing	beginTransaction ()
	Manually grabs the transaction lock. More...
nothing	clearEventQueue ()
	Clears the queue object for DBI events on the datasource. More...
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. More...
nothing	commit ()
	Commits the current transaction and releases the transaction lock. More...
	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. More...
	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() More...
	constructor (hash< auto > opts, *Qore::Thread::Queue queue, auto arg)
	Creates a Datasource object from a hash argument giving parameters for the constructor. More...
	copy ()
	Creates a new Datasource object with the same driver as the original and copies of all the connection parameters. More...
bool	currentThreadInTransaction ()
	Returns True if the current thread is in a transaction (i.e. holds the transaction lock), False if not. More...
*hash< auto >	describe (string sql,...)
	Executes an SQL select statement on the server and returns a description of the result set as a hash. More...
	destructor ()
	Closes the datasource if it's open (if any operations are in progress, will block until the operations complete) and destroys the object. More...
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). More...
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) More...
bool	getAutoCommit ()
	Returns the autocommit status for the object. More...
int	getCapabilities ()
	Returns an integer bitfield of DBI driver capabilities. More...
list< auto >	getCapabilityList ()
	Returns a list of strings giving the capabilities of the current DBI driver. More...
auto	getClientVersion ()
	Retrieves the driver-specific client library version information; this method may not be implemented for all drivers. More...
hash< auto >	getConfigHash ()
	Returns a datasource hash describing the configuration of the current object. More...
string	getConfigString ()
	Returns a string giving the configuration of the current object in a format that can be parsed by parse_datasource() More...
*string	getDBCharset ()
	Retrieves the database-specific charset set encoding for the current connection. More...
*string	getDBEncoding ()
	Retrieves the database-specific charset set encoding for the current connection. More...
*string	getDBName ()
	Returns the database name parameter as a string or NOTHING if none is set. More...
string	getDriverName ()
	Returns the name of the driver used for the object. More...
string	getDriverRealName ()
	Returns the real DB driver name if supported by the driver, otherwise the Qore driver name. More...
*string	getHostName ()
	Returns the hostname parameter as a string or NOTHING if none is set. More...
string	getOSCharset ()
	Returns the Qore character encoding name for the current connection as a string or "(unknown)" if none is set. More...
*string	getOSEncoding ()
	Returns the Qore character encoding name for the current connection as a string or NOTHING if none is set. More...
auto	getOption (string opt)
	Returns the current value for the given option. More...
hash< auto >	getOptionHash ()
	returns the valid options for the driver associated with the Datasource with descriptions and current values for the current Datasource object More...
*string	getPassword ()
	Returns the password parameter as a string or NOTHING if none is set. More...
*int	getPort ()
	Gets the port number that will be used for the next connection to the server. More...
AbstractSQLStatement	getSQLStatement ()
	Returns an AbstractSQLStatement object based on the current database connection object. More...
auto	getServerVersion ()
	Returns the driver-specific server version data for the current connection. More...
int	getTransactionLockTimeout ()
	Retrieves the transaction lock timeout value as an integer in milliseconds. More...
*string	getUserName ()
	Returns the username parameter as a string or NOTHING if none is set. More...
bool	inTransaction ()
	Returns True if a transaction is currently in progress, False if not. More...
nothing	open ()
	Opens a connection to the datasouce, using the connection parameters already set; an exception is thrown if any errors occur. More...
nothing	reset ()
	Closes and reopens the Datasource. More...
nothing	rollback ()
	Rolls the current transaction back and releases the transaction lock. More...
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) More...
*hash< auto >	selectRow (string sql,...)
	Executes an SQL select statement on the server and returns the first row as a hash (the column values) More...
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) More...
nothing	setAutoCommit (bool ac=True)
	Turns autocommit on or off for this object. More...
nothing	setDBCharset (string encoding)
	Sets the database-specific character encoding name for the next connection to the server. More...
nothing	setDBEncoding (string encoding)
	Sets the database-specific character encoding name for the next connection to the server. More...
nothing	setDBName (string db)
	Sets the database name parameter for the time a connection to the server is established. More...
nothing	setEventQueue (Qore::Thread::Queue queue, auto arg)
	Sets a queue object for DBI events on the datasource. More...
nothing	setHostName (string host)
	Sets the hostname to use for the next connection to the server. More...
	setOption (string opt, auto val)
	sets an option for the datasource More...
nothing	setPassword (string pass)
	Sets the password parameter for the time a connection to the server is established. More...
nothing	setPort (softint port=0)
	Sets the port number to use for the connection. More...
nothing	setTransactionLockTimeout (timeout timeout_ms=0)
	Sets the transaction lock timeout value in milliseconds; set to 0 for no timeout. More...
nothing	setUserName (string user)
	Sets the username parameter for the time a connection to the server is established. More...
int	transactionTid ()
	Returns the TID of the thread holding the transaction lock or -1 if it's not currently held. More...
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. More...
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. More...
*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. More...
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. More...
Public Member Methods inherited from Qore::SQL::AbstractDatasource
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 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) More...
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) More...
abstract auto	getClientVersion ()
	Retrieves the driver-specific client library version information. More...
abstract hash< auto >	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...
string	getDriverRealName ()
	Returns the real DB driver name if supported by the driver, otherwise the Qore driver name. 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...
auto	getOption (string opt)
	Returns the current value for the given option. More...
hash< auto >	getOptionHash ()
	Returns the valid options for the driver associated with the AbstractDatasource with descriptions and current values for the current AbstractDatasource object. 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...
AbstractSQLStatement	getSQLStatement ()
	Returns an AbstractSQLStatement object based on the current database connection object. More...
abstract auto	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 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) More...
abstract auto	selectRow (string sql,...)
	Executes an SQL select statement on the server and returns the first row as a hash (the column values) More...
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) More...
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. More...
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. More...
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. More...
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. More...
Public Member Methods 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)
	converts the object to binary data representing the object More...
binary	serialize ()
	converts the object to binary data representing the object More...
hash< SerializationInfo >	serializeToData ()
	converts the object to a serialization hash representing the object More...

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

Detailed Description

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:

• Hash: (default for drivers that do not require placeholder buffer specifications): returns the entire result set as data
• RESULTSET: (for drivers that support Qore::SQL::DBI_CAP_HAS_RESULTSET_OUTPUT): returns an SQLStatement representing the result set. This option allows a large result set to be returned in smaller pieces using the SQLStatement API if desired.

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

# example of a result set output variable with Oracle
SQLStatement stmt = ds.select("begin open :rs for select * from my_table; end;", RESULTSET);
# we have to release the transaction when done
on_exit ds.rollback();
# iterate through the rows of the result set
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

Member Function Documentation

beginTransaction()

nothing Qore::SQL::Datasource::beginTransaction ( )

virtual

Manually grabs the transaction lock.

This method should be called when the Datasource object will be shared between more than 1 thread, and a transaction will be started with a Datasource::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.

It is an error to call this method when autocommit is enabled for the Datasource.

Example:

db.beginTransaction();

Exceptions

AUTOCOMMIT-ERROR	Cannot start a transaction when autocommit is enabled
TRANSACTION-LOCK-TIMEOUT	Timeout trying to acquire the transaction lock

Implements Qore::SQL::AbstractDatasource.

clearEventQueue()

nothing Qore::SQL::Datasource::clearEventQueue

(

)

Clears the queue object for DBI events on the datasource.

Since

Qore 0.8.9

close()

nothing Qore::SQL::Datasource::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.

Example:

db.close();

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

commit()

nothing Qore::SQL::Datasource::commit ( )

virtual

Commits the current transaction and releases the transaction lock.

Example:

db.commit();

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

Implements Qore::SQL::AbstractDatasource.

constructor() [1/3]

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

Creates a Datasource 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. Also see Datasource::setUserName() for a method that allows this parameter to be set after the constructor pass: (*string) The password for the new connection. Also see Datasource::setPassword() for a method that allows this parameter to be set after the constructor db: (*string) The database name for the new connection. Also see Datasource::setDBName() for a method that allows this parameter to be set after the constructor charset: (*string) 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 for the Qore process will be used instead host: (*string) The host name for the new connection. Also see Datasource::setHostName() for a method that allows this parameter to be set after the constructor port: (softint) The port number for the new connection. Also see Datasource::setPort() for a method that allows this parameter to be set after the constructor. If this key is present and is 0 then an exception will be raised. options: (*hash) Any options for the new connection
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);

Exceptions

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

constructor() [2/3]

Qore::SQL::Datasource::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()

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:

Datasource 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::Datasource::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.

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.
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.
options	Any options for the database driver for the new connection
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(DSPGSQL, "user", "pass", "database", "utf8", "localhost", 5432);

Exceptions

DATASOURCE-UNSUPPORTED-DATABASE	DBI driver cannot be loaded
DATASOURCE-CONSTRUCTOR-ERROR	port value is <= 0
DBI-OPTION-ERROR	unknown or unsupported option passed to driver

copy()

Qore::SQL::Datasource::copy

(

)

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

Example:

Datasource new_ds = ds.copy();

currentThreadInTransaction()

bool Qore::SQL::Datasource::currentThreadInTransaction

(

)

Returns True if the current thread is in a transaction (i.e. holds the transaction lock), False if not.

Returns

True if the current thread is in a transaction (i.e. holds the transaction lock), False if not

Code Flags:

CONSTANT

Example:

bool b = db.currentThreadInTransaction();

See also

Datasource::transactionTid()

Since

Qore 0.8.7

describe()

*hash< auto > Qore::SQL::Datasource::describe	(	string	sql,
			...
	)

Executes an SQL select statement on the server and returns a description of the result set as a hash.

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 transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"), execute Datasource::beginTransaction() first to ensure that the transaction lock 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

a hash describing the result set with the following keys:

• name: the name of the column
• type: a string giving the type of the column
• maxsize: an integer giving the column size
• native_type: a string giving the native column type
• internal_id: an integer giving the native column type code

Example:

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

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

Since

Qore 0.8.9

destructor()

Qore::SQL::Datasource::destructor

(

)

Closes the datasource if it's open (if any operations are in progress, will block until the operations complete) and destroys the object.

Example:

delete db;

Exceptions

DATASOURCE-TRANSACTION-EXCEPTION

The Datasource was destroyed while a transaction was still in progress; the transaction will be automatically rolled back

exec()

auto Qore::SQL::Datasource::exec ( string  sql,   ...  )

virtual

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).

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

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

Implements Qore::SQL::AbstractDatasource.

execRaw()

auto Qore::SQL::Datasource::execRaw ( string  sql )

virtual

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)

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

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

Implements Qore::SQL::AbstractDatasource.

getAutoCommit()

bool Qore::SQL::Datasource::getAutoCommit

(

)

Returns the autocommit status for the object.

Returns

the autocommit status for the object

Code Flags:

CONSTANT

Example:

bool b = db.getAutoCommit();

getCapabilities()

int Qore::SQL::Datasource::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 = db.getCapabilities();
if (!(caps & DBI_CAP_TRANSACTION_MANAGEMENT))
    throw "DATASOURCE-ERROR", sprintf("DBI driver %y does not support transaction management", db.getDriverName());

getCapabilityList()

list< auto > Qore::SQL::Datasource::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);

getClientVersion()

auto Qore::SQL::Datasource::getClientVersion ( )

virtual

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

Implements Qore::SQL::AbstractDatasource.

getConfigHash()

hash< auto > Qore::SQL::Datasource::getConfigHash ( )

virtual

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

This method does not require a connection to the server. The return value may differ for connected and unconnected objects, as the DB driver may set default option values when the datasource is connected.

Since

Qore 0.8.8

Implements Qore::SQL::AbstractDatasource.

getConfigString()

string Qore::SQL::Datasource::getConfigString ( )

virtual

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()

This method does not require a connection to the server. The return value may differ for connected and unconnected objects, as the DB driver may set default option values when the datasource is connected.

Since

Qore 0.8.8

Implements Qore::SQL::AbstractDatasource.

getDBCharset()

*string Qore::SQL::Datasource::getDBCharset

(

)

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

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

Returns

the database-specific charset set encoding for the current connection

Code Flags:

CONSTANT

Example:

*string enc = db.getDBCharset();

getDBEncoding()

*string Qore::SQL::Datasource::getDBEncoding ( )

virtual

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

Returns

the database-specific charset set encoding for the current connection

Code Flags:

CONSTANT

Example:

*string enc = db.getDBEncoding();

See also

Datasource::getOSEncoding();

Implements Qore::SQL::AbstractDatasource.

getDBName()

*string Qore::SQL::Datasource::getDBName ( )

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

Code Flags:

CONSTANT

Example:

*string db = db.getDBName();

Implements Qore::SQL::AbstractDatasource.

getDriverName()

string Qore::SQL::Datasource::getDriverName ( )

virtual

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()

Implements Qore::SQL::AbstractDatasource.

getDriverRealName()

string Qore::SQL::Datasource::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:

CONSTANT

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()

Since

Qore 1.14

getHostName()

*string Qore::SQL::Datasource::getHostName ( )

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

Code Flags:

CONSTANT

Example:

*string host = db.getHostName();

Implements Qore::SQL::AbstractDatasource.

getOption()

auto Qore::SQL::Datasource::getOption

(

string

opt

)

Returns the current value for the given option.

Code Flags:

RET_VALUE_ONLY

Parameters

opt	the option to get

Note

in order to ensure atomicity when dealing with Datasource options, the transaction lock is acquired before executing this method if it was not already owned by the calling thread

Exceptions

DBI-OPTION-ERROR	unknown or unsupported option passed to driver
TRANSACTION-LOCK-TIMEOUT	Timeout trying to acquire the transaction lock

Since

Qore 0.8.6

getOptionHash()

hash< auto > Qore::SQL::Datasource::getOptionHash

(

)

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

Code Flags:

RET_VALUE_ONLY

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

Note

in order to ensure atomicity when dealing with Datasource options, the transaction lock is acquired before executing this method if it was not already owned by the calling thread

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Since

Qore 0.8.6

getOSCharset()

string Qore::SQL::Datasource::getOSCharset

(

)

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

Returns

the Qore character encoding name for the current connection as a string or "(unknown)" if none is set

Code Flags:

CONSTANT

Example:

string enc = db.getOSCharset();

See also

Datasource::getOSEncoding()

getOSEncoding()

*string Qore::SQL::Datasource::getOSEncoding ( )

virtual

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

Returns

the Qore character encoding for the current connection as a string or NOTHING if none is set

Code Flags:

CONSTANT

Example:

*string enc = db.getOSEncoding();

Implements Qore::SQL::AbstractDatasource.

getPassword()

*string Qore::SQL::Datasource::getPassword ( )

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

Code Flags:

CONSTANT

Example:

*string pass = db.getPassword();

Implements Qore::SQL::AbstractDatasource.

getPort()

*int Qore::SQL::Datasource::getPort ( )

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

Code Flags:

CONSTANT

Example:

*int port = db.getPort();

Implements Qore::SQL::AbstractDatasource.

getServerVersion()

auto Qore::SQL::Datasource::getServerVersion ( )

virtual

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

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

Implements Qore::SQL::AbstractDatasource.

getSQLStatement()

AbstractSQLStatement Qore::SQL::Datasource::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

getTransactionLockTimeout()

int Qore::SQL::Datasource::getTransactionLockTimeout

(

)

Retrieves the transaction lock timeout value as an integer in milliseconds.

Returns

the transaction lock timeout value as an integer in milliseconds

Code Flags:

CONSTANT

Example:

int to_ms = db.getTransactionLockTimeout();

getUserName()

*string Qore::SQL::Datasource::getUserName ( )

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

Code Flags:

CONSTANT

Example:

*string user = db.getUserName();

Implements Qore::SQL::AbstractDatasource.

inTransaction()

bool Qore::SQL::Datasource::inTransaction ( )

virtual

Returns True if a transaction is currently in progress, False if not.

Returns

True if a transaction is currently in progress, False if not

Code Flags:

CONSTANT

Example:

bool b = db.inTransaction();

Implements Qore::SQL::AbstractDatasource.

open()

nothing Qore::SQL::Datasource::open

(

)

Opens a connection to the datasouce, using the connection parameters already set; an exception is thrown if any errors occur.

If the connection is already open, then no action is taken.

Example:

db.open();

Note

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

See also

Datasource::reset()

reset()

nothing Qore::SQL::Datasource::reset

(

)

Closes and reopens the Datasource.

Example:

db.reset();

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

rollback()

nothing Qore::SQL::Datasource::rollback ( )

virtual

Rolls the current transaction back and releases the transaction lock.

Example:

db.rollback();

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

Implements Qore::SQL::AbstractDatasource.

select()

auto Qore::SQL::Datasource::select ( string  sql,   ...  )

virtual

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 transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"), execute Datasource::beginTransaction() first to ensure that the transaction lock 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");

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

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

• Datasource::vselect()
• <hash>::contextIterator()
• context Statements

Implements Qore::SQL::AbstractDatasource.

selectRow()

*hash< auto > Qore::SQL::Datasource::selectRow ( string  sql,   ...  )

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 Datasource::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 transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"), execute Datasource::beginTransaction() first to ensure that the transaction lock 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 row data or NOTHING if no row is found for the query when executed with an SQL select statement

Example:

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

Exceptions

TRANSACTION-LOCK-TIMEOUT	Timeout trying to acquire the transaction lock
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

Implements Qore::SQL::AbstractDatasource.

selectRows()

auto Qore::SQL::Datasource::selectRows ( string  sql,   ...  )

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 Datasource::select() method, therefore for larger amounts of data, it is recommended to use Datasource::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 transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"), execute Datasource::beginTransaction() first to ensure that the transaction lock 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");

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

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

Datasource::select()

Implements Qore::SQL::AbstractDatasource.

setAutoCommit()

nothing Qore::SQL::Datasource::setAutoCommit

(

bool

ac = True

)

Turns autocommit on or off for this object.

Parameters

ac	True to turn on autocommit (a commit will be executed after every SQL call to the server), False to turn off autocommit (commits must be manually triggered)

Example:

db.setAutoCommit(False);

setDBCharset()

nothing Qore::SQL::Datasource::setDBCharset

(

string

encoding

)

Sets the database-specific character encoding name for the next connection to the server.

This is a method synonym for the Datasource::setDBEncoding() method, kept for backwards-compatibility.

Invalid character encoding names will cause an exception to be thrown when the connection is opened.

Parameters

encoding

the database-specific character encoding name for the next connection to the server

Example:

db.setDBCharset(encoding);

setDBEncoding()

nothing Qore::SQL::Datasource::setDBEncoding

(

string

encoding

)

Sets the database-specific character encoding name for the next connection to the server.

Invalid character encoding names will cause an exception to be thrown when the connection is opened.

Parameters

encoding

the database-specific character encoding name for the next connection to the server

Example:

db.setDBEncoding(encoding);

setDBName()

nothing Qore::SQL::Datasource::setDBName

(

string

db

)

Sets the database name parameter for the time a connection to the server is established.

Invalid database names will cause an exception to be thrown when the connection is opened

Parameters

db	the database name parameter for the time a connection to the server is established

Example:

db.setDBName(db);

setEventQueue()

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

Sets a queue object for DBI events on the datasource.

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

setHostName()

nothing Qore::SQL::Datasource::setHostName

(

string

host

)

Sets the hostname to use for the next connection to the server.

Invalid hostnames will cause an exception to be thrown when the connection is opened.

Parameters

host	the hostname to use for the next connection to the server

Example:

db.setHostName(host);

setOption()

Qore::SQL::Datasource::setOption	(	string	opt,
		auto	val
	)

sets an option for the datasource

Parameters

opt	the option to set
val	the value to set

Note

in order to ensure atomicity when dealing with Datasource options, the transaction lock is acquired before executing this method if it was not already owned by the calling thread

Exceptions

DBI-OPTION-ERROR	unknown or unsupported option passed to driver
DATASOURCE-ERROR	the datasource must be open for this call
TRANSACTION-LOCK-TIMEOUT	Timeout trying to acquire the transaction lock

Since

Qore 0.8.6

setPassword()

nothing Qore::SQL::Datasource::setPassword

(

string

pass

)

Sets the password parameter for the time a connection to the server is established.

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

Parameters

pass	the password parameter for the time a connection to the server is established

Example:

db.setPassword(pass);

setPort()

nothing Qore::SQL::Datasource::setPort

(

softint

port = 0

)

Sets the port number to use for the connection.

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

Parameters

port	the port number to use for the connection

Example:

db.setPort(port);

setTransactionLockTimeout()

nothing Qore::SQL::Datasource::setTransactionLockTimeout

(

timeout

timeout_ms = 0

)

Sets the transaction lock timeout value in milliseconds; set to 0 for no timeout.

Parameters

timeout_ms

the transaction lock timeout value in milliseconds; set to 0 for no timeout. Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms for 2.5 seconds).

Example:

db.setTransactionLockTimeout(4s);

setUserName()

nothing Qore::SQL::Datasource::setUserName

(

string

user

)

Sets the username parameter for the time a connection to the server is established.

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

Parameters

user	the username parameter for the time a connection to the server is established

Example:

db.setUserName(user);

transactionTid()

int Qore::SQL::Datasource::transactionTid

(

)

Returns the TID of the thread holding the transaction lock or -1 if it's not currently held.

If the Datasource object is used in a multithreaded context and if the transaction lock is not held by the current thread, then the transaction lock status could change at any time.

Returns

the TID of the thread holding the transaction lock or -1 if it's not currently held

Code Flags:

CONSTANT

Example:

int tid = db.transactionTid();

See also

Datasource::currentThreadInTransaction()

Since

Qore 0.8.7

vexec()

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

virtual

Grabs the transaction lock (if autocommit is disabled) and executes SQL code on the DB connection, taking a list for all bind arguments.

Same as Datasource::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);

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

Implements Qore::SQL::AbstractDatasource.

vselect()

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

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 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 transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"), execute Datasource::beginTransaction() first to ensure that the transaction lock 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");

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

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

• Datasource::select()
• <hash>::contextIterator()
• context Statements

Implements Qore::SQL::AbstractDatasource.

vselectRow()

*hash< auto > Qore::SQL::Datasource::vselectRow ( string  sql, *softlist< auto >  vargs  )

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 Datasource::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 transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"), execute Datasource::beginTransaction() first to ensure that the transaction lock 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 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

Example:

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

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

Note

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

See also

Datasource::selectRow()

Implements Qore::SQL::AbstractDatasource.

vselectRows()

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

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 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 Datasource::select() method, therefore for larger amounts of data, it is recommended to use Datasource::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 transaction lock if it was not already acquired before this method is called, so to execute select statements that begin a transaction (such as "select for update"), execute Datasource::beginTransaction() first to ensure that the transaction lock 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);

Exceptions

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock

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

Datasource::selectRows()

Implements Qore::SQL::AbstractDatasource.