SqlUtil::AbstractDatabase Class Referenceabstract

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

Inheritance diagram for SqlUtil::AbstractDatabase:
[legend]

## Public Member Functions

| computeStatistics (*hash options)
| Compute database statistics. More...
bool | dropFunctionIfExists (string name, *hash opt)
| drops the given function if it exists; returns True if the function was dropped, False if not More...
bool | dropProcedureIfExists (string name, *hash opt)
| drops the given procedure if it exists; returns True if the procedure was dropped, False if not More...
bool | dropSequenceIfExists (string name, *hash opt)
| drops the given sequence if it exists; returns True if the sequence was dropped, False if not More...
bool | dropTableIfExists (string name, *hash opt)
| drops the given table if it exists; returns True if the table was dropped, False if not More...
bool | dropViewIfExists (string name, *hash opt)
| drops the given view if it exists; returns True if the view was dropped, False if not More...
list | features ()
| See DBFeaturesConstants.
Qore::ListIterator | functionIterator ()
| returns an iterator listing the string function names in the database
list | getAlignFunctionSql (AbstractFunction f, *hash opt)
| returns a list of SQL strings that can be used to update a function in the database to the function definition passed as an argument More...
list | getAlignProcedureSql (AbstractFunction f, *hash opt)
| returns a list of SQL strings that can be used to update a stored procedure in the database to the stored procedure definition passed as an argument More...
list | getAlignSql (hash schema_hash, *hash opt, *Tables table_cache)
| accepts a hash argument describing a database schema and returns a list of SQL strings that can be used to align the structure and configuration of the current schema with that of the argument; if the objects described are identical then an empty list is returned More...
int | getCurrentSequenceValue (string name)
| returns the last value issued for the given sequence in the current session More...
*string | getDropFunctionSqlIfExists (string name, *hash opt)
| returns the SQL require to drop the given function if it exists or NOTHING if the named function does not exist More...
*string | getDropProcedureSqlIfExists (string name, *hash opt)
| returns the SQL require to drop the given procedure if it exists or NOTHING if the named procedure does not exist More...
list | getDropSchemaSql (hash schema_hash, *hash opt)
| accepts a hash argument describing a database schema and returns a list of SQL strings that can be used to drop any existing objects described in the schema; if none of the described objects exist, then an empty list is returned More...
*string | getDropSequenceSqlIfExists (string name, *hash opt)
| returns the SQL require to drop the given sequence if it exists or NOTHING if the named sequence does not exist More...
*list | getDropTableSqlIfExists (string name, *hash opt)
| returns the SQL require to drop the given table if it exists or NOTHING if the named table does not exist More...
*AbstractFunction | getFunction (string name)
| returns an AbstractFunction argument for the given function name or NOTHING if the function cannot be found More...
int | getNextSequenceValue (string name)
| returns the next value in the given sequence More...
*AbstractFunction | getProcedure (string name)
| returns an AbstractFunction argument for the given stored procedure name or NOTHING if the stored procedure cannot be found More...
*AbstractSequence | getSequence (string name)
| returns an AbstractSequence argument for the given sequence name or NOTHING if the sequence cannot be found More...
string | getSqlFromList (list l)
| returns an SQL string corresponding to the list of commands in the argument More...
*AbstractTable | getTable (string name)
| returns an AbstractTable argument for the given table name or NOTHING if the table cannot be found More...
*AbstractView | getView (string name)
| returns an AbstractView argument for the given view name or NOTHING if the view cannot be found More...
list | listFunctions ()
| returns a list of string function names in the database
list | listProcedures ()
| returns a list of string procedure names in the database
list | listSequences ()
| returns a list of string sequence names in the database
list | listTables ()
| returns a list of string table names in the database
list | listViews ()
| returns a list of string view names in the database
AbstractFunction | makeFunction (string name, string src, *hash opts)
| creates a database-specific AbstractFunction object corresponding to the arguments More...
AbstractFunction | makeProcedure (string name, string src, *hash opt)
| creates a database-specific AbstractFunction object for a stored procedure corresponding to the arguments More...
AbstractSequence | makeSequence (string name, number start=1, number increment=1, *softnumber end, *hash opts)
| creates a database-specific AbstractSequence object corresponding to the arguments More...
AbstractTable | makeTable (string name, hash desc, *hash opts)
| creates a database-specific AbstractTable object corresponding to the arguments More...
Qore::ListIterator | procedureIterator ()
| returns an iterator listing the string procedure names in the database
bool | rebuildIndex (string name, *hash options)
| Rebuild an index in the DB. More...
bool | rebuildIndex (AbstractIndex index, *hash options)
| Rebuild an index in the DB. More...
| reclaimSpace (*hash options)
| Reclaim taken but unused space in the DB. More...
Qore::ListIterator | sequenceIterator ()
| returns an iterator listing the string sequence names in the database
bool | supportsPackages ()
| returns True if the database supports packages
bool | supportsSequences ()
| returns True if the database supports sequences
bool | supportsTypes ()
| returns True if the database supports named types
Qore::ListIterator | tableIterator ()
| returns an iterator listing the string table names in the database
any | tryExec (string sql)
| executes some SQL with optional arguments so that if an error occurs the current transaction state is not lost More...
any | tryExecArgs (string sql, *softlist args)
| executes some SQL with optional arguments so that if an error occurs the current transaction state is not lost More...
any | tryExecRaw (string sql)
| executes some SQL so that if an error occurs the current transaction state is not lost More...
Qore::ListIterator | viewIterator ()
| returns an iterator listing the string view names in the database
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 | AC_Add = 6
| used when an element is added to an existing object
const | AC_Create = 1
| used when a new object is created
const | AC_Delete = 10
| used when data is deleted in a table
const | AC_Drop = 2
| used when an object is dropped
const | AC_Insert = 8
| used when data is inserted in a table
const | AC_Modify = 4
| used when an object is modified in place
const | AC_NotFound = 11
| used when dropping object but the object is not present
const | AC_Recreate = 7
| used when an object is recreated (usually dropped and recreated in place)
const | AC_Rename = 3
| used when an object is renamed
const | AC_Truncate = 5
| used when a table is truncated
const | AC_Unchanged = 0
| used when an existing object matches the template and no changes are made
const | AC_Update = 9
| used when data is updated in a table
const | ActionDescMap
| maps from action descriptions to action codes
const | ActionLetterMap
| maps from action codes to action letter codes
const | ActionMap
| maps from action codes to action descriptions
const | AlignSchemaOptions
| default generic schema description / alignment options More...
const | CacheOptions
| generic cache options More...
const | CallbackOptions
| generic callback options More...
const | ComputeStatisticsOptions
| Options for computeStatistics()
const | CreationOptions
| default generic creation options More...
const | DatabaseOptions
| database options More...
const | DropSchemaOptions
| default generic drop schema options More...
const | ReclaimSpaceOptions
| Options for reclaimSpace()
const | SchemaDescriptionOptions
| default generic schema description keys More...
const | SequenceDescriptionOptions
| default generic sequence description keys More...

## Private Member Functions

| constructor (AbstractDatasource nds, *hash nopts)
| creates the object; private constructor More...
hash | getAlignSchemaOptions ()
| override in subclasses to return driver-specific options
hash | getCacheOptions ()
| override in subclasses to return driver-specific options
hash | getCallbackOptions ()
| override in subclasses to return driver-specific options
hash | getComputeStatisticsOptions ()
| override in subclasses to return driver-specific options
hash | getCreationOptions ()
| override in subclasses to return driver-specific options
abstract int | getCurrentSequenceValueImpl (string name)
| returns the last value issued for the given sequence in the current session
hash | getDatabaseOptions ()
| override in subclasses to return driver-specific options
hash | getDropSchemaOptions ()
| override in subclasses to return driver-specific options
abstract int | getNextSequenceValueImpl (string name)
| returns the next value in the given sequence
hash | getRebuildIndexOptions ()
| override in subclasses to return driver-specific options
hash | getReclaimSpaceOptions ()
| override in subclasses to return driver-specific options
hash | getSchemaDescriptionOptions ()
| override in subclasses to return driver-specific options
hash | getSequenceDescriptionOptions ()
| override in subclasses to return driver-specific options
abstract bool | supportsSequencesImpl ()
| returns True if the database supports sequences
auto | tryExecArgsImpl (string sql, *softlist args)
| tries to execute a command so that if an error occurs the current transaction status is not lost
auto | tryExecRawImpl (string sql)
| tries to execute a command so that if an error occurs the current transaction status is not lost

## Private Attributes

bool | native_case = False
| native case option

## Detailed Description

the base abstract class for the database implementation

## Member Function Documentation

## computeStatistics()

SqlUtil::AbstractDatabase::computeStatistics | ( | *hash | options | ) |

Compute database statistics.

See Database Statistics

Parameters

  options | an optional database-specific option hash

Exceptions

  COMPUTE-STATISTICS-ERROR | in case of wrong options given

Since
  SqlUtil 1.2

## constructor()

SqlUtil::AbstractDatabase::constructor | ( | AbstractDatasource | nds,
|  | *hash | nopts
| ) |  |

private

creates the object; private constructor

Parameters

  nds | the AbstractDatasource for the connection to the database
  nopts | a hash of options for the function creation string; see AbstractDatabase::DatabaseOptions for common options; each driver can support additional driver-specific options

Exceptions

  OPTION-ERROR | invalid or unsupported option passed

## dropFunctionIfExists()

bool SqlUtil::AbstractDatabase::dropFunctionIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

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

Example:
  db.dropFunctionIfExists(name);

Parameters

  name | the name of the function
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  True if the function was dropped, False if not

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## dropProcedureIfExists()

bool SqlUtil::AbstractDatabase::dropProcedureIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

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

Example:
  db.dropProcedureIfExists(name);

Parameters

  name | the name of the procedure
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  True if the procedure was dropped, False if not

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## dropSequenceIfExists()

bool SqlUtil::AbstractDatabase::dropSequenceIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

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

Example:
  db.dropSequenceIfExists(name);

Parameters

  name | the name of the sequence
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  True if the sequence was dropped, False if not

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## dropTableIfExists()

bool SqlUtil::AbstractDatabase::dropTableIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

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

Example:
  db.dropTableIfExists(name);

Parameters

  name | the name of the table
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  True if the table was dropped, False if not

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## dropViewIfExists()

bool SqlUtil::AbstractDatabase::dropViewIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

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

Example:
  db.dropViewIfExists(name);

Parameters

  name | the name of the view
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  True if the view was dropped, False if not

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## getAlignFunctionSql()

list SqlUtil::AbstractDatabase::getAlignFunctionSql | ( | AbstractFunction | f,
|  | *hash | opt
| ) |  |

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

Example:
  list l = db.getAlignFunctionSql(f);

Parameters

  f | the template or target version of the function to compare to the database version
  opt | an optional hash of options for the generation of the SQL strings; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options

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

Exceptions

  OPTION-ERROR | invalid or unsupported option passed

## getAlignProcedureSql()

list SqlUtil::AbstractDatabase::getAlignProcedureSql | ( | AbstractFunction | f,
|  | *hash | opt
| ) |  |

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

Example:
  list l = db.getAlignProcedureSql(f);

Parameters

  f | the template or target version of the stored procedure to compare to the database version
  opt | an optional hash of options for the generation of the SQL strings; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options

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

Exceptions

  OPTION-ERROR | invalid or unsupported option passed

## getAlignSql()

list SqlUtil::AbstractDatabase::getAlignSql | ( | hash | schema_hash,
|  | *hash | opt,
|  | *Tables | table_cache
| ) |  |

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

Example:
  list l = db.getAlignSql(schema_hash);

Parameters

  schema_hash | the schema description hash that decribes the target state of the schema
  opt | a hash of options for the SQL creation strings; see AbstractDatabase::AlignSchemaOptions for common options; each driver can support additional driver-specific options
  table_cache | an optional object of class Tables to return the cache of AbstractTable objects keyed by table name for the schema template (ie target table definitions)

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

Exceptions

  SCHEMA-DESCRIPTION-ERROR | the schema description hash has an error or a required object does not exist
  OPTION-ERROR | invalid or unsupported option passed

## getCurrentSequenceValue()

int SqlUtil::AbstractDatabase::getCurrentSequenceValue | ( | string | name | ) |

returns the last value issued for the given sequence in the current session

Example:
  number n = db.getCurrentSequenceValue("seq_customers");

Parameters

  name | the name of the sequence

Returns
  the last value issued for the given sequence in the current session

## getDropFunctionSqlIfExists()

*string SqlUtil::AbstractDatabase::getDropFunctionSqlIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

returns the SQL require to drop the given function if it exists or NOTHING if the named function does not exist

Example:
  string sql = db.getDropFunctionSqlIfExists(name);

Parameters

  name | the name of the function
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  the SQL require to drop the given function if it exists or NOTHING if the named function does not exist

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## getDropProcedureSqlIfExists()

*string SqlUtil::AbstractDatabase::getDropProcedureSqlIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

returns the SQL require to drop the given procedure if it exists or NOTHING if the named procedure does not exist

Example:
  string sql = db.getDropProcedureSqlIfExists(name);

Parameters

  name | the name of the procedure
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  the SQL require to drop the given procedure if it exists or NOTHING if the named procedure does not exist

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## getDropSchemaSql()

list SqlUtil::AbstractDatabase::getDropSchemaSql | ( | hash | schema_hash,
|  | *hash | opt
| ) |  |

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

Example:
  list l = db.getDropSchemaSql(schema_hash);

Parameters

  schema_hash | the schema description hash that decribes the state of the schema
  opt | a hash of options for the SQL creation strings; see AbstractDatabase::DropSchemaOptions for common options; each driver can support additional driver-specific options

Returns
  a list of SQL strings that can be used to drop any existing objects in the database; if none of the described objects exist, then an empty list is returned

Exceptions

  SCHEMA-DESCRIPTION-ERROR | the schema description hash has an error
  OPTION-ERROR | invalid or unsupported option passed

## getDropSequenceSqlIfExists()

*string SqlUtil::AbstractDatabase::getDropSequenceSqlIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

returns the SQL require to drop the given sequence if it exists or NOTHING if the named sequence does not exist

Example:
  string sql = db.getDropSequenceSqlIfExists(name);

Parameters

  name | the name of the sequence
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  the SQL require to drop the given sequence if it exists or NOTHING if the named sequence does not exist

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## getDropTableSqlIfExists()

*list SqlUtil::AbstractDatabase::getDropTableSqlIfExists | ( | string | name,
|  | *hash | opt
| ) |  |

returns the SQL require to drop the given table if it exists or NOTHING if the named table does not exist

Example:
  string sql = db.getDropTableSqlIfExists(name);

Parameters

  name | the name of the table
  opt | optional callback options; see AbstractDatabase::CallbackOptions for more info

Returns
  the SQL require to drop the given table if it exists or NOTHING if the named table does not exist

Exceptions

  OPTION-ERROR | invalid or unknown callback option

## getFunction()

*AbstractFunction SqlUtil::AbstractDatabase::getFunction | ( | string | name | ) |

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

Example:
  *AbstractFunction f = db.getFunction("update_queue");

Parameters

  name | the uniquely-identifying name of the function to retrieve

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

Note
  for databases that support overloaded functions, the arguments must be passed in parentheses after the name to match overloaded functions properly

## getNextSequenceValue()

int SqlUtil::AbstractDatabase::getNextSequenceValue | ( | string | name | ) |

returns the next value in the given sequence

Example:
  number n = db.getNextSequenceValue("seq_customers");

Parameters

  name | the name of the sequence

Returns
  the next value in the given sequence

## getProcedure()

*AbstractFunction SqlUtil::AbstractDatabase::getProcedure | ( | string | name | ) |

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

Example:
  *AbstractFunction f = db.getProcedure("update_queue");

Parameters

  name | the uniquely-identifying name of the stored procedure to retrieve

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

Note
  for databases that support overloaded stored procedures, the arguments must be passed in parentheses after the name to match overloaded stored procedures properly

## getSequence()

*AbstractSequence SqlUtil::AbstractDatabase::getSequence | ( | string | name | ) |

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

Example:
  *AbstractSequence seq = db.getSequence("seq_queues");

Parameters

  name | the uniquely-identifying name of the sequence to retrieve

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

## getSqlFromList()

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

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

Example:
  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

## getTable()

*AbstractTable SqlUtil::AbstractDatabase::getTable | ( | string | name | ) |

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

Example:
  *AbstractTable table = db.getTable("queues");

Parameters

  name | the uniquely-identifying name of the table to retrieve

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

## getView()

*AbstractView SqlUtil::AbstractDatabase::getView | ( | string | name | ) |

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

Example:
  *AbstractFunction f = db.getView("my_view");

Parameters

  name | the uniquely-identifying name of the view to retrieve

Returns
  an AbstractView argument for the given view name or NOTHING if the sview cannot be found

## makeFunction()

AbstractFunction SqlUtil::AbstractDatabase::makeFunction | ( | string | name,
|  | string | src,
|  | *hash | opts
| ) |  |

creates a database-specific AbstractFunction object corresponding to the arguments

Example:
  AbstractFunction f = db.makeFunction("update_queue", src);

Parameters

  name | the name of the function
  src | the database-specific source code of the function (see the database-specific documentation for information about the format of this parameter; generally it's simply the normal source code for the function required by the database)
  opts | an optional hash of options for the creation of the function; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options

Exceptions

  OPTION-ERROR | invalid or unsupported option passed

## makeProcedure()

AbstractFunction SqlUtil::AbstractDatabase::makeProcedure | ( | string | name,
|  | string | src,
|  | *hash | opt
| ) |  |

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

Example:
  AbstractFunction f = db.makeProcedure("get_queue_info", src);

Parameters

  name | the name of the stored procedure
  src | the database-specific source code of the stored procedure (see the database-specific documentation for information about the format of this parameter; generally it's simply the normal source code for the stored procedure required by the database)
  opt | an optional hash of options for the creation of the stored procedure; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options

Exceptions

  OPTION-ERROR | invalid or unsupported option passed

## makeSequence()

AbstractSequence SqlUtil::AbstractDatabase::makeSequence | ( | string | name,
|  | number | start = `1`,
|  | number | increment = `1`,
|  | *softnumber | end,
|  | *hash | opts
| ) |  |

creates a database-specific AbstractSequence object corresponding to the arguments

Example:
  AbstractSequence seq = db.makeSequence("seq_queues");

Parameters

  name | the name of the sequence
  start | the starting value of the sequence
  increment | the increment value of the sequence
  end | the endinf value of the sequence, omit for no ending value
  opts | an optional hash of options for the creation of the sequence; see AbstractDatabase::CreationOptions for common options; each driver can support additional driver-specific options

Exceptions

  OPTION-ERROR | invalid or unsupported option passed
  SEQUENCE-ERROR | end not compatible with start and increment, increment is zero

## makeTable()

AbstractTable SqlUtil::AbstractDatabase::makeTable | ( | string | name,
|  | hash | desc,
|  | *hash | opts
| ) |  |

creates a database-specific AbstractTable object corresponding to the arguments

Example:
  AbstractTable table = db.makeTable("table", th);

Parameters

  name | the name of the table
  desc | a table description hash describing the table
  opts | 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

See also
  SqlUtil::AbstractTable::constructor()

## rebuildIndex() [1/2]

bool SqlUtil::AbstractDatabase::rebuildIndex | ( | string | name,
|  | *hash | options
| ) |  |

Rebuild an index in the DB.

See Index Management

Parameters

  name | an index name
  options | an optional database-specific option hash

Returns
  bool True if the index was rebuild, False it it was left untouched

Exceptions

  REBUILD-INDEX-ERROR | in case of MySQL or in case of wrong options given

Since
  SqlUtil 1.2

## rebuildIndex() [2/2]

bool SqlUtil::AbstractDatabase::rebuildIndex | ( | AbstractIndex | index,
|  | *hash | options
| ) |  |

Rebuild an index in the DB.

See Index Management

Parameters

  index | an AbstractIndex object
  options | an optional database-specific option hash

Exceptions

  REBUILD-INDEX-ERROR | in case of MySQL or in case of wrong options given

Since
  SqlUtil 1.2

## reclaimSpace()

SqlUtil::AbstractDatabase::reclaimSpace | ( | *hash | options | ) |

Reclaim taken but unused space in the DB.

See Space Management

Parameters

  options | an optional database-specific option hash

Exceptions

  RECLAIM-SPACE-ERROR | in case of wrong options given

Since
  SqlUtil 1.2

## tryExec()

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

## tryExecArgs()

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

## tryExecRaw()

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

## Member Data Documentation

## AlignSchemaOptions

const SqlUtil::AbstractDatabase::AlignSchemaOptions

Initial value:
= CreationOptions + (
"force": Type::Boolean,
)

default generic schema description / alignment options

Currently this option is identical to AbstractDatabase::CreationOptions plus the following keys:

- `force:` (bool) is True and supported by the underlying db driver, `FORCE` or `CASCADE` options are used when dropping or aligning objects

## CacheOptions

const SqlUtil::AbstractDatabase::CacheOptions

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

generic cache 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

## CallbackOptions

const SqlUtil::AbstractDatabase::CallbackOptions

Initial value:
= (
"info_callback": "code",
"sql_callback": "code",
"sql_callback_executed": Type::Boolean,
)

generic callback options

The following keys can be set for this option:

- `info_callback:` see SQL Info CallBack Closure or Call Ceference
- `sql_callback:` see SQL Raw/DDL CallBack Closure or Call Ceference
- `sql_callback_executed:` see SQL CallBack Executed Flag

## CreationOptions

const SqlUtil::AbstractDatabase::CreationOptions

Initial value:
= CallbackOptions + (
"replace": Type::Boolean,
"table_cache": "Tables",
"data_tablespace": Type::String,
"index_tablespace": Type::String,
)

default generic creation options

This option is comprised of AbstractDatabase::CallbackOptions plus the following keys:

- `replace:` (bool) if True and supported by the underlying db driver, `"create or replace"` text is used when creating objects
- `table_cache:` (Tables) an optional table cache for maintaining cached tables and foreign key relationships between tables
- `data_tablespace:` (string) a string giving the data tablespace to use for tables
- `index_tablespace:` (string) a string giving the index tablespace to use for indexes

## DatabaseOptions

const SqlUtil::AbstractDatabase::DatabaseOptions

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

database 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

## DropSchemaOptions

const SqlUtil::AbstractDatabase::DropSchemaOptions

Initial value:
= CallbackOptions + (
"force": Type::Boolean,
)

default generic drop schema options

Currently this option is identical to AbstractDatabase::CallbackOptions plus the following keys:

- `force:` (bool) is True and supported by the underlying db driver, `FORCE` or `CASCADE` options are used when dropping objects

## SchemaDescriptionOptions

const SqlUtil::AbstractDatabase::SchemaDescriptionOptions

Initial value:
= (
"tables": Type::Hash,
"table_map": Type::Hash,
"sequences": Type::Hash,
"sequence_map": Type::Hash,
"functions": Type::Hash,
"function_map": Type::Hash,
"procedures": Type::Hash,
"procedure_map": Type::Hash,
)

default generic schema description keys

The following keys can be set in schema description hashes:

- `tables:` a hash keyed by table name set to table description hash values
- `table_map:` a hash for automatically renaming tables; if the source name (key) exists and the target name (value) does not exist, then the source table is automatically renamed
- `sequences:` a hash keyed by sequence name set to sequence hash description values
- `sequence_map:` a hash for automatically renaming sequences; if the source name (key) exists and the target name (value) does not exist, then the source sequence is automatically renamed
- `functions:` a hash keyed by function name set to function source string values
- `function_map:` a hash for automatically renaming functions; if the source name (key) exists and the target name (value) does not exist, then the source function is automatically renamed
- `procedures:` a hash keyed by procedure name set to procedure source string values
- `procedure_map:` a hash for automatically renaming procedures; if the source name (key) exists and the target name (value) does not exist, then the source procedure is automatically renamed

See also
  Schema Description Hash for more information

## SequenceDescriptionOptions

const SqlUtil::AbstractDatabase::SequenceDescriptionOptions

Initial value:
= (
"start": Type::Int,
"increment": Type::Int,
"end": Type::Int,
)

default generic sequence description keys

The following keys can be set in sequence description hashes:

- `start:` (int) the starting value for the sequence
- `increment:` (int) the increment value for the sequence
- `end:` (int) the ending value for the sequence