Schema.qm.dox.h
// -*- mode: c++; indent-tabs-mode: nil -*-
// @file Schema.qm Qore user module for working with SQL data
/* Schema.qm Copyright 2014 - 2016 Qore Technologies, s.r.o.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
*/
// this module requires Qore 0.8.12 or better
// requires the SqlUtil module
// requires the Util module
// don't use "$" signs for variables and class members, assume local variable scope
// require type definitions everywhere
// enable all warnings
// strict args
namespace Schema {
const C_NULL = False;
const C_NOT_NULL = True;
hash c_int(bool notnull = False, *string comment);
hash c_int(string comment);
hash c_varchar(int size, bool notnull = False, *string comment);
hash c_varchar(int size, string comment);
hash c_char(int size, bool notnull = False, *string comment);
hash c_char(int size, string comment);
hash c_date(bool notnull = False, *string comment);
hash c_date(string comment);
hash c_timestamp(bool notnull = False, *string comment);
hash c_timestamp(string comment);
hash c_number(bool notnull = False, *string comment);
hash c_number(int size, int scale, bool notnull = False, *string comment);
hash c_number(int size, bool notnull = False, *string comment);
hash c_number(int size, string comment);
class SchemaCallbackHelper {
public:
public :
AbstractSchema schema;
int verbose;
int change_count = 0;
int dot_count = 0;
int error_count = 0;
list sql_cache = ();
public:
constructor(AbstractSchema sc, int v = 0);
infoCallback(string str, int ac, *string type, *string name, *string table, *string new_name, *string info);
sqlCallback(string str);
nothing sqlForceCallback(string str);
hash getCallbacks(bool force = False);
};
class AbstractSchema {
public:
private :
string name;
string version;
hash schema;
*hash index_options;
*hash creation_options;
*hash column_options;
*hash all_options;
AbstractDatasource ds;
string drv;
SqlUtil::Database db;
hash pure_callback_opts;
hash callback_opts;
code info_callback;
*string data_ts;
*string index_ts;
public:
constructor(AbstractDatasource n_ds, *string dts, *string its, *hash opts);
string getName();
string getVersion();
AbstractDatasource getDatasource();
AbstractDatabase getDatabase();
logpf(string fmt);
log(string fmt);
logProgress(string str);
int align(bool force = False, int verbose = 0);
drop(bool force = False, int verbose = 0);
*hash getIndexOptions();
*hash getCreationOptions();
*hash getColumnOptions();
*hash getTables();
*hash getSequences();
*hash getTypes();
*hash getFunctions();
*hash getProcedures();
*hash getPackages();
*hash getMaterializedViews();
*hash getStrictReferenceDataHash();
*hash getReferenceDataHash();
*hash getCreateOnlyReferenceData();
*hash getInsertOnlyReferenceData();
private abstract string getNameImpl();
private abstract string getVersionImpl();
private *hash getIndexOptionsImpl();
private *hash getColumnOptionsImpl();
private *hash getGenericOptionsImpl();
private *hash getTablesImpl();
private *hash getSequencesImpl();
private *hash getTypesImpl();
private *hash getFunctionsImpl();
private *hash getProceduresImpl();
private *hash getPackagesImpl();
private *hash getMaterializedViewsImpl();
private *hash getStrictReferenceDataHashImpl();
private *hash getReferenceDataHashImpl();
private *hash getCreateOnlyReferenceDataImpl();
private *hash getInsertOnlyReferenceDataImpl();
private bool checkExistence();
private bool checkFirstTimeInstall();
private bool checkDropSchema(bool force);
private bool checkUpdateSchema(bool force, reference initial_schema_info);
private doPostAlignment(Tables table_cache, bool first_time_install, *hash initial_schema_info);
private int getUpsertStrategy(bool first_time_install);
private postDataActions(bool first_time_install);
private doTable(AbstractTable table, list rows, int upsert_strategy, bool delete_others, int verbose, reference sh);
static list getRows(*softlist l);
static hash combineOptions(*hash h);
};
class AbstractVersionedSchema : public AbstractSchema {
public:
private :
string version_table;
string version_column;
hash version_where;
public:
constructor(AbstractDatasource ds, *string dts, *string its, *hash opts) ;
private *softstring getSchemaVersion();
private bool checkDropSchema(bool force);
private bool checkUpdateSchema(bool force, reference initial_schema_info);
private bool checkUpgrade(string current_version);
private bool checkDowngrade(string current_version);
private string getVersionTable();
private string getVersionColumn();
private hash getVersionWhere();
private abstract string getVersionTableImpl();
private abstract string getVersionColumnImpl();
private abstract hash getVersionWhereImpl();
};
};
Schema::AbstractSchema::getDatabase
AbstractDatabase getDatabase()
returns the AbstractDatabase object used for the schema
Schema::AbstractVersionedSchema::getVersionColumn
private string getVersionColumn()
returns the name of the column holding the schema version string by calling getVersionColumnImpl() ...
Schema::AbstractSchema::getTablesImpl
private *hash getTablesImpl()
returns table definitions
Schema::AbstractSchema::logProgress
logProgress(string str)
outputs a log message without any newline
Schema::c_timestamp
hash c_timestamp(bool notnull=False, *string comment)
returns a column hash for a TIMESTAMP column
Schema::c_date
hash c_date(bool notnull=False, *string comment)
returns a column hash for a DATE column
Schema::AbstractSchema::getIndexOptions
*hash getIndexOptions()
returns index options
Schema::AbstractVersionedSchema::checkUpgrade
private bool checkUpgrade(string current_version)
this method is called if the current schema version is less than the target version; returns True if ...
Schema::AbstractSchema::getProcedures
*hash getProcedures()
returns stored procedure definitions
Schema::AbstractSchema::getStrictReferenceDataHashImpl
private *hash getStrictReferenceDataHashImpl()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
Schema::AbstractSchema::getGenericOptionsImpl
private *hash getGenericOptionsImpl()
returns schema creation options
Schema::AbstractVersionedSchema::getVersionColumnImpl
abstract private string getVersionColumnImpl()
returns the name of the column holding the schema version string
Schema::SchemaCallbackHelper::getCallbacks
hash getCallbacks(bool force=False)
returns a callback option hash usable with SqlUtil schema operations
Schema::SchemaCallbackHelper::infoCallback
infoCallback(string str, int ac, *string type, *string name, *string table, *string new_name, *string info)
this is the informational callback method for schema operations
Schema::AbstractSchema::getReferenceDataHashImpl
private *hash getReferenceDataHashImpl()
returns a hash of "normal reference data", describing data that must appear in the target table...
Schema::AbstractSchema::ds
AbstractDatasource ds
the datasource for the schema
Definition: Schema.qm.dox.h:305
Schema::AbstractSchema::checkUpdateSchema
private bool checkUpdateSchema(bool force, reference initial_schema_info)
this method returns True if the schema can be updated
Schema::AbstractSchema::name
string name
the name of the schema
Definition: Schema.qm.dox.h:288
Schema::AbstractSchema::getSequences
*hash getSequences()
returns sequence definitions
Schema::AbstractVersionedSchema::getVersionWhere
private hash getVersionWhere()
returns the where clause hash defining the row where the schema version string is located by calling ...
Schema::AbstractSchema::doPostAlignment
private 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...
Schema::AbstractSchema::getVersion
string getVersion()
returns the version of the schema
True
const True
Schema::AbstractSchema::getTables
*hash getTables()
returns table definitions
Schema::AbstractSchema::column_options
*hash column_options
column options, as provided by getColumnOptions()
Definition: Schema.qm.dox.h:300
Schema::AbstractSchema::checkFirstTimeInstall
private bool checkFirstTimeInstall()
returns True if checkExistence() returns False
Schema::c_varchar
hash c_varchar(int size, bool notnull=False, *string comment)
returns a column hash for a VARCHAR column
Schema::AbstractSchema::getReferenceDataHash
*hash getReferenceDataHash()
returns a hash of "normal reference data", describing data that must appear in the target table...
Schema::AbstractSchema::getColumnOptions
*hash getColumnOptions()
returns column options
Schema::AbstractSchema::callback_opts
hash callback_opts
callback options plus all options
Definition: Schema.qm.dox.h:315
Schema::AbstractVersionedSchema::getVersionWhereImpl
abstract private hash getVersionWhereImpl()
returns the where clause hash defining the row where the schema version string is located ...
Schema::AbstractSchema::align
int align(bool force=False, int verbose=0)
executes a schema alignment action on the database with the current schema template ...
SqlUtil::Database
Schema::AbstractSchema::getFunctions
*hash getFunctions()
returns function definitions
False
const False
list
list list(...)
Schema::AbstractSchema::index_options
*hash index_options
index options, as provided by getIndexOptions()
Definition: Schema.qm.dox.h:296
Schema::SchemaCallbackHelper::sqlCallback
sqlCallback(string str)
this is the SQL callback method for schema operations
Schema::AbstractVersionedSchema::version_column
string version_column
the name of the column containing the version string
Definition: Schema.qm.dox.h:637
Schema::AbstractSchema::getColumnOptionsImpl
private *hash getColumnOptionsImpl()
returns column options
Schema::AbstractSchema::drop
drop(bool force=False, int verbose=0)
executes a schema drop operation in the database
Schema::AbstractSchema::data_ts
*string data_ts
explicit data tablespace name
Definition: Schema.qm.dox.h:321
Schema::AbstractSchema::getMaterializedViews
*hash getMaterializedViews()
returns materialized view definitions
Schema::AbstractSchema::constructor
constructor(AbstractDatasource n_ds, *string dts, *string its, *hash opts)
creates the object from the arguments
Schema::C_NULL
const C_NULL
Helper constant for column hash functions with "NULL" constraint for better readability.
Definition: Schema.qm.dox.h:83
Schema::SchemaCallbackHelper::constructor
constructor(AbstractSchema sc, int v=0)
creates the callback object from the given arguments
Schema
this namespace contains all public definitions in the Schema module
Definition: Schema.qm.dox.h:81
Schema::AbstractSchema::log
log(string fmt)
outputs a log message
Schema::AbstractSchema::getCreateOnlyReferenceData
*hash getCreateOnlyReferenceData()
returns a hash of "create-only reference data", describing data that is written to the table when the...
Schema::AbstractVersionedSchema::getVersionTableImpl
abstract private string getVersionTableImpl()
returns the name of the table holding the schema version string
Schema::AbstractSchema::getSequencesImpl
private *hash getSequencesImpl()
returns sequence definitions
Schema::AbstractVersionedSchema
this class extends Schema::AbstractSchema by providing version logic based on a schema version string...
Definition: Schema.qm.dox.h:630
Schema::AbstractSchema::getVersionImpl
abstract private string getVersionImpl()
returns the version of the schema
Schema::AbstractVersionedSchema::checkDropSchema
private bool checkDropSchema(bool force)
this method returns True if the schema can be dropped
Schema::AbstractSchema::postDataActions
private postDataActions(bool first_time_install)
this method is called after schema reference data has been managed
type
string type(any arg)
Schema::AbstractSchema::creation_options
*hash creation_options
creation options, as provided by getCreationOptions()
Definition: Schema.qm.dox.h:298
Schema::c_char
hash c_char(int size, bool notnull=False, *string comment)
returns a column hash for a CHAR column
Schema::AbstractSchema::getIndexOptionsImpl
private *hash getIndexOptionsImpl()
returns index options
Schema::AbstractSchema::schema
hash schema
the schema template, as assembled from method callbacks providing schema element definitions ...
Definition: Schema.qm.dox.h:293
Schema::AbstractSchema::getInsertOnlyReferenceDataImpl
private *hash getInsertOnlyReferenceDataImpl()
returns a hash of "insert-only reference data", describing data that will only be inserted if missing...
Schema::SchemaCallbackHelper
this class provides callback support for schema operations
Definition: Schema.qm.dox.h:213
Schema::AbstractSchema::getStrictReferenceDataHash
*hash getStrictReferenceDataHash()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
Schema::AbstractVersionedSchema::constructor
constructor(AbstractDatasource ds, *string dts, *string its, *hash opts)
creates the object based on the arguments giving the location of the schema
Schema::AbstractSchema::getInsertOnlyReferenceData
*hash getInsertOnlyReferenceData()
returns a hash of "create-only reference data", describing data that will only be inserted if missing...
Schema::AbstractSchema::getCreationOptions
*hash getCreationOptions()
returns schema creation options
Schema::AbstractSchema::getRows
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...
Schema::AbstractSchema::checkExistence
private bool checkExistence()
returns True if the method can detect that DB objects defined in the schema exist in the database ...
Schema::AbstractVersionedSchema::version_table
string version_table
the name of the table containing the version string
Definition: Schema.qm.dox.h:635
Schema::AbstractSchema::getTypes
*hash getTypes()
returns type definitions
Schema::AbstractSchema::getName
string getName()
returns the name of the schema
Schema::AbstractSchema::db
SqlUtil::Database db
the Database object for the schema
Definition: Schema.qm.dox.h:310
Schema::AbstractSchema::getProceduresImpl
private *hash getProceduresImpl()
returns stored procedure definitions
Schema::AbstractSchema::info_callback
code info_callback
the info callback for schema operations; can be used for explicit logging
Definition: Schema.qm.dox.h:318
Schema::AbstractSchema::getFunctionsImpl
private *hash getFunctionsImpl()
returns function definitions
Schema::AbstractSchema::version
string version
the version of the schema
Definition: Schema.qm.dox.h:290
Schema::AbstractVersionedSchema::checkUpdateSchema
private bool checkUpdateSchema(bool force, reference initial_schema_info)
this method returns True if the schema can be updated
Schema::C_NOT_NULL
const C_NOT_NULL
Helper constant for column hash functions with "NOT NULL" constraint for better readability.
Definition: Schema.qm.dox.h:85
Schema::AbstractSchema::all_options
*hash all_options
combined creation and column options
Definition: Schema.qm.dox.h:302
Schema::AbstractVersionedSchema::getSchemaVersion
private *softstring getSchemaVersion()
returns the existing schema version or NOTHING if not present
Schema::AbstractSchema::getNameImpl
abstract private string getNameImpl()
returns the version of the schema
Schema::AbstractSchema::drv
string drv
the name of the database driver
Definition: Schema.qm.dox.h:307
Schema::AbstractSchema::getUpsertStrategy
private int getUpsertStrategy(bool first_time_install)
this method is called to return the upsert strategy before schema reference data management ...
Schema::AbstractVersionedSchema::version_where
hash version_where
a where clause hash defining the row where the schema version string is located
Definition: Schema.qm.dox.h:639
Schema::AbstractVersionedSchema::checkDowngrade
private bool checkDowngrade(string current_version)
this method is called if the current schema version is greater than the target version; returns True ...
Schema::AbstractSchema::getDatasource
AbstractDatasource getDatasource()
returns the datasource used for the schema
Schema::AbstractSchema::logpf
logpf(string fmt)
outputs a log message prefixed with the schema name
Schema::AbstractSchema::pure_callback_opts
hash pure_callback_opts
just callback options
Definition: Schema.qm.dox.h:313
Schema::AbstractSchema::getMaterializedViewsImpl
private *hash getMaterializedViewsImpl()
returns materialized view definitions
Schema::c_number
hash c_number(bool notnull=False, *string comment)
returns a column hash for a NUMBER or NUMERIC column
hash
hash hash(object obj)
Schema::AbstractSchema::doTable
private doTable(AbstractTable table, list rows, int upsert_strategy, bool delete_others, int verbose, reference sh)
this method is called to perform schema reference data managment on the given table with the given da...
Schema::AbstractSchema::getPackagesImpl
private *hash getPackagesImpl()
returns (Oracle) package definitions
Schema::AbstractSchema::getPackages
*hash getPackages()
returns (Oracle) package definitions
Schema::AbstractVersionedSchema::getVersionTable
private string getVersionTable()
returns the name of the table holding the schema version string by calling getVersionTableImpl() ...
Schema::AbstractSchema::getCreateOnlyReferenceDataImpl
private *hash getCreateOnlyReferenceDataImpl()
returns a hash of "create-only reference data", describing data that is written to the table when the...
Schema::AbstractSchema::getTypesImpl
private *hash getTypesImpl()
returns type definitions
Schema::AbstractSchema::index_ts
*string index_ts
explicit index tablespace name
Definition: Schema.qm.dox.h:324
Schema::SchemaCallbackHelper::sqlForceCallback
nothing sqlForceCallback(string str)
this is the SQL callback method for forced schema operations
Schema::AbstractSchema
the AbstractSchema class is a base class to assist with automatic schema management ...
Definition: Schema.qm.dox.h:283
Schema::AbstractSchema::combineOptions
static hash combineOptions(*hash h)
combines option hashes into a single target option hash
Schema::c_int
hash c_int(bool notnull=False, *string comment)
returns a column hash for an INT column
Schema::AbstractSchema::checkDropSchema
private bool checkDropSchema(bool force)
this method returns True if the schema can be dropped