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

represents a database table; this class embeds an AbstractTable 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

AbstractCheckConstraint addCheckConstraint (string cname, string src, *hash opt, *reference sql)
 adds a check constraint to the table; if the table is already known to be in the database, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example More...
 
AbstractColumn addColumn (string cname, hash opt, bool nullable=True, *reference lsql)
 adds a column to the table; if the table already exists, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example More...
 
AbstractForeignConstraint addForeignConstraint (string cname, softlist cols, string table, *softlist tcols, *hash opt, *reference sql)
 adds an foreign constraint to the table; if the table is already known to be in the database, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example More...
 
AbstractIndex addIndex (string iname, bool unique, softlist cols, *hash opt, *reference sql)
 adds an index to the table; if the table already exists, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example More...
 
AbstractPrimaryKey addPrimaryKey (string cname, softlist cols, *hash opt, *reference sql)
 adds a primary key to the table; if the table already exists, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example More...
 
AbstractTrigger addTrigger (string tname, string src, *hash opt, *reference lsql)
 adds a trigger to the table; if the table is already known to be in the database, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example More...
 
AbstractUniqueConstraint addUniqueConstraint (string cname, softlist cols, *hash opt, *reference sql)
 adds a unique constraint to the table; if the table is known to be in the database already, then the constraint is added to the database also immediately; otherwise it is only added internally and can be created when create() is called for example More...
 
 cache (*hash opts)
 reads in all attributes of the table from the database More...
 
 clear ()
 purges the current table definition More...
 
 commit ()
 commits the current transaction on the underlying Qore::SQL::AbstractDatasource
 
 constructor (AbstractDatasource ds, string name, *hash opts)
 creates the Table object More...
 
 constructor (string ds, string name, *hash opts)
 creates the Table object More...
 
 constructor (hash ds, string name, *hash opts)
 creates the Table object More...
 
 constructor (AbstractDatasource ds, hash desc, string name, *hash opts)
 creates the object from a table description hash More...
 
 create (*hash opt)
 creates the table in the database; releases the transaction lock after creating the table More...
 
 createNoCommit (*hash opt)
 creates the table with all associated properties (indexes, constraints, etc) without any transaction management More...
 
int del (*hash cond, *reference sql)
 deletes rows in the table matching the condition and returns the count of rows deleted; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
int del (*hash cond, *hash opt)
 deletes rows in the table matching the condition and returns the count of rows deleted; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
int delNoCommit (*hash cond, *reference sql)
 deletes rows in the table matching the condition and returns the count of rows deleted; no transaction management is performed with this method More...
 
int delNoCommit (*hash cond, *hash opt)
 deletes rows in the table matching the condition and returns the count of rows deleted; no transaction management is performed with this method More...
 
Columns describe ()
 returns an object of class Columns describing the Table More...
 
 drop (*hash opt)
 drops the table from the database; releases the transaction lock after dropping the table More...
 
AbstractColumn dropColumn (string cname, *reference lsql)
 drops a column from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally More...
 
AbstractConstraint dropConstraint (string cname, *reference sql)
 drops a constraint from the table; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally More...
 
AbstractForeignConstraint dropForeignConstraint (string cname, *reference sql)
 drops the foreign constraint from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally More...
 
AbstractIndex dropIndex (string iname, *reference sql)
 drops the index from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally More...
 
 dropNoCommit (*hash opt)
 drops the table from the database without any transaction management More...
 
AbstractPrimaryKey dropPrimaryKey (*reference lsql)
 drops the primary key from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally More...
 
AbstractTrigger dropTrigger (string tname, *reference sql)
 drops the given trigger from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally More...
 
bool empty ()
 returns True if the table has no definitions, False if not More...
 
bool emptyData ()
 returns True if the table has no data rows, False if not More...
 
*hash find (any id)
 finds a row in the table with the given primary key value; if no row matches the primary key value passed then NOTHING is returned More...
 
*list find (list ids)
 finds rows in the table with the given primary key values; if no row matches any primary key value passed then NOTHING is returned More...
 
*hash find (hash row)
 finds a row in the table with the given primary key value given as a hash; if no row matches the primary key value passed then NOTHING is returned More...
 
*list findAll (*hash cond)
 finds all rows in the table with the given column values; a list of hashes is returned representing the rows returned More...
 
*hash findSingle (*hash cond)
 finds a single row in the table that match the row condition passed; multiple rows may match, but only one row will be returned from the database; if no row matches the condition hash passed then NOTHING is returned More...
 
*AbstractUniqueConstraint findUniqueConstraint (string name)
 returns the given AbstractUniqueConstraint object if defined for the table (also includes the primary key) More...
 
string getAddCheckConstraintSql (string cname, string src, *hash copt, *hash opt)
 returns an SQL string that can be used to add a check constraint to the table More...
 
list getAddColumnSql (string cname, hash copt, bool nullable=True, *hash opt)
 returns a list of SQL strings that can be use to add a column to the table More...
 
string getAddForeignConstraintSql (string cname, softlist cols, string table, *softlist tcols, *hash fkopt, *hash opt)
 returns an SQL string that can be used to add a foreign constraint to the table More...
 
string getAddIndexSql (string iname, bool unique, softlist cols, *hash ixopt, *hash opt)
 returns an SQL string that can be used to add an index to the table More...
 
string getAddPrimaryKeySql (string pkname, softlist cols, *hash pkopt, *hash opt)
 returns the SQL that can be used to add a primary key to the table More...
 
list getAddTriggerSql (string tname, string src, *hash topt, *hash opt)
 returns a list of SQL strings that can be used to add a trigger to the table More...
 
string getAddUniqueConstraintSql (string cname, softlist cols, *hash ukopt, *hash opt)
 returns an SQL string that can be used to add a unique constraint to the table More...
 
list getAlignSql (AbstractTable table, *hash opt)
 accepts an AbstractTable argument and returns a list of SQL strings required to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty list is returned More...
 
list getAlignSql (Table table, *hash opt)
 accepts an AbstractTable argument and returns a list of SQL strings required to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty list is returned More...
 
string getAlignSqlString (AbstractTable table, *hash opt)
 accepts an AbstractTable argument and returns an SQL string that could be executed to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty string is returned More...
 
string getAlignSqlString (Table table, *hash opt)
 accepts an AbstractTable argument and returns an SQL string that could be executed to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty string is returned More...
 
Constraints getConstraints ()
 returns a Constraints object describing non-foreign constraints on the table
 
*list getCreateConstraintsSql (*hash opt)
 returns a list of SQL strings that could be used to create non-foreign constraints on the table or NOTHING if there are no non-foreign constraints on the table More...
 
*list getCreateForeignConstraintsSql (*hash opt)
 returns a list of SQL strings that could be used to create foreign constraints on the table or NOTHING if there are no foreign constraints on the table More...
 
*list getCreateIndexesSql (*hash opt)
 returns a list of SQL strings that could be used to create indexes on the table or NOTHING if there are no indexes on the table More...
 
*list getCreateMiscSql (*hash opt)
 returns a list of SQL strings that could be used to create other table attributes (such as comments, if supported and present) or NOTHING if there are none More...
 
*string getCreatePrimaryKeySql (*hash opt)
 returns an SQL string that could be used to create the primary key on the table More...
 
list getCreateSql (*hash opt)
 returns a list of SQL strings that could be used to create the table and all known properties of the table More...
 
string getCreateSqlString (*hash opt)
 returns an SQL string that could be used to create the table and all known properties of the table More...
 
string getCreateTableSql (*hash opt)
 returns an SQL string that could be used to create the basic table structure without indexes and constraints More...
 
*list getCreateTriggersSql (*hash opt)
 returns a list of SQL strings that could be used to create triggers on the table or NOTHING if there are no triggers on the table More...
 
Qore::SQL::AbstractDatasource getDatasource ()
 gets the underlying AbstractDatasource
 
string getDriverName ()
 returns the database driver name
 
list getDropColumnSql (string cname, *hash opt)
 returns the SQL that can be used to drop a column from the table More...
 
*string getDropConstraintIfExistsSql (string cname, *hash opt, *reference cref)
 gets the SQL that can be used to drop a constraint from the table if it exists, otherwise returns NOTHING; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint More...
 
string getDropConstraintSql (string cname, *hash opt)
 gets the SQL that can be used to drop a constraint from the table; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint More...
 
string getDropIndexSql (string iname, *hash opt)
 gets the SQL that can be used to drop an index from the table More...
 
list getDropPrimaryKeySql (*hash opt)
 gets a list of SQL strings that can be used to drop the primary key from the table More...
 
list getDropTriggerSql (string tname, *hash opt)
 returns SQL that can be used to drop the given trigger from the table More...
 
ForeignConstraints getForeignConstraints (*hash opt)
 returns a ForeignConstraints object describing the foreign constraints that the table has on other tables
 
Indexes getIndexes ()
 returns an object of class Indexes describing the indexes on the table More...
 
list getModifyColumnSql (string cname, hash copt, bool nullable=True, *hash opt)
 gets a list of SQL strings that can be used to modify an existing column in the table More...
 
string getName ()
 returns the name of the table
 
AbstractPrimaryKey getPrimaryKey ()
 returns an object of class AbstractPrimaryKey describing the primary key of the table More...
 
string getRenameColumnSql (string old_name, string new_name, *hash opt)
 gets an SQL string that can be used to rename an existing column in the table More...
 
string getRenameSql (string new_name, *hash opt)
 returns an SQL string that could be used to rename the table in the database More...
 
Qore::SQL::SQLStatement getRowIterator (*hash sh, *reference sql)
 returns an SQLStatement object that will iterate the results of a select statement matching the arguments More...
 
Qore::SQL::SQLStatement getRowIterator (*hash sh, *hash opt)
 returns an SQLStatement object that will iterate the results of a select statement matching the arguments More...
 
string getSelectSql (*hash sh, *reference args)
 returns the SQL string to be executed corresponding to the argument hash with an output parameter for the select bind arguments More...
 
string getSqlFromList (list l)
 returns an SQL string corresponding to the list of commands in the argument More...
 
string getSqlValue (any v)
 returns a string for use in SQL queries representing the DB-specific value of the argument More...
 
AbstractTable getTable ()
 returns the AbstractTable object contained by this object
 
Triggers getTriggers ()
 returns an object of class Triggers describing the triggers on the table More...
 
string getTruncateSql (*hash opt)
 gets the SQL that can be used to truncate the table More...
 
Qore::AbstractIterator getUniqueConstraintIterator ()
 returns an iterator for all unique constraints on the table (including the primary key if any) More...
 
code getUpsertClosure (hash example_row, int upsert_strategy=AbstractTable::UpsertAuto)
 returns a closure that can be executed given a hash argument representing a single row that will be updated or inserted in the database with the given upsert strategy; the table must have a unique key to do this; the closure returned does not check the input hash for validity More...
 
code getUpsertClosureWithValidation (hash example_row, int upsert_strategy=AbstractTable::UpsertAuto)
 returns a closure that can be executed given a hash argument representing a single row that will be updated or inserted in the database with the given upsert strategy; the table must have a unique key to do this; the closure returned validates the input hash for validity More...
 
bool inDb ()
 returns True if the table has been read from or created in the database, False if not More...
 
 insert (hash row, *reference sql)
 inserts a row into the table; the transaction is committed if successful, if an error occurs, it is rolled back More...
 
 insert (hash row, *hash opt)
 inserts a row into the table; the transaction is committed if successful, if an error occurs, it is rolled back More...
 
int insertFromIterator (Qore::AbstractIterator i, *hash opt)
 this method inserts data from the given iterator argument (whose getValue() method must return a hash giving row values) into the current table; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
int insertFromIteratorNoCommit (Qore::AbstractIterator i, *hash opt)
 this method inserts data from the given iterator argument (whose getValue() method must return a hash giving row values) into the current table; no transaction management is performed with this method More...
 
int insertFromSelect (list cols, AbstractTable source, *hash sh, *reference sql)
 inserts rows into a table based on a select statement from another table (which must be using the same datasource as the current table); the transaction is committed if successful, if an error occurs, it is rolled back More...
 
int insertFromSelect (list cols, AbstractTable source, *hash sh, *hash opt)
 inserts rows into a table based on a select statement from another table (which must be using the same datasource as the current table); the transaction is committed if successful, if an error occurs, it is rolled back More...
 
int insertFromSelectNoCommit (list cols, AbstractTable source, *hash sh, *reference sql)
 inserts rows into a table based on a select statement from another table (which must be using the same datasource as the current table); a transaction will be in progress after this method is successfully executed More...
 
int insertFromSelectNoCommit (list cols, AbstractTable source, *hash sh, *hash opt)
 inserts rows into a table based on a select statement from another table (which must be using the same datasource as the current table); a transaction will be in progress after this method is successfully executed More...
 
 insertNoCommit (hash row, *reference sql)
 inserts a row into the table without any transaction management; a transaction will be in progress after this method is successfully executed More...
 
 insertNoCommit (hash row, *hash opt)
 inserts a row into the table without any transaction management; a transaction will be in progress after this method is successfully executed More...
 
any methodGate (string meth)
 executes a method on the contained AbstractTable object
 
AbstractColumn modifyColumn (string cname, hash opt, bool nullable=True, *reference lsql)
 modifies an existing column in the table; if the table already exists, then the changes are effected in the database also immediately; otherwise it is only updated internally and the new column definition will be created when create() is called for example More...
 
AbstractForeignConstraint removeForeignConstraint (string cname)
 removes the named foreign constraint from the table; no SQL is executed in any case, only the named foreign constraint is removed from the table definition More...
 
 rename (string new_name, *reference sql, *Tables table_cache)
 renames the table; if the table already exists in the database, then the changes are effected in the database also immediately; otherwise it is only updated internally More...
 
AbstractColumn renameColumn (string old_name, string new_name, reference sql)
 renames an existing column; if the table already exists, then the changes are effected in the database also immediately; otherwise it is only updated internally More...
 
AbstractConstraint renameConstraint (string old_name, string new_name, reference lsql)
 renames an existing constraint; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint; if the table is already known to be in the database, then the changes are effected in the database also immediately; otherwise it is only updated internally More...
 
AbstractIndex renameIndex (string old_name, string new_name, reference sql)
 renames an existing index; if the table is already known to be in the database, then the changes are effected in the database also immediately; otherwise it is only updated internally More...
 
 rollback ()
 rolls back the current transaction on the underlying Qore::SQL::AbstractDatasource
 
softint rowCount ()
 returns the number of rows in the table More...
 
*hash select (*hash sh, *reference sql)
 returns a hash of lists representing the columns and rows in the table that match the argument hahs More...
 
*hash select (*hash sh, *hash opt)
 returns a hash of lists representing the columns and rows in the table that match the argument hahs More...
 
*hash selectRow (*hash sh, *reference sql)
 returns a hash representing the row in the table that matches the argument hash; if more than one row would be returned an exception is raised More...
 
*hash selectRow (*hash sh, *hash opt)
 returns a hash representing the row in the table that matches the argument hash; if more than one row would be returned an exception is raised More...
 
*list selectRows (*hash sh, *reference sql)
 returns a list of hashes representing the rows in the table that match the argument hash More...
 
*list selectRows (*hash sh, *hash opt)
 returns a list of hashes representing the rows in the table that match the argument hash More...
 
 setDatasource (AbstractDatasource nds)
 changes the datasource for the table; if the inDb flag is True, then it is set to False by calling this method More...
 
 setupTable (hash desc, *hash opt)
 creates the object from a table description hash More...
 
 truncate ()
 truncates all the table data; releases the transaction lock after executing More...
 
 truncateNoCommit ()
 truncates all the table data without any transaction management More...
 
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...
 
int update (hash set, *hash cond, *reference sql)
 updates rows in the table matching an optional condition and returns the count of rows updated; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
int update (hash set, *hash cond, *hash opt)
 updates rows in the table matching an optional condition and returns the count of rows updated; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
int updateNoCommit (hash set, *hash cond, *reference sql)
 updates rows in the table matching an optional condition and returns the count of rows updated; no transaction management is performed with this method More...
 
int updateNoCommit (hash set, *hash cond, *hash opt)
 updates rows in the table matching an optional condition and returns the count of rows updated; no transaction management is performed with this method More...
 
int upsert (hash row, int upsert_strategy=AbstractTable::UpsertAuto)
 update or insert the data in the table according to the hash argument; the table must have a unique key to do this; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
*hash upsertFromIterator (Qore::AbstractIterator i, int upsert_strategy=AbstractTable::UpsertAuto, *hash opt)
 this method upserts or merges data from the given iterator argument (whose getValue() method must return a hash giving row values) into the current table; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
*hash upsertFromIteratorNoCommit (Qore::AbstractIterator i, int upsert_strategy=AbstractTable::UpsertAuto, *hash opt)
 this method upserts or merges data from the given iterator argument (whose getValue() method must return a hash giving row values) into the current table; no transaction management is performed with this method More...
 
*hash upsertFromSelect (AbstractTable src, *hash sh, int upsert_strategy=AbstractTable::UpsertAuto, *hash opt)
 this method upserts or merges data from the given foreign table and select option hash into the current table; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
*hash upsertFromSelect (Table src, *hash sh, int upsert_strategy=AbstractTable::UpsertAuto, *hash opt)
 this method upserts or merges data from the given foreign table and select option hash into the current table; the transaction is committed if successful, if an error occurs then it is rolled back More...
 
*hash upsertFromSelectNoCommit (AbstractTable src, *hash sh, int upsert_strategy=AbstractTable::UpsertAuto, *hash opt)
 this method upserts or merges data from the given foreign table and select option hash into the current table; no transaction management is performed with this method More...
 
*hash upsertFromSelectNoCommit (Table src, *hash sh, int upsert_strategy=AbstractTable::UpsertAuto, *hash opt)
 this method upserts or merges data from the given foreign table and select option hash into the current table; no transaction management is performed with this method More...
 
int upsertNoCommit (hash row, int upsert_strategy=AbstractTable::UpsertAuto)
 update or insert the data in the table according to the hash argument; the table must have a unique key to do this; no transaction management is performed with this method More...
 

Private Attributes

AbstractTable t
 the embedded AbstractTable object that actually provides the functionality for this class
 

Detailed Description

represents a database table; this class embeds an AbstractTable 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 AbstractTable 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

AbstractCheckConstraint SqlUtil::Table::addCheckConstraint ( string  cname,
string  src,
*hash  opt,
*reference  sql 
)

adds a check constraint to the table; if the table is already known to be in the database, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example

Example:
my string $sql;
my AbstractCheckConstraint $cc = $table.addCheckConstraint("check_mytable_id", "id > 10", NOTHING, \$sql);
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the new constraint
srcthe source of the constraint clause
opta hash of options for the new foreign constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
an AbstractCheckConstraint object corresponding to the check constraint created
Exceptions
CHECK-CONSTRAINT-ERRORthe table already has a constraint with the given name or invalid columns or options were passed
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractColumn SqlUtil::Table::addColumn ( string  cname,
hash  opt,
bool  nullable = True,
*reference  lsql 
)

adds a column to the table; if the table already exists, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example

Example:
$table.addColumn("name", ("qore_type": Type::String, "size": 50), False);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the column
opta hash describing the column; the following keys are permitted (other column options may be supported depending on the underlying AbstractTable implementation):
  • qore_type: a qore type string that will be converted to a native DB type with some default conversion;
  • native_type: the native database column type; if both native_type and qore_type are given then native_type is used
  • size: for data types requiring a size component, the size; for numeric columns this represents the precision for example
  • scale: for numeric data types, this value gives the scale
  • default_value: the default value for the column
lsqlan optional reference to a list of strings to retrieve the SQL used to modify the table (only executed if the table is already in the database)
nullableif True then the column can hold NULL values; note that primary key columns cannot be nullable
Exceptions
COLUMN-ERRORno native_type or qore_type keys in column option hash, column already exists, invalid column data
Note
make sure and add a default_value value when adding a column with a "not null" constraint with existing data
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractForeignConstraint SqlUtil::Table::addForeignConstraint ( string  cname,
softlist  cols,
string  table,
*softlist  tcols,
*hash  opt,
*reference  sql 
)

adds an foreign constraint to the table; if the table is already known to be in the database, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example

Example:
my string $sql;
my AbstractForeignConstraint $fc = $table.addForeignConstraint("fk_mytable_other_table", ("name", "version"), "other_table", NOTHING, \$sql);
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the new foreign constraint
colsa single column name or a list of columns in the local table that make up the foreign constraint
tablethe name of the other table that the constraint targets
tcolsa single column name or a list of columns in the foreign table or NOTHING meaning that the column names are the same as in the local table; if column names are given the same number of columns must be given in the local and foreign tables
opta hash of options for the new foreign constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ForeignConstraintOptions
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
an AbstractForeignConstraint object corresponding to the foreign constraint created
Exceptions
FOREIGN-CONSTRAINT-ERRORthe table already has an foreign constraint with the given name or invalid columns were passed
OPTION-ERRORinvalid or unsupported option passed
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractIndex SqlUtil::Table::addIndex ( string  iname,
bool  unique,
softlist  cols,
*hash  opt,
*reference  sql 
)

adds an index to the table; if the table already exists, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example

Example:
my string $sql;
my AbstractIndex $ix = $table.addIndex("uk_mytable_name", True, "name", ("index_tablespace": "index1"), \$sql);
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
inamethe name of the new index
uniquea flag to tell if the new index should be unique or not
colsa single column name or a list of columns that make up the index
opta hash of options for the new index; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::IndexOptions
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
an AbstractIndex object corresponding to the index created
Exceptions
INDEX-ERRORthe table already has an index with the given name or invalid columns were passed
OPTION-ERRORinvalid or unsupported option passed
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractPrimaryKey SqlUtil::Table::addPrimaryKey ( string  cname,
softlist  cols,
*hash  opt,
*reference  sql 
)

adds a primary key to the table; if the table already exists, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example

Example:
my string $sql;
my AbstractPrimaryKey $pk = $table.addPrimaryKey("pk_mytable", "id", ("index_tablespace": "index1"), \$sql);
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the new primary key constraint
colsa single column name or a list of columns that make up the primary key
opta hash of options for the new primary key; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
an AbstractPrimaryKey object corresponding to the primary key created
Exceptions
PRIMARY-KEY-ERRORthe table already has a primary key or invalid columns passed
OPTION-ERRORinvalid or unsupported option passed
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractTrigger SqlUtil::Table::addTrigger ( string  tname,
string  src,
*hash  opt,
*reference  lsql 
)

adds a trigger to the table; if the table is already known to be in the database, then it is added in the database also immediately; otherwise it is only added internally and can be created when create() is called for example

Example:
my string $sql;
my AbstractTrigger $trig = $table.addTrigger("trig_mytable",x $trigger_source, NOTHING, \$sql);
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
tnamethe name of the new trigger
srcthe database-specific source of the trigger
opta hash of options for the new trigger; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::TriggerOptions
lsqlan optional reference to a list of strings to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
an AbstractTrigger object corresponding to the trigger created
Exceptions
TRIGGER-ERRORthe table already has a trigger with the given name or invalid options were passed
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractUniqueConstraint SqlUtil::Table::addUniqueConstraint ( string  cname,
softlist  cols,
*hash  opt,
*reference  sql 
)

adds a unique constraint to the table; if the table is known to be in the database already, then the constraint is added to the database also immediately; otherwise it is only added internally and can be created when create() is called for example

Example:
my string $sql;
my AbstractUniqueConstraint $c = $table.addUniqueConstraint("uk_mytable", "name", ("index_tablespace": "index1"), \$sql);
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the new unique constraint
colsa single column name or a list of columns that make up the unique constraint
opta hash of options for the new unique constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
an AbstractUniqueConstraint object corresponding to the unique constraint created
Exceptions
UNIQUE-CONSTRAINT-ERRORthe table already has a constraint with the given name or invalid columns passed
OPTION-ERRORinvalid or unsupported option passed
See Also
  • inDb() for a method that tells if the table is already in the database or not
  • dropUniqueConstraint() for a method that allows unique constraints to be dropped from the table
SqlUtil::Table::cache ( *hash  opts)

reads in all attributes of the table from the database

Example:
$table.cache();
Parameters
optscache options; see SqlUtil::AbstractTable::CacheOptions for common options; each driver can support additional driver-specific options
SqlUtil::Table::clear ( )

purges the current table definition

Example:
$table.clear();
SqlUtil::Table::constructor ( AbstractDatasource  ds,
string  name,
*hash  opts 
)

creates the Table object

Example:
my Table $table($ds, "table");
Parameters
dsthe AbstractDatasource object used to provide the DB connection
namethe name of the table
optsa hash of options for the table creation string; see SqlUtil::AbstractTable::TableOptions for common options; each driver can support additional driver-specific options
Exceptions
TABLE-DRIVER-ERRORno database-specific module can be loaded
OPTION-ERRORinvalid or unsupported option passed
SqlUtil::Table::constructor ( string  ds,
string  name,
*hash  opts 
)

creates the Table object

Example:
my Table $table("pgsql:user/pass@db%host", "table");
Parameters
dsa datasource description string in the format that can be parsed by parse_datasource()
namethe name of the table
optsa hash of options for the table creation string; see SqlUtil::AbstractTable::TableOptions for common options; each driver can support additional driver-specific options
Exceptions
TABLE-DRIVER-ERRORno database-specific module can be loaded
OPTION-ERRORinvalid or unsupported option passed
SqlUtil::Table::constructor ( hash  ds,
string  name,
*hash  opts 
)

creates the Table object

Example:
my Table $table("pgsql:user/pass@db%host", "table");
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
namethe name of the table
optsa hash of options for the table creation string; see SqlUtil::AbstractTable::TableOptions for common options; each driver can support additional driver-specific options
Exceptions
TABLE-DRIVER-ERRORno database-specific module can be loaded
OPTION-ERRORinvalid or unsupported option passed
SqlUtil::Table::constructor ( AbstractDatasource  ds,
hash  desc,
string  name,
*hash  opts 
)

creates the object from a table description hash

Parameters
dsthe AbstractDatasource for the connection to the database
desca table description hash describing the table
namethe name of 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
DESCRIPTION-ERRORinvalid or unsupported description hash value passed
SqlUtil::Table::create ( *hash  opt)

creates the table in the database; releases the transaction lock after creating the table

Example:
$table.create();
Parameters
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::TableCreationOptions for common options; each driver can support additional driver-specific options
Note
The transaction is committed if successful or rolled back if an exception occurs; use createNoCommit() to execute without any transaction management
Exceptions
OPTION-ERRORinvalid or unsupported option passed
SqlUtil::Table::createNoCommit ( *hash  opt)

creates the table with all associated properties (indexes, constraints, etc) without any transaction management

Example:
$table.createNoCommit();
Parameters
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::TableCreationOptions for common options; each driver can support additional driver-specific options
Note
Transaction management is normally not performed when creating tables, however this method uses the Qore::SQL::AbstractDatasource::exec() method, which normally participates in acquiring a transaction lock for the underlying datasource object; therefore after this method executes normally the transaction lock will be dedicated to the calling thread.
int SqlUtil::Table::del ( *hash  cond,
*reference  sql 
)

deletes rows in the table matching the condition and returns the count of rows deleted; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
my int $dcnt = $table.del(("name": $name));
Parameters
conda hash of conditions for the where clause; see Where Clauses for more information
sqlan optional reference to a string to return the SQL generated for the delete statement
Returns
the count of rows deleted
Exceptions
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
See Also
delNoCommit(*hash)
int SqlUtil::Table::del ( *hash  cond,
*hash  opt 
)

deletes rows in the table matching the condition and returns the count of rows deleted; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
my int $dcnt = $table.del(("name": $name));
Parameters
conda hash of conditions for the where clause; see Where Clauses for more information
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
the count of rows deleted
Exceptions
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
See Also
delNoCommit(*hash)
int SqlUtil::Table::delNoCommit ( *hash  cond,
*reference  sql 
)

deletes rows in the table matching the condition and returns the count of rows deleted; no transaction management is performed with this method

Example:
my int $dcnt = $table.delNoCommit(("name": $name));
Parameters
conda hash of conditions for the where clause; see Where Clauses for more information
sqlan optional reference to a string to return the SQL generated for the delete statement
Returns
the count of rows deleted
Exceptions
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
See Also
del(*hash)
int SqlUtil::Table::delNoCommit ( *hash  cond,
*hash  opt 
)

deletes rows in the table matching the condition and returns the count of rows deleted; no transaction management is performed with this method

Example:
my int $dcnt = $table.delNoCommit(("name": $name));
Parameters
conda hash of conditions for the where clause; see Where Clauses for more information
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
the count of rows deleted
Exceptions
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
See Also
del(*hash)
Columns SqlUtil::Table::describe ( )

returns an object of class Columns describing the Table

Example:
my Columns $cols = $table.describe();
Returns
an object of class Columns describing the Table
SqlUtil::Table::drop ( *hash  opt)

drops the table from the database; releases the transaction lock after dropping the table

Example:
$table.drop();
Parameters
optoptional callback options; see AbstractDatabase::CallbackOptions for more info
Exceptions
OPTION-ERRORinvalid or unknown callback option
Note
The transaction is committed if successful or rolled back if an exception occurs; use dropNoCommit() to execute without any transaction management
AbstractColumn SqlUtil::Table::dropColumn ( string  cname,
*reference  lsql 
)

drops a column from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally

Example:
$table.dropColumn("notes_2");

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the column to drop
lsqlan optional reference to a list of strings to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Exceptions
COLUMN-ERRORthe named column is not present in the table
Note
this method retrieves the table definition from the database if none has already been defined
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractConstraint SqlUtil::Table::dropConstraint ( string  cname,
*reference  sql 
)

drops a constraint from the table; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally

Example:
$table.dropConstraint("uk_mytable_name");

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the constraint to drop
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
the constraint dropped from the table
Exceptions
CONSTRAINT-ERRORthe given constraint does not exist in the table
Note
this method retrieves current constraint definitions from the database if not already loaded or defined
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractForeignConstraint SqlUtil::Table::dropForeignConstraint ( string  cname,
*reference  sql 
)

drops the foreign constraint from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally

Example:
$table.dropForeignConstraint("uk_mytable_name");

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the foreign constraint to drop
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
the foreign constraint dropped from the table
Exceptions
FOREIGN-CONSTRAINT-ERRORthe given constraint does not exist
Note
this method retrieves all current foreign constraint definitions from the database if none have already been defined
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractIndex SqlUtil::Table::dropIndex ( string  iname,
*reference  sql 
)

drops the index from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally

Example:
$table.dropIndex("uk_mytable_name");

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
inamethe name of the index to drop
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
the index dropped from the table
Exceptions
INDEX-ERRORthe given index does not exist
Note
this method retrieves all current index definitions from the database if none have already been defined
See Also
inDb() for a method that tells if the table is already in the database or not
SqlUtil::Table::dropNoCommit ( *hash  opt)

drops the table from the database without any transaction management

Example:
$table.dropNoCommit();
Parameters
optoptional callback options; see AbstractDatabase::CallbackOptions for more info
Exceptions
OPTION-ERRORinvalid or unknown callback option
Note
Transaction management is normally not performed when dropping tables, however this method uses the Qore::SQL::AbstractDatasource::exec() method, which normally participates in acquiring a transaction lock for the underlying datasource object; therefore after this method executes normally the transaction lock will be dedicated to the calling thread.
AbstractPrimaryKey SqlUtil::Table::dropPrimaryKey ( *reference  lsql)

drops the primary key from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally

Example:
$table.dropPrimaryKey();

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
lsqlan optional reference to a list of strings to retrieve the SQL used to modify the database (only executed if the table is already in the database)
Returns
the primary key dropped from the table
Exceptions
PRIMARY-KEY-ERRORno primary key exists
Note
  • this method retrieves the primary key definition from the database if none has already been defined
  • if there are known foreign contraints on the primary key, SQL for dropping those constraints is also included
See Also
inDb() for a method that tells if the table is already in the database or not
AbstractTrigger SqlUtil::Table::dropTrigger ( string  tname,
*reference  sql 
)

drops the given trigger from the table; if the table is known to be in the database already, then it is also dropped from the database immediately; otherwise it is only removed internally

Example:
$table.dropTrigger("trig_mytable");

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
tnamethe name of the trigger to drop
sqlan optional reference to a string to retrieve the SQL used to modify the database (only executed if the table is already in the database)
Returns
the trigger dropped from the table
Exceptions
TRIGGER-ERRORthe given trigger does not exist
Note
this method retrieves all current trigger definitions from the database if none have already been defined
See Also
inDb() for a method that tells if the table is already in the database or not
bool SqlUtil::Table::empty ( )

returns True if the table has no definitions, False if not

Example:
my bool $b = $table.empty();
Returns
True if the table has no definitions, False if not
See Also
emptyData()
bool SqlUtil::Table::emptyData ( )

returns True if the table has no data rows, False if not

Example:
my bool $b = $table.emptyData();
Returns
True if the table has no data rows, False if not
See Also
*hash SqlUtil::Table::find ( any  id)

finds a row in the table with the given primary key value; if no row matches the primary key value passed then NOTHING is returned

Example:
my *hash $row = $table.find($id);
Parameters
idthe primary key ID to find
Returns
a hash of the row value matching the primary key ID or NOTHING if no row matches the primary key value passed
Exceptions
PRIMARY-KEY-ERRORthe table has no primary key or the primary key has more than one column
*list SqlUtil::Table::find ( list  ids)

finds rows in the table with the given primary key values; if no row matches any primary key value passed then NOTHING is returned

Example:
my *list $rows = $table.find($list);
Parameters
idsthe list of primary key IDs to find
Returns
a list of hashes of rows matching the primary key IDs passed or NOTHING if no row matches any primary key value passed
Exceptions
PRIMARY-KEY-ERRORthe table has no primary key or the primary key has more than one column
*hash SqlUtil::Table::find ( hash  row)

finds a row in the table with the given primary key value given as a hash; if no row matches the primary key value passed then NOTHING is returned

Example:
my *hash $row = $table.find(("account_type": $type, "name": $name));
Parameters
rowa hash giving the primary key value to find; other columns may also appear in the hash, however at least all columns of the primary key must be present
Returns
a hash of the row value matching the primary key value passed or NOTHING if no row matches the primary key value passed
Exceptions
PRIMARY-KEY-ERRORthe table has no primary key or the the hash passed does not contain all columns of the primary key
*list SqlUtil::Table::findAll ( *hash  cond)

finds all rows in the table with the given column values; a list of hashes is returned representing the rows returned

Example:
my *list $rows = $table.findAll($h);
Parameters
conda hash giving the column values to find; see Where Clauses for the format of this argument
Returns
a list of hashes is returned representing the rows returned
Exceptions
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
Note
this is equivalent to calling selectRows() with where = cond
*hash SqlUtil::Table::findSingle ( *hash  cond)

finds a single row in the table that match the row condition passed; multiple rows may match, but only one row will be returned from the database; if no row matches the condition hash passed then NOTHING is returned

Example:
my *hash $row = $table.findSingle($h);
Parameters
conda hash giving the column values to find; see Where Clauses for the format of this argument
Returns
a hash representing a single row in the table with the given column values; multiple rows may match, but only one row will be returned from the database; if no row matches the condition hash passed then NOTHING is returned
Exceptions
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
Note
this is equivalent to calling selectRow() with where = cond and limit = 1
See Also
selectRow()
*AbstractUniqueConstraint SqlUtil::Table::findUniqueConstraint ( string  name)

returns the given AbstractUniqueConstraint object if defined for the table (also includes the primary key)

Example:
my *AbstractUniqueConstraint uk = $table.findUniqueConstraint("uk_table2");
Parameters
namethe name of the unique constraint to find
Returns
the given AbstractUniqueConstraint object if defined for the table (also includes the primary key)
string SqlUtil::Table::getAddCheckConstraintSql ( string  cname,
string  src,
*hash  copt,
*hash  opt 
)

returns an SQL string that can be used to add a check constraint to the table

Example:
my string $sql = $table.getAddCheckConstraintSql("check_mytable_id", "id > 10");
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the new constraint
srcthe source of the constraint clause
copta hash of options for the new constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that can be used to add a check constraint to the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
CHECK-CONSTRAINT-ERRORthe table already has a constraint with the given name or invalid columns or options were passed
See Also
inDb() for a method that tells if the table is already in the database or not
Note
if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
list SqlUtil::Table::getAddColumnSql ( string  cname,
hash  copt,
bool  nullable = True,
*hash  opt 
)

returns a list of SQL strings that can be use to add a column to the table

Example:
my list $l = $table.getAddColumnSql("name", ("qore_type": Type::String, "size": 50), False);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the column
copta hash describing the column; the following keys are permitted (other column options may be supported depending on the underlying AbstractTable implementation):
  • qore_type: a qore type string that will be converted to a native DB type with some default conversion;
  • native_type: the native database column type; if both native_type and qore_type are given then native_type is used
  • size: for data types requiring a size component, the size; for numeric columns this represents the precision for example
  • scale: for numeric data types, this value gives the scale
  • default_value: the default value for the column
nullableif True then the column can hold NULL values; note that primary key columns cannot be nullable
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that can be use to add a column to the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
COLUMN-ERRORno native_type or qore_type keys in column option hash, column already exists, invalid column data
Note
  • make sure and add a default_value value when adding a column with a "not null" constraint with existing data
  • if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
See Also
inDb() for a method that tells if the table is already in the database or not
string SqlUtil::Table::getAddForeignConstraintSql ( string  cname,
softlist  cols,
string  table,
*softlist  tcols,
*hash  fkopt,
*hash  opt 
)

returns an SQL string that can be used to add a foreign constraint to the table

Example:
my string $sql = $table.getAddForeignConstraintSql("fk_mytable_other_table", ("name", "version"), "other_table");
printf("%s;\n", $sql);
Parameters
cnamethe name of the new foreign constraint
colsa single column name or a list of columns in the local table that make up the foreign constraint
tablethe name of the other table that the constraint targets
tcolsa single column name or a list of columns in the foreign table or NOTHING meaning that the column names are the same as in the local table; if column names are given the same number of columns must be given in the local and foreign tables
fkopta hash of options for the new foreign constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ForeignConstraintOptions
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that can be used to add a foreign constraint to the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
FOREIGN-CONSTRAINT-ERRORthe table already has a constraint with the given name or invalid columns or options were passed
See Also
inDb() for a method that tells if the table is already in the database or not
Note
if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
string SqlUtil::Table::getAddIndexSql ( string  iname,
bool  unique,
softlist  cols,
*hash  ixopt,
*hash  opt 
)

returns an SQL string that can be used to add an index to the table

Example:
my string $sql = $table.getAddIndexSql("uk_mytable_name", True, "name", ("index_tablespace": "index1"));
printf("%s;\n", $sql);
Parameters
inamethe name of the new index
uniquea flag to tell if the new index should be unique or not
colsa single column name or a list of columns that make up the index
ixopta hash of options for the new index; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::IndexOptions
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that can be used to add an index to the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
INDEX-ERRORthe table already has an index with the given name or invalid columns or options were passed
See Also
inDb() for a method that tells if the table is already in the database or not
Note
if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
string SqlUtil::Table::getAddPrimaryKeySql ( string  pkname,
softlist  cols,
*hash  pkopt,
*hash  opt 
)

returns the SQL that can be used to add a primary key to the table

Example:
my string $sql = $table.getAddPrimaryKeySql("pk_mytable", "id", ("index_tablespace": "index1"), opt);
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
pknamethe name of the new primary key constraint
colsa single column name or a list of columns that make up the primary key
pkopta hash of options for the new primary key; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
the SQL that can be used to add a primary key to the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
PRIMARY-KEY-ERRORthe table already has a primary key or invalid columns or options passed
See Also
inDb() for a method that tells if the table is already in the database or not
Note
if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
list SqlUtil::Table::getAddTriggerSql ( string  tname,
string  src,
*hash  topt,
*hash  opt 
)

returns a list of SQL strings that can be used to add a trigger to the table

Example:
my string $sql = $table.getAddTriggerSql("trig_mytable", $trigger_src);
printf("%s;\n", $sql);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
tnamethe name of the new trigger
srcthe source of the trigger
topta hash of options for the new trigger; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::TriggerOptions
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that can be used to add a trigger to the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
TRIGGER-ERRORthe table already has a trigger with the given name or invalid options were passed
See Also
inDb() for a method that tells if the table is already in the database or not
Note
if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
string SqlUtil::Table::getAddUniqueConstraintSql ( string  cname,
softlist  cols,
*hash  ukopt,
*hash  opt 
)

returns an SQL string that can be used to add a unique constraint to the table

Example:
my string $sql = $table.getAddUniqueConstraintSql("uk_mytable", "name", ("index_tablespace": "index1"));
printf("%s;\n", $sql);
Parameters
cnamethe name of the new unique constraint
colsa single column name or a list of columns that make up the unique constraint
ukopta hash of options for the new unique constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that can be used to add a unique constraint to the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
UNIQUE-CONSTRAINT-ERRORthe table already has a constraint with the given name or invalid columns passed
See Also
inDb() for a method that tells if the table is already in the database or not
Note
if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
list SqlUtil::Table::getAlignSql ( AbstractTable  table,
*hash  opt 
)

accepts an AbstractTable argument and returns a list of SQL strings required to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty list is returned

Example:
my list $l = $table.getAlignSql($table2);
Parameters
tablethe template table that the current table will be compared to
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings required to align the structure and configuration of the current table with that of the AbstractTable argument; if the tables are identical then an empty list is returned
Exceptions
TABLE-COMPATIBILITY-ERRORthe argument must be of the same class as the current object
OPTION-ERRORinvalid or unsupported option passed
list SqlUtil::Table::getAlignSql ( Table  table,
*hash  opt 
)

accepts an AbstractTable argument and returns a list of SQL strings required to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty list is returned

Example:
my list $l = $table.getAlignSql($table2);
Parameters
tablethe template table that the current table will be compared to
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings required to align the structure and configuration of the current table with that of the AbstractTable argument; if the tables are identical then an empty list is returned
Exceptions
TABLE-COMPATIBILITY-ERRORthe argument must be of the same class as the current object
OPTION-ERRORinvalid or unsupported option passed
string SqlUtil::Table::getAlignSqlString ( AbstractTable  table,
*hash  opt 
)

accepts an AbstractTable argument and returns an SQL string that could be executed to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty string is returned

Example:
my string $sql = $table.getAlignSqlString($table2);
Parameters
tablethe template table that the current table will be compared to
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that could be executed to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty string is returned
Exceptions
ALIGN-TABLE-ERRORthe argument must be of the same class as the current object; template table has no columns
OPTION-ERRORinvalid or unsupported option passed
string SqlUtil::Table::getAlignSqlString ( Table  table,
*hash  opt 
)

accepts an AbstractTable argument and returns an SQL string that could be executed to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty string is returned

Example:
my string $sql = $table.getAlignSqlString($table2);
Parameters
tablethe template table that the current table will be compared to
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that could be executed to align the structure and configuration of the current table with that of the argument; if the tables are identical then an empty string is returned
Exceptions
ALIGN-TABLE-ERRORthe argument must be of the same class as the current object; template table has no columns
OPTION-ERRORinvalid or unsupported option passed
*list SqlUtil::Table::getCreateConstraintsSql ( *hash  opt)

returns a list of SQL strings that could be used to create non-foreign constraints on the table or NOTHING if there are no non-foreign constraints on the table

Example:
my *list $l = $table.getCreateConstraintsSql();
Parameters
opta hash of options for the non-foreign constraint creation string; see SqlUtil::AbstractTable::ConstraintOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that could be used to create non-foreign constraints on the table or NOTHING if there are no non-foreign constraints on the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
See Also
getCreateForeignConstraintsSql()
*list SqlUtil::Table::getCreateForeignConstraintsSql ( *hash  opt)

returns a list of SQL strings that could be used to create foreign constraints on the table or NOTHING if there are no foreign constraints on the table

Example:
my *list $l = $table.getCreateForeignConstraintsSql();
Parameters
opta hash of options for the new foreign constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ForeignConstraintOptions
Returns
a list of SQL strings that could be used to create foreign constraints on the table or NOTHING if there are no foreign constraints on the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
*list SqlUtil::Table::getCreateIndexesSql ( *hash  opt)

returns a list of SQL strings that could be used to create indexes on the table or NOTHING if there are no indexes on the table

Example:
my *list $l = $table.getCreateIndexesSql();
Parameters
opta hash of options for the new index; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::IndexOptions
Returns
a list of SQL strings that could be used to create indexes on the table or NOTHING if there are no indexes on the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
*list SqlUtil::Table::getCreateMiscSql ( *hash  opt)

returns a list of SQL strings that could be used to create other table attributes (such as comments, if supported and present) or NOTHING if there are none

Example:
my *list $l = $table.getCreateMiscSql();
Parameters
opta hash of options for the SQL creation string(s); see SqlUtil::AbstractTable::TableCreationOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that could be used to create other table attributes (such as comments, if supported and present) or NOTHING if there are none
Exceptions
OPTION-ERRORinvalid or unsupported option passed
*string SqlUtil::Table::getCreatePrimaryKeySql ( *hash  opt)

returns an SQL string that could be used to create the primary key on the table

Example:
my *string $sql = $table.getCreatePrimaryKeySql();
Parameters
opta hash of options for the new primary key; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
Returns
an SQL string that could be used to create the primary key on the table or NOTHING if there is no primary key on the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
list SqlUtil::Table::getCreateSql ( *hash  opt)

returns a list of SQL strings that could be used to create the table and all known properties of the table

Example:
map printf("$1;\n", $1), $table.getCreateSql();
Parameters
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::TableCreationOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that could be used to create the table and all known properties of the table
string SqlUtil::Table::getCreateSqlString ( *hash  opt)

returns an SQL string that could be used to create the table and all known properties of the table

Example:
printf("%s\n", $table.getCreateSqlString());
Parameters
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::TableCreationOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that could be used to create the table and all known properties of the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
string SqlUtil::Table::getCreateTableSql ( *hash  opt)

returns an SQL string that could be used to create the basic table structure without indexes and constraints

Example:
my string $sql = $table.getCreateTableSql();
Parameters
opta hash of options for the SQL creation string; see SqlUtil::AbstractTable::TableCreationOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that could be used to create the basic table structure without indexes and constraints
Exceptions
OPTION-ERRORinvalid or unsupported option passed
*list SqlUtil::Table::getCreateTriggersSql ( *hash  opt)

returns a list of SQL strings that could be used to create triggers on the table or NOTHING if there are no triggers on the table

Example:
my *list $l = $table.getCreateTriggersSql();
Parameters
opta hash of options for the trigger creation strings; see SqlUtil::AbstractTable::TableCreationOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that could be used to create triggers on the table or NOTHING if there are no triggers on the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
list SqlUtil::Table::getDropColumnSql ( string  cname,
*hash  opt 
)

returns the SQL that can be used to drop a column from the table

Example:
my list $l = $table.getDropColumnSql("notes_2");
Parameters
cnamethe name of the column to drop
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
the SQL that can be used to drop a column from the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
COLUMN-ERRORthe named column is not present in the table
Note
See Also
inDb() for a method that tells if the table is already in the database or not
*string SqlUtil::Table::getDropConstraintIfExistsSql ( string  cname,
*hash  opt,
*reference  cref 
)

gets the SQL that can be used to drop a constraint from the table if it exists, otherwise returns NOTHING; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint

Example:
my *string $sql = $table.getDropConstraintIfExistsSql("uk_mytable_name");
Parameters
cnamethe name of the constraint to drop
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
crefan optional reference to an AbstractConstraint object that will return the constraint dropped
Returns
the SQL that can be used to drop a constraint from the table if it exists, otherwise returns NOTHING; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint
Exceptions
OPTION-ERRORinvalid or unsupported option passed
Note
  • this method retrieves current constraint definitions from the database if not already loaded or defined
  • if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
See Also
inDb() for a method that tells if the table is already in the database or not
string SqlUtil::Table::getDropConstraintSql ( string  cname,
*hash  opt 
)

gets the SQL that can be used to drop a constraint from the table; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint

Example:
my string $sql = $table.getDropConstraintSql("uk_mytable_name");
Parameters
cnamethe name of the constraint to drop
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
the SQL that can be used to drop a constraint from the table; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint
Exceptions
OPTION-ERRORinvalid or unsupported option passed
CONSTRAINT-ERRORthe given constraint does not exist in the table
Note
  • this method retrieves current constraint definitions from the database if not already loaded or defined
  • if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
See Also
inDb() for a method that tells if the table is already in the database or not
string SqlUtil::Table::getDropIndexSql ( string  iname,
*hash  opt 
)

gets the SQL that can be used to drop an index from the table

Example:
my string $sql = $table.getDropIndexSql("uk_mytable_name");
Parameters
inamethe name of the index to drop
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
the SQL that can be used to drop an index from the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
INDEX-ERRORthe given index does not exist in the table
Note
  • this method retrieves current index definitions from the database if not already loaded or defined
  • if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
See Also
inDb() for a method that tells if the table is already in the database or not
list SqlUtil::Table::getDropPrimaryKeySql ( *hash  opt)

gets a list of SQL strings that can be used to drop the primary key from the table

Example:
my list $l = $table.getDropPrimaryKeySql();
Parameters
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that can be used to drop the primary key from the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
PRIMARY-KEY-ERRORthe table has no primary key
Note
  • this method retrieves current primary key definition from the database if not already loaded or defined
  • if there are known foreign contraints on the primary key, SQL for dropping those constraints is also returned
  • if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
See Also
inDb() for a method that tells if the table is already in the database or not
list SqlUtil::Table::getDropTriggerSql ( string  tname,
*hash  opt 
)

returns SQL that can be used to drop the given trigger from the table

Example:
my list $l = $table.getDropTriggerSql("trig_mytable");
Parameters
tnamethe name of the trigger to drop
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
the SQL that can be used to drop the given trigger from the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
TRIGGER-ERRORthe given trigger does not exist
Note
  • this method retrieves all current trigger definitions from the database if none have already been defined
  • if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
See Also
inDb() for a method that tells if the table is already in the database or not
Indexes SqlUtil::Table::getIndexes ( )

returns an object of class Indexes describing the indexes on the table

If there are no indexes on the table then the object returned will be empty (see SqlUtil::Indexes::empty())

Example:
my Indexes $ix = $table.getIndexes();
Returns
an object of class Indexes describing the indexes on the table
list SqlUtil::Table::getModifyColumnSql ( string  cname,
hash  copt,
bool  nullable = True,
*hash  opt 
)

gets a list of SQL strings that can be used to modify an existing column in the table

Example:
my list $l = $table.getModifyColumnSql("name", ("qore_type": Type::String, "size": 240), False);
Parameters
cnamethe name of the column
copta hash describing the column; the following keys are permitted (other column options may be supported depending on the underlying AbstractTable implementation):
  • qore_type: a qore type string that will be converted to a native DB type with some default conversion;
  • native_type: the native database column type; if both native_type and qore_type are given then native_type is used
  • size: for data types requiring a size component, the size; for numeric columns this represents the precision for example
  • scale: for numeric data types, this value gives the scale
  • default_value: the default value for the column
nullableif True then the column can hold NULL values; note that primary key columns cannot be nullable
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
a list of SQL strings that can be used to modify an existing column in the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
COLUMN-ERRORno native_type or qore_type keys in column option hash, column does not exist, invalid column data
Note
make sure and add a default_value value when modifying a column to have a "not null" constraint with existing data
  • make sure and add a default_value value when modifying a column to have a "not null" constraint with existing data
  • if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
AbstractPrimaryKey SqlUtil::Table::getPrimaryKey ( )

returns an object of class AbstractPrimaryKey describing the primary key of the table

If there is no primary key then the object returned will be empty (see SqlUtil::AbstractPrimaryKey::empty())

Example:
my AbstractPrimaryKey $cols = $table.getPrimaryKey();
Returns
an object of class AbstractPrimaryKey describing the primary key of the table
string SqlUtil::Table::getRenameColumnSql ( string  old_name,
string  new_name,
*hash  opt 
)

gets an SQL string that can be used to rename an existing column in the table

Example:
my string $sql = $table.getRenameColumnSql("name", "family_name");
Parameters
old_namethe current name of the column
new_namethe new name of the column
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that can be used to rename an existing column in the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
COLUMN-ERRORif the given column does not exist in the table
See Also
getModifyColumnSql() for a method that allows the column definition to be updated
Note
if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
string SqlUtil::Table::getRenameSql ( string  new_name,
*hash  opt 
)

returns an SQL string that could be used to rename the table in the database

Example:
my string $sql = $table.getRenameSql("new_name");
Parameters
new_namethe new name for the table
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
an SQL string that could be used to rename the table in the database
Exceptions
OPTION-ERRORinvalid or unsupported option passed
Note
If the sql_callback_executed option key is True, this method also renames the object internally (see SQL CallBack Executed Flag for more information), additionally if the "db_table_cache" option key is assigned to a Tables argument, then the table cache is also updated with the name change in this case
See Also
  • rename()
  • inDb() for a method that tells if the table is already in the database or not
Qore::SQL::SQLStatement SqlUtil::Table::getRowIterator ( *hash  sh,
*reference  sql 
)

returns an SQLStatement object that will iterate the results of a select statement matching the arguments

Example:
my SQLStatement $i = $table.getRowIterator();
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
sqlan optional reference to a string to return the SQL generated for the select statement
Returns
an SQLStatement object that will iterate the results of a select statement matching the arguments
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
  • if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
  • the SQLStatement object created by a successful call to this method acquires a thread resource for the underlying AbstractDatasource object that must be released by calling commit() or rollback(), even if the statement does not acquire any database locks
Qore::SQL::SQLStatement SqlUtil::Table::getRowIterator ( *hash  sh,
*hash  opt 
)

returns an SQLStatement object that will iterate the results of a select statement matching the arguments

Example:
my SQLStatement $i = $table.getRowIterator();
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
an SQLStatement object that will iterate the results of a select statement matching the arguments
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
  • if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
  • the SQLStatement object created by a successful call to this method acquires a thread resource for the underlying AbstractDatasource object that must be released by calling commit() or rollback(), even if the statement does not acquire any database locks
string SqlUtil::Table::getSelectSql ( *hash  sh,
*reference  args 
)

returns the SQL string to be executed corresponding to the argument hash with an output parameter for the select bind arguments

Example:
my list $args;
my string $sql = $table.getSelectSql($sh, \$args);
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
argsan optional reference to a list for any bind arguments
Returns
the SQL that can be used to execute a select on the database corresponding to the arguments; the select bind arguments are returned in an output parameter
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
  • the select string is specific to the arguments passed (for example NULL arguments will have clauses like 'is null')
  • if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
string SqlUtil::Table::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
string SqlUtil::Table::getSqlValue ( any  v)

returns a string for use in SQL queries representing the DB-specific value of the argument

Example:
my string $str = $table.getSqlValue($date);
Parameters
vthe value to convert to an SQL value
Returns
a string representing the value usable in SQL strings for the given database driver
Exceptions
VALUE-ERRORthe given value cannot be converted to an SQL string (missing rules for value)
Triggers SqlUtil::Table::getTriggers ( )

returns an object of class Triggers describing the triggers on the table

If there are no triggers on the table then the object returned will be empty (see SqlUtil::Triggers::empty())

Example:
my Triggers $trig = $table.getTriggers();
Returns
an object of class Triggers describing the triggers on the table
string SqlUtil::Table::getTruncateSql ( *hash  opt)

gets the SQL that can be used to truncate the table

Example:
my string $sql = $table.getTruncateSql();
Parameters
opta hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
Returns
the SQL that can be used to truncate the table
Exceptions
OPTION-ERRORinvalid or unsupported option passed
See Also
inDb() for a method that tells if the table is already in the database or not
Note
if the sql_callback_executed option is True in opt, then the changes are also effected in the current object, if not, then they are not (see SQL CallBack Executed Flag for more information)
Qore::AbstractIterator SqlUtil::Table::getUniqueConstraintIterator ( )

returns an iterator for all unique constraints on the table (including the primary key if any)

Example:
map printf("unique constraint %s\n", $1.getName()), $table.getUniqueConstraintIterator();
Returns
an iterator for all unique constraints on the table (including the primary key if any)
code SqlUtil::Table::getUpsertClosure ( hash  example_row,
int  upsert_strategy = AbstractTable::UpsertAuto 
)

returns a closure that can be executed given a hash argument representing a single row that will be updated or inserted in the database with the given upsert strategy; the table must have a unique key to do this; the closure returned does not check the input hash for validity

Example:
my Datasource $ds("pgsql:user/pass@db%localhost");
my Table $table($ds, "table_name");
my code $upsert = $table.getUpsertClosure($row, AbstractTable::UpsertSelectFirst);
on_success $ds.commit();
on_error $ds.rollback();
map $upsert($1), $row_list;
Parameters
example_rowa hash representing an example row to insert or update; every row passed to the upsert closure returned must have the same keys in the same order
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
Returns
a closure that can be executed given a hash argument representing a single row that will be updated or inserted in the database with the given upsert strategy; the closure returned does not check the input hash for validity; the closure has the following signature:
int sub upsert(hash $row) {}
The return value of the closuse is an integer code giving the result of the update; see Upsert Result Codes for more information
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
the row values passed to the closure for upserting are not checked if they match the example row passed to the getUpsertClosure() method; passing non-conforming data will cause errors; see SqlUtil::AbstractTable::getUpsertClosureWithValidation() for a similar method that returns a validating closure; the closure returned by this method is faster than the one returned by SqlUtil::AbstractTable::getUpsertClosure() since there is no validation
See Also
code SqlUtil::Table::getUpsertClosureWithValidation ( hash  example_row,
int  upsert_strategy = AbstractTable::UpsertAuto 
)

returns a closure that can be executed given a hash argument representing a single row that will be updated or inserted in the database with the given upsert strategy; the table must have a unique key to do this; the closure returned validates the input hash for validity

Example:
my Datasource $ds("pgsql:user/pass@db%localhost");
my Table $table($ds, "table_name");
my code $upsert = $table.getUpsertClosureWithValidation($row, AbstractTable::UpsertSelectFirst);
on_success $ds.commit();
on_error $ds.rollback();
map $upsert($1), $row_list;
Parameters
example_rowa hash representing an example row to insert or update; every row passed to the upsert closure returned must have the same keys in the same order or the closure returned will throw an UPSERT-ERROR exception
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
Returns
a closure that can be executed given a hash argument representing a single row that will be updated or inserted in the database with the given upsert strategy; the closure has the following signature:
int sub upsert(hash $row) {}
The return value of the closuse is an integer code giving the result of the update; see Upsert Result Codes for more information
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
the row values passed to the closure for upserting are checked if they match the example row passed to the getUpsertClosure() method; passing non-conforming data to the closure will cause the closure to throw an UPSERT-ERROR exception; see SqlUtil::AbstractTable::getUpsertClosure() for a similar method that returns a non-validating closure; the closure returned by this method is a little slower than the one returned by SqlUtil::AbstractTable::getUpsertClosure() since each row is validated
See Also
bool SqlUtil::Table::inDb ( )

returns True if the table has been read from or created in the database, False if not

Example:
my bool $b = $table.inDb();
Returns
True if the table has been read from or created in the database, False if not
SqlUtil::Table::insert ( hash  row,
*reference  sql 
)

inserts a row into the table; the transaction is committed if successful, if an error occurs, it is rolled back

Example:
$table.insert($row);
Parameters
rowa hash representing the row to insert
sqlan optional reference to a string to return the SQL generated for the insert statement
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
SqlUtil::Table::insert ( hash  row,
*hash  opt 
)

inserts a row into the table; the transaction is committed if successful, if an error occurs, it is rolled back

Example:
$table.insert($row);
Parameters
rowa hash representing the row to insert
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
int SqlUtil::Table::insertFromIterator ( Qore::AbstractIterator  i,
*hash  opt 
)

this method inserts data from the given iterator argument (whose getValue() method must return a hash giving row values) into the current table; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
my int $rows = $table.insertFromIterator($i);
Parameters
ithe Qore::AbstractIterator argument that will provide the data to insert into the current table; the getValue() method of this object must return a hash giving row values (for example, the Qore::SQL::SQLStatement class is well-suited to be used here); note that the iterator is assumed to return the same columns in the same order in every element
opta hash of options for the insert operation; see SqlUtil::AbstractTable::InsertOptions for common options; each driver can support additional driver-specific options
Returns
the number of rows inserted
Exceptions
OPTION-ERRORinvalid or unsupported option
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
See Also
int SqlUtil::Table::insertFromIteratorNoCommit ( Qore::AbstractIterator  i,
*hash  opt 
)

this method inserts data from the given iterator argument (whose getValue() method must return a hash giving row values) into the current table; no transaction management is performed with this method

Example:
my int $rows = $table.insertFromIteratorNoCommit($i);
Parameters
ithe Qore::AbstractIterator argument that will provide the data to insert into the current table; the getValue() method of this object must return a hash giving row values (for example, the Qore::SQL::SQLStatement class is well-suited to be used here); note that the iterator is assumed to return the same columns in the same order in every element
opta hash of options for the insert operation; see SqlUtil::AbstractTable::InsertOptions for common options; each driver can support additional driver-specific options
Returns
the number of rows inserted
Exceptions
OPTION-ERRORinvalid or unsupported option
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
See Also
int SqlUtil::Table::insertFromSelect ( list  cols,
AbstractTable  source,
*hash  sh,
*reference  sql 
)

inserts rows into a table based on a select statement from another table (which must be using the same datasource as the current table); the transaction is committed if successful, if an error occurs, it is rolled back

Example:
my int $rows = $table.insertFromSelect(("id", "name", "created"), $source_table, (("columns": ("id", "name", "created"), "where": ("type": "CUSTOMER"))));
Parameters
colsthe list of column names to use to insert in the current table
sourcethe source table for the select statement
sha hash of conditions for the select statement; see select option hash for information about this argument
sqlan optional reference to a string to return the SQL generated for the select statement
Returns
the number of rows inserted
Exceptions
OPTION-ERRORinvalid or unsupported option
COLUMN-ERRORunknown or invalid column in insert list
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
this method does not take insert options because it is executed entirely in the database server; use insertFromIterator() or insertFromIteratorNoCommit() to insert arbitrary data with insert options
int SqlUtil::Table::insertFromSelect ( list  cols,
AbstractTable  source,
*hash  sh,
*hash  opt 
)

inserts rows into a table based on a select statement from another table (which must be using the same datasource as the current table); the transaction is committed if successful, if an error occurs, it is rolled back

Example:
my int $rows = $table.insertFromSelect(("id", "name", "created"), $source_table, (("columns": ("id", "name", "created"), "where": ("type": "CUSTOMER"))));
Parameters
colsthe list of column names to use to insert in the current table
sourcethe source table for the select statement
sha hash of conditions for the select statement; see select option hash for information about this argument
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
the number of rows inserted
Exceptions
OPTION-ERRORinvalid or unsupported option
COLUMN-ERRORunknown or invalid column in insert list
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
this method does not take insert options because it is executed entirely in the database server; use insertFromIterator() or insertFromIteratorNoCommit() to insert arbitrary data with insert options
int SqlUtil::Table::insertFromSelectNoCommit ( list  cols,
AbstractTable  source,
*hash  sh,
*reference  sql 
)

inserts rows into a table based on a select statement from another table (which must be using the same datasource as the current table); a transaction will be in progress after this method is successfully executed

Example:
my int $rows = $table.insertFromSelectNoCommit(("id", "name", "created"), $source_table, (("columns": ("id", "name", "created"), "where": ("type": "CUSTOMER"))));
Parameters
colsthe list of column names to use to insert in the current table
sourcethe source table for the select statement
sha hash of conditions for the select statement; see select option hash for information about this argument
sqlan optional reference to a string to return the SQL generated for the select statement
Returns
the number of rows inserted
Exceptions
OPTION-ERRORinvalid or unsupported option
COLUMN-ERRORunknown or invalid column in insert list
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
this method does not take insert options because it is executed entirely in the database server; use insertFromIterator() or insertFromIteratorNoCommit() to insert arbitrary data with insert options
int SqlUtil::Table::insertFromSelectNoCommit ( list  cols,
AbstractTable  source,
*hash  sh,
*hash  opt 
)

inserts rows into a table based on a select statement from another table (which must be using the same datasource as the current table); a transaction will be in progress after this method is successfully executed

Example:
my int $rows = $table.insertFromSelectNoCommit(("id", "name", "created"), $source_table, (("columns": ("id", "name", "created"), "where": ("type": "CUSTOMER"))));
Parameters
colsthe list of column names to use to insert in the current table
sourcethe source table for the select statement
sha hash of conditions for the select statement; see select option hash for information about this argument
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
the number of rows inserted
Exceptions
OPTION-ERRORinvalid or unsupported option
COLUMN-ERRORunknown or invalid column in insert list
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
this method does not take insert options because it is executed entirely in the database server; use insertFromIterator() or insertFromIteratorNoCommit() to insert arbitrary data with insert options
SqlUtil::Table::insertNoCommit ( hash  row,
*reference  sql 
)

inserts a row into the table without any transaction management; a transaction will be in progress after this method is successfully executed

Example:
$table.insertNoCommit($row);
Parameters
rowa hash representing the row to insert
sqlan optional reference to a string to return the SQL generated for the insert statement
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
SqlUtil::Table::insertNoCommit ( hash  row,
*hash  opt 
)

inserts a row into the table without any transaction management; a transaction will be in progress after this method is successfully executed

Example:
$table.insertNoCommit($row);
Parameters
rowa hash representing the row to insert
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
AbstractColumn SqlUtil::Table::modifyColumn ( string  cname,
hash  opt,
bool  nullable = True,
*reference  lsql 
)

modifies an existing column in the table; if the table already exists, then the changes are effected in the database also immediately; otherwise it is only updated internally and the new column definition will be created when create() is called for example

Example:
$table.modifyColumn("name", ("qore_type": Type::String, "size": 240), False);

In case the table is already in the database, this method commits the transaction on success and rolls back the transaction if there's an error.

Parameters
cnamethe name of the column
opta hash describing the column; the following keys are permitted (other column options may be supported depending on the underlying AbstractTable implementation):
  • qore_type: a qore type string that will be converted to a native DB type with some default conversion;
  • native_type: the native database column type; if both native_type and qore_type are given then native_type is used
  • size: for data types requiring a size component, the size; for numeric columns this represents the precision for example
  • scale: for numeric data types, this value gives the scale
  • default_value: the default value for the column
lsqlan optional reference to a list of strings to retrieve the SQL used to modify the table (only executed if the table is already in the database)
nullableif True then the column can hold NULL values; note that primary key columns cannot be nullable
Exceptions
COLUMN-ERRORno native_type or qore_type keys in column option hash, column does not exist, invalid column data
Note
make sure and add a default_value value when modifying a column to have a "not null" constraint with existing data
See Also
  • inDb() for a method that tells if the table is already in the database or not
  • renameColumn() for a method that allows the column name to be changed
AbstractForeignConstraint SqlUtil::Table::removeForeignConstraint ( string  cname)

removes the named foreign constraint from the table; no SQL is executed in any case, only the named foreign constraint is removed from the table definition

Example:
$table.removeForeignConstraint("uk_mytable_name");
Parameters
cnamethe name of the foreign constraint to remove
Returns
the foreign constraint removed from the table
Exceptions
FOREIGN-CONSTRAINT-ERRORthe given constraint does not exist
Note
this method retrieves all current foreign constraint definitions from the database if none have already been defined
See Also
inDb() for a method that tells if the table is already in the database or not
SqlUtil::Table::rename ( string  new_name,
*reference  sql,
*Tables  table_cache 
)

renames the table; if the table already exists in the database, then the changes are effected in the database also immediately; otherwise it is only updated internally

Example:
$table.rename("new_name");
Parameters
new_namethe new name for the table
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
table_cachean optional Tables argument to update the table name in any table cache
See Also
getRenameSql()
AbstractColumn SqlUtil::Table::renameColumn ( string  old_name,
string  new_name,
reference  sql 
)

renames an existing column; if the table already exists, then the changes are effected in the database also immediately; otherwise it is only updated internally

Example:
my AbstractColumn $col = $table.renameColumn("name", "family_name");
Parameters
old_namethe current name of the column
new_namethe new name for the column
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
the column object that was updated
Exceptions
COLUMN-ERRORif the given column does not exist in the table
See Also
modifyColumn() for a method that allows the column definition to be updated
Note
if any primary key or foreign table constraints refer to the column, the internal reprepsentations are also renamed, however check constraints are not updated and will be invalid if they refer to the renamed column
AbstractConstraint SqlUtil::Table::renameConstraint ( string  old_name,
string  new_name,
reference  lsql 
)

renames an existing constraint; this can be any constraint on the table, a primary key, a foreign key constraint, or a generic constraint; if the table is already known to be in the database, then the changes are effected in the database also immediately; otherwise it is only updated internally

Example:
my AbstractConstraint $con = $table.renameConstraint("pk_table_name", "pkey_table_name");
Parameters
old_namethe current name of the constraint
new_namethe new name for the constraint
lsqlan optional reference to a list of strings to retrieve the SQL used to modify the constraint (only executed if the table is already in the database)
Returns
the constraint object that was updated
Exceptions
CONSTRAINT-ERRORif the old constraint does not exist in the table or if the new constraint name already exists
AbstractIndex SqlUtil::Table::renameIndex ( string  old_name,
string  new_name,
reference  sql 
)

renames an existing index; if the table is already known to be in the database, then the changes are effected in the database also immediately; otherwise it is only updated internally

Example:
my AbstractIndex $ix = $table.renameIndex("uk_table_name", "unique_table_name");
Parameters
old_namethe current name of the index
new_namethe new name for the index
sqlan optional reference to a string to retrieve the SQL used to modify the table (only executed if the table is already in the database)
Returns
the index object that was updated
Exceptions
INDEX-ERRORif the old index does not exist in the table or if the new index name already exists
softint SqlUtil::Table::rowCount ( )

returns the number of rows in the table

Example:
my int $cnt = $table.rowCount();
Returns
the number of rows in the table
Note
to see if the table is empty or not, use emptyData() as this is much faster than rowCount()
See Also
emptyData()
*hash SqlUtil::Table::select ( *hash  sh,
*reference  sql 
)

returns a hash of lists representing the columns and rows in the table that match the argument hahs

Example:
my *hash $h = $table.select($sh);
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
sqlan optional reference to a string to return the SQL generated for the select statement
Returns
a hash of lists representing the columns and rows in the table that match the argument hash
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
*hash SqlUtil::Table::select ( *hash  sh,
*hash  opt 
)

returns a hash of lists representing the columns and rows in the table that match the argument hahs

Example:
my *hash $h = $table.select($sh);
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
a hash of lists representing the columns and rows in the table that match the argument hash
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
*hash SqlUtil::Table::selectRow ( *hash  sh,
*reference  sql 
)

returns a hash representing the row in the table that matches the argument hash; if more than one row would be returned an exception is raised

Example:
my *hash $h = $table.selectRow($sh);
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
sqlan optional reference to a string to return the SQL generated for the select statement
Returns
a hash representing the row in the table that matches the argument hash; if more than one row would be returned an exception is raised
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
DBI-SELECT-ROW-ERRORmore than 1 row retrieved from the server
Note
if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
*hash SqlUtil::Table::selectRow ( *hash  sh,
*hash  opt 
)

returns a hash representing the row in the table that matches the argument hash; if more than one row would be returned an exception is raised

Example:
my *hash $h = $table.selectRow($sh);
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
a hash representing the row in the table that matches the argument hash; if more than one row would be returned an exception is raised
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
DBI-SELECT-ROW-ERRORmore than 1 row retrieved from the server
Note
if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
*list SqlUtil::Table::selectRows ( *hash  sh,
*reference  sql 
)

returns a list of hashes representing the rows in the table that match the argument hash

Example:
my *list $l = $table.selectRows($sh);
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
sqlan optional reference to a string to return the SQL generated for the select statement
Returns
a list of hashes representing the rows in the table that match the argument hash
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
*list SqlUtil::Table::selectRows ( *hash  sh,
*hash  opt 
)

returns a list of hashes representing the rows in the table that match the argument hash

Example:
my *list $l = $table.selectRows($sh);
Parameters
sha hash of conditions for the select statement; see select option hash for information about this argument
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
a list of hashes representing the rows in the table that match the argument hash
Exceptions
OPTION-ERRORinvalid or unsupported select option
SELECT-ERROR'offset' supplied without 'orderby' or 'limit', 'orderby' with 'limit' and 'offset' does not match any unique constraint
Note
if "offset" is supplied and no "orderby" is supplied, then if any primary key exists, the primary key columns will be used for the "orderby" option automatically
SqlUtil::Table::setDatasource ( AbstractDatasource  nds)

changes the datasource for the table; if the inDb flag is True, then it is set to False by calling this method

Example:
my Table $table($ds1, "table_name");
$table.setDatasource($ds2);
$table.create();
Parameters
ndsthe new datasource for the table
Note
it's generally not safe to call this method while SQL operations are in progress in other threads on the same table
SqlUtil::Table::setupTable ( hash  desc,
*hash  opt 
)

creates the object from a table description hash

Parameters
desca table description hash describing the table
optan 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
DESCRIPTION-ERRORinvalid or unsupported description hash value passed
SqlUtil::Table::truncate ( )

truncates all the table data; releases the transaction lock after executing

Example:
$table.truncate();
Note
The transaction is committed if successful or rolled back if an exception occurs; use truncateNoCommit() to execute without any transaction management
SqlUtil::Table::truncateNoCommit ( )

truncates all the table data without any transaction management

Example:
$table.truncateNoCommit();
Note
Transaction management may not be applied when truncating tables depending on the database driver (for example truncating tables in Oracle does not participate in transaction management), however this method uses the Qore::SQL::AbstractDatasource::exec() method, which normally participates in acquiring a transaction lock for the underlying datasource object; therefore after this method executes normally the transaction lock will be dedicated to the calling thread.
any SqlUtil::Table::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::Table::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::Table::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
int SqlUtil::Table::update ( hash  set,
*hash  cond,
*reference  sql 
)

updates rows in the table matching an optional condition and returns the count of rows updated; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
my int $ucnt = $table.update(("id": $id), ("name": $name));
Parameters
setthe hash of values to set, key values are column names, hash values are the values to assign to those columns or update operators (see SQL Update Operator Functions)
conda hash of conditions for the where clause; see Where Clauses for more information
sqlan optional reference to a string to return the SQL generated for the update statement
Returns
the count of rows updated
Exceptions
UPDATE-ERRORthe set hash is empty
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
See Also
updateNoCommit()
int SqlUtil::Table::update ( hash  set,
*hash  cond,
*hash  opt 
)

updates rows in the table matching an optional condition and returns the count of rows updated; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
my int $ucnt = $table.update(("id": $id), ("name": $name));
Parameters
setthe hash of values to set, key values are column names, hash values are the values to assign to those columns or update operators (see SQL Update Operator Functions)
conda hash of conditions for the where clause; see Where Clauses for more information
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
the count of rows updated
Exceptions
UPDATE-ERRORthe set hash is empty
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
See Also
updateNoCommit()
int SqlUtil::Table::updateNoCommit ( hash  set,
*hash  cond,
*reference  sql 
)

updates rows in the table matching an optional condition and returns the count of rows updated; no transaction management is performed with this method

Example:
my int $ucnt = $table.updateNoCommit(("id": $id), ("name": $name));
Parameters
setthe hash of values to set, key values are column names, hash values are the values to assign to those columns or update operators (see SQL Update Operator Functions)
conda hash of conditions for the where clause; see Where Clauses for more information
sqlan optional reference to a string to return the SQL generated for the update statement
Returns
the count of rows updated
Exceptions
UPDATE-ERRORthe set hash is empty
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
See Also
update()
int SqlUtil::Table::updateNoCommit ( hash  set,
*hash  cond,
*hash  opt 
)

updates rows in the table matching an optional condition and returns the count of rows updated; no transaction management is performed with this method

Example:
my int $ucnt = $table.updateNoCommit(("id": $id), ("name": $name));
Parameters
setthe hash of values to set, key values are column names, hash values are the values to assign to those columns or update operators (see SQL Update Operator Functions)
conda hash of conditions for the where clause; see Where Clauses for more information
optoptional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info
Returns
the count of rows updated
Exceptions
UPDATE-ERRORthe set hash is empty
WHERE-ERRORunknown operator or invalid arguments given in the cond hash for the where clause
See Also
update()
int SqlUtil::Table::upsert ( hash  row,
int  upsert_strategy = AbstractTable::UpsertAuto 
)

update or insert the data in the table according to the hash argument; the table must have a unique key to do this; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
$table.upsert($row);
Parameters
rowa hash representing the row to insert or update
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
Returns
an integer code giving the result of the update; see Upsert Result Codes for more information
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
if upserting multiple rows; it's better to use getUpsertClosure() or getUpsertClosureWithValidation() and execute the closure on each row; when using this method, the overhead for setting up the upsert is made for each row which is very inefficient
See Also
*hash SqlUtil::Table::upsertFromIterator ( Qore::AbstractIterator  i,
int  upsert_strategy = AbstractTable::UpsertAuto,
*hash  opt 
)

this method upserts or merges data from the given iterator argument (whose getValue() method must return a hash giving row values) into the current table; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
my hash $h = $table.upsertFromIterator($i, AbstractTable::UpsertUpdateFirst);
Parameters
ithe Qore::AbstractIterator argument that will provide the data to upsert or merge into the current table; the getValue() method of this object must return a hash giving row values (for example, the Qore::SQL::SQLStatement class is well-suited to be used here)
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
opta hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options
Returns
NOTHING if no actions were taken or a hash with the following keys assigned to numeric values indicating the number of rows processed (keys correspond to SqlUtil::AbstractTable::UpsertResultDescriptionMap keys):
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
if upsert option delete_others is True, then a hash of primary key values in the input data is built as the input data is iterated. After iterating, if the row count of the table and the input data matches, then nothing more is done, otherwise, every row of the table is iterated and compared to the primary key hash; if a row does not match a primary key value, then it is deleted. This operation is only executed if delete_others is True and is expensive for large data sets.
See Also
*hash SqlUtil::Table::upsertFromIteratorNoCommit ( Qore::AbstractIterator  i,
int  upsert_strategy = AbstractTable::UpsertAuto,
*hash  opt 
)

this method upserts or merges data from the given iterator argument (whose getValue() method must return a hash giving row values) into the current table; no transaction management is performed with this method

Example:
my hash $h = $table.upsertFromIteratorNoCommit($i, AbstractTable::UpsertUpdateFirst);
Parameters
ithe Qore::AbstractIterator argument that will provide the data to upsert or merge into the current table; the getValue() method of this object must return a hash giving row values (for example, the Qore::SQL::SQLStatement class is well-suited to be used here)
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
opta hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options
Returns
NOTHING if no actions were taken or a hash with the following keys assigned to numeric values indicating the number of rows processed (keys correspond to SqlUtil::AbstractTable::UpsertResultDescriptionMap keys):
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
if upsert option delete_others is True, then a hash of primary key values in the input data is built as the input data is iterated. After iterating, if the row count of the table and the input data matches, then nothing more is done, otherwise, every row of the table is iterated and compared to the primary key hash; if a row does not match a primary key value, then it is deleted. This operation is only executed if delete_others is True and is expensive for large data sets.
See Also
*hash SqlUtil::Table::upsertFromSelect ( AbstractTable  src,
*hash  sh,
int  upsert_strategy = AbstractTable::UpsertAuto,
*hash  opt 
)

this method upserts or merges data from the given foreign table and select option hash into the current table; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
my hash $h = $table.upsertFromSelect($table2, ("where": ("account_type": "CUSTOMER")), AbstractTable::UpsertUpdateFirst);

The table argument does not need to be in the same database as the current table; it can also be in a different database server or a database server of a different type (you can use this method to upsert or merge data to or from any database supported by SqlUtil).

Parameters
srcthe table for the source data; this does not need to be in the same database as the target (the current table), nor does it need to be the same database type
sha hash of conditions for the select statement; see select option hash for information about this argument
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
opta hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options
Returns
NOTHING if no actions were taken or a hash with the following keys assigned to numeric values indicating the number of rows processed (keys correspond to SqlUtil::AbstractTable::UpsertResultDescriptionMap keys):
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
  • if upsert option delete_others is True, then a hash of primary key values in the input data is built as the input data is iterated. After iterating, if the row count of the table and the input data matches, then nothing more is done, otherwise, every row of the table is iterated and compared to the primary key hash; if a row does not match a primary key value, then it is deleted. This operation is only executed if delete_others is True and is expensive for large data sets.
  • this method also calls commit() or rollback() on the source table to release the transaction lock on the underlying source table datasource as an SQLStatement object is used to pipeline the data to the upsert code; use upsertFromSelectNoCommit() to do manual transaction management instead
  • unlike insertFromSelect() and insertFromSelectNoCommit(), this method processes arbitrary input data and accepts upsert options
See Also
*hash SqlUtil::Table::upsertFromSelect ( Table  src,
*hash  sh,
int  upsert_strategy = AbstractTable::UpsertAuto,
*hash  opt 
)

this method upserts or merges data from the given foreign table and select option hash into the current table; the transaction is committed if successful, if an error occurs then it is rolled back

Example:
my hash $h = $table.upsertFromSelect($table2, ("where": ("account_type": "CUSTOMER")), AbstractTable::UpsertUpdateFirst);

The table argument does not need to be in the same database as the current table; it can also be in a different database server or a database server of a different type (you can use this method to upsert or merge data to or from any database supported by SqlUtil).

Parameters
srcthe table for the source data; this does not need to be in the same database as the target (the current table), nor does it need to be the same database type
sha hash of conditions for the select statement; see select option hash for information about this argument
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
opta hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options
Returns
NOTHING if no actions were taken or a hash with the following keys assigned to numeric values indicating the number of rows processed (keys correspond to SqlUtil::AbstractTable::UpsertResultDescriptionMap keys):
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
  • if upsert option delete_others is True, then a hash of primary key values in the input data is built as the input data is iterated. After iterating, if the row count of the table and the input data matches, then nothing more is done, otherwise, every row of the table is iterated and compared to the primary key hash; if a row does not match a primary key value, then it is deleted. This operation is only executed if delete_others is True and is expensive for large data sets.
  • this method also calls commit() or rollback() on the source table to release the transaction lock on the underlying source table datasource as an SQLStatement object is used to pipeline the data to the upsert code; use upsertFromSelectNoCommit() to do manual transaction management instead
  • unlike insertFromSelect() and insertFromSelectNoCommit(), this method processes arbitrary input data and accepts upsert options
See Also
*hash SqlUtil::Table::upsertFromSelectNoCommit ( AbstractTable  src,
*hash  sh,
int  upsert_strategy = AbstractTable::UpsertAuto,
*hash  opt 
)

this method upserts or merges data from the given foreign table and select option hash into the current table; no transaction management is performed with this method

Example:
on_success { $table.commit(); $table2.commit(); }
on_error { $table.rollback(); $table2.rollback(); }
my hash $h = $table.upsertFromSelectNoCommit($table2, ("where": ("account_type": "CUSTOMER")), AbstractTable::UpsertUpdateFirst);

The table argument does not need to be in the same database as the current table; it can also be in a different database server or a database server of a different type (you can use this method to upsert or merge data to or from any database supported by SqlUtil).

Parameters
srcthe table for the source data; this does not need to be in the same database as the target (the current table), nor does it need to be the same database type
sha hash of conditions for the select statement; see select option hash for information about this argument
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
opta hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options
Returns
NOTHING if no actions were taken or a hash with the following keys assigned to numeric values indicating the number of rows processed (keys correspond to SqlUtil::AbstractTable::UpsertResultDescriptionMap keys):
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
  • if upsert option delete_others is True, then a hash of primary key values in the input data is built as the input data is iterated. After iterating, if the row count of the table and the input data matches, then nothing more is done, otherwise, every row of the table is iterated and compared to the primary key hash; if a row does not match a primary key value, then it is deleted. This operation is only executed if delete_others is True and is expensive for large data sets.
*hash SqlUtil::Table::upsertFromSelectNoCommit ( Table  src,
*hash  sh,
int  upsert_strategy = AbstractTable::UpsertAuto,
*hash  opt 
)

this method upserts or merges data from the given foreign table and select option hash into the current table; no transaction management is performed with this method

Example:
on_success { $table.commit(); $table2.commit(); }
on_error { $table.rollback(); $table2.rollback(); }
my hash $h = $table.upsertFromSelectNoCommit($table2, ("where": ("account_type": "CUSTOMER")), AbstractTable::UpsertUpdateFirst);

The table argument does not need to be in the same database as the current table; it can also be in a different database server or a database server of a different type (you can use this method to upsert or merge data to or from any database supported by SqlUtil).

Parameters
srcthe table for the source data; this does not need to be in the same database as the target (the current table), nor does it need to be the same database type
sha hash of conditions for the select statement; see select option hash for information about this argument
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
opta hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options
Returns
NOTHING if no actions were taken or a hash with the following keys assigned to numeric values indicating the number of rows processed (keys correspond to SqlUtil::AbstractTable::UpsertResultDescriptionMap keys):
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
  • if upsert option delete_others is True, then a hash of primary key values in the input data is built as the input data is iterated. After iterating, if the row count of the table and the input data matches, then nothing more is done, otherwise, every row of the table is iterated and compared to the primary key hash; if a row does not match a primary key value, then it is deleted. This operation is only executed if delete_others is True and is expensive for large data sets.
int SqlUtil::Table::upsertNoCommit ( hash  row,
int  upsert_strategy = AbstractTable::UpsertAuto 
)

update or insert the data in the table according to the hash argument; the table must have a unique key to do this; no transaction management is performed with this method

Example:
$table.upsertNoCommit($row);
Parameters
rowa hash representing the row to insert or update
upsert_strategysee Upsert Strategy Codes for possible values for the upsert strategy
Returns
an integer code giving the result of the update; see Upsert Result Codes for more information
Exceptions
COLUMN-ERRORan unknown column was referenced in the hash to be inserted
UPSERT-ERRORno primary key, unique constraint, or unique index for upsert; not all columns of the unique constraint/index are used in the upsert statement
Note
if upserting multiple rows; it's better to use getUpsertClosure() or getUpsertClosureWithValidation() and execute the closure on each row; when using this method, the overhead for setting up the upsert is made for each row which is very inefficient
See Also