Qore Schema Module Reference  1.2
Schema::AbstractSchema Class Referenceabstract

the AbstractSchema class is a base class to assist with automatic schema management More...

Inheritance diagram for Schema::AbstractSchema:

Public Member Functions

int align (bool force=False, int verbose=0)
 executes a schema alignment action on the database with the current schema template More...
 
 constructor (Qore::SQL::AbstractDatasource n_ds, *string dts, *string its, *hash opts)
 creates the object from the arguments More...
 
 drop (bool force=False, int verbose=0)
 executes a schema drop operation in the database
 
*hash getColumnOptions ()
 returns column options More...
 
*hash getCreateOnlyReferenceData ()
 returns a hash of "create-only reference data", describing data that is written to the table when the table is created More...
 
*hash getCreationOptions ()
 returns schema creation options More...
 
SqlUtil::AbstractDatabase getDatabase ()
 returns the AbstractDatabase object used for the schema
 
Qore::SQL::AbstractDatasource getDatasource ()
 returns the datasource used for the schema
 
*hash getFunctions ()
 returns function definitions More...
 
*hash getIndexOptions ()
 returns index options More...
 
*hash getInsertOnlyReferenceData ()
 returns a hash of "create-only reference data", describing data that will only be inserted if missing, otherwise existing rows with changed data are left unchanged More...
 
*hash getMaterializedViews ()
 returns materialized view definitions More...
 
string getName ()
 returns the name of the schema
 
*hash getPackages ()
 returns (Oracle) package definitions More...
 
*hash getProcedures ()
 returns stored procedure definitions More...
 
*hash getReferenceDataHash ()
 returns a hash of "normal reference data", describing data that must appear in the target table, however additional rows are also acceptable More...
 
*hash getSequences ()
 returns sequence definitions More...
 
*hash getStrictReferenceDataHash ()
 returns a hash of "strict reference data", describing the only data that can appear in the target table More...
 
*hash getTables ()
 returns table definitions More...
 
*hash getTypes ()
 returns type definitions More...
 
string getVersion ()
 returns the version of the schema
 
 log (string fmt)
 outputs a log message More...
 
 logpf (string fmt)
 outputs a log message prefixed with the schema name More...
 
 logProgress (string str)
 outputs a log message without any newline More...
 

Static Public Member Functions

static hash combineOptions (*hash h)
 combines option hashes into a single target option hash
 
static list getRows (*softlist l)
 returns a list of hashes from a list of lists where the first list element in the top-level list is a list of column names, and subsequent lists are column values More...
 

Private Member Functions

bool checkDropSchema (bool force)
 this method returns True if the schema can be dropped
 
bool checkExistence ()
 returns True if the method can detect that DB objects defined in the schema exist in the database More...
 
bool checkFirstTimeInstall ()
 returns True if checkExistence() returns False
 
bool checkUpdateSchema (bool force, reference< hash > initial_schema_info)
 this method returns True if the schema can be updated
 
 doPostAlignment (Tables table_cache, bool first_time_install, *hash initial_schema_info)
 this method is called after schema structural alignment has been executed but before schema reference data management
 
 doTable (AbstractTable table, list rows, int upsert_strategy, bool delete_others, int verbose, reference< hash > sh)
 this method is called to perform schema reference data managment on the given table with the given data
 
*hash getColumnOptionsImpl ()
 returns column options More...
 
*hash getCreateOnlyReferenceDataImpl ()
 returns a hash of "create-only reference data", describing data that is written to the table when the table is created More...
 
*hash getFunctionsImpl ()
 returns function definitions More...
 
*hash getGenericOptionsImpl ()
 returns schema creation options More...
 
*hash getIndexOptionsImpl ()
 returns index options More...
 
*hash getInsertOnlyReferenceDataImpl ()
 returns a hash of "insert-only reference data", describing data that will only be inserted if missing, otherwise existing rows with changed data are left unchanged More...
 
*hash getMaterializedViewsImpl ()
 returns materialized view definitions More...
 
abstract string getNameImpl ()
 returns the name of the schema
 
*hash getPackagesImpl ()
 returns (Oracle) package definitions More...
 
*hash getProceduresImpl ()
 returns stored procedure definitions More...
 
*hash getReferenceDataHashImpl ()
 returns a hash of "normal reference data", describing data that must appear in the target table, however additional rows are also acceptable More...
 
*hash getSequencesImpl ()
 returns sequence definitions More...
 
*hash getStrictReferenceDataHashImpl ()
 returns a hash of "strict reference data", describing the only data that can appear in the target table More...
 
*hash getTablesImpl ()
 returns table definitions More...
 
*hash getTypesImpl ()
 returns type definitions More...
 
int getUpsertStrategy (bool first_time_install)
 this method is called to return the upsert strategy before schema reference data management
 
abstract string getVersionImpl ()
 returns the version of the schema
 
 postDataActions (bool first_time_install)
 this method is called after schema reference data has been managed
 

Private Attributes

*hash all_options
 combined creation and column options
 
hash callback_opts
 callback options plus all options
 
*hash column_options
 column options, as provided by getColumnOptions()
 
*hash creation_options
 creation options, as provided by getCreationOptions()
 
*string data_ts
 explicit data tablespace name
 
SqlUtil::Database db
 the Database object for the schema
 
string drv
 the name of the database driver
 
Qore::SQL::AbstractDatasource ds
 the datasource for the schema
 
*hash index_options
 index options, as provided by getIndexOptions()
 
*string index_ts
 explicit index tablespace name
 
code info_callback
 the info callback for schema operations; can be used for explicit logging
 
string name
 the name of the schema
 
hash pure_callback_opts
 just callback options
 
hash schema
 the schema template, as assembled from method callbacks providing schema element definitions
 
string version
 the version of the schema
 

Detailed Description

the AbstractSchema class is a base class to assist with automatic schema management

This class allows the following actions to be performed:

  • schema creation, upgrades, and downgrades (through schema alignment)
  • schema deletion / dropping

This class does not provide for any intelligence based on the schema template's version and a schema version string stored in the schema itself; this is provided instead by the AbstractVersionedSchema class.

The following abstract methods must be re-implemented in subclasses to define basic schema attributes:

The following methods should be re-implemented in subclasses to define schema definitions from which DDL will be generated::

The following methods should be re-implemented in subclasses to define schema creation options to affect the generated DDL:

The following methods should be re-implemented in subclasses to define schema reference data:

  • getStrictReferenceDataHashImpl(): returns a hash of "strict reference data", describing the only data that can appear in the target table
  • getReferenceDataHashImpl(): returns a hash of "normal reference data", describing data that must appear in the target table, however additional rows are also acceptable
  • getCreateOnlyReferenceDataImpl(): returns a hash of "create-only reference data", describing data that is written to the table when the table is created
  • getInsertOnlyReferenceDataImpl(): returns a hash of "insert-only reference data", describing data that will only be inserted if missing, otherwise existing rows with changed data are left unchanged

Member Function Documentation

◆ align()

int Schema::AbstractSchema::align ( bool  force = False,
int  verbose = 0 
)

executes a schema alignment action on the database with the current schema template

this causes the database to be aligned with the schema template, which will result in:

  • the schema being created in an empty schema
  • the schema being upgraded if an older version of the schema exists in the database
  • the schema being downgraded if a newer version of the schema exists in the database
Note
if other database objects not belonging to the schema already exist in the given database, they are not touched unless explicitly dropped by upgrade or downgrade code in the schema class; note that any undefined attributes of tables defined in the schema (columns, indexes, constraints, etc) will be dropped however

◆ checkExistence()

bool Schema::AbstractSchema::checkExistence ( )
private

returns True if the method can detect that DB objects defined in the schema exist in the database

Currently this method checks if at least one of the first tables, sequences, functions, or procedures defined in the schema template exists. If so, this method returns True, otherwise it returns False

◆ constructor()

Schema::AbstractSchema::constructor ( Qore::SQL::AbstractDatasource  n_ds,
*string  dts,
*string  its,
*hash  opts 
)

creates the object from the arguments

Parameters
n_dsthe datasource for the schema
dtsan optional data tablespace name for the schema
itsan optional index tablespace name for the schema
optsoptions for SqlUtil::Database::constructor()

◆ getColumnOptions()

*hash Schema::AbstractSchema::getColumnOptions ( )

returns column options

this function wraps getColumnOptionsImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getColumnOptionsImpl()

◆ getColumnOptionsImpl()

*hash Schema::AbstractSchema::getColumnOptionsImpl ( )
private

returns column options

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom options

◆ getCreateOnlyReferenceData()

*hash Schema::AbstractSchema::getCreateOnlyReferenceData ( )

returns a hash of "create-only reference data", describing data that is written to the table when the table is created

this function wraps (); for forwards-compatibility, do not override this method in subclasses, instead re-implement ()

◆ getCreateOnlyReferenceDataImpl()

*hash Schema::AbstractSchema::getCreateOnlyReferenceDataImpl ( )
private

returns a hash of "create-only reference data", describing data that is written to the table when the table is created

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getCreationOptions()

*hash Schema::AbstractSchema::getCreationOptions ( )

returns schema creation options

this function wraps getGenericOptionsImpl() and getIndexOptionsImpl() and sets the data and index tablespace names as creation options automatically if set in the constructor() if not already set

◆ getFunctions()

*hash Schema::AbstractSchema::getFunctions ( )

returns function definitions

this function wraps getFunctionsImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getFunctionsImpl()

◆ getFunctionsImpl()

*hash Schema::AbstractSchema::getFunctionsImpl ( )
private

returns function definitions

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getGenericOptionsImpl()

*hash Schema::AbstractSchema::getGenericOptionsImpl ( )
private

returns schema creation options

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom options

◆ getIndexOptions()

*hash Schema::AbstractSchema::getIndexOptions ( )

returns index options

this function wraps getIndexOptionsImpl() and sets the index tablespace name as an index option automatically if set in the constructor() if not already set

◆ getIndexOptionsImpl()

*hash Schema::AbstractSchema::getIndexOptionsImpl ( )
private

returns index options

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom options

◆ getInsertOnlyReferenceData()

*hash Schema::AbstractSchema::getInsertOnlyReferenceData ( )

returns a hash of "create-only reference data", describing data that will only be inserted if missing, otherwise existing rows with changed data are left unchanged

this function wraps (); for forwards-compatibility, do not override this method in subclasses, instead re-implement ()

◆ getInsertOnlyReferenceDataImpl()

*hash Schema::AbstractSchema::getInsertOnlyReferenceDataImpl ( )
private

returns a hash of "insert-only reference data", describing data that will only be inserted if missing, otherwise existing rows with changed data are left unchanged

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getMaterializedViews()

*hash Schema::AbstractSchema::getMaterializedViews ( )

returns materialized view definitions

this function wraps getMaterializedViewsImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getMaterializedViewsImpl()

◆ getMaterializedViewsImpl()

*hash Schema::AbstractSchema::getMaterializedViewsImpl ( )
private

returns materialized view definitions

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getPackages()

*hash Schema::AbstractSchema::getPackages ( )

returns (Oracle) package definitions

this function wraps getPackagesImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getPackagesImpl()

◆ getPackagesImpl()

*hash Schema::AbstractSchema::getPackagesImpl ( )
private

returns (Oracle) package definitions

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getProcedures()

*hash Schema::AbstractSchema::getProcedures ( )

returns stored procedure definitions

this function wraps getProceduresImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getProceduresImpl()

◆ getProceduresImpl()

*hash Schema::AbstractSchema::getProceduresImpl ( )
private

returns stored procedure definitions

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getReferenceDataHash()

*hash Schema::AbstractSchema::getReferenceDataHash ( )

returns a hash of "normal reference data", describing data that must appear in the target table, however additional rows are also acceptable

this function wraps getReferenceDataHashImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getReferenceDataHashImpl()

◆ getReferenceDataHashImpl()

*hash Schema::AbstractSchema::getReferenceDataHashImpl ( )
private

returns a hash of "normal reference data", describing data that must appear in the target table, however additional rows are also acceptable

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getRows()

static list Schema::AbstractSchema::getRows ( *softlist  l)
static

returns a list of hashes from a list of lists where the first list element in the top-level list is a list of column names, and subsequent lists are column values

meant to be used to translate reference data lists into lists of hashes to be used for upserting in reference data tables during schema management

◆ getSequences()

*hash Schema::AbstractSchema::getSequences ( )

returns sequence definitions

this function wraps getSequencesImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getSequencesImpl()

◆ getSequencesImpl()

*hash Schema::AbstractSchema::getSequencesImpl ( )
private

returns sequence definitions

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getStrictReferenceDataHash()

*hash Schema::AbstractSchema::getStrictReferenceDataHash ( )

returns a hash of "strict reference data", describing the only data that can appear in the target table

this function wraps getStrictReferenceDataHashImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getStrictReferenceDataHashImpl()

◆ getStrictReferenceDataHashImpl()

*hash Schema::AbstractSchema::getStrictReferenceDataHashImpl ( )
private

returns a hash of "strict reference data", describing the only data that can appear in the target table

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getTables()

*hash Schema::AbstractSchema::getTables ( )

returns table definitions

this function wraps getTablesImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getTablesImpl()

◆ getTablesImpl()

*hash Schema::AbstractSchema::getTablesImpl ( )
private

returns table definitions

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ getTypes()

*hash Schema::AbstractSchema::getTypes ( )

returns type definitions

this function wraps getTypesImpl(); for forwards-compatibility, do not override this method in subclasses, instead re-implement getTypesImpl()

◆ getTypesImpl()

*hash Schema::AbstractSchema::getTypesImpl ( )
private

returns type definitions

the default behavior of this method is to return NOTHING, reimplement in subclasses to return custom configuration

◆ log()

Schema::AbstractSchema::log ( string  fmt)

outputs a log message

the log string is output with a following newline, and the terminal I/O is flushed

◆ logpf()

Schema::AbstractSchema::logpf ( string  fmt)

outputs a log message prefixed with the schema name

the log string is output with a following newline, and the terminal I/O is flushed

◆ logProgress()

Schema::AbstractSchema::logProgress ( string  str)

outputs a log message without any newline

the terminal I/O is flushed as well