Qore Schema Module Reference  1.2
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 - 2017 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.13 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 
89 namespace Schema {
92  const C_NULL = False;
94  const C_NOT_NULL = True;
95 
97 
104  hash<GenericColumnInfo> c_int(bool notnull = False, *string comment);
105 
106 
108 
114  hash<GenericColumnInfo> c_int(string comment);
115 
116 
118 
122  hash<GenericColumnInfo> c_varchar(int size, bool notnull = False, *string comment);
123 
124 
126 
129  hash<GenericColumnInfo> c_varchar(int size, string comment);
130 
131 
133 
137  hash<GenericColumnInfo> c_char(int size, bool notnull = False, *string comment);
138 
139 
141 
144  hash<GenericColumnInfo> c_char(int size, string comment);
145 
146 
148 
153  hash<GenericColumnInfo> c_date(bool notnull = False, *string comment);
154 
155 
157 
161  hash<GenericColumnInfo> c_date(string comment);
162 
163 
165 
170  hash<GenericColumnInfo> c_timestamp(bool notnull = False, *string comment);
171 
172 
174 
178  hash<GenericColumnInfo> c_timestamp(string comment);
179 
180 
182 
188  hash<GenericColumnInfo> c_number(bool notnull = False, *string comment);
189 
190 
192 
199  hash<GenericColumnInfo> c_number(int size, int scale, bool notnull = False, *string comment);
200 
201 
203 
209  hash<GenericColumnInfo> c_number(int size, bool notnull = False, *string comment);
210 
211 
213 
218  hash<GenericColumnInfo> c_number(int size, string comment);
219 
220 
222 
227  hash<GenericColumnInfo> c_blob(bool notnull = False, *string comment);
228 
229 
231 
235  hash<GenericColumnInfo> c_blob(string comment);
236 
237 
239 
244  hash<GenericColumnInfo> c_clob(bool notnull = False, *string comment);
245 
246 
248 
252  hash<GenericColumnInfo> c_clob(string comment);
253 
254 
257 
258 public:
259  public :
260  AbstractSchema schema;
261  int verbose;
262  int change_count = 0;
263  int dot_count = 0;
264  int error_count = 0;
265  list sql_cache = ();
266 
267 public:
268 
270 
273  constructor(AbstractSchema sc, int v = 0);
274 
275 
277  infoCallback(string str, int ac, *string type, *string name, *string table, *string new_name, *string info);
278 
279 
281  sqlCallback(string str);
282 
283 
285  nothing sqlForceCallback(string str);
286 
287 
289  hash getCallbacks(bool force = False);
290 
291  };
292 
294 
327 
328 public:
329  private :
331  string name;
333  string version;
334 
337 
346 
350  string drv;
351 
354 
359 
362 
364  *string data_ts;
365 
367  *string index_ts;
368 
369 public:
370 
372 
377  constructor(Qore::SQL::AbstractDatasource n_ds, *string dts, *string its, *hash opts);
378 
379 
381  string getName();
382 
383 
385  string getVersion();
386 
387 
390 
391 
394 
395 
397 
399  logpf(string fmt);
400 
401 
403 
405  log(string fmt);
406 
407 
409 
411  logProgress(string str);
412 
413 
415 
422  int align(bool force = False, int verbose = 0);
423 
424 
426  drop(bool force = False, int verbose = 0);
427 
428 
430 
435 
436 
438 
443 
444 
446 
450 
451 
453 
456  *hash getTables();
457 
458 
460 
463  *hash getSequences();
464 
465 
467 
470  *hash getTypes();
471 
472 
474 
477  *hash getFunctions();
478 
479 
481 
484  *hash getProcedures();
485 
486 
488 
491  *hash getPackages();
492 
493 
495 
499 
500 
502 
506 
507 
509 
513 
514 
516 
520 
521 
523 
527 
528 
530 
531 private:
532  abstract string getNameImpl();
533 public:
534 
536 
537 private:
538  abstract string getVersionImpl();
539 public:
540 
542 
545 private:
547 public:
548 
549 
551 
554 private:
556 public:
557 
558 
560 
563 private:
565 public:
566 
567 
569 
572 private:
573  *hash getTablesImpl();
574 public:
575 
576 
578 
581 private:
583 public:
584 
585 
587 
590 private:
591  *hash getTypesImpl();
592 public:
593 
594 
596 
599 private:
601 public:
602 
603 
605 
608 private:
610 public:
611 
612 
614 
617 private:
619 public:
620 
621 
623 
626 private:
628 public:
629 
630 
632 
635 private:
637 public:
638 
639 
641 
644 private:
646 public:
647 
648 
650 
653 private:
655 public:
656 
657 
659 
662 private:
664 public:
665 
666 
668 
672 private:
673  bool checkExistence();
674 public:
675 
676 
678 
679 private:
680  bool checkFirstTimeInstall();
681 public:
682 
683 
685 
686 private:
687  bool checkDropSchema(bool force);
688 public:
689 
690 
692 
693 private:
694  bool checkUpdateSchema(bool force, reference<hash> initial_schema_info);
695 public:
696 
697 
699 
700 private:
701  doPostAlignment(Tables table_cache, bool first_time_install, *hash initial_schema_info);
702 public:
703 
704 
706 
707 private:
708  int getUpsertStrategy(bool first_time_install);
709 public:
710 
711 
713 
714 private:
715  postDataActions(bool first_time_install);
716 public:
717 
718 
720 
721 private:
722  doTable(AbstractTable table, list rows, int upsert_strategy, bool delete_others, int verbose, reference<hash> sh);
723 public:
724 
725 
727 
729  static list getRows(*softlist l);
730 
732  static hash combineOptions(*hash h);
733  };
734 
736 
746 
747 public:
748  private :
755 
756 public:
757 
759 
764  constructor(Qore::SQL::AbstractDatasource ds, *string dts, *string its, *hash opts) ;
765 
766 
768 
769 private:
770  *softstring getSchemaVersion();
771 public:
772 
773 
775 
776 private:
777  bool checkDropSchema(bool force);
778 public:
779 
780 
782 
783 private:
784  bool checkUpdateSchema(bool force, reference<hash> initial_schema_info);
785 public:
786 
787 
789 
790 private:
791  bool checkUpgrade(string current_version);
792 public:
793 
794 
796 
797 private:
798  bool checkDowngrade(string current_version);
799 public:
800 
801 
803 
807 private:
808  string getVersionTable();
809 public:
810 
811 
813 
817 private:
818  string getVersionColumn();
819 public:
820 
821 
823 
827 private:
829 public:
830 
831 
833 
834 private:
835  abstract string getVersionTableImpl();
836 public:
837 
839 
840 private:
841  abstract string getVersionColumnImpl();
842 public:
843 
845 
846 private:
847  abstract hash getVersionWhereImpl();
848 public:
849  };
850 };
logProgress(string str)
outputs a log message without any newline
*hash getIndexOptions()
returns index options
*hash getProcedures()
returns stored procedure definitions
Qore::SQL::AbstractDatasource ds
the datasource for the schema
Definition: Schema.qm.dox.h:348
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
*hash getProceduresImpl()
returns stored procedure definitions
hash< GenericColumnInfo > c_varchar(int size, bool notnull=False, *string comment)
returns a column hash for a VARCHAR column
*hash getInsertOnlyReferenceDataImpl()
returns a hash of "insert-only reference data", describing data that will only be inserted if missing...
*hash getTablesImpl()
returns table definitions
string getVersionColumn()
returns the name of the column holding the schema version string by calling getVersionColumnImpl() ...
string name
the name of the schema
Definition: Schema.qm.dox.h:331
*hash getFunctionsImpl()
returns function definitions
*hash getSequences()
returns sequence definitions
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...
hash< GenericColumnInfo > c_clob(bool notnull=False, *string comment)
returns a column hash for a CLOB column
*hash getMaterializedViewsImpl()
returns materialized view definitions
string getVersion()
returns the version of the schema
const True
hash< GenericColumnInfo > c_char(int size, bool notnull=False, *string comment)
returns a column hash for a CHAR column
*hash getTables()
returns table definitions
*hash column_options
column options, as provided by getColumnOptions()
Definition: Schema.qm.dox.h:343
constructor(Qore::SQL::AbstractDatasource n_ds, *string dts, *string its, *hash opts)
creates the object from the arguments
*hash getSequencesImpl()
returns sequence definitions
*hash getReferenceDataHash()
returns a hash of "normal reference data", describing data that must appear in the target table...
*hash getIndexOptionsImpl()
returns index options
*hash getColumnOptions()
returns column options
bool checkDowngrade(string current_version)
this method is called if the current schema version is greater than the target version; returns True ...
hash getVersionWhere()
returns the where clause hash defining the row where the schema version string is located by calling ...
hash callback_opts
callback options plus all options
Definition: Schema.qm.dox.h:358
hash< GenericColumnInfo > c_int(bool notnull=False, *string comment)
returns a column hash for an INT column
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
hash< GenericColumnInfo > c_blob(bool notnull=False, *string comment)
returns a column hash for a BLOB column
string getVersionTable()
returns the name of the table holding the schema version string by calling getVersionTableImpl() ...
list list(...)
*hash index_options
index options, as provided by getIndexOptions()
Definition: Schema.qm.dox.h:339
*softstring getSchemaVersion()
returns the existing schema version or NOTHING if not present
*hash getReferenceDataHashImpl()
returns a hash of "normal reference data", describing data that must appear in the target table...
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:752
bool checkUpgrade(string current_version)
this method is called if the current schema version is less than the target version; returns True if ...
*hash getGenericOptionsImpl()
returns schema creation options
*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:364
*hash getMaterializedViews()
returns materialized view definitions
hash< GenericColumnInfo > c_timestamp(bool notnull=False, *string comment)
returns a column hash for a TIMESTAMP column
int getUpsertStrategy(bool first_time_install)
this method is called to return the upsert strategy before schema reference data management ...
hash< GenericColumnInfo > c_number(bool notnull=False, *string comment)
returns a column hash for a NUMBER or NUMERIC column
const C_NULL
Helper constant for column hash functions with "NULL" constraint for better readability.
Definition: Schema.qm.dox.h:92
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 da...
SqlUtil::AbstractDatabase getDatabase()
returns the AbstractDatabase object used for the schema
constructor(AbstractSchema sc, int v=0)
creates the callback object from the given arguments
this namespace contains all public definitions in the Schema module
Definition: Schema.qm.dox.h:90
log(string fmt)
outputs a log message
bool checkDropSchema(bool force)
this method returns True if the schema can be dropped
*hash getCreateOnlyReferenceData()
returns a hash of "create-only reference data", describing data that is written to the table when the...
postDataActions(bool first_time_install)
this method is called after schema reference data has been managed
bool checkDropSchema(bool force)
this method returns True if the schema can be dropped
this class extends Schema::AbstractSchema by providing version logic based on a schema version string...
Definition: Schema.qm.dox.h:745
bool checkExistence()
returns True if the method can detect that DB objects defined in the schema exist in the database ...
constructor(Qore::SQL::AbstractDatasource ds, *string dts, *string its, *hash opts)
creates the object based on the arguments giving the location of the schema
*hash creation_options
creation options, as provided by getCreationOptions()
Definition: Schema.qm.dox.h:341
hash schema
the schema template, as assembled from method callbacks providing schema element definitions ...
Definition: Schema.qm.dox.h:336
this class provides callback support for schema operations
Definition: Schema.qm.dox.h:256
*hash getStrictReferenceDataHash()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
abstract hash getVersionWhereImpl()
returns the where clause hash defining the row where the schema version string is located ...
*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
string type(auto arg)
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...
string version_table
the name of the table containing the version string
Definition: Schema.qm.dox.h:750
*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:353
bool checkUpdateSchema(bool force, reference< hash > initial_schema_info)
this method returns True if the schema can be updated
code info_callback
the info callback for schema operations; can be used for explicit logging
Definition: Schema.qm.dox.h:361
string version
the version of the schema
Definition: Schema.qm.dox.h:333
const C_NOT_NULL
Helper constant for column hash functions with "NOT NULL" constraint for better readability.
Definition: Schema.qm.dox.h:94
*hash all_options
combined creation and column options
Definition: Schema.qm.dox.h:345
abstract string getVersionImpl()
returns the version of the schema
string drv
the name of the database driver
Definition: Schema.qm.dox.h:350
*hash getCreateOnlyReferenceDataImpl()
returns a hash of "create-only reference data", describing data that is written to the table when the...
hash version_where
a where clause hash defining the row where the schema version string is located
Definition: Schema.qm.dox.h:754
hash< GenericColumnInfo > c_date(bool notnull=False, *string comment)
returns a column hash for a DATE column
logpf(string fmt)
outputs a log message prefixed with the schema name
*hash getTypesImpl()
returns type definitions
hash pure_callback_opts
just callback options
Definition: Schema.qm.dox.h:356
Qore::SQL::AbstractDatasource getDatasource()
returns the datasource used for the schema
abstract string getVersionTableImpl()
returns the name of the table holding the schema version string
bool checkFirstTimeInstall()
returns True if checkExistence() returns False
hash hash(object obj)
abstract string getNameImpl()
returns the name of the schema
*hash getPackagesImpl()
returns (Oracle) package definitions
*hash getPackages()
returns (Oracle) package definitions
bool checkUpdateSchema(bool force, reference< hash > initial_schema_info)
this method returns True if the schema can be updated
*string index_ts
explicit index tablespace name
Definition: Schema.qm.dox.h:367
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:326
*hash getStrictReferenceDataHashImpl()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
static hash combineOptions(*hash h)
combines option hashes into a single target option hash
abstract string getVersionColumnImpl()
returns the name of the column holding the schema version string