Qore SqlUtil Module Reference  1.1
 All Classes Namespaces Functions Variables Groups Pages
SqlUtil::Database Class Reference

represents a database; this class embeds an AbstractDatabase object that is created automatically in the constructor based on the database driver for the AbstractDatasource object providing the database connection More...

Public Member Functions

 constructor (AbstractDatasource ds, *hash opts)
 creates the Database object More...
 
 constructor (string ds, *hash opts)
 creates the AbstractDatabase object More...
 
 constructor (hash ds, *hash opts)
 creates the AbstractDatabase object More...
 
bool dropFunctionIfExists (string name, *hash opt)
 drops the given function if it exists; returns True if the function was dropped, False if not More...
 
bool dropProcedureIfExists (string name, *hash opt)
 drops the given procedure if it exists; returns True if the procedure was dropped, False if not More...
 
bool dropSequenceIfExists (string name, *hash opt)
 drops the given sequence if it exists; returns True if the sequence was dropped, False if not More...
 
bool dropTableIfExists (string name, *hash opt)
 drops the given table if it exists; returns True if the table was dropped, False if not More...
 
Qore::ListIterator functionIterator ()
 returns an iterator listing the string function names in the database
 
list getAlignFunctionSql (AbstractFunction f, *hash opt)
 returns a list of SQL strings that can be used to update a function in the database to the function definition passed as an argument More...
 
list getAlignProcedureSql (AbstractFunction f, *hash opt)
 returns a list of SQL strings that can be used to update a stored procedure in the database to the stored procedure definition passed as an argument More...
 
list getAlignSql (hash schema_hash, *hash opt, *Tables table_cache)
 accepts a hash argument describing a database schema and returns a list of SQL strings that can be used to align the structure and configuration of the current schema with that of the argument; if the objects described are identical then an empty list is returned More...
 
Qore::SQL::AbstractDatasource getDatasource ()
 gets the underlying AbstractDatasource
 
list getDropSchemaSql (hash schema_hash, *hash opt)
 accepts a hash argument describing a database schema and returns a list of SQL strings that can be used to drop any existing objects described in the schema; if none of the described objects exist, then an empty list is returned More...
 
*AbstractFunction getFunction (string name)
 returns an AbstractFunction argument for the given function name or NOTHING if the function cannot be found More...
 
int getNextSequenceValue (string name)
 returns the next value in the given sequence More...
 
*AbstractFunction getProcedure (string name)
 returns an AbstractFunction argument for the given stored procedure name or NOTHING if the stored procedur cannot be found More...
 
*AbstractSequence getSequence (string name)
 returns an AbstractSequence argument for the given sequence name or NOTHING if the sequence cannot be found More...
 
string getSqlFromList (list l)
 returns an SQL string corresponding to the list of commands in the argument More...
 
*AbstractTable getTable (string name)
 returns an AbstractTable argument for the given table name or NOTHING if the table cannot be found More...
 
*AbstractView getView (string name)
 returns an AbstractView argument for the given view name or NOTHING if the view More...
 
list listFunctions ()
 returns a list of string function names in the database
 
list listProcedures ()
 returns a list of string procedure names in the database
 
list listSequences ()
 returns a list of string sequence names in the database
 
list listTables ()
 returns a list of string table names in the database
 
list listViews ()
 returns a list of string view names in the database
 
AbstractFunction makeFunction (string name, string src, *hash opt)
 creates a database-specific AbstractFunction object corresponding to the arguments More...
 
AbstractFunction makeProcedure (string name, string src, *hash opt)
 creates a database-specific AbstractFunction object for a stored procedure corresponding to the arguments More...
 
AbstractSequence makeSequence (string name, number start=1, number increment=1, *softnumber end, *hash opts)
 creates a database-specific AbstractSequence object corresponding to the arguments More...
 
AbstractTable makeTable (string name, hash desc, *hash opts)
 creates a database-specific AbstractTable object corresponding to the arguments More...
 
any methodGate (string meth)
 executes a method on the contained AbstractDatabase object
 
Qore::ListIterator procedureIterator ()
 returns an iterator listing the string procedure names in the database
 
Qore::ListIterator sequenceIterator ()
 returns an iterator listing the string sequence names in the database
 
bool supportsSequences ()
 returns True if the database supports sequences
 
Qore::ListIterator tableIterator ()
 returns an iterator listing the string table names in the database
 
any tryExec (string sql)
 executes some SQL with optional arguments so that if an error occurs the current transaction state is not lost More...
 
any tryExecArgs (string sql, *softlist args)
 executes some SQL with optional arguments so that if an error occurs the current transaction state is not lost More...
 
any tryExecRaw (string sql)
 executes some SQL so that if an error occurs the current transaction state is not lost More...
 
Qore::ListIterator viewIterator ()
 returns an iterator listing the string view names in the database
 

Private Attributes

AbstractDatabase db
 the embedded AbstractDatabase object that actually provides the functionality for this class
 

Detailed Description

represents a database; this class embeds an AbstractDatabase object that is created automatically in the constructor based on the database driver for the AbstractDatasource object providing the database connection

Driver-specific modules that provide the AbstractDatabase implementation embedded in this class are loaded on demand based on the driver's name. The driver-specific module's name is generated based on the db-driver's name with the first letter capitalized then with "SqlUtil" appended.

For example:

etc.

Member Function Documentation

SqlUtil::Database::constructor ( AbstractDatasource  ds,
*hash  opts 
)

creates the Database object

Example:
my Database $db($ds);
Parameters
dsthe AbstractDatasource object used to provide the DB connection
optsa hash of options for the function creation string; see AbstractDatabase::DatabaseOptions for common options; each driver can support additional driver-specific options
Exceptions
DATABASE-DRIVER-ERRORno database-specific module can be loaded
OPTION-ERRORinvalid or unsupported option passed
SqlUtil::Database::constructor ( string  ds,
*hash  opts 
)

creates the AbstractDatabase object

Example:
my AbstractDatabase $db("pgsql:user/pass@db%host");
Parameters
dsa datasource description string in the format that can be parsed by parse_datasource()
optsa hash of options for the function creation string; see AbstractDatabase::DatabaseOptions for common options; each driver can support additional driver-specific options
Exceptions
OPTION-ERRORinvalid or unsupported option passed
SqlUtil::Database::constructor ( hash  ds,
*hash  opts 
)

creates the AbstractDatabase object

Example:
my AbstractDatabase $db("pgsql:user/pass@db%host");
Parameters
dsa hash giving parameters for the new datasource with the following possible keys (the "type" key is mandatory, also usable with the output of the parse_datasource() function):
  • type: (*string) The name of the database driver to use; this key is mandatory; if not present, an exception will be raised. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver (this string should be the name of the driver to be loaded)
  • user: (*string) The user name for the new connection
  • pass: (*string) The password for the new connection
  • db: (*string) The database name for the new connection
  • charset: (*string) The database-specific name of the character encoding to use for the new connection. Also see Qore::SQL::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
  • port: (softint) The port number for the new connection
  • options: (*hash) Any options for the new connection
optsa hash of options for the table creation string; see AbstractDatabase::DatabaseOptions for common options; each driver can support additional driver-specific options
Exceptions
OPTION-ERRORinvalid or unsupported option passed
bool SqlUtil::Database::dropFunctionIfExists ( string  name,
*hash  opt 
)

drops the given function if it exists; returns True if the function was dropped, False if not

Example:
$db.dropFunctionIfExists($name);
Parameters
namethe name of the function
optoptional callback options; see AbstractDatabase::CallbackOptions for more info
Returns
True if the function was dropped, False if not
Exceptions
OPTION-ERRORinvalid or unknown callback option
bool SqlUtil::Database::dropProcedureIfExists ( string  name,
*hash  opt 
)

drops the given procedure if it exists; returns True if the procedure was dropped, False if not

Example:
$db.dropProcedureIfExists($name);
Parameters
namethe name of the procedure
optoptional callback options; see AbstractDatabase::CallbackOptions for more info
Returns
True if the procedure was dropped, False if not
Exceptions
OPTION-ERRORinvalid or unknown callback option
bool SqlUtil::Database::dropSequenceIfExists ( string  name,
*hash  opt 
)

drops the given sequence if it exists; returns True if the sequence was dropped, False if not

Example:
$db.dropSequenceIfExists($name);
Parameters
namethe name of the sequence
optoptional callback options; see AbstractDatabase::CallbackOptions for more info
Returns
True if the sequence was dropped, False if not
Exceptions
OPTION-ERRORinvalid or unknown callback option
bool SqlUtil::Database::dropTableIfExists ( string  name,
*hash  opt 
)

drops the given table if it exists; returns True if the table was dropped, False if not

Example:
$db.dropTableIfExists($name);
Parameters
namethe name of the table
optoptional callback options; see AbstractDatabase::CallbackOptions for more info
Returns
True if the table was dropped, False if not
Exceptions
OPTION-ERRORinvalid or unknown callback option
list SqlUtil::Database::getAlignFunctionSql ( AbstractFunction  f,
*hash  opt 
)

returns a list of SQL strings that can be used to update a function in the database to the function definition passed as an argument

Example:
my list $l = $db.getAlignFunctionSql($f);
Parameters
fthe template or target version of the function to compare to the database version
optan optional hash of options for the generation of the SQL strings; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that can be used to update a function in the database to the function definition passed as an argument
Exceptions
OPTION-ERRORinvalid or unsupported option passed
list SqlUtil::Database::getAlignProcedureSql ( AbstractFunction  f,
*hash  opt 
)

returns a list of SQL strings that can be used to update a stored procedure in the database to the stored procedure definition passed as an argument

Example:
my list $l = $db.getAlignProcedureSql($f);
Parameters
fthe template or target version of the stored procedure to compare to the database version
optan optional hash of options for the generation of the SQL strings; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that can be used to update a stored procedure in the database to the stored procedure definition passed as an argument
Exceptions
OPTION-ERRORinvalid or unsupported option passed
list SqlUtil::Database::getAlignSql ( hash  schema_hash,
*hash  opt,
*Tables  table_cache 
)

accepts a hash argument describing a database schema and returns a list of SQL strings that can be used to align the structure and configuration of the current schema with that of the argument; if the objects described are identical then an empty list is returned

Example:
my list $l = $db.getAlignSql($schema_hash);
Parameters
schema_hashthe schema template hash that decribes the target state of the schema
opta hash of options for the SQL creation strings; see AbstractDatabase::AlignSchemaOptions for common options; each driver can support additional driver-specific options
table_cachean optional object of class Tables to return the cache of AbstractTable objects keyed by table name for the schema template (ie target table definitions)
Returns
a list of SQL strings that can be used to align the structure and configuration of the current schema with that of the argument; if the objects described are identical then an empty list is returned
Exceptions
SCHEMA-DESCRIPTION-ERRORthe schema description hash has an error or a required object does not exist
OPTION-ERRORinvalid or unsupported option passed
list SqlUtil::Database::getDropSchemaSql ( hash  schema_hash,
*hash  opt 
)

accepts a hash argument describing a database schema and returns a list of SQL strings that can be used to drop any existing objects described in the schema; if none of the described objects exist, then an empty list is returned

Example:
my list $l = $db.getDropSchemaSql($schema_hash);
Parameters
schema_hashthe schema template hash that decribes the state of the schema
opta hash of options for the SQL strings; see AbstractDatabase::DropSchemaOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that can be used to drop any existing objects in the database; if none of the described objects exist, then an empty list is returned
Exceptions
SCHEMA-DESCRIPTION-ERRORthe schema description hash has an error
OPTION-ERRORinvalid or unsupported option passed
*AbstractFunction SqlUtil::Database::getFunction ( string  name)

returns an AbstractFunction argument for the given function name or NOTHING if the function cannot be found

Example:
my *AbstractFunction $f = $db.getFunction("update_queue");
Parameters
namethe uniquely-identifying name of the function to retrieve
Returns
an AbstractFunction argument for the given function name or NOTHING if the function cannot be found
Note
for databases that support overloaded functions, the arguments must be passed in parentheses after the name to match overloaded functions properly
int SqlUtil::Database::getNextSequenceValue ( string  name)

returns the next value in the given sequence

Example:
my number $n = $db.getNextSequenceValue("seq_customers");
Parameters
namethe name of the sequence
Returns
the next value in the given sequence
*AbstractFunction SqlUtil::Database::getProcedure ( string  name)

returns an AbstractFunction argument for the given stored procedure name or NOTHING if the stored procedur cannot be found

Example:
my *AbstractFunction $f = $db.getProcedure("update_queue");
Parameters
namethe uniquely-identifying name of the stored procedure to retrieve
Returns
an AbstractFunction argument for the given stored procedure name or NOTHING if the stored procedure cannot be found
Note
for databases that support overloaded stored procedures, the arguments must be passed in parentheses after the name to match overloaded stored procedures properly
*AbstractSequence SqlUtil::Database::getSequence ( string  name)

returns an AbstractSequence argument for the given sequence name or NOTHING if the sequence cannot be found

Example:
my *AbstractSequence $seq = $db.getSequence("seq_queues");
Parameters
namethe uniquely-identifying name of the sequence to retrieve
Returns
an AbstractSequence argument for the given sequence name or NOTHING if the sequence cannot be found
string SqlUtil::Database::getSqlFromList ( list  l)

returns an SQL string corresponding to the list of commands in the argument

Example:
my string $sql = $t.getSqlFromList($list);
Parameters
la list of SQL commands
Returns
an SQL string corresponding to the list of commands in the argument
*AbstractTable SqlUtil::Database::getTable ( string  name)

returns an AbstractTable argument for the given table name or NOTHING if the table cannot be found

Example:
my *AbstractTable $table = $db.getTable("queues");
Parameters
namethe uniquely-identifying name of the table to retrieve
Returns
an AbstractTable argument for the given table name or NOTHING if the table cannot be found
*AbstractView SqlUtil::Database::getView ( string  name)

returns an AbstractView argument for the given view name or NOTHING if the view

Example:
my *AbstractView $f = $db.getView("my_view");
Parameters
namethe uniquely-identifying name of the view to retrieve
Returns
an AbstractView argument for the given stored procedure name or NOTHING if the stored procedure cannot be found
AbstractFunction SqlUtil::Database::makeFunction ( string  name,
string  src,
*hash  opt 
)

creates a database-specific AbstractFunction object corresponding to the arguments

Example:
my AbstractFunction $f = $db.makeFunction("update_queue", $src);
Parameters
namethe name of the function
srcthe database-specific source code of the function (see the database-specific documentation for information about the format of this parameter; generally it's simply the normal source code for the function required by the database)
optan optional hash of options for the creation of the function; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options
Exceptions
OPTION-ERRORinvalid or unsupported option passed
AbstractFunction SqlUtil::Database::makeProcedure ( string  name,
string  src,
*hash  opt 
)

creates a database-specific AbstractFunction object for a stored procedure corresponding to the arguments

Example:
my AbstractFunction $f = $db.makeProcedure("get_queue_info", $src);
Parameters
namethe name of the stored procedure
srcthe database-specific source code of the stored procedure (see the database-specific documentation for information about the format of this parameter; generally it's simply the normal source code for the stored procedure required by the database)
optan optional hash of options for the creation of the stored procedure; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options
Exceptions
OPTION-ERRORinvalid or unsupported option passed
AbstractSequence SqlUtil::Database::makeSequence ( string  name,
number  start = 1,
number  increment = 1,
*softnumber  end,
*hash  opts 
)

creates a database-specific AbstractSequence object corresponding to the arguments

Example:
my AbstractSequence $seq = $db.makeSequence("seq_queues");
Parameters
namethe name of the sequence
startthe starting value of the sequence
incrementthe increment value of the sequence
endthe endinf value of the sequence, omit for no ending value
optsan optional hash of options for the creation of the sequence; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options
Exceptions
OPTION-ERRORinvalid or unsupported option passed
SEQUENCE-ERRORend not compatible with start and increment, increment is zero
AbstractTable SqlUtil::Database::makeTable ( string  name,
hash  desc,
*hash  opts 
)

creates a database-specific AbstractTable object corresponding to the arguments

Example:
my AbstractTable $table = $db.makeTable("table", $th);
Parameters
namethe name of the table
desca table description hash describing the table
optsan optional hash of options for the table creation string; see SqlUtil::AbstractTable::TableOptions for common options; each driver can support additional driver-specific options
Exceptions
OPTION-ERRORinvalid or unsupported option passed
See Also
SqlUtil::Table::constructor()
any SqlUtil::Database::tryExec ( string  sql)

executes some SQL with optional arguments so that if an error occurs the current transaction state is not lost

Example:
$t.tryExec("drop table tmp_table");

Include any arguments in the parameter list after the sql argument

Parameters
sqlthe SQL to execute
Returns
any return value from the SQL command executed
any SqlUtil::Database::tryExecArgs ( string  sql,
*softlist  args 
)

executes some SQL with optional arguments so that if an error occurs the current transaction state is not lost

Example:
$t.tryExec("delete from tmp_table where id = %v and name = %v", $arglist);
Parameters
sqlthe SQL to execute
argsthe bind / placeholder or other arguments corresponding to the SQL string
Returns
any return value from the SQL command executed
any SqlUtil::Database::tryExecRaw ( string  sql)

executes some SQL so that if an error occurs the current transaction state is not lost

Example:
$t.tryExecRaw("drop table tmp_table");

Include any arguments in the parameter list after the sql argument

Parameters
sqlthe SQL to execute
Returns
any return value from the SQL command executed