Qore Schema Module Reference 1.4.2
Loading...
Searching...
No Matches
Schema.qm.dox.h
1// -*- mode: c++; indent-tabs-mode: nil -*-
3
4/* Schema.qm Copyright 2014 - 2023 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// minimum Qore version
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
117namespace Schema {
119 const C_NULL = False;
121 const C_NOT_NULL = True;
122
124
132 hash<GenericColumnInfo> c_int(bool notnull = False, *string comment);
133
134
136
142 hash<GenericColumnInfo> c_int(string comment);
143
144
146
151 hash<GenericColumnInfo> c_varchar(int size, bool notnull = False, *string comment);
152
153
155
158 hash<GenericColumnInfo> c_varchar(int size, string comment);
159
160
162
167 hash<GenericColumnInfo> c_char(int size, bool notnull = False, *string comment);
168
169
171
174 hash<GenericColumnInfo> c_char(int size, string comment);
175
176
178
184 hash<GenericColumnInfo> c_date(bool notnull = False, *string comment);
185
186
188
192 hash<GenericColumnInfo> c_date(string comment);
193
194
196
202 hash<GenericColumnInfo> c_timestamp(bool notnull = False, *string comment);
203
204
206
210 hash<GenericColumnInfo> c_timestamp(string comment);
211
212
214
221 hash<GenericColumnInfo> c_number(bool notnull = False, *string comment);
222
223
225
233 hash<GenericColumnInfo> c_number(int size, int scale, bool notnull = False, *string comment);
234
235
237
244 hash<GenericColumnInfo> c_number(int size, bool notnull = False, *string comment);
245
246
248
253 hash<GenericColumnInfo> c_number(int size, string comment);
254
255
257
263 hash<GenericColumnInfo> c_blob(bool notnull = False, *string comment);
264
265
267
271 hash<GenericColumnInfo> c_blob(string comment);
272
273
275
281 hash<GenericColumnInfo> c_clob(bool notnull = False, *string comment);
282
283
285
289 hash<GenericColumnInfo> c_clob(string comment);
290
291
293 public hashdecl SchemaAlignmentInfo {
295
298
301
303 *hash<string, int> change_map;
304
306 *hash<string, int> data_change_map;
307 };
308
311
312public:
313 AbstractSchema schema;
314 int verbose;
315 int change_count = 0;
316 int dot_count = 0;
317 int error_count = 0;
318
319 list<string> sql_cache = ();
320
322 hash<string, int> change_map;
323
325 hash<string, int> data_change_map;
326
328
331
334 AbstractDatabase::AC_Create: True,
335 AbstractDatabase::AC_Add: True,
336 AbstractDatabase::AC_Insert: True,
337 };
338
340
344
345
347 hash<SchemaAlignmentInfo> getInfo();
348
349
351 infoCallback(string str, int ac, *string type, *string name, *string table, *string new_name, *string info);
352
353
355 sqlCallback(string str);
356
357
359 nothing sqlForceCallback(string str);
360
361
363 hash<auto> getCallbacks(bool force = False);
364
365 };
366
368 public hashdecl SchemaOptionInfo {
370 *string data_ts;
371
373 *string index_ts;
374
376 *hash<auto> db_opts;
377 };
378
380
413
414public:
415protected:
417 string name;
419 string version;
420
422 hash schema;
423
432
436 string drv;
437
440
445
448
450 *string data_ts;
451
453 *string index_ts;
454
455public:
456
458
463 constructor(Qore::SQL::AbstractDatasource ds, *string dts, *string its, *hash opts);
464
465
467
472 constructor(Qore::SQL::AbstractDatasource ds, *hash<SchemaOptionInfo> opts);
473
474
476 string getName();
477
478
480 string getVersion();
481
482
485
486
489
490
492
494 logpf(string fmt);
495
496
498
500 log(string fmt);
501
502
504
506 logProgress(string str);
507
508
510
522 int align(bool force = False, int verbose = 0, bool do_msgs = True);
523
524
526
538 hash<SchemaAlignmentInfo> alignWithInfo(bool force = False, int verbose = 0, bool do_msgs = True);
539
540
542
554protected:
555 SchemaCallbackHelper alignIntern(bool force = False, int verbose = 0, bool do_msgs = True);
556public:
557
558
560 drop(bool force = False, int verbose = 0, bool do_msgs = True);
561
562
564
568 *hash<auto> getIndexOptions();
569
570
572
576 *hash<auto> getCreationOptions();
577
578
580
583 *hash<auto> getColumnOptions();
584
585
587
590 *hash<auto> getTables();
591
592
594
597 *hash<auto> getSequences();
598
599
601
604 *hash<auto> getTypes();
605
606
608
611 *hash<auto> getFunctions();
612
613
615
618 *hash<auto> getProcedures();
619
620
622
625 *hash<auto> getPackages();
626
627
629
632 *hash<auto> getMaterializedViews();
633
634
636
640
641
643
646 *hash<auto> getReferenceDataHash();
647
648
650
654
655
657
661
662
664protected:
665 init(Qore::SQL::AbstractDatasource ds, *hash<SchemaOptionInfo> opts);
666public:
667
668
670protected:
671 abstract string getNameImpl();
672public:
673
675protected:
676 abstract string getVersionImpl();
677public:
678
680
682protected:
683 *hash<auto> getIndexOptionsImpl();
684public:
685
686
688
690protected:
691 *hash<auto> getColumnOptionsImpl();
692public:
693
694
696
698protected:
700public:
701
702
704
706protected:
707 *hash<auto> getTablesImpl();
708public:
709
710
712
714protected:
715 *hash<auto> getSequencesImpl();
716public:
717
718
720
722protected:
723 *hash<auto> getTypesImpl();
724public:
725
726
728
730protected:
731 *hash<auto> getFunctionsImpl();
732public:
733
734
736
738protected:
739 *hash<auto> getProceduresImpl();
740public:
741
742
744
746protected:
747 *hash<auto> getPackagesImpl();
748public:
749
750
752
754protected:
756public:
757
758
760
762protected:
764public:
765
766
768
770protected:
772public:
773
774
776
778protected:
780public:
781
782
784
786protected:
788public:
789
790
792
795protected:
797public:
798
799
801protected:
803public:
804
805
807protected:
808 bool checkDropSchema(bool force);
809public:
810
811
813protected:
814 bool checkUpdateSchema(bool force, reference<hash<auto>> initial_schema_info);
815public:
816
817
819protected:
820 doPostAlignment(Tables table_cache, bool first_time_install, *hash<auto> initial_schema_info, int verbose);
821public:
822
823
825protected:
826 doPostAlignment(Tables table_cache, bool first_time_install, *hash<auto> initial_schema_info);
827public:
828
829
831protected:
832 int getUpsertStrategy(bool first_time_install);
833public:
834
835
837protected:
838 postDataActions(Tables table_cache, bool first_time_install, *hash<auto> initial_schema_info, int verbose);
839public:
840
841
843protected:
844 postDataActions(bool first_time_install);
845public:
846
847
849 private doTable(AbstractTable table, list rows, int upsert_strategy, bool delete_others, int verbose,
850 reference<hash<string, int>> sh) {
851 // if we are reporting the status, then change to "UpsertSelectFirst" so that we can only report updated rows
852 if (verbose > 0);
853
854
855 bool dot = False;
856
857 hash<string, int> tsh;
858 code cb = (string table_name, hash row, int result);
859;
860
861 table.upsertFromIterator(AbstractSchema::getRows(rows).iterator(), upsert_strategy, ("delete_others": delete_others, "info_callback": cb));
862
863 // show table summary if verbose = 1
864 if (verbose > 0);
865
866 }
867
869
871 static list getRows(*softlist<auto> l);
872
874 static hash combineOptions(*hash h);
875 };
876
878
888
889public:
890protected:
897
898public:
899
901
906 constructor(Qore::SQL::AbstractDatasource ds, *string dts, *string its, *hash opts) ;
907
908
910protected:
911 *softstring getSchemaVersion();
912public:
913
914
916protected:
917 bool checkDropSchema(bool force);
918public:
919
920
922protected:
923 bool checkUpdateSchema(bool force, reference<hash<auto>> initial_schema_info);
924public:
925
926
928protected:
929 bool checkUpgrade(string current_version);
930public:
931
932
934protected:
935 bool checkDowngrade(string current_version);
936public:
937
938
940
943protected:
945public:
946
947
949
952protected:
954public:
955
956
958
961protected:
963public:
964
965
967protected:
968 abstract string getVersionTableImpl();
969public:
970
972protected:
973 abstract string getVersionColumnImpl();
974public:
975
977protected:
978 abstract hash getVersionWhereImpl();
979public:
980 };
981};
the AbstractSchema class is a base class to assist with automatic schema management
Definition: Schema.qm.dox.h:412
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...
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...
hash schema
the schema template, as assembled from method callbacks providing schema element definitions
Definition: Schema.qm.dox.h:422
string getVersion()
returns the version of the schema
constructor(Qore::SQL::AbstractDatasource ds, *hash< SchemaOptionInfo > opts)
creates the object from the arguments
*hash< auto > getTablesImpl()
returns table definitions
hash callback_opts
callback options plus all options
Definition: Schema.qm.dox.h:444
string drv
the name of the database driver
Definition: Schema.qm.dox.h:436
abstract string getNameImpl()
returns the name of the schema
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...
*hash< auto > getPackages()
returns (Oracle) package definitions
SqlUtil::Database db
the Database object for the schema
Definition: Schema.qm.dox.h:439
static hash combineOptions(*hash h)
combines option hashes into a single target option hash
*hash< auto > getMaterializedViewsImpl()
returns materialized view definitions
*hash< auto > getReferenceDataHashImpl()
returns a hash of "normal reference data", describing data that must appear in the target table,...
Qore::SQL::AbstractDatasource ds
the datasource for the schema
Definition: Schema.qm.dox.h:434
*string data_ts
explicit data tablespace name
Definition: Schema.qm.dox.h:450
*hash< auto > getTypesImpl()
returns type definitions
*hash< auto > getMaterializedViews()
returns materialized view definitions
constructor(Qore::SQL::AbstractDatasource ds, *string dts, *string its, *hash opts)
creates the object from the arguments
logpf(string fmt)
outputs a log message prefixed with the schema name
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
*hash creation_options
creation options, as provided by getCreationOptions()
Definition: Schema.qm.dox.h:427
*hash< auto > getReferenceDataHash()
returns a hash of "normal reference data", describing data that must appear in the target table,...
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< auto > getFunctionsImpl()
returns function definitions
bool checkDropSchema(bool force)
this method returns True if the schema can be dropped
*hash< auto > getTables()
returns table definitions
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
*hash< auto > getTypes()
returns type definitions
*hash< auto > getGenericOptionsImpl()
returns schema creation options
*hash< auto > getProcedures()
returns stored procedure definitions
private 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 da...
Definition: Schema.qm.dox.h:849
hash pure_callback_opts
just callback options
Definition: Schema.qm.dox.h:442
init(Qore::SQL::AbstractDatasource ds, *hash< SchemaOptionInfo > opts)
shared constructor initialization
*hash column_options
column options, as provided by getColumnOptions()
Definition: Schema.qm.dox.h:429
code info_callback
the info callback for schema operations; can be used for explicit logging
Definition: Schema.qm.dox.h:447
*hash< auto > getCreateOnlyReferenceData()
returns a hash of "create-only reference data", describing data that is written to the table when the...
*string index_ts
explicit index tablespace name
Definition: Schema.qm.dox.h:453
*hash< auto > getCreationOptions()
returns schema creation options
string version
the version of the schema
Definition: Schema.qm.dox.h:419
postDataActions(bool first_time_install)
this method is called after schema reference data has been managed
*hash< auto > getColumnOptionsImpl()
returns column options
Qore::SQL::AbstractDatasource getDatasource()
returns the datasource used for the schema
int getUpsertStrategy(bool first_time_install)
this method is called to return the upsert strategy before schema reference data management
*hash index_options
index options, as provided by getIndexOptions()
Definition: Schema.qm.dox.h:425
*hash< auto > getIndexOptions()
returns index options
bool checkFirstTimeInstall()
returns True if checkExistence() returns False
*hash< auto > getColumnOptions()
returns column options
*hash< auto > getProceduresImpl()
returns stored procedure definitions
*hash< auto > getIndexOptionsImpl()
returns index options
*hash< auto > getPackagesImpl()
returns (Oracle) package definitions
abstract string getVersionImpl()
returns the version of the schema
SqlUtil::AbstractDatabase getDatabase()
returns the AbstractDatabase object used for the schema
*hash< auto > getFunctions()
returns function definitions
bool checkExistence()
returns True if the method can detect that DB objects defined in the schema exist in the database
*hash< auto > getInsertOnlyReferenceDataImpl()
returns a hash of "insert-only reference data", describing data that will only be inserted if missing...
string getName()
returns the name of the schema
*hash< auto > getCreateOnlyReferenceDataImpl()
returns a hash of "create-only reference data", describing data that is written to the table when the...
*hash all_options
combined creation and column options
Definition: Schema.qm.dox.h:431
*hash< auto > getInsertOnlyReferenceData()
returns a hash of "create-only reference data", describing data that will only be inserted if missing...
*hash< auto > getSequences()
returns sequence definitions
string name
the name of the schema
Definition: Schema.qm.dox.h:417
*hash< auto > getSequencesImpl()
returns sequence definitions
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
drop(bool force=False, int verbose=0, bool do_msgs=True)
executes a schema drop operation in the database
*hash< auto > getStrictReferenceDataHashImpl()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
*hash< auto > getStrictReferenceDataHash()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
logProgress(string str)
outputs a log message without any newline
bool checkUpdateSchema(bool force, reference< hash< auto > > initial_schema_info)
this method returns True if the schema can be updated
log(string fmt)
outputs a log message
this class extends Schema::AbstractSchema by providing version logic based on a schema version string...
Definition: Schema.qm.dox.h:887
bool checkDowngrade(string current_version)
this method is called if the current schema version is greater than the target version; returns True ...
string version_column
the name of the column containing the version string
Definition: Schema.qm.dox.h:894
string getVersionTable()
returns the name of the table holding the schema version string by calling getVersionTableImpl()
abstract hash getVersionWhereImpl()
returns the where clause hash defining the row where the schema version string is located
bool checkUpdateSchema(bool force, reference< hash< auto > > initial_schema_info)
this method returns True if the schema can be updated
abstract string getVersionColumnImpl()
returns the name of the column holding the schema version string
string getVersionColumn()
returns the name of the column holding the schema version string by calling getVersionColumnImpl()
*softstring getSchemaVersion()
returns the existing schema version or NOTHING if not present
hash getVersionWhere()
returns the where clause hash defining the row where the schema version string is located by calling ...
bool checkUpgrade(string current_version)
this method is called if the current schema version is less than the target version; returns True if ...
hash version_where
a where clause hash defining the row where the schema version string is located
Definition: Schema.qm.dox.h:896
abstract string getVersionTableImpl()
returns the name of the table holding the schema version string
constructor(Qore::SQL::AbstractDatasource ds, *string dts, *string its, *hash opts)
creates the object based on the arguments giving the location of the schema
bool checkDropSchema(bool force)
this method returns True if the schema can be dropped
string version_table
the name of the table containing the version string
Definition: Schema.qm.dox.h:892
this class provides callback support for schema operations
Definition: Schema.qm.dox.h:310
const CreateActionMap
Map of create actions.
Definition: Schema.qm.dox.h:333
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
bool created
Set to True if only creations / additions were made.
Definition: Schema.qm.dox.h:330
constructor(AbstractSchema sc, int v=0)
creates the callback object from the given arguments
nothing sqlForceCallback(string str)
this is the SQL callback method for forced schema operations
sqlCallback(string str)
this is the SQL callback method for schema operations
hash< string, int > change_map
Change map; action code -> count.
Definition: Schema.qm.dox.h:322
hash< SchemaAlignmentInfo > getInfo()
Returns information about schema changes made.
hash< auto > getCallbacks(bool force=False)
returns a callback option hash usable with SqlUtil schema operations
hash< string, int > data_change_map
Summary map for data changes; upsert action code -> count.
Definition: Schema.qm.dox.h:325
this namespace contains all public definitions in the Schema module
Definition: Schema.qm.dox.h:117
hash< GenericColumnInfo > c_blob(bool notnull=False, *string comment)
returns a column hash for a BLOB column
hash< GenericColumnInfo > c_date(bool notnull=False, *string comment)
returns a column hash for a DATE column
hash< GenericColumnInfo > c_clob(bool notnull=False, *string comment)
returns a column hash for a CLOB column
hash< GenericColumnInfo > c_number(bool notnull=False, *string comment)
returns a column hash for a NUMBER or NUMERIC column
hash< GenericColumnInfo > c_timestamp(bool notnull=False, *string comment)
returns a column hash for a TIMESTAMP column
hash< GenericColumnInfo > c_varchar(int size, bool notnull=False, *string comment)
returns a column hash for a VARCHAR column
hash< GenericColumnInfo > c_char(int size, bool notnull=False, *string comment)
returns a column hash for a CHAR column
hash< GenericColumnInfo > c_int(bool notnull=False, *string comment)
returns a column hash for an INT column
const C_NULL
Helper constant for column hash functions with "NULL" constraint for better readability.
Definition: Schema.qm.dox.h:119
const C_NOT_NULL
Helper constant for column hash functions with "NOT NULL" constraint for better readability.
Definition: Schema.qm.dox.h:121
Provides information on schema changes.
Definition: Schema.qm.dox.h:293
bool created
Set to True if only creations / additions were made.
Definition: Schema.qm.dox.h:297
*hash< string, int > change_map
Change map; action code -> count.
Definition: Schema.qm.dox.h:303
int num_changes
The total number of changes made.
Definition: Schema.qm.dox.h:300
*hash< string, int > data_change_map
Summary map for data changes; upsert action code -> count.
Definition: Schema.qm.dox.h:306
Schema option hash definitions.
Definition: Schema.qm.dox.h:368
*string data_ts
explicit data tablespace name
Definition: Schema.qm.dox.h:370
*hash< auto > db_opts
options for SqlUtil::Database::constructor()
Definition: Schema.qm.dox.h:376
*string index_ts
explicit index tablespace name
Definition: Schema.qm.dox.h:373