Qore Schema Module Reference  1.0
 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 Qore Technologies, sro
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.10 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 
57 namespace Schema {
61 
62 public:
63  public :
64  AbstractSchema schema;
65  int verbose;
66  int change_count = 0;
67  int dot_count = 0;
68  int error_count = 0;
69  list sql_cache = ();
70 
71 public:
72 
74 
77  constructor(AbstractSchema sc, int v = 0);
78 
79 
81  infoCallback(string str, int ac, *string type, *string name, *string table, *string new_name, *string info);
82 
83 
85  sqlCallback(string str);
86 
87 
89  nothing sqlForceCallback(string str);
90 
91 
93  hash getCallbacks(bool force = False);
94 
95  };
96 
98 
131 
132 public:
133  private :
135  string name;
137  string version;
138 
141 
150 
152  AbstractDatasource ds;
154  string drv;
155 
158 
163 
166 
168  *string data_ts;
169 
171  *string index_ts;
172 
173 public:
174 
176 
180  constructor(AbstractDatasource n_ds, *string dts, *string its);
181 
182 
184  string getName();
185 
186 
188  string getVersion();
189 
190 
192  AbstractDatasource getDatasource();
193 
194 
196  AbstractDatabase getDatabase();
197 
198 
200 
202  logpf(string fmt);
203 
204 
206 
208  log(string fmt);
209 
210 
212 
214  logProgress(string str);
215 
216 
218 
225  int align(bool force = False, int verbose = 0);
226 
227 
229  drop(bool force = False, int verbose = 0);
230 
231 
233 
238 
239 
241 
246 
247 
249 
253 
254 
256 
259  *hash getTables();
260 
261 
263 
266  *hash getSequences();
267 
268 
270 
273  *hash getTypes();
274 
275 
277 
280  *hash getFunctions();
281 
282 
284 
287  *hash getProcedures();
288 
289 
291 
294  *hash getPackages();
295 
296 
298 
302 
303 
305 
309 
310 
312 
316 
317 
319 
323 
324 
326 
330 
331 
333  private abstract string getNameImpl();
334 
336  private abstract string getVersionImpl();
337 
339 
341  private *hash getIndexOptionsImpl();
342 
343 
345 
347  private *hash getColumnOptionsImpl();
348 
349 
351 
353  private *hash getGenericOptionsImpl();
354 
355 
357 
359  private *hash getTablesImpl();
360 
361 
363 
365  private *hash getSequencesImpl();
366 
367 
369 
371  private *hash getTypesImpl();
372 
373 
375 
377  private *hash getFunctionsImpl();
378 
379 
381 
383  private *hash getProceduresImpl();
384 
385 
387 
389  private *hash getPackagesImpl();
390 
391 
393 
395  private *hash getMaterializedViewsImpl();
396 
397 
399 
402 
403 
405 
407  private *hash getReferenceDataHashImpl();
408 
409 
411 
414 
415 
417 
420 
421 
423 
426  private bool checkExistence();
427 
428 
430  private bool checkFirstTimeInstall();
431 
432 
434  private bool checkDropSchema(bool force);
435 
436 
438  private bool checkUpdateSchema(bool force, reference initial_schema_info);
439 
440 
442  private doPostAlignment(Tables table_cache, bool first_time_install, *hash initial_schema_info);
443 
444 
446  private int getUpsertStrategy(bool first_time_install);
447 
448 
450  private postDataActions(bool first_time_install);
451 
452 
454  private doTable(AbstractTable table, list rows, int upsert_strategy, bool delete_others, int verbose, reference sh);
455 
456 
458 
460  static list getRows(*softlist l);
461 
463  static hash combineOptions(*hash h);
464  };
465 
467 
477 
478 public:
479  private :
486 
487 public:
488 
490 
492  constructor(AbstractDatasource ds, *string dts, *string its);
493 
494 
496  private *softstring getSchemaVersion();
497 
498 
500  private bool checkDropSchema(bool force);
501 
502 
504  private bool checkUpdateSchema(bool force, reference initial_schema_info);
505 
506 
508  private bool checkUpgrade(string current_version);
509 
510 
512  private bool checkDowngrade(string current_version);
513 
514 
516 
519  private string getVersionTable();
520 
521 
523 
526  private string getVersionColumn();
527 
528 
530 
533  private hash getVersionWhere();
534 
535 
537  private abstract string getVersionTableImpl();
538 
540  private abstract string getVersionColumnImpl();
541 
543  private abstract hash getVersionWhereImpl();
544  };
545 };
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 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:152
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:135
*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
*hash getTables()
returns table definitions
*hash column_options
column options, as provided by getColumnOptions()
Definition: Schema.qm.dox.h:147
private bool checkFirstTimeInstall()
returns True if checkExistence() returns False
*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:162
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:143
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:483
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:168
*hash getMaterializedViews()
returns materialized view definitions
constructor(AbstractDatasource n_ds, *string dts, *string its)
creates the object from the arguments
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:476
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:145
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:140
private *hash getInsertOnlyReferenceDataImpl()
returns a hash of "create-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:60
*hash getStrictReferenceDataHash()
returns a hash of "strict reference data", describing the only data that can appear in the target tab...
*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:481
*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:157
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:165
private *hash getFunctionsImpl()
returns function definitions
string version
the version of the schema
Definition: Schema.qm.dox.h:137
private bool checkUpdateSchema(bool force, reference initial_schema_info)
this method returns True if the schema can be updated
*hash all_options
combined creation and column options
Definition: Schema.qm.dox.h:149
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:154
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:485
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:160
private *hash getMaterializedViewsImpl()
returns materialized view definitions
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:171
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:130
static hash combineOptions(*hash h)
combines option hashes into a single target option hash
constructor(AbstractDatasource ds, *string dts, *string its)
creates the object based on the arguments giving the location of the schema
private bool checkDropSchema(bool force)
this method returns True if the schema can be dropped