Loading...
Searching...
No Matches
Schema::AbstractSchema Class Referenceabstract

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

Inheritance diagram for Schema::AbstractSchema:
[legend]

## Public Member Functions

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

## Static Public Member Functions

static hash | combineOptions (*hash h)
| combines option hashes into a single target option hash
static list | getRows (*softlist< auto > 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

## Protected Member Functions

SchemaCallbackHelper | alignIntern (bool force=False, int verbose=0, bool do_msgs=True)
| executes a schema alignment action on the database with the current schema template
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
bool | checkFirstTimeInstall ()
| returns True if checkExistence() returns False
bool | checkUpdateSchema (bool force, reference< hash< auto > > initial_schema_info)
| this method returns True if the schema can be updated
| doPostAlignment (Tables table_cache, bool first_time_install, *hash< auto > initial_schema_info)
| this method is called after schema structural alignment has been executed but before schema reference data management
| doPostAlignment (Tables table_cache, bool first_time_install, *hash< auto > initial_schema_info, int verbose)
| 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< string, int > > sh)
| this method is called to perform schema reference data managment on the given table with the given data
*hash< auto > | getColumnOptionsImpl ()
| returns column options
*hash< auto > | getCreateOnlyReferenceDataImpl ()
| returns a hash of "create-only reference data", describing data that is written to the table when the table is created
*hash< auto > | getFunctionsImpl ()
| returns function definitions
*hash< auto > | getGenericOptionsImpl ()
| returns schema creation options
*hash< auto > | getIndexOptionsImpl ()
| returns index options
*hash< auto > | 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
*hash< auto > | getMaterializedViewsImpl ()
| returns materialized view definitions
abstract string | getNameImpl ()
| returns the name of the schema
*hash< auto > | getPackagesImpl ()
| returns (Oracle) package definitions
*hash< auto > | getProceduresImpl ()
| returns stored procedure definitions
*hash< auto > | getReferenceDataHashImpl ()
| returns a hash of "normal reference data", describing data that must appear in the target table, however additional rows are also acceptable
*hash< auto > | getSequencesImpl ()
| returns sequence definitions
*hash< auto > | getStrictReferenceDataHashImpl ()
| returns a hash of "strict reference data", describing the only data that can appear in the target table
*hash< auto > | getTablesImpl ()
| returns table definitions
*hash< auto > | getTypesImpl ()
| returns type definitions
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
| init (Qore::SQL::AbstractDatasource ds, *hash< SchemaOptionInfo > opts)
| shared constructor initialization
| postDataActions (bool first_time_install)
| this method is called after schema reference data has been managed
| postDataActions (Tables table_cache, bool first_time_install, *hash< auto > initial_schema_info, int verbose)
| this method is called after schema reference data has been managed

## Protected 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:

- getNameImpl(): returns the schema name
- getVersionImpl(): returns the schema version

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

- getTablesImpl(): returns table definitions
- getSequencesImpl(): returns sequence definitions
- getTypesImpl(): returns type definitions
- getFunctionsImpl(): returns function definitions
- getProceduresImpl(): returns procedure definitions
- getPackagesImpl(): returns (Oracle) package definitions
- getMaterializedViewsImpl(): returns materialized view definitions

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

- getIndexOptionsImpl(): returns index options
- getColumnOptionsImpl(): returns column options
- getGenericOptionsImpl(): returns generic options

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`,
|  | bool | do_msgs = `True`
| ) |  |

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

Returns
  the number of changes made to the schema

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

## alignIntern()

SchemaCallbackHelper Schema::AbstractSchema::alignIntern | ( | bool | force = `False`,
|  | int | verbose = `0`,
|  | bool | do_msgs = `True`
| ) |  |

protected

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

Returns
  the SchemaCallbackHelper with information on the changes made

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

## alignWithInfo()

hash< SchemaAlignmentInfo > Schema::AbstractSchema::alignWithInfo | ( | bool | force = `False`,
|  | int | verbose = `0`,
|  | bool | do_msgs = `True`
| ) |  |

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

Returns
  the SchemaCallbackHelper with information on the changes made

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 | ( |  | ) |

protected

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

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

## constructor() [1/2]

Schema::AbstractSchema::constructor | ( | Qore::SQL::AbstractDatasource | ds,
|  | *hash< SchemaOptionInfo > | opts
| ) |  |

creates the object from the arguments

Parameters

  ds | the datasource for the schema
  dts | an optional data tablespace name for the schema
  its | an optional index tablespace name for the schema
  opts | options for SqlUtil::Database::constructor()

## constructor() [2/2]

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

creates the object from the arguments

Parameters

  ds | the datasource for the schema
  dts | an optional data tablespace name for the schema
  its | an optional index tablespace name for the schema
  opts | options for SqlUtil::Database::constructor()

## getColumnOptions()

*hash< auto > 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< auto > Schema::AbstractSchema::getColumnOptionsImpl | ( |  | ) |

protected

returns column options

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

## getCreateOnlyReferenceData()

*hash< auto > 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< auto > Schema::AbstractSchema::getCreateOnlyReferenceDataImpl | ( |  | ) |

protected

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< auto > 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< auto > 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< auto > Schema::AbstractSchema::getFunctionsImpl | ( |  | ) |

protected

returns function definitions

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

## getGenericOptionsImpl()

*hash< auto > Schema::AbstractSchema::getGenericOptionsImpl | ( |  | ) |

protected

returns schema creation options

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

## getIndexOptions()

*hash< auto > 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< auto > Schema::AbstractSchema::getIndexOptionsImpl | ( |  | ) |

protected

returns index options

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

## getInsertOnlyReferenceData()

*hash< auto > 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< auto > Schema::AbstractSchema::getInsertOnlyReferenceDataImpl | ( |  | ) |

protected

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< auto > 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< auto > Schema::AbstractSchema::getMaterializedViewsImpl | ( |  | ) |

protected

returns materialized view definitions

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

## getPackages()

*hash< auto > 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< auto > Schema::AbstractSchema::getPackagesImpl | ( |  | ) |

protected

returns (Oracle) package definitions

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

## getProcedures()

*hash< auto > 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< auto > Schema::AbstractSchema::getProceduresImpl | ( |  | ) |

protected

returns stored procedure definitions

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

## getReferenceDataHash()

*hash< auto > 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< auto > Schema::AbstractSchema::getReferenceDataHashImpl | ( |  | ) |

protected

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< auto > | 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< auto > 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< auto > Schema::AbstractSchema::getSequencesImpl | ( |  | ) |

protected

returns sequence definitions

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

## getStrictReferenceDataHash()

*hash< auto > 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< auto > Schema::AbstractSchema::getStrictReferenceDataHashImpl | ( |  | ) |

protected

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< auto > 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< auto > Schema::AbstractSchema::getTablesImpl | ( |  | ) |

protected

returns table definitions

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

## getTypes()

*hash< auto > 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< auto > Schema::AbstractSchema::getTypesImpl | ( |  | ) |

protected

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