Qore SqlUtil Module Reference 1.0

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

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

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Public Attributes | Private Member Functions | Private Attributes | List of all members
SqlUtil::AbstractTable Class Referenceabstract

the base abstract class for the table implementation More...

Inheritance diagram for SqlUtil::AbstractTable:
[legend]

## 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 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...
AbstractForeignConstraint | addForeignConstraint (string cname, softlist cols, string table, *softlist tcols, *hash opt, *reference sql)
| adds a 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 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...
AbstractPrimaryKey | addPrimaryKey (string pkname, softlist cols, *hash opt, *reference sql)
| adds a primary key 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...
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...
bool | checkExistence ()
| returns True if the table exists in the database, False if not
| clear ()
| purges the current table definition More...
| commit ()
| commits the current transaction on the underlying Qore::SQL::AbstractDatasource
| copy (AbstractTable old)
| copies the object
| 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 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 a 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 given 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 t, *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 t, *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 the non-foreign constraints on the table
*list | getCreateConstraintsSql (*hash opt, bool cache=True)
| 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, bool cache=True)
| 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, bool cache=True)
| 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, bool cache=True)
| 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, bool cache=True)
| 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, bool cache=True)
| 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...
list | getDropAllConstraintsAndIndexesOnColumnSql (string cname, *hash opt)
| gets a list of SQL strings to drop all constraints and indexes with the given column name; if the column does not exist then an empty list is returned More...
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...
softlist | getDropSql (*hash opt)
| returns the sql required to drop the table; reimplement in subclasses if necessary 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 | getSqlName ()
| returns the name of the table to be used in SQL (with a possible qualifiers for schema, etc)
string | getSqlValue (any v)
| returns a string for use in SQL queries representing the DB-specific value of the argument More...
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=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=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 checks 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...
AbstractColumn | modifyColumn (string cname, hash opt, bool nullable=True, *reference lsql)
| modifies an existing column in the table; 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 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 is already known to be in the database 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 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...
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=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 t, *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 t, *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 t, *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 t, *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=UpsertAuto)
| update or insert the data in the table according to the hash argument; the table must have a unique key to do this More...
Public Member Functions inherited from SqlUtil::AbstractSqlUtilBase
Qore::SQL::AbstractDatasource | getDatasource ()
| gets the underlying AbstractDatasource
string | getDatasourceDesc ()
| returns a descriptive string for the datasource
string | getDriverName ()
| returns the database driver name

## Public Attributes
const | AdditionalColumnDescOptions
| additional column description keys valid when describing columns in a table description hash More...
const | AlignTableOptions
| table alignment options More...
const | CacheOptions
| default cache options
const | ColumnDescOptions
| Column description options. More...
const | ColumnOptions = hash()
| Column options; this is currently empty and can be extended in database-specific modules.
const | ConstraintOptions = IndexOptions
| default constraint options More...
const | ForeignConstraintOptions
| default foreign constraint options More...
const | IndexOptions
| default index options More...
const | InsertOptions
| default insert option keys More...
const | SelectOptions
| default select options More...
const | SqlDataCallbackOptions
| generic SQL data operation callbacks More...
const | TableCreationOptions
| table creation options More...
const | TableDescriptionHashOptions
| Table description options. More...
const | TableOmissionOptions
| alignment omission options
const | TableOptions
| table options More...
const | TriggerOptions = AbstractDatabase::CreationOptions
| default trigger options More...
const | UpsertAuto = 4
| Upsert option: if the target table is empty, use UpsertInsertFirst, otherwise use UpsertUpdateFirst. More...
const | UpsertInsertFirst = 1
| Upsert option: insert first, if the insert fails, then update. More...
const | UpsertOptions
| default upsert option keys More...
const | UpsertResultDescriptionMap
| hash mapping upsert descriptions to codes More...
const | UpsertResultLetterMap
| maps upsert result codes to single letter symbols
const | UpsertResultMap
| hash mapping upsert results to a description More...
const | UpsertSelectFirst = 3
| Upsert option: select first, if the row is unchanged, do nothing, if it doesn't exist, insert, otherwise update. More...
const | UpsertUpdateFirst = 2
| Upsert option: update first, if the update fails, then insert. More...
const | UR_Deleted = 5
| row was deleted (only possible with batch upsert methods such as Table::upsertFromIterator() where upsert option `delete_others` is True)
const | UR_Inserted = 1
| row was inserted
const | UR_Unchanged = 4
| row was unchanged (only possible with UpsertSelectFirst)
const | UR_Updated = 3
| row was updated because it was different (only possible with UpsertSelectFirst)
const | UR_Verified = 2
| row was updated unconditionally (not returned with UpsertSelectFirst)

## Private Member Functions
abstract bool | checkExistenceImpl ()
| returns True if the table exists in the DB, False if not More...
| clearImpl ()
| clears any driver-specific table information
abstract bool | constraintsLinkedToIndexesImpl ()
| returns True if the database links constraints to indexes (ie dropping the constraint drops the index, etc)
| constructor (AbstractDatasource nds, string nname, *hash nopts)
| creates the object; private constructor More...
abstract | copyImpl (AbstractTable old)
| db-specific copy actions
abstract | doSelectLimitOnlyUnlockedImpl (reference sql, reference args, *hash qh)
| processes a string for use in SQL select statements when there is a "limit" argument, but no "orderby" or "offset" arguments
abstract | doSelectOrderByWithOffsetSqlUnlockedImpl (reference sql, reference args, *hash qh, *hash jch, *hash ch)
| processes a string for use in SQL select statements when there is an "order by" and "offset" argument
hash | getAlignTableOptions ()
| returns the align table options for this driver More...
hash | getCacheOptions ()
| returns the cache options for this driver More...
hash | getColumnDescOptions ()
| returns the column description options for this driver More...
hash | getColumnOperatorMap ()
| returns the column operator map for this object More...
hash | getColumnOptions ()
| returns the column options for this driver More...
hash | getConstraintOptions ()
| returns the constraint options for this driver More...
hash | getForeignConstraintOptions ()
| return the foreign constraint options for this driver More...
hash | getIndexOptions ()
| returns the index options for this driver More...
hash | getInsertOptions ()
| returns the insert options for this driver More...
abstract hash | getQoreTypeMapImpl ()
| returns the qore type -> column type map
hash | getSelectOptions ()
| returns the select options for this driver More...
hash | getSqlDataCallbackOptions ()
| returns the sql data operation callback options for this driver More...
abstract *string | getSqlValueImpl (any v)
| returns a string for use in SQL queries representing the DB-specific value of the argument; returns NOTHING if the type cannot be converted to an SQL string
hash | getTableColumnDescOptions ()
| returns the table column description options for this driver More...
hash | getTableCreationOptions ()
| returns the table creation options for this driver More...
hash | getTableDescriptionHashOptions ()
| returns the table description hash options for this driver More...
hash | getTableOptions ()
| returns the table options for this driver More...
hash | getTriggerOptions ()
| returns the trigger options for this driver More...
abstract hash | getTypeMapImpl ()
| returns the type name -> type description hash
hash | getUpdateOperatorMap ()
| returns the update operator map for this object More...
hash | getUpsertOptions ()
| returns the upsert options for this driver More...
hash | getWhereOperatorMap ()
| returns the "where" operator map for this object More...
abstract bool | supportsTablespacesImpl ()
| returns True if the database support tablespaces
any | tryExecArgsImpl (string sql, *softlist args)
| tries to execute a command so that if an error occurs the current transaction status is not lost
any | tryExecRawImpl (string sql)
| tries to execute a command so that if an error occurs the current transaction status is not lost
abstract bool | tryInsertImpl (string sql, hash row)
| tries to insert a row, if there is a duplicate key, then it returns False, if successful, returns True
abstract bool | uniqueIndexCreatesConstraintImpl ()
| returns True if the database automatically creates a unique constraint when a unique index is created (ex: mysql)
| validateColumnOptions (string cname, reference opt, bool nullable)
| validates column options

## Private Attributes
Columns | columns
| column description object
Constraints | constraints
| constraint descriptions
ForeignConstraints | foreignConstraints
| foreign constraints description
bool | inDb = False
| in database
Indexes | indexes
| index descriptions
bool | manual = False
| manual edits
string | name
| the table's name
bool | native_case = False
| native case option
AbstractPrimaryKey | primaryKey
| primary key description
Triggers | triggers
| trigger descriptions

## Detailed Description

the base abstract class for the table implementation

## Member Function Documentation

AbstractCheckConstraint SqlUtil::AbstractTable::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

  cname | the name of the new constraint
  src | the source of the constraint clause
  opt | a hash of options for the new constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
  sql | an 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-ERROR | the 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::AbstractTable::addColumn | ( | string | cname,
|  | hash | opt,
|  | bool | nullable = `True`,
|  | *reference | lsql
| ) |  |

adds a column 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:
  $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

  cname | the name of the column
  opt | a 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
  nullable | if True then the column can hold NULL values; note that primary key columns cannot be nullable
  lsql | an 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-ERROR | no `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::AbstractTable::addForeignConstraint | ( | string | cname,
|  | softlist | cols,
|  | string | table,
|  | *softlist | tcols,
|  | *hash | opt,
|  | *reference | sql
| ) |  |

adds a 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

  cname | the name of the new foreign constraint
  cols | a single column name or a list of columns in the local table that make up the foreign constraint
  table | the name of the other table that the constraint targets
  tcols | a 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
  opt | a hash of options for the new foreign constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ForeignConstraintOptions
  sql | an 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-ERROR | the 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

AbstractIndex SqlUtil::AbstractTable::addIndex | ( | string | iname,
|  | bool | unique,
|  | softlist | cols,
|  | *hash | opt,
|  | *reference | sql
| ) |  |

adds an index 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 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

  iname | the name of the new index
  unique | a flag to tell if the new index should be unique or not
  cols | a single column name or a list of columns that make up the index
  opt | a hash of options for the new index; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::IndexOptions
  sql | an 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-ERROR | the 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

AbstractPrimaryKey SqlUtil::AbstractTable::addPrimaryKey | ( | string | pkname,
|  | softlist | cols,
|  | *hash | opt,
|  | *reference | sql
| ) |  |

adds a primary key 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 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

  pkname | the name of the new primary key constraint
  cols | a single column name or a list of columns that make up the primary key
  opt | a hash of options for the new primary key; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
  sql | an 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-ERROR | the 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

AbstractTrigger SqlUtil::AbstractTable::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", "", 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

  tname | the name of the new trigger
  src | the source of the trigger
  opt | a hash of options for the new trigger; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::TriggerOptions
  lsql | an 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-ERROR | the 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::AbstractTable::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

  cname | the name of the new unique constraint
  cols | a single column name or a list of columns that make up the unique constraint
  opt | a hash of options for the new unique constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
  sql | an 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-ERROR | the table already has a constraint with the given name or invalid columns passed
  OPTION-ERROR | invalid or unsupported option passed

See Also
  inDb() for a method that tells if the table is already in the database or not

SqlUtil::AbstractTable::cache | ( | *hash | opts | ) |

reads in all attributes of the table from the database

Example:
  $table.cache();

Parameters

  opts | cache options; see SqlUtil::AbstractTable::CacheOptions for common options; each driver can support additional driver-specific options

abstract bool SqlUtil::AbstractTable::checkExistenceImpl | ( |  | ) |
| private pure virtual

returns True if the table exists in the DB, False if not

this method will only be called if inDb is False and should set inDb = True if it returns True

SqlUtil::AbstractTable::clear | ( |  | ) |

purges the current table definition

Example:
  $table.clear();

SqlUtil::AbstractTable::constructor | ( | AbstractDatasource | nds,
|  | string | nname,
|  | *hash | nopts
| ) |  |
| private

creates the object; private constructor

Parameters

  nds | the AbstractDatasource for the connection to the database
  nname | the name of the table
  nopts | an 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-ERROR | invalid or unsupported option passed

SqlUtil::AbstractTable::create | ( | *hash | opt | ) |

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

Example:
  $table.create();

Parameters

  opt | a hash of options for the SQL creation strings

Note
  The transaction is committed if successful or rolled back if an exception occurs; use createNoCommit() to execute without any transaction management

SqlUtil::AbstractTable::createNoCommit | ( | *hash | opt | ) |

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

Example:
  $table.createNoCommit();

Parameters

  opt | a hash of options for the SQL creation strings

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.

Exceptions

  CREATE-TABLE-ERROR | table has already been read from or created in the database

int SqlUtil::AbstractTable::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

  cond | a hash of conditions for the where clause; see Where Clauses for more information
  sql | an optional reference to a string to return the SQL generated for the select statement

Returns
  the count of rows deleted

Exceptions

  WHERE-ERROR | unknown operator or invalid arguments given in the cond hash for the where clause

See Also
  delNoCommit(*hash)

int SqlUtil::AbstractTable::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

  cond | a hash of conditions for the where clause; see Where Clauses for more information
  opt | optional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info

Returns
  the count of rows deleted

Exceptions

  WHERE-ERROR | unknown operator or invalid arguments given in the cond hash for the where clause

See Also
  delNoCommit(*hash)

int SqlUtil::AbstractTable::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

  cond | a hash of conditions for the where clause; see Where Clauses for more information
  sql | an optional reference to a string to return the SQL generated for the select statement

Returns
  the count of rows deleted

Exceptions

  WHERE-ERROR | unknown operator or invalid arguments given in the cond hash for the where clause

See Also
  del(*hash)

int SqlUtil::AbstractTable::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

  cond | a hash of conditions for the where clause; see Where Clauses for more information
  opt | optional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info

Returns
  the count of rows deleted

Exceptions

  WHERE-ERROR | unknown operator or invalid arguments given in the cond hash for the where clause

See Also
  del(*hash)

Columns SqlUtil::AbstractTable::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::AbstractTable::drop | ( | *hash | opt | ) |

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

Example:
  $table.drop();

Parameters

  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Exceptions

  OPTION-ERROR | invalid 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::AbstractTable::dropColumn | ( | string | cname,
|  | *reference | lsql
| ) |  |

drops a column from the table

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

  cname | the name of the column to drop
  lsql | an 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
  the AbstractColumn object representing the column dropped from the table

Exceptions

  COLUMN-ERROR | the 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::AbstractTable::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

  cname | the name of the constraint to drop
  sql | an 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-ERROR | the 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::AbstractTable::dropForeignConstraint | ( | string | cname,
|  | *reference | sql
| ) |  |

drops a 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

  cname | the name of the foreign constraint to drop
  sql | an 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-ERROR | the 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::AbstractTable::dropIndex | ( | string | iname,
|  | *reference | sql
| ) |  |

drops the given 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

  iname | the name of the index to drop
  sql | an 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-ERROR | the 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::AbstractTable::dropNoCommit | ( | *hash | opt | ) |

drops the table from the database without any transaction management

Example:
  $table.dropNoCommit();

Parameters

  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Exceptions

  OPTION-ERROR | invalid 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::AbstractTable::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

  lsql | an 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 primary key dropped from the table

Exceptions

  PRIMARY-KEY-ERROR | no 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::AbstractTable::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

  tname | the name of the trigger to drop
  sql | an 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-ERROR | the 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::AbstractTable::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::AbstractTable::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
  - empty()
  - rowCount()

*hash SqlUtil::AbstractTable::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);

Exceptions

  PRIMARY-KEY-ERROR | the table has no primary key or the primary key has more than one column

*list SqlUtil::AbstractTable::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

  ids | the list of primary key IDs to find; if the list is empty then NOTHING is returned

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-ERROR | the table has no primary key or the primary key has more than one column

*hash SqlUtil::AbstractTable::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

  row | a 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-ERROR | the table has no primary key or the the hash passed does not contain all columns of the primary key

Note
  a table with a primary key with a single column can also be used with this method; just pass a hash with one key

*list SqlUtil::AbstractTable::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

  cond | a 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-ERROR | unknown 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::AbstractTable::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

  cond | a 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-ERROR | unknown 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

*AbstractUniqueConstraint SqlUtil::AbstractTable::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

  name | the name of the unique constraint to find

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

string SqlUtil::AbstractTable::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

  cname | the name of the new constraint
  src | the source of the constraint clause
  copt | a hash of options for the new constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
  opt | a 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-ERROR | invalid or unsupported option passed
  CHECK-CONSTRAINT-ERROR | the 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::AbstractTable::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

  cname | the name of the column
  copt | a 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
  nullable | if True then the column can hold NULL values; note that primary key columns cannot be nullable
  opt | a 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-ERROR | invalid or unsupported option passed
  COLUMN-ERROR | no `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::AbstractTable::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

  cname | the name of the new foreign constraint
  cols | a single column name or a list of columns in the local table that make up the foreign constraint
  table | the name of the other table that the constraint targets
  tcols | a 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
  fkopt | a hash of options for the new foreign constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ForeignConstraintOptions
  opt | a 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-ERROR | invalid or unsupported option passed
  FOREIGN-CONSTRAINT-ERROR | the 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::AbstractTable::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

  iname | the name of the new index
  unique | a flag to tell if the new index should be unique or not
  cols | a single column name or a list of columns that make up the index
  ixopt | a hash of options for the new index; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::IndexOptions
  opt | a 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-ERROR | invalid or unsupported option passed
  INDEX-ERROR | the 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::AbstractTable::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

  pkname | the name of the new primary key constraint
  cols | a single column name or a list of columns that make up the primary key
  pkopt | a hash of options for the new primary key; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
  opt | a 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-ERROR | invalid or unsupported option passed
  PRIMARY-KEY-ERROR | the 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::AbstractTable::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

  tname | the name of the new trigger
  src | the source of the trigger
  topt | a hash of options for the new trigger; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::TriggerOptions
  opt | a 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-ERROR | invalid or unsupported option passed
  TRIGGER-ERROR | the 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::AbstractTable::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

  cname | the name of the new unique constraint
  cols | a single column name or a list of columns that make up the unique constraint
  ukopt | a hash of options for the new unique constraint; each driver may implement its own options; for common options, see SqlUtil::AbstractTable::ConstraintOptions
  opt | a 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-ERROR | invalid or unsupported option passed
  UNIQUE-CONSTRAINT-ERROR | the 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::AbstractTable::getAlignSql | ( | AbstractTable | t,
|  | *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

  t | the template table that the current table will be compared to
  opt | a 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

  ALIGN-TABLE-ERROR | the argument must be of the same class as the current object; template table has no columns
  OPTION-ERROR | invalid or unsupported option passed

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::AbstractTable::getAlignSqlString | ( | AbstractTable | t,
|  | *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

  t | the template table that the current table will be compared to
  opt | a 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-ERROR | the argument must be of the same class as the current object; template table has no columns
  OPTION-ERROR | invalid or unsupported option passed

hash SqlUtil::AbstractTable::getAlignTableOptions | ( |  | ) |
| private

returns the align table options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getCacheOptions | ( |  | ) |
| private

returns the cache options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getColumnDescOptions | ( |  | ) |
| private

returns the column description options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getColumnOperatorMap | ( |  | ) |
| private

returns the column operator map for this object

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getColumnOptions | ( |  | ) |
| private

returns the column options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getConstraintOptions | ( |  | ) |
| private

returns the constraint options for this driver

override in subclasses to return driver-specific options

*list SqlUtil::AbstractTable::getCreateConstraintsSql | ( | *hash | opt,
|  | bool | cache = `True`
| ) |  |

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

  opt | a 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
  cache | read in data from the database for uncached properties of the table

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

See Also
  getCreateForeignConstraintsSql()

Exceptions

  OPTION-ERROR | invalid or unsupported option passed

*list SqlUtil::AbstractTable::getCreateForeignConstraintsSql | ( | *hash | opt,
|  | bool | cache = `True`
| ) |  |

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

  opt | a hash of options for the foreign constraint creation string; see SqlUtil::AbstractTable::ForeignConstraintOptions for common options; each driver can support additional driver-specific options
  cache | read in data from the database for uncached properties of the table

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-ERROR | invalid or unsupported option passed

*list SqlUtil::AbstractTable::getCreateIndexesSql | ( | *hash | opt,
|  | bool | cache = `True`
| ) |  |

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

  opt | a hash of options for the index creation string; see SqlUtil::AbstractTable::IndexOptions for common options; each driver can support additional driver-specific options
  cache | read in data from the database for uncached properties of the table

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-ERROR | invalid or unsupported option passed

*list SqlUtil::AbstractTable::getCreateMiscSql | ( | *hash | opt,
|  | bool | cache = `True`
| ) |  |

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

  opt | a hash of options for the SQL creation string; see TableCreationOptions for common options; each driver can support additional driver-specific options
  cache | read in data from the database for uncached properties of the table

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-ERROR | invalid or unsupported option passed

*string SqlUtil::AbstractTable::getCreatePrimaryKeySql | ( | *hash | opt,
|  | bool | cache = `True`
| ) |  |

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

Example:
  my *string $sql = $table.getCreatePrimaryKeySql();

Parameters

  opt | a hash of options for the primary key creation string; see SqlUtil::AbstractTable::ConstraintOptions for common options; each driver can support additional driver-specific options
  cache | read in data from the database for uncached properties of the table

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-ERROR | invalid or unsupported option passed

list SqlUtil::AbstractTable::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

  opt | a hash of options for the table, index, and constraint creation strings; see 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::AbstractTable::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.getCreateSql());

Parameters

  opt | a hash of options for the SQL creation string

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

string SqlUtil::AbstractTable::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

  opt | a hash of options for the table creation string; see 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-ERROR | invalid or unsupported option passed

*list SqlUtil::AbstractTable::getCreateTriggersSql | ( | *hash | opt,
|  | bool | cache = `True`
| ) |  |

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

  opt | a hash of options for the trigger creation strings; see TableCreationOptions for common options; each driver can support additional driver-specific options
  cache | read in data from the database for uncached properties of the table

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-ERROR | invalid or unsupported option passed

See Also
  getCreateTriggersSql()

list SqlUtil::AbstractTable::getDropAllConstraintsAndIndexesOnColumnSql | ( | string | cname,
|  | *hash | opt
| ) |  |

gets a list of SQL strings to drop all constraints and indexes with the given column name; if the column does not exist then an empty list is returned

Example:
  my list $l = $table.getDropAllConstraintsAndIndexesOnColumnSql("status");

Parameters

  cname | the name of the column
  opt | a hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options

Exceptions

  OPTION-ERROR | invalid or unsupported option passed

Note
  - this method retrieves current primary key definition 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::AbstractTable::getDropColumnSql | ( | string | cname,
|  | *hash | opt
| ) |  |

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

Example:
  my string $sql = $table.getDropColumnSql("notes_2");

Parameters

  cname | the name of the column to drop
  opt | a 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-ERROR | invalid or unsupported option passed
  COLUMN-ERROR | the named column is not present in the table

Note
  - this method retrieves the column 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

*string SqlUtil::AbstractTable::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

  cname | the name of the constraint to drop
  opt | a hash of options for the SQL string; see SqlUtil::AbstractTable::AlignTableOptions for common options; each driver can support additional driver-specific options
  cref | an 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-ERROR | invalid 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::AbstractTable::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

  cname | the name of the constraint to drop
  opt | a 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-ERROR | invalid or unsupported option passed
  CONSTRAINT-ERROR | the 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::AbstractTable::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

  iname | the name of the index to drop
  opt | a 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-ERROR | invalid or unsupported option passed
  INDEX-ERROR | the 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::AbstractTable::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

  opt | a 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-ERROR | invalid or unsupported option passed
  PRIMARY-KEY-ERROR | the 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

softlist SqlUtil::AbstractTable::getDropSql | ( | *hash | opt | ) |

returns the sql required to drop the table; reimplement in subclasses if necessary

Example:

Parameters

  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  a list of strings that can be used to drop the table and any other objects assocatied with the table (for example: PostgreSQL table trigger function(s))

Exceptions

  OPTION-ERROR | invalid or unknown callback option

list SqlUtil::AbstractTable::getDropTriggerSql | ( | string | tname,
|  | *hash | opt
| ) |  |

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

Example:
  my string $sql = $table.getDropTriggerSql("trig_mytable");

Parameters

  tname | the name of the trigger to drop
  opt | a 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-ERROR | invalid or unsupported option passed
  TRIGGER-ERROR | the 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

hash SqlUtil::AbstractTable::getForeignConstraintOptions | ( |  | ) |
| private

return the foreign constraint options for this driver

override in subclasses to return driver-specific options

Indexes SqlUtil::AbstractTable::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

hash SqlUtil::AbstractTable::getIndexOptions | ( |  | ) |
| private

returns the index options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getInsertOptions | ( |  | ) |
| private

returns the insert options for this driver

override in subclasses to return driver-specific options

list SqlUtil::AbstractTable::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

  cname | the name of the column
  copt | a 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
  nullable | if True then the column can hold NULL values; note that primary key columns cannot be nullable
  opt | a 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-ERROR | invalid or unsupported option passed
  COLUMN-ERROR | no `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
  - 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

AbstractPrimaryKey SqlUtil::AbstractTable::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:

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

string SqlUtil::AbstractTable::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_name | the current name of the column
  new_name | the new name of the column
  opt | a 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-ERROR | invalid or unsupported option passed
  COLUMN-ERROR | if the old column does not exist in the table or the new column already does

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::AbstractTable::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_name | the new name for the table
  opt | a 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-ERROR | invalid 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::AbstractTable::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($sh);

Parameters

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  sql | an 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-ERROR | invalid 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::AbstractTable::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

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  opt | optional 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-ERROR | invalid 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

hash SqlUtil::AbstractTable::getSelectOptions | ( |  | ) |
| private

returns the select options for this driver

override in subclasses to return driver-specific options

string SqlUtil::AbstractTable::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

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  args | an 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-ERROR | invalid 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

hash SqlUtil::AbstractTable::getSqlDataCallbackOptions | ( |  | ) |
| private

returns the sql data operation callback options for this driver

override in subclasses to return driver-specific options

string SqlUtil::AbstractTable::getSqlFromList | ( | list | l | ) |

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

Example:
  my string $sql = $t.getSqlFromList($list);

Parameters

  l | a list of SQL commands

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

string SqlUtil::AbstractTable::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

  v | the value to convert to an SQL value

Returns
  a string representing the value usable in SQL strings for the given database driver

Exceptions

  VALUE-ERROR | the given value cannot be converted to an SQL string (missing rules for value)

hash SqlUtil::AbstractTable::getTableColumnDescOptions | ( |  | ) |
| private

returns the table column description options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getTableCreationOptions | ( |  | ) |
| private

returns the table creation options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getTableDescriptionHashOptions | ( |  | ) |
| private

returns the table description hash options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getTableOptions | ( |  | ) |
| private

returns the table options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getTriggerOptions | ( |  | ) |
| private

returns the trigger options for this driver

override in subclasses to return driver-specific options

Triggers SqlUtil::AbstractTable::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::AbstractTable::getTruncateSql | ( | *hash | opt | ) |

gets the SQL that can be used to truncate the table

Example:
  my string $sql = $table.getTruncateSql();

Parameters

  opt | a 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-ERROR | invalid 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::AbstractTable::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)

hash SqlUtil::AbstractTable::getUpdateOperatorMap | ( |  | ) |
| private

returns the update operator map for this object

override in subclasses to return driver-specific options

code SqlUtil::AbstractTable::getUpsertClosure | ( | hash | example_row,
|  | int | upsert_strategy = `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_row | a 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_strategy | see 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-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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

code SqlUtil::AbstractTable::getUpsertClosureWithValidation | ( | hash | example_row,
|  | int | upsert_strategy = `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 checks 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_row | a 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_strategy | see 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-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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

hash SqlUtil::AbstractTable::getUpsertOptions | ( |  | ) |
| private

returns the upsert options for this driver

override in subclasses to return driver-specific options

hash SqlUtil::AbstractTable::getWhereOperatorMap | ( |  | ) |
| private

returns the "where" operator map for this object

override in subclasses to return driver-specific options

bool SqlUtil::AbstractTable::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::AbstractTable::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

  row | a hash representing the row to insert
  sql | an optional reference to a string to return the SQL generated for the insert statement

Exceptions

  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted

SqlUtil::AbstractTable::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

  row | a hash representing the row to insert
  opt | optional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info

Exceptions

  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted

int SqlUtil::AbstractTable::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

  i | the 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 every element
  opt | a 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-ERROR | invalid or unsupported option
  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted

See Also
  - insertFromIteratorNoCommit()
  - upsertFromIterator()
  - upsertFromIteratorNoCommit()

int SqlUtil::AbstractTable::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

  i | the 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
  opt | a hash of options for the insert operation; see SqlUtil::AbstractTable::InsertOptions for common options; each driver can support additional driver-specific options; note that this method ignores any `"commit_block"` option

Returns
  the number of rows inserted

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted

See Also
  - insertFromIterator()
  - upsertFromIterator()
  - upsertFromIteratorNoCommit()

int SqlUtil::AbstractTable::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

  cols | the list of column names to use to insert in the current table
  source | the source table for the select statement
  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  sql | an optional reference to a string to return the SQL generated for the select statement

Returns
  the number of rows inserted

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | unknown 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::AbstractTable::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

  cols | the list of column names to use to insert in the current table
  source | the source table for the select statement
  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  opt | optional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info

Returns
  the number of rows inserted

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | unknown 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::AbstractTable::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

  cols | the list of column names to use to insert in the current table
  source | the source table for the select statement
  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  sql | an optional reference to a string to return the SQL generated for the select statement

Returns
  the number of rows inserted

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | unknown 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::AbstractTable::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

  cols | the list of column names to use to insert in the current table
  source | the source table for the select statement
  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  opt | optional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info

Returns
  the number of rows inserted

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | unknown 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::AbstractTable::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.insert($row);

Parameters

  row | a hash representing the row to insert
  sql | an optional reference to a string to return the SQL generated for the insert statement

Exceptions

  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted

SqlUtil::AbstractTable::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.insert($row);

Parameters

  row | a hash representing the row to insert
  opt | optional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info

Exceptions

  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted

AbstractColumn SqlUtil::AbstractTable::modifyColumn | ( | string | cname,
|  | hash | opt,
|  | bool | nullable = `True`,
|  | *reference | lsql
| ) |  |

modifies an existing column in the table; 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 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

  cname | the name of the column
  opt | a 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
  lsql | an 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)
  nullable | if True then the column can hold NULL values; note that primary key columns cannot be nullable

Exceptions

  COLUMN-ERROR | no `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

AbstractForeignConstraint SqlUtil::AbstractTable::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

  cname | the name of the foreign constraint to remove

Returns
  the foreign constraint removed from the table

Exceptions

  FOREIGN-CONSTRAINT-ERROR | the 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::AbstractTable::rename | ( | string | new_name,
|  | *reference | sql,
|  | *Tables | table_cache
| ) |  |

renames the table; if the table is already known to be in the database 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_name | the new name for the table
  sql | an 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_cache | an optional Tables argument to update the table name in any table cache

See Also
  getRenameSql()

AbstractColumn SqlUtil::AbstractTable::renameColumn | ( | string | old_name,
|  | string | new_name,
|  | reference | sql
| ) |  |

renames an existing column; 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 AbstractColumn $col = $table.renameColumn("name", "family_name");

Parameters

  old_name | the current name of the column
  new_name | the new name of the column
  sql | an 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-ERROR | if 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 representations are also renamed, however check constraints are not updated and will be invalid if they refer to the renamed column

AbstractConstraint SqlUtil::AbstractTable::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_name | the current name of the constraint
  new_name | the new name for the constraint
  lsql | an 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-ERROR | if the old constraint does not exist in the table or if the new constraint name already exists

AbstractIndex SqlUtil::AbstractTable::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_name | the current name of the index
  new_name | the new name for the index
  sql | an 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-ERROR | if the old index does not exist in the table or if the new index name already exists

softint SqlUtil::AbstractTable::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::AbstractTable::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

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  sql | an 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-ERROR | invalid 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::AbstractTable::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

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  opt | optional 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-ERROR | invalid 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::AbstractTable::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

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  sql | an 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-ERROR | invalid 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-ERROR | more 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::AbstractTable::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

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  opt | optional 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-ERROR | invalid 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-ERROR | more 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::AbstractTable::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

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  sql | an 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-ERROR | invalid 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::AbstractTable::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

  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  opt | optional 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-ERROR | invalid 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::AbstractTable::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

  nds | the 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::AbstractTable::setupTable | ( | hash | desc,
|  | *hash | opt
| ) |  |

creates the object from a table description hash

Parameters

  desc | a table description hash describing the table
  opt | an 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-ERROR | invalid or unsupported option passed
  DESCRIPTION-ERROR | invalid or unsupported description hash value passed

SqlUtil::AbstractTable::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::AbstractTable::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::AbstractTable::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

  sql | the SQL to execute

Returns
  any return value from the SQL command executed

any SqlUtil::AbstractTable::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

  sql | the SQL to execute
  args | the bind / placeholder or other arguments corresponding to the SQL string

Returns
  any return value from the SQL command executed

any SqlUtil::AbstractTable::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

  sql | the SQL to execute

Returns
  any return value from the SQL command executed

int SqlUtil::AbstractTable::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

  set | the 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)
  cond | a hash of conditions for the where clause; see Where Clauses for more information
  sql | an optional reference to a string to return the SQL generated for the select statement

Returns
  the count of rows updated

Exceptions

  UPDATE-ERROR | the set hash is empty
  WHERE-ERROR | unknown operator or invalid arguments given in the cond hash for the where clause

See Also
  updateNoCommit()

int SqlUtil::AbstractTable::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

  set | the 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)
  cond | a hash of conditions for the where clause; see Where Clauses for more information
  opt | optional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info

Returns
  the count of rows updated

Exceptions

  UPDATE-ERROR | the set hash is empty
  WHERE-ERROR | unknown operator or invalid arguments given in the cond hash for the where clause

See Also
  updateNoCommit()

int SqlUtil::AbstractTable::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

  set | the 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)
  cond | a hash of conditions for the where clause; see Where Clauses for more information
  sql | an optional reference to a string to return the SQL generated for the select statement

Returns
  the count of rows updated

Exceptions

  UPDATE-ERROR | the set hash is empty
  WHERE-ERROR | unknown operator or invalid arguments given in the cond hash for the where clause

See Also
  update()

int SqlUtil::AbstractTable::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

  set | the 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)
  cond | a hash of conditions for the where clause; see Where Clauses for more information
  opt | optional SQL data operation callback options; see AbstractTable::SqlDataCallbackOptions for more info

Returns
  the count of rows updated

Exceptions

  UPDATE-ERROR | the set hash is empty
  WHERE-ERROR | unknown operator or invalid arguments given in the cond hash for the where clause

See Also
  update()

int SqlUtil::AbstractTable::upsert | ( | hash | row,
|  | int | upsert_strategy = `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

  row | a hash representing the row to insert or update
  upsert_strategy | see 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-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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

*hash SqlUtil::AbstractTable::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

  i | the 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_strategy | see Upsert Strategy Codes for possible values for the upsert strategy
  opt | a 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):
  - `"inserted"`: the number of rows inserted
  - `"verified"`: the number of rows updated unconditionally; note that this key is returned with all upsert strategy codes other than SqlUtil::AbstractTable::UpsertSelectFirst instead of `"updated"`
  - `"updated"`: the number of rows updated; note that this key is only returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, otherwise updated rows are reported as `"verified"` since rows are updated unconditionally with other the upsert strategy codes
  - `"unchanged"`: the number of rows unchanged; this key can only be returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, since this is the only upsert strategy that compares row data
  - `"deleted"`: the number of rows deleted; this can only be returned if upsert option `delete_others` is True

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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
  - upsertFromIteratorNoCommit()
  - upsertFromSelect()
  - upsertFromSelectNoCommit()
  - upsert()
  - upsertNoCommit()
  - getUpsertClosure()
  - insertFromIteratorNoCommit()
  - insertFromIterator()

*hash SqlUtil::AbstractTable::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

  i | the 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_strategy | see Upsert Strategy Codes for possible values for the upsert strategy
  opt | a hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options; note that this method ignores any `"commit_block"` option

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):
  - `"inserted"`: the number of rows inserted
  - `"verified"`: the number of rows updated unconditionally; note that this key is returned with all upsert strategy codes other than SqlUtil::AbstractTable::UpsertSelectFirst instead of `"updated"`
  - `"updated"`: the number of rows updated; note that this key is only returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, otherwise updated rows are reported as `"verified"` since rows are updated unconditionally with other the upsert strategy codes
  - `"unchanged"`: the number of rows unchanged; this key can only be returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, since this is the only upsert strategy that compares row data
  - `"deleted"`: the number of rows deleted; this can only be returned if upsert option `delete_others` is True

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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
  - upsertFromIteratorNoCommit()
  - upsertFromSelect()
  - upsertFromSelectNoCommit()
  - upsert()
  - upsertNoCommit()
  - getUpsertClosure()
  - insertFromIteratorNoCommit()
  - insertFromIterator()

*hash SqlUtil::AbstractTable::upsertFromSelect | ( | AbstractTable | t,
|  | *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

  t | the 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
  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  upsert_strategy | see Upsert Strategy Codes for possible values for the upsert strategy
  opt | a 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):
  - `"inserted"`: the number of rows inserted
  - `"verified"`: the number of rows updated unconditionally; note that this key is returned with all upsert strategy codes other than SqlUtil::AbstractTable::UpsertSelectFirst instead of `"updated"`
  - `"updated"`: the number of rows updated; note that this key is only returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, otherwise updated rows are reported as `"verified"` since rows are updated unconditionally with other the upsert strategy codes
  - `"unchanged"`: the number of rows unchanged; this key can only be returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, since this is the only upsert strategy that compares row data
  - `"deleted"`: the number of rows deleted; this can only be returned if upsert option `delete_others` is True

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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
  - upsertFromSelectNoCommit()
  - upsertFromIterator()
  - upsertFromIteratorNoCommit()
  - upsert()
  - upsertNoCommit()
  - getUpsertClosure()

*hash SqlUtil::AbstractTable::upsertFromSelect | ( | Table | t,
|  | *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

  t | the 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
  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  upsert_strategy | see Upsert Strategy Codes for possible values for the upsert strategy
  opt | a 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):
  - `"inserted"`: the number of rows inserted
  - `"verified"`: the number of rows updated unconditionally; note that this key is returned with all upsert strategy codes other than SqlUtil::AbstractTable::UpsertSelectFirst instead of `"updated"`
  - `"updated"`: the number of rows updated; note that this key is only returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, otherwise updated rows are reported as `"verified"` since rows are updated unconditionally with other the upsert strategy codes
  - `"unchanged"`: the number of rows unchanged; this key can only be returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, since this is the only upsert strategy that compares row data
  - `"deleted"`: the number of rows deleted; this can only be returned if upsert option `delete_others` is True

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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
  - upsertFromSelectNoCommit()
  - upsertFromIterator()
  - upsertFromIteratorNoCommit()
  - upsert()
  - upsertNoCommit()
  - getUpsertClosure()

*hash SqlUtil::AbstractTable::upsertFromSelectNoCommit | ( | AbstractTable | t,
|  | *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

  t | the 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
  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  upsert_strategy | see Upsert Strategy Codes for possible values for the upsert strategy
  opt | a hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options; note that this method ignores any `"commit_block"` option

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):
  - `"inserted"`: the number of rows inserted
  - `"verified"`: the number of rows updated unconditionally; note that this key is returned with all upsert strategy codes other than SqlUtil::AbstractTable::UpsertSelectFirst instead of `"updated"`
  - `"updated"`: the number of rows updated; note that this key is only returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, otherwise updated rows are reported as `"verified"` since rows are updated unconditionally with other the upsert strategy codes
  - `"unchanged"`: the number of rows unchanged; this key can only be returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, since this is the only upsert strategy that compares row data
  - `"deleted"`: the number of rows deleted; this can only be returned if upsert option `delete_others` is True

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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 uses an SQLStatement object to pipeline the select data to the upsert code; to release the transaction lock acquired by the SQLStatement object, a commit() or rollback() action must be executed on the underlying datasource object as in the example above

  - unlike insertFromSelect() and insertFromSelectNoCommit(), this method processes arbitrary input data and accepts upsert options
  See Also
    - upsertFromSelect()
    - upsertFromIterator()
    - upsertFromIteratorNoCommit()
    - upsert()
    - upsertNoCommit()
    - getUpsertClosure()

*hash SqlUtil::AbstractTable::upsertFromSelectNoCommit | ( | Table | t,
|  | *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

  t | the 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
  sh | a hash of conditions for the select statement; see select option hash for information about this argument
  upsert_strategy | see Upsert Strategy Codes for possible values for the upsert strategy
  opt | a hash of options for the upsert operation; see SqlUtil::AbstractTable::UpsertOptions for common options; each driver can support additional driver-specific options; note that this method ignores any `"commit_block"` option

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):
  - `"inserted"`: the number of rows inserted
  - `"verified"`: the number of rows updated unconditionally; note that this key is returned with all upsert strategy codes other than SqlUtil::AbstractTable::UpsertSelectFirst instead of `"updated"`
  - `"updated"`: the number of rows updated; note that this key is only returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, otherwise updated rows are reported as `"verified"` since rows are updated unconditionally with other the upsert strategy codes
  - `"unchanged"`: the number of rows unchanged; this key can only be returned if upsert_strategy is SqlUtil::AbstractTable::UpsertSelectFirst, since this is the only upsert strategy that compares row data
  - `"deleted"`: the number of rows deleted; this can only be returned if upsert option `delete_others` is True

Exceptions

  OPTION-ERROR | invalid or unsupported option
  COLUMN-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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 uses an SQLStatement object to pipeline the select data to the upsert code; to release the transaction lock acquired by the SQLStatement object, a commit() or rollback() action must be executed on the underlying datasource object as in the example above

  - unlike insertFromSelect() and insertFromSelectNoCommit(), this method processes arbitrary input data and accepts upsert options
  See Also
    - upsertFromSelect()
    - upsertFromIterator()
    - upsertFromIteratorNoCommit()
    - upsert()
    - upsertNoCommit()
    - getUpsertClosure()

int SqlUtil::AbstractTable::upsertNoCommit | ( | hash | row,
|  | int | upsert_strategy = `UpsertAuto`
| ) |  |

update or insert the data in the table according to the hash argument; the table must have a unique key to do this

Example:
  $table.upsertNoCommit($row);

Parameters

  row | a hash representing the row to insert or update
  upsert_strategy | see 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-ERROR | an unknown column was referenced in the hash to be inserted
  UPSERT-ERROR | no 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

## Member Data Documentation

const SqlUtil::AbstractTable::AdditionalColumnDescOptions

Initial value:
= (
"notnull": Type::Boolean,
)

additional column description keys valid when describing columns in a table description hash

the following keys are valid in a table description hash in addition to any AbstractTable::ColumnDescOptions:

- `notnull:` (bool) if True then the column will have a not null constraint

const SqlUtil::AbstractTable::AlignTableOptions

Initial value:
= TableCreationOptions + (
"column_map": Type::Hash,
"index_map": Type::Hash,
"constraint_map": Type::Hash,
"trigger_map": Type::Hash,
"db_table_cache": "Tables",
)

table alignment options

currently this option is a combination of SqlUtil::AbstractTable::TableCreationOptions and the following options:

- `column_map:` a hash for automatically renaming columns; if the source name (key) exists and the target name (value) does not exist, then the source column is automatically renamed
- `index_map:` a hash for automatically renaming indexes; if the source name (key) exists and the target name (value) does not exist, then the source index is automatically renamed
- `constraint_map:` a hash for automatically renaming constraints; if the source name (key) exists and the target name (value) does not exist, then the source constraint is automatically renamed
- `trigger_map:` a hash for automatically renaming triggers; if the source name (key) exists and the target name (value) does not exist, then the source trigger is automatically renamed
- `db_table_cache:` (Tables) an optional table cache for maintaining tables in the database and foreign key relationships between tables

const SqlUtil::AbstractTable::ColumnDescOptions

Initial value:
= (
"qore_type": Type::String,
"native_type": Type::String,
"size": Type::Int,
"scale": Type::Int,
"default_value": Type::NothingType,
"comment": Type::String,
)

Column description options.

this option is made up of the following keys:

- `qore_type:` (string) a qore type string that will be converted to a native DB type with some default conversion
- `native_type:` (string) the native database column type; if both `native_type` and `qore_type` are given then `native_type` is used
- `size:` (int) for data types requiring a size component, the size; for numeric columns this represents the precision for example
- `scale:` (int) for numeric data types, this value gives the scale
- `default_value:` the default value for the column
- `comment:` (string) an optional comment for the column
- `notnull:` if the column should have a "not null" constraint on it; if missing the default value is False
- `driver:` this key can optionally contain a hash keyed by driver name which contains a hash of values that will be added to the column description hash before processing; this way a column description hash can contain all the information required for the column including driver-specific options; any driver-specific options will overwrite values in the top level of the hash if there are duplicate hash keys, see below for an example
  See Also
    Column Description Hash

const SqlUtil::AbstractTable::ConstraintOptions = IndexOptions

default constraint options

currently this option is identical to SqlUtil::AbstractTable::IndexOptions

const SqlUtil::AbstractTable::ForeignConstraintOptions

Initial value:
= ConstraintOptions + (
"table_cache": "Tables",
)

default foreign constraint options

The following keys can be set for this option:

- `table_cache:` (Tables) an optional table cache for maintaining cached tables and foreign key relationships between tables

const SqlUtil::AbstractTable::IndexOptions

Initial value:
= (
"index_tablespace": Type::String,
"replace": Type::Boolean,
)

default index options

- `index_tablespace:` (string) a string giving the index tablespace to use for indexes
- `replace:` (bool) if True and supported by the underlying db driver "create or replace" text is used when creating objects

const SqlUtil::AbstractTable::InsertOptions

Initial value:
= SqlDataCallbackOptions + (
"info_callback": "code",
"commit_block": Type::Int,
)

default insert option keys

In addition to any SqlDataCallbackOptions, the following keys can be set for this option:

- `info_callback:` see Insert Info Callback
- `commit_block:` the number of changes made before an automatic commit is made for insert methods that perform commits

const SqlUtil::AbstractTable::SelectOptions

Initial value:
= (
"comment": Type::String,
"hint": Type::String,
"columns": Type::NothingType,
"where": "hash/list",
"orderby": "softstringhashlist",
"desc": Type::Boolean,
"limit": Type::Int,
"offset": Type::Int,
"join": Type::Hash,
"groupby": "softstringhashlist",
"having": Type::Hash,
"superquery": Type::Hash,
)

default select options

the possible keys for select options are as follows (all keys are optional):

- columns: describes the output columns and any output column operations
- where: describes how any `"where"` clause will be built
- orderby: describes the ordering of the results
- desc: specifies descending order for results
- limit: specifies the maximum number of results to be returned
- offset: specifies the starting offset of the first record to be returned (starting with 0)
- join: specifies any SQL join operations to return results from multiple tables
- groupby: specifies grouping for aggregate column functions
- having: specifies filtering for results with aggregate column functions
- superquery: specifies that the rest of the argument belong to a subquery and the hash arguments under this key will select from the subquery

const SqlUtil::AbstractTable::SqlDataCallbackOptions

Initial value:
= (
"sqlarg_callback": "code",
)

generic SQL data operation callbacks

The following keys can be set for this option:

- `sqlarg_callback:` see SQL Operation Callback Closure or Call Reference

const SqlUtil::AbstractTable::TableCreationOptions

Initial value:
= IndexOptions + AbstractDatabase::CreationOptions + (
"omit": "softstringlist",
)

table creation options

currently this option is a combination of SqlUtil::AbstractTable::IndexOptions and AbstractDatabase::CreationOptions plus the following:

- `omit:` a list pf attributes to omit; possible values are: `indexes`, `foreign_constraints`, `triggers` (see TableOmissionOptions)

const SqlUtil::AbstractTable::TableDescriptionHashOptions

Initial value:
= (
"columns": Type::Hash,
"primary_key": Type::Hash,
"indexes": Type::Hash,
"triggers": Type::Hash,
"foreign_constraints": Type::Hash,
"unique_constraints": Type::Hash,
"table_cache": "Tables",
)

Table description options.

this option is made up of the following keys:

- `columns:` (column description hash) a hash describing the column
- `primary_key` : (primary key description hash) a hash describing the primary key for the table
- `indexes:` (index description hashes) a hash describing the indexes on the table
- `triggers:` a hash of trigger information keyed by trigger name; the values are the trigger source code; since triggers are driver-dependent, a driver-independent table description would include trigger hashes under the `drivers` key and the driver key name under that
- `foreign_constraints:` (foreign constraint hashes) a hash describing the foreign constraints on the table
- `unique_constraints:` (unique constraint hashes) a hash describing the unique constraints on the table
- `table_cache:` (Tables) an optional table cache for maintaining cached tables and foreign key relationships between tables

See Also
  Table Description Hash

const SqlUtil::AbstractTable::TableOptions

Initial value:
= (
"native_case": Type::Boolean,
"table_cache": "Tables",
)

table options

The following keys can be set for this option:

- `native_case:` (bool) if True then objects will be returned in the case the database server returns them in even if the database server uses case-insensitive names; normally in this case SqlUtil will convert the names to lower-case
- `table_cache:` (Tables) an optional table cache for maintaining cached tables and foreign key relationships between tables

const SqlUtil::AbstractTable::TriggerOptions = AbstractDatabase::CreationOptions

default trigger options

currently this option is identical to AbstractDatabase::CreationOptions

const SqlUtil::AbstractTable::UpsertOptions

Initial value:
= (
"info_callback": "code",
"commit_block": Type::Int,
"delete_others": Type::Boolean,
)

default upsert option keys

The following keys can be set for this option:

- `info_callback:` see Upsert Info Callback
- `commit_block:` the number of changes made before an automatic commit is made for upsert methods that perform commits
- `delete_others:` if this option 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 allows tables to be completely synchronized by removing rows in the target table not present in the source table. This operation is expensive for large data sets.

const SqlUtil::AbstractTable::UpsertResultDescriptionMap

Initial value:
= (
"inserted": UR_Inserted,
"verified": UR_Verified,
"updated": UR_Updated,
"unchanged": UR_Unchanged,
"deleted": UR_Deleted,
)

hash mapping upsert descriptions to codes

See Also
  UpsertResultMap for a reverse mapping

const SqlUtil::AbstractTable::UpsertResultMap

Initial value:
= (
UR_Inserted: "inserted",
UR_Verified: "verified",
UR_Updated: "updated",
UR_Unchanged: "unchanged",
UR_Deleted: "deleted",
)

hash mapping upsert results to a description

See Also
  UpsertResultDescriptionMap for a reverse mapping