User Schema Management

Table of Contents

• Introduction to User Schema Management
• User Schema Module Files
  • User Schema Module Example

Back to the Developer's Guide Table of Contents

Introduction to User Schema Management

User schema module files allow Qorus developers to manage user schemas automatically by provided a user schema module file describing the schema.

oload and schema-tool both recognize the qsm extension and apply the configuration therein to the given schema.

When oload loads such a schema file, the schema will be automatically aligned in the target datasource as described by the user schema module. Furthermore schema-tool allows for manual schema creation and alignment as well as schema dropping of user schemas using the -V,–align-schema=ARG and –drop-schema=ARG options, respectively.

User Schema Module Files

Qorus user schema module files are Qore user modules that use the Schema module to provide the configuration and management of user schemas.

A Qorus user schema module must have the extension qsm and should be located in the modules subdirectory of the user subdirectory.

The user schema module must provide the following public (ie exported) functions:

• public string sub get_datasource_name(): this function must return the name of the datasource to be used for schema management
• AbstractSchema sub get_user_schema(AbstractDatasource ds, *string dts, *string its): this function must return the schema object to be managed; the arguments to the function correspond to the arguments to the AbstractSchema::constructor() method

The AbstractSchema object returned by get_user_schema() represents the schema that will be managed.

User Schema Module Example

The following is an example of a user schema module file:

# -*- mode: qore; indent-tabs-mode: nil -*-
# @file InventoryExampleSchema.qsm Qorus Integration System inventory example user schema description module
 
%requires qore >= 1.12
 
module InventoryExampleSchema {
    version = "1.0";
    desc = "Qorus inventory example user schema module";
    author = "Qore Technologies <info@qoretechnologies.com>";
    url = "https://www.qoretechnologies.com";
}
 
# here we add fallback paths to the QORE_MODULE_DIR search path,
# in case QORE_MODULE_DIR is not set properly for Qorus
%append-module-path /var/opt/qorus/qlib:$OMQ_DIR/qlib:/opt/qorus/qlib
 
%requires Schema
%requires SqlUtil
 
%new-style
%require-types
%strict-args
%enable-all-warnings
 
# private namespace for private schema declarations
namespace Private {
    const GenericOptions = (
        "replace": True,
    );
 
    const IndexOptions = (
        "driver": (
            "oracle": (
                "compute_statistics": True,
            ),
        ),
    );
 
    const ColumnOptions = (
        "driver": (
            "oracle": ("character_semantics": True,),
        ),
    );
 
    const T_InventoryExample = (
        "columns": (
            "id": c_int(True, "PK ID field"),
            "filename": c_varchar(200, True, "input filename"),
            "uuid": c_varchar(40, True, "system-supplied UUID for the file"),
            "store_code": c_varchar(200, True, "input store code"),
            "product_code": c_varchar(50, True, "input product code / EAN"),
            "product_desc": c_varchar(200, True, "input product description"),
            "ordered": c_int(True),
            "available": c_int(True),
            "in_transit": c_int(True),
            "total": c_int(True),
            "qorus_wfiid": c_int(True),
        ),
        "primary_key": ("name": "pk_inventory_example", "columns": ("id")),
        "indexes": (
            "sk_inventory_example_filename": ("columns": ("filename")),
            "sk_inventory_example_uuid": ("columns": ("uuid")),
            "sk_inventory_example_q_wfiid": ("columns": ("qorus_wfiid")),
        ),
    );
 
    const Tables = (
        "inventory_example": T_InventoryExample,
    );
 
    const Sequences = (
        "seq_inventory_example": {},
    );
}
 
public namespace InventoryExampleSchema {
    public string sub get_datasource_name() {
        return "omquser";
    }
 
    public InventoryExampleSchema sub get_user_schema(AbstractDatasource ds, *string dts, *string its) {
        return new InventoryExampleSchema(ds, dts, its);
    }
 
    public class InventoryExampleSchema inherits AbstractSchema {
        public {
            const SchemaName = "InventoryExampleSchema";
            const SchemaVersion = "1.0";
        }
 
        constructor(AbstractDatasource ds, *string dts, *string its) :  AbstractSchema(ds, dts, its) {
        }
 
        private string getNameImpl() {
            return SchemaName;
        }
 
        private string getVersionImpl() {
            return SchemaVersion;
        }
 
        private *hash getTablesImpl() {
            return Tables;
        }
 
        private *hash getSequencesImpl() {
            return Sequences;
        }
 
        private *hash getIndexOptionsImpl() {
            return IndexOptions;
        }
 
        private *hash getGenericOptionsImpl() {
            return GenericOptions;
        }
 
        private *hash getColumnOptionsImpl() {
            return ColumnOptions;
        }
    }
}