Qore Schema Module Reference  1.1
 All Classes Namespaces Functions Variables Groups Pages
Schema.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file Schema.qm Qore user module for working with SQL data
3 
4 /* Schema.qm Copyright 2014 - 2016 Qore Technologies, s.r.o.
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
25 // this module requires Qore 0.8.12 or better
26 
27 // requires the SqlUtil module
28 
29 // requires the Util module
30 
31 // don't use "$" signs for variables and class members, assume local variable scope
32 
33 // require type definitions everywhere
34 
35 // enable all warnings
36 
37 // strict args
38 
39 
80 namespace Schema {
83  const C_NULL = False;
85  const C_NOT_NULL = True;
86 
88 
95  hash c_int(bool notnull = False, *string comment);
96 
97 
99 
105  hash c_int(string comment);
106 
107 
109 
113  hash c_varchar(int size, bool notnull = False, *string comment);
114 
115 
117 
120  hash c_varchar(int size, string comment);
121 
122 
124 
128  hash c_char(int size, bool notnull = False, *string comment);
129 
130 
132 
135  hash c_char(int size, string comment);
136 
137 
139 
144  hash c_date(bool notnull = False, *string comment);
145 
146 
148 
152  hash c_date(string comment);
153 
154 
156 
161  hash c_timestamp(bool notnull = False, *string comment);
162 
163 
165 
169  hash c_timestamp(string comment);
170 
171 
173 
179  hash c_number(bool notnull = False, *string comment);
180 
181 
183 
190  hash c_number(int size, int scale, bool notnull = False, *string comment);
191 
192 
194 
200  hash c_number(int size, bool notnull = False, *string comment);
201 
202 
204 
209  hash c_number(int size, string comment);
210 
211 
214 
215 public:
216  public :
217  AbstractSchema schema;
218  int verbose;
219  int change_count = 0;
220  int dot_count = 0;
221  int error_count = 0;
222  list sql_cache = ();
223 
224 public:
225 
227 
230  constructor(AbstractSchema sc, int v = 0);
231 
232 
234  infoCallback(string str, int ac, *string type, *string name, *string table, *string new_name, *string info);
235 
236 
238  sqlCallback(string str);
239 
240 
242  nothing sqlForceCallback(string str);
243 
244 
246  hash getCallbacks(bool force = False);
247 
248  };
249 
251 
284 
285 public:
286  private :
288  string name;
290  string version;
291 
294 
303 
305  AbstractDatasource ds;
307  string drv;
308 
311 
316 
319 
321  *string data_ts;
322 
324  *string index_ts;
325 
326 public:
327 
329 
334  constructor(AbstractDatasource n_ds, *string dts, *string its, *hash opts);
335 
336 
338  string getName();
339 
340 
342  string getVersion();
343 
344 
346  AbstractDatasource getDatasource();
347 
348 
350  AbstractDatabase getDatabase();
351 
352 
354 
356  logpf(string fmt);
357 
358 
360 
362  log(string fmt);
363 
364 
366 
368  logProgress(string str);
369 
370 
372 
379  int align(bool force = False, int verbose = 0);
380 
381 
383  drop(bool force = False, int verbose = 0);
384 
385 
387 
392 
393 
395 
400 
401 
403 
407 
408 
410 
413  *hash getTables();
414 
415 
417 
420  *hash getSequences();
421 
422 
424 
427  *hash getTypes();
428 
429 
431 
434  *hash getFunctions();
435 
436 
438 
441  *hash getProcedures();
442 
443 
445 
448  *hash getPackages();
449 
450 
452 
456 
457 
459 
463 
464 
466 
470 
471 
473 
477 
478 
480 
484 
485 
487  private abstract string getNameImpl();
488 
490  private abstract string getVersionImpl();
491 
493 
495  private *hash getIndexOptionsImpl();
496 
497 
499 
501  private *hash getColumnOptionsImpl();
502 
503 
505 
507  private *hash getGenericOptionsImpl();
508 
509 
511 
513  private *hash getTablesImpl();
514 
515 
517 
519  private *hash getSequencesImpl();
520 
521 
523 
525  private *hash getTypesImpl();
526 
527 
529 
531  private *hash getFunctionsImpl();
532 
533 
535 
537  private *hash getProceduresImpl();
538 
539 
541 
543  private *hash getPackagesImpl();
544 
545 
547 
549  private *hash getMaterializedViewsImpl();
550 
551 
553 
556 
557 
559 
561  private *hash getReferenceDataHashImpl();
562 
563 
565 
568 
569 
571 
574 
575 
577 
580  private bool checkExistence();
581 
582 
584  private bool checkFirstTimeInstall();
585 
586 
588  private bool checkDropSchema(bool force);
589 
590 
592  private bool checkUpdateSchema(bool force, reference initial_schema_info);
593 
594 
596  private doPostAlignment(Tables table_cache, bool first_time_install, *hash initial_schema_info);
597 
598 
600  private int getUpsertStrategy(bool first_time_install);
601 
602 
604  private postDataActions(bool first_time_install);
605 
606 
608  private doTable(AbstractTable table, list rows, int upsert_strategy, bool delete_others, int verbose, reference sh);
609 
610 
612 
614  static list getRows(*softlist l);
615 
617  static hash combineOptions(*hash h);
618  };
619 
621 
631 
632 public:
633  private :
640 
641 public:
642 
644 
649  constructor(AbstractDatasource ds, *string dts, *string its, *hash opts) ;
650 
651 
653  private *softstring getSchemaVersion();
654 
655 
657  private bool checkDropSchema(bool force);
658 
659 
661  private bool checkUpdateSchema(bool force, reference initial_schema_info);
662 
663 
665  private bool checkUpgrade(string current_version);
666 
667 
669  private bool checkDowngrade(string current_version);
670 
671 
673 
676  private string getVersionTable();
677 
678 
680 
683  private string getVersionColumn();
684 
685 
687 
690  private hash getVersionWhere();
691 
692 
694  private abstract string getVersionTableImpl();
695 
697  private abstract string getVersionColumnImpl();
698 
700  private abstract hash getVersionWhereImpl();
701  };
702 };
AbstractDatabase getDatabase()
returns the AbstractDatabase object used for the schema
private string getVersionColumn()
returns the name of the column holding the schema version string by calling getVersionColumnImpl() ...
private *hash getTablesImpl()
returns table definitions
logProgress(string str)
outputs a log message without any newline
hash c_timestamp(bool notnull=False, *string comment)
returns a column hash for a TIMESTAMP column
hash c_date(bool notnull=False, *string comment)
returns a column hash for a DATE column
*hash getIndexOptions()
returns index options
private bool checkUpgrade(string current_version)
this method is called if the current schema version is less than the target version; returns True if ...
*hash getProcedures()
returns stored procedure definitions
private *hash getStrictReferenceDataHashImpl()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
private *hash getGenericOptionsImpl()
returns schema creation options
abstract private string getVersionColumnImpl()
returns the name of the column holding the schema version string
hash getCallbacks(bool force=False)
returns a callback option hash usable with SqlUtil schema operations
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
private *hash getReferenceDataHashImpl()
returns a hash of "normal reference data", describing data that must appear in the target table...
AbstractDatasource ds
the datasource for the schema
Definition: Schema.qm.dox.h:305
private bool checkUpdateSchema(bool force, reference initial_schema_info)
this method returns True if the schema can be updated
string name
the name of the schema
Definition: Schema.qm.dox.h:288
*hash getSequences()
returns sequence definitions
private hash getVersionWhere()
returns the where clause hash defining the row where the schema version string is located by calling ...
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...
string getVersion()
returns the version of the schema
const True
*hash getTables()
returns table definitions
*hash column_options
column options, as provided by getColumnOptions()
Definition: Schema.qm.dox.h:300
private bool checkFirstTimeInstall()
returns True if checkExistence() returns False
hash c_varchar(int size, bool notnull=False, *string comment)
returns a column hash for a VARCHAR column
*hash getReferenceDataHash()
returns a hash of "normal reference data", describing data that must appear in the target table...
*hash getColumnOptions()
returns column options
hash callback_opts
callback options plus all options
Definition: Schema.qm.dox.h:315
abstract private hash getVersionWhereImpl()
returns the where clause hash defining the row where the schema version string is located ...
int align(bool force=False, int verbose=0)
executes a schema alignment action on the database with the current schema template ...
*hash getFunctions()
returns function definitions
const False
list list(...)
*hash index_options
index options, as provided by getIndexOptions()
Definition: Schema.qm.dox.h:296
sqlCallback(string str)
this is the SQL callback method for schema operations
string version_column
the name of the column containing the version string
Definition: Schema.qm.dox.h:637
private *hash getColumnOptionsImpl()
returns column options
drop(bool force=False, int verbose=0)
executes a schema drop operation in the database
*string data_ts
explicit data tablespace name
Definition: Schema.qm.dox.h:321
*hash getMaterializedViews()
returns materialized view definitions
constructor(AbstractDatasource n_ds, *string dts, *string its, *hash opts)
creates the object from the arguments
const C_NULL
Helper constant for column hash functions with "NULL" constraint for better readability.
Definition: Schema.qm.dox.h:83
constructor(AbstractSchema sc, int v=0)
creates the callback object from the given arguments
log(string fmt)
outputs a log message
*hash getCreateOnlyReferenceData()
returns a hash of "create-only reference data", describing data that is written to the table when the...
abstract private string getVersionTableImpl()
returns the name of the table holding the schema version string
private *hash getSequencesImpl()
returns sequence definitions
this class extends Schema::AbstractSchema by providing version logic based on a schema version string...
Definition: Schema.qm.dox.h:630
abstract private string getVersionImpl()
returns the version of the schema
private bool checkDropSchema(bool force)
this method returns True if the schema can be dropped
private postDataActions(bool first_time_install)
this method is called after schema reference data has been managed
string type(any arg)
*hash creation_options
creation options, as provided by getCreationOptions()
Definition: Schema.qm.dox.h:298
hash c_char(int size, bool notnull=False, *string comment)
returns a column hash for a CHAR column
private *hash getIndexOptionsImpl()
returns index options
hash schema
the schema template, as assembled from method callbacks providing schema element definitions ...
Definition: Schema.qm.dox.h:293
private *hash getInsertOnlyReferenceDataImpl()
returns a hash of "insert-only reference data", describing data that will only be inserted if missing...
this class provides callback support for schema operations
Definition: Schema.qm.dox.h:213
*hash getStrictReferenceDataHash()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
constructor(AbstractDatasource ds, *string dts, *string its, *hash opts)
creates the object based on the arguments giving the location of the schema
*hash getInsertOnlyReferenceData()
returns a hash of "create-only reference data", describing data that will only be inserted if missing...
*hash getCreationOptions()
returns schema creation options
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...
private bool checkExistence()
returns True if the method can detect that DB objects defined in the schema exist in the database ...
string version_table
the name of the table containing the version string
Definition: Schema.qm.dox.h:635
*hash getTypes()
returns type definitions
string getName()
returns the name of the schema
SqlUtil::Database db
the Database object for the schema
Definition: Schema.qm.dox.h:310
private *hash getProceduresImpl()
returns stored procedure definitions
code info_callback
the info callback for schema operations; can be used for explicit logging
Definition: Schema.qm.dox.h:318
private *hash getFunctionsImpl()
returns function definitions
string version
the version of the schema
Definition: Schema.qm.dox.h:290
private bool checkUpdateSchema(bool force, reference initial_schema_info)
this method returns True if the schema can be updated
const C_NOT_NULL
Helper constant for column hash functions with "NOT NULL" constraint for better readability.
Definition: Schema.qm.dox.h:85
*hash all_options
combined creation and column options
Definition: Schema.qm.dox.h:302
private *softstring getSchemaVersion()
returns the existing schema version or NOTHING if not present
abstract private string getNameImpl()
returns the version of the schema
string drv
the name of the database driver
Definition: Schema.qm.dox.h:307
private int getUpsertStrategy(bool first_time_install)
this method is called to return the upsert strategy before schema reference data management ...
hash version_where
a where clause hash defining the row where the schema version string is located
Definition: Schema.qm.dox.h:639
private bool checkDowngrade(string current_version)
this method is called if the current schema version is greater than the target version; returns True ...
AbstractDatasource getDatasource()
returns the datasource used for the schema
logpf(string fmt)
outputs a log message prefixed with the schema name
hash pure_callback_opts
just callback options
Definition: Schema.qm.dox.h:313
private *hash getMaterializedViewsImpl()
returns materialized view definitions
hash c_number(bool notnull=False, *string comment)
returns a column hash for a NUMBER or NUMERIC column
hash hash(object obj)
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...
private *hash getPackagesImpl()
returns (Oracle) package definitions
*hash getPackages()
returns (Oracle) package definitions
private string getVersionTable()
returns the name of the table holding the schema version string by calling getVersionTableImpl() ...
private *hash getCreateOnlyReferenceDataImpl()
returns a hash of "create-only reference data", describing data that is written to the table when the...
private *hash getTypesImpl()
returns type definitions
*string index_ts
explicit index tablespace name
Definition: Schema.qm.dox.h:324
nothing sqlForceCallback(string str)
this is the SQL callback method for forced schema operations
the AbstractSchema class is a base class to assist with automatic schema management ...
Definition: Schema.qm.dox.h:283
static hash combineOptions(*hash h)
combines option hashes into a single target option hash
hash c_int(bool notnull=False, *string comment)
returns a column hash for an INT column
private bool checkDropSchema(bool force)
this method returns True if the schema can be dropped