Rdb Data Deployment Library

This library provides a simple framework that automates the promotion of data from one environment to another. This automation exports data from a source database schema, packages it, deploys and imports it to target database schemas using one standardized end-to-end process.

What is it?

This is a library of command modules that build on the ControlTier automation base types and establish an end-to-end data build and deployment process. This process is defined in terms of command workflows. The figure below describes three primary workflows:

1. Coordinated Export and Deploy: This workflow defines the end-to-end process and a single command to execute it called "BuildAndDeploy".
2. Data Export: This workflow is responsible for exporting data from the master database, packaging and staging it into the repository.
3. Data Deploy: The import workflow manages the distribution and installation of the data packages, importing the export file and calling any pre- or -post-import SQL scripts.

Why use it?

This library builds on the ControlTier service provisioning platform to offer a number of notable features for organizations where data migration and promotion is an important part of the application lifecycle and is a frequent and critical process:

• End-to-end automation: This framework ties together many individual procedures that are often run independently. Building on the ControlTier base types, this Library offers a single command that: exports data, packages and versions it, manages package dependencies and deploys to multiple hosts, imports the file calling necessary SQL scripts.
• Rollback: All data distributions are packaged and versioned. You can rollback to any previous version.
• Task delegation and self-service: You end up with schedulable "jobs" letting a less knowledable person run the export-import process on demand or at defined periods.
• Standardized operational interface: End users can rely on simple and predictable commands no matter what environment, database platform, schema or application.
• Reporting: Every deployment is logged. Reports show who deployed what where and when. The full output of the job is saved can can be used for auditing later.
• Graphical interfaces: All operational tasks can be done via a graphical interface. ControlTier's JobCenter is used to run commands while Workbench can be used to review the current deployment environment dependencies.
• Security: Using the ControlTier access control infrastructure, you can control who updates what when and where.
• Extendability: The library offers a workinng end to end process but it is not monolithic. You can override various parts of the process via sub-typing.

Getting started

You can start using the this library by following the steps of the documentation pages listed below:

1. Install: Describes how to download and install the library
2. Configure: Describes how to configure the library to define new "BuildAndDeploy" job
3. Run: Explains how to run the job either via the graphical JobCenter application or by command line.

Next: Install →

Install

Overview

This document describes the installation steps necessary to use the library.

Step #1: Install the ControlTier platform software

This library assumes you have installed the latest stable release of the ControlTier platform software on a a designated server host and one or more client hosts. Refer to the general ControlTier installation procedures for more info.

You will need to know the URL to the Workbench and JobCenter applications.

Step #2: Download the library archive

Binary distributions of the library can be found in the "File Releases" section of the ModuleForge Download page on Sourceforge. The package is called "Rdb Data Deployment Library" and will be named something like: rdb-seed-x.y.jar where "x.y" denote the version.

It is always suggested to download the latest release.

Step #3: Choose or create a project

All work is done within the context of a "project". You may already have a project in mind, or you may wish to create a new one just for the use of this library.

1. Navigate to the Admin page. (eg., go to the URL: http://localhost:8080/itnav/do/menu/Admin
2. Press the "Create Project" button. (eg., go to the URL: http://localhost:8080/itnav/do/projects/Input
3. Fill out the form and press "Create" button. It takes a few minutes for the new project to be created.

Step #4: Load the library archive

Once you have chosen the desired project, you can load the library into that project.

Be sure you have already logged into Workbench and selected the desired project where you want the library loaded. If you just created a new project, you are all ready.

1. Navigate to the Admin page. (eg., go to the URL: http://localhost:8080/itnav/do/menu/Admin
2. Press the "Import Seed" button. (eg., go to the URL: http://localhost:8080/itnav/do/projects/ImportSeedInput
3. Locate and select the rdb-seed-x.y.jar file in the file chooser. This is the same file you downloaded in step #2.
4. Press the "Import" button. It takes a few minutes for Workbench to load the library.

Once the library has been installed into your chosen project the next step is to configure these modules for use.

Next: Configure →

Configure

Overview

This document describes how to configure a project to use this library.

The diagram below illustrates the configuration is driven by a defaults.xml file. This file is used as input by a command generate-objects which in conjunction with template files, produces two output files: object.xml and job.xml.

Step #1: Edit defaults.xml

The defaults.xml file contains all the essential environment-specific information needed by the library. It answers questions like: What host has the master database schema? What host will the database export file be distributed? What are the username and passwords to access both schemas?

Open a text editor or better yet an XML editor. Cut and paste the contents of the XML shown below and save it to disk.

<defaults>
  <default>
    <node>${framework.node}</node>
    <!-- opts.name is passed in via the generate-objects command -->
    <name>${opts.name}</name>
  </default>
  <updater>
    <node>${defaults.default.node}</node>
    <databuilder>
      <node>${defaults.updater.node}</node>
      <rdb>
        <!-- host where master database schema resides -->
        <node>exporthost</node>
        <name>${opts.name}Source</name>
        <!-- database instance identifier -->
        <instancename>SID</instancename>
        <installroot>/path/to/rdb/home</installroot>
        <!-- database username -->
        <username>root</username>
        <!-- database password -->
        <password></password>
        <!-- module containing rdb-specific commands -->
        <strategy>RdbMysqlStrategy</strategy>
        <exportdir>/tmp/exportdir</exportdir>
        <config></config>
        <schema>
  	  <!-- schema name -->
          <name>contentDB</name>
	  <!-- schema username -->
          <username>schema_user</username>
	  <!-- schema password -->
          <password>schema_pass</password>
        </schema>
      </rdb>
    </databuilder>
    <site>
      <node>${defaults.updater.node}</node>
      <rdb>
        <!-- host where target database schema resides -->
        <node>${defaults.default.node}</node>
        <name>${opts.name}Target</name>
        <!-- database instance identifier -->
        <instancename>SID</instancename>
        <installroot>/path/to/rdb/home</installroot>
        <!-- database username -->
        <username>root</username>
        <!-- database password -->
        <password></password>
        <config></config>
        <schema>
  	  <!-- schema name -->
          <name>contentDB</name>
	  <!-- schema username -->
          <username>schema_user</username>
	  <!-- schema password -->
          <password>schema_pass</password>
	  <!-- Path to SQL script to run before import -->
          <preImportSqlScript>${entity.attribute.rdbSqlPackageInstallroot}/import/pre-import.sql</preImportSqlScript>
	  <!-- Path to SQL script to run after import -->
          <postImportSqlScript>${entity.attribute.rdbSqlPackageInstallroot}/import/post-import.sql</postImportSqlScript>
        </schema>
      </rdb>
    </site>
  </updater>
</defaults>
      

Some of the defaults can be taken as-is but the tags that are bold are ones that you must change, supplying the required local information.

Step #2: Configure library objects

Install and register an RdbProjectBuilder:

ad -p project -t RdbProjectBuilder -o name -c Install

ad -p project -t RdbProjectBuilder -o name -c Register -- \
      -basedir $CTIER_ROOT/src/project \
      -installroot $CTIER_ROOT/target/project

Copy the defaults.xml you created in Step #1 to $CTIER_ROOT/src/project/defaults.xml

Run the generate-objects command:

ad -p project -t RdbProjectBuilder -o name -c generate-objects -- \
      -name aName \
      -defaults $CTIER_ROOT/src/project/defaults.xml -load

Before you can run the job, it is necessary to deploy the objects. This is done via the AntDepo command, depot-setup. On the adminstrative node, run:

depot-setup -p project -a deploy 

After this command successfully completes, a new set of objects will be loaded into the ControlTier repository. You can view them via RdbProjectBuilder's find-objects command:

ad -p project -t RdbProjectBuilder -o name -c find-objects -- \
      -name aName 

Step #3: Upload job definition

The generate-objects command run in Step #2 will have produced a job.xml file. This file can be used to define a new job in the JobCenter application.

1. Login to JobCenter (e.g, go to URL: http://localhost:9090/jobcenter/menu/index
2. Press the "Create a new Job..." button
3. Press the "Upload job.xml" button
4. Locate and select the job.xml file output by generate-objects in the file chooser
5. Press "Save" button

The new job will be listed on the home page of JobCenter

Optional Step: Check-in generated files

It is considered best practice to maintain the files generated by generate-objects in a source code repository.

Next: Run →

Run

Overview

This document describes how to run a Rdb data BuildAndDeploy workflow job or command and is pertinent to users responsible for releasing Rdb data changes from the master database to target database schemas in other environments.

By running one of these workflows, the content of the master database will be exported to a file, packaged up and deployed to the node where the target database schema resides.

For a new job to be established, the steps covered in the Configure section will already have been completed yielding a new rdb BuildAndDeploy workflow.

Their are two interfaces available to execute the Rdb data BuildAndDeploy:

• Using JobCenter, the web-based graphical application,
• Using AntDepo's ad shell command

Instructions for running the BuildAndDeploy command using either interface are explained below.

Execute via JobCenter

In Configure Step #3, a new job will have been defined for the BuildAndDeploy process. After logging into JobCenter a list of the defined jobs will be displayed. Choosing and running a job will execute the underlying BuildAndDeploy command.

The general steps to using JobCenter to operate rdb BuildAndDeploy are listed:

1. Login to JobCenter
2. Identify the desired job
3. Run the job
4. Customize a report

Execute via 'ad'

An alternative to executing the BuildAndDeploy command via JobCenter is to execute it directly via the ad shell command. The general usage is shown below:

ad -p project -t Updater -o name -c BuildAndDeploy -- \
      -buildstamp buildstamp

A typical convention is to use the date and time as the -buildstamp argument. For example:

ad -p project -t Updater -o name -c BuildAndDeploy -- \
      -buildstamp 200711071500

If you are an experienced AntDepo user, you may also know how to run individual parts of the build and deploy workflow by running the appropriate command from one of the subordinate commands. For example, to run just the Deploy:

adminhost$ ad -p project -t Updater -o name -c Deploy

Or to run just the build, you can execute the Builder directly

buildhost$ ad -p project -t RdbDataBuilder -o name -c Build -- \
      -buildstamp buildstamp

Rolling back

A nice feature of this library is its support for rollback. Users can choose from any RdbDataPackage in the repository and restore the schema data content to the desired version.

General Usage

Rollback is accomplished by running two commands on the admin host:

1. runChangeDependencies: This configures the deployments to depend on the rollback package:

   ad -p project -t Updater -o name -c runChangedepencies -- \
   	-buildstamp buildstamp
   

2. Deploy: This deploys the rollback package to the RdbSchemas:

   ad -p project -t Updater -o name -c Deploy

In depth descriptions of the library commands can be found in the Reference section of the documentation.

Next: Reference →

Reference

Overview

This section is useful to developers interested how the library works and users interested in knowing all the command syntax offered by the modules in this library.

This library builds on the standard ControlTier "process building blocks" - Package, Builder, Updater, Site and Deployment - each a separate workflow that compose into the single end-to-end workflow command, BuildAndDeploy.

General Command Workflow

The sequence diagram below describes the workflow structure defined by the modules in the library.

Type Model

The diagram below describes the inheritance and composition hierarchies defined by the types in the library.

All the attributes and commands are defined in the Type Reference section of the documentation. There you will find a document page for each type.

Next: Type Reference →

Types

Type Reference

• Rdb: A relational database service
  • RdbConfigFile: Database configuration file
  • RdbExportDir: Directory where database export files are written
  • RdbInstallRoot: Database installation root
  • RdbInstanceName: Stores the value of the database instance name
  • RdbPassword: A schema user's password
  • RdbSetting: an Rdb setting
  • RdbStrategyModule: Adapter to database
  • RdbUserName: A user for a schema
• RdbDataBuilder: General purpose ControlTier data builder
• RdbDataPackage: A database schema export file generated by an RdbSchema
• RdbMysqlStrategy: MySQL RDB strategy
• RdbOracleStrategy: Oracle RDB strategy
• RdbProjectBuilder: Builds and manages projects that use the content library
  • RdbProjectBuilderSetting: A RdbProjectBuilder setting.
• RdbSchema: Represents a database schema
  • RdbSchemaExportParams: Sql import parameters
  • RdbSchemaName: A schema name
  • RdbSchemaPassword: A schema user's password
  • RdbSchemaPostImportSqlScript: Sql script to run post runImport
  • RdbSchemaPreImportSqlScript: Sql script to run before runImport
  • RdbSchemaSetting: an RdbSchema setting
  • RdbSchemaUserName: A user for a schema
  • RdbStrategy: A schema name
• RdbSqlPackage: A package containing build and deploy database sql scripts
• RdbStrategy: Abstract RDB strategy
  • RdbStrategyModule: Specifies the unique key value identifying which type database type is in use (e.g. "RdbMysqlStrategy" or "RdbOracleStrategy", etc)
  • RdbStrategySetting: an RdbStrategySetting setting

RdbProjectBuilder

Overview

RdbProjectBuilder: Builds and manages projects that use the content library

RdbProjectBuilder is derived from ProjectBuilder providing the ability to manage a ControlTier project. If you are new to ProjectBuilder see the tutorial starting with: Getting started using ProjectBuilder

The following sections describe how to obtain, install and use the data Module Library.

Obtaining the data library

Follow the steps below to obtain and install the data library.

1) Download the desired library jar file from Sourceforge:

data Module Library file release

2) Run the Register command specifying the following arguments:

ad -p project -t ProjectBuilder -o data -c Register -- \
	 -basedir /path/to/basedir -installroot /path/to/targetdir

3) Run the load-library command specifying the following arguments:

ad -p project -t ProjectBuilder -o data -c load-library -- \
        -jar /path/to/downloaded/data-version.jar

The destination project should now have the data library types loaded.

Using the data library

If you do not have the data types loaded, see the preceding section.

After the data library is installed, begin using the types in the library beginning with RdbProjectBuilder:

1) Run the Register command specifying the following arguments:

 ad -p project -t RdbProjectBuilder -o name -c Register -- \
        -basedir /path/to/module/srcdir -installroot /path/to/build/targetdir -install

2) Run the generate-objects command specifying the following arguments:

 ad -p project -t RdbProjectBuilder -o name -c generate-objects -- \
        -name aName -defaults /path/to/your/defaults.properties -load

The -name argument is used as the name for each generated object. The -load flag specifies to have loaded the object definitions loaded on the server.

3) Run the depot-setup command to deploy the objects in AntDepo:

depot-setup -p project -a deploy

The objects are now ready for use either via the AntDepo CLI command, ad, or via JobCenter webapp GUI.

The objects are now ready for use either via the AntDepo CLI command, ad, or via JobCenter webapp GUI.

4) Run the BuildAndUpdate command that will use the newly generated set of objects:

ad -p project -t dataUpdater -o aName -c BuildAndUpdate -- \
        -buildstamp buildstamp

Design

Super Type

ProjectBuilder

Extends ProjectBuilder

Role	Concrete. (Objects can be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name	RdbProjectBuilder

Constraints

Allowed Child Dependencies

• BuilderBuildFile¹
• BuilderBuildTarget¹
• BuilderScmBinding¹
• BuilderScmConnection¹
• BuilderScmLabel¹
• BuilderScmModule¹
• BuilderStageExtension¹
• BuilderStageFilebase¹
• ProjectBuilderDocBase¹
• ProjectBuilderForrestHome¹
• ProjectBuilderOrganizationDescription¹
• ProjectBuilderOrganizationName¹
• ProjectBuilderOrganizationURL¹
• ProjectBuilderProjectDescription¹
• ProjectBuilderProjectName¹
• ProjectBuilderProjectURL¹
• RdbProjectBuilderDefaults¹
• RdbProjectBuilderTemplateDir¹

¹: These types have a Singleton constraint. Only one instance may be added as a resource.

Allowed Parent Dependencies

• Node

Attributes

Exported Attributes

Name	Property
basedir	deployment-basedir
targetdir	deployment-install-root

Defaults for Imported Attributes

Name	Default
buildfile	${modules.dir}/RdbProjectBuilder/lib/build.xml
buildtarget	all
defaults	${modules.dir}/RdbProjectBuilder/templates/defaults.properties
organizationDescription	Maker of the ControlTier software
organizationName	ControlTier
organizationURL	http://www.controltier.com
projectDescription	The data deployment types
projectName	atg
projectURL	http://open.controltier.com
scmConnection	https://moduleforge.svn.sourceforge.net/svnroot/moduleforge/trunk
scmModule	atg
stageextension	jar
stagefilebase	.*
templateDir	${modules.dir}/RdbProjectBuilder/templates

Commands

Related Types

The following types are defined for use with RdbProjectBuilder.

RdbProjectBuilderSetting

Overview

RdbProjectBuilderSetting: A RdbProjectBuilder setting.

Design

Super Type

Setting

Role	Abstract. (Objects cannot be created.)
Instance Names	Unique

Constraints

Allowed Parent Dependencies

• Builder

RdbDataBuilder

Overview

RdbDataBuilder: General purpose ControlTier data builder

Design

Super Type

Builder

Role	Concrete. (Objects can be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name	RdbDataBuilder

Constraints

Allowed Child Dependencies

• BuilderBuildFile¹
• BuilderBuildTarget¹
• BuilderPackageExtension¹
• BuilderPackageFilebase¹
• BuilderPackageInstallroot¹
• BuilderPackageType¹
• BuilderPackageVersion¹
• BuilderrunImportMax¹
• BuilderrunImportMin¹
• BuilderScmBinding¹
• BuilderScmConnection¹
• BuilderScmLabel¹
• BuilderScmModule¹
• Rdb
• RdbExportDir¹
• RdbInstanceName¹
• RdbSchemaName¹

¹: These types have a Singleton constraint. Only one instance may be added as a resource.

Allowed Parent Dependencies

• Node
• Updater

Attributes

Exported Attributes

Name	Property	Description
basedir	deployment-basedir	Directory where source code is checked out
targetdir	deployment-install-root	Directory where build artifacts are written

Defaults for Imported Attributes

Name	Default	Description
buildFile		Build file to invoke
buildTarget		Target to invoke
importMax	1	maximum number of packages to import after build
importMin	1	minimum number of packages to import after build
packageExtension	.*	name or pattern of file name extensions to import
packageFilebase	.*?	root name or pattern of filenames to import (minus file extension and option version qualifier)
packageInstallroot	${entity.instance.dir}/RdbDataPackage	Directory built package should be extracted
packageType	RdbDataPackage	Object type to use when registering uploaded packages
packageVersion	${opts.buildstamp}	String to use for assigning version for package registration
rdbInstanceName	default	Target rdb
rdbSchemaName	default	Target rdb schema name
scmBinding	cvs	binds scm commands to concrete SCM client commandsxs
scmConnection		connection string to access SCM repository
scmLabel		name of the label/branch to access in SCM repository
scmModule		name of code module in SCM repository

Commands

Build

Run the data build cycle, delegating schema export to the configured Rdb deployment.

Usage

Build [-buildstamp <>]

Workflow

1. rdbSchemaExport
2. repoImport

Options

Option	Description
buildstamp	build identifier

dispatchCmd

Dispatch specified command to selected child dependencies.

Usage

dispatchCmd [-buildstamp <>] -command <> [-keepgoing] [-resourcename <.*>] [-resourceorder <[^.]*>] [-resourcetype <[^.]*>] [-sortorder <ascending>] [-targetdir <>]

Options

Option	Description
buildstamp	Unique build and deployment identifier
command	command to dispatch
keepgoing	If true, all iterations of the called workflow will be executed, even if a task in one or more of them fails.
resourcename	resource name pattern
resourceorder	resource order name
resourcetype	resource type name
sortorder	order to sort resources
targetdir	target directory

rdbSchemaExport

Dispatch the RdbSchema export operation via the configured Rdb child dependency.

Usage

rdbSchemaExport [-buildstamp <>] [-command <Export>] [-resourcename <.*>] [-resourcetype <Rdb>] [-targetdir <>]

Workflow

1. dispatchCmd

Options

Option	Description
buildstamp	build identifier
command	command name
resourcename	resource name pattern
resourcetype	resource type name
targetdir	target directory

Rdb

Overview

Rdb: A relational database service

Design

Super Type

Service

Role	Concrete. (Objects can be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name

Constraints

Allowed Child Dependencies

• RdbConfigFile ¹
• RdbExportDir ¹
• RdbInstallRoot ¹
• RdbInstanceName ¹
• RdbPassword ¹
• RdbSchema
• RdbSchema
• RdbStrategyModule ¹
• RdbUserName ¹

¹: These types have a Singleton constraint. Only one instance may be added as a resource.

Allowed Parent Dependencies

• Node
• RdbDataBuilder
• Site

Commands

assertServiceIsDown

Confirm the Rdb service is down.

Usage

assertServiceIsDown -installroot <> [-instance <>] [-rdbpassword <>] [-rdbusername <>] [-strategy <>]

Options

Option	Description
installroot	path to database install
instance	Instance name
rdbpassword	Database user's password
rdbusername	Database user name
strategy	Database strategy name

assertServiceIsUp

Confirm the Rdb service is process is running.

Usage

assertServiceIsUp -installroot <> [-instance <>] [-rdbpassword <>] [-rdbusername <>] [-strategy <>]

Options

Option	Description
installroot	path to database install
instance	Instance name
rdbpassword	Database user's password
rdbusername	Database user name
strategy	Database strategy name

dispatchCmd

Dispatch the command to selected child dependency.

Usage

dispatchCmd [-buildstamp <>] -command <> [-keepgoing] [-resourcename <.*>] [-resourceorder <[^.]*>] [-resourcetype <[^.]*>] [-sortorder <ascending>] [-targetdir <>]

Options

Option	Description
buildstamp	Unique build and deployment identifier
command	command to dispatch
keepgoing	If true, all iterations of the called workflow will be executed, even if a task in one or more of them fails.
resourcename	resource name pattern
resourceorder	resource order name
resourcetype	resource type name
sortorder	order to sort resources
targetdir	target directory

Export

Call each RdbSchema dependency to dump its database schema to a package.

Usage

Export -buildstamp <> [-command <Export>] [-resourcetype <RdbSchema>] [-targetdir <>]

Workflow

1. dispatchCmd

Options

Option	Description
buildstamp	Unique build identifier
command	Command to execute
resourcetype	Type of resource to dispatch
targetdir	target directory

deployRdbSchemas

Call each RdbSchema dependency to import its exportfile.

Usage

deployRdbSchemas -buildstamp <> [-command <Deploy>] [-resourcetype <RdbSchema>]

Workflow

1. dispatchCmd

Options

Option	Description
buildstamp	Unique build identifier
command	Command to execute
resourcetype	Resource type to dispatch

Deploy

Call each RdbSchema dependency to run their Deploy cycle.

Usage

Deploy [-buildstamp <>]

Workflow

1. deployRdbSchemas

Options

Option	Description
buildstamp	Unique build identifier

Related Types

The following types are defined for use with Rdb.

RdbSetting

Overview

RdbSetting: an Rdb setting

Design

Super Type

Setting

Role	Abstract. (Objects cannot be created.)
Instance Names	Unique

Constraints

Allowed Parent Dependencies

• Rdb

RdbUserName

Overview

RdbUserName: A user for a schema

Design

Super Type

RdbSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbUserName	settingValue

RdbPassword

Overview

RdbPassword: A schema user's password

Design

Super Type

RdbSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Constraints

Attributes

Exported Attributes

Name	Property
rdbPassword	settingValue

RdbInstanceName

Overview

RdbInstanceName: Stores the value of the database instance name

Design

Super Type

RdbSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbInstanceName	settingValue

RdbInstallRoot

Overview

RdbInstallRoot: Database installation root

Design

Super Type

RdbSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbInstallRoot	settingValue

RdbExportDir

Overview

RdbExportDir: Directory where database export files are written

Design

Super Type

RdbSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbExportDir	settingValue

RdbConfigFile

Overview

RdbConfigFile: Database configuration file

Design

Super Type

RdbSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbConfigFile	settingValue

RdbStrategyModule

Overview

RdbStrategyModule: Adapter to database

Design

Super Type

RdbSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbStrategy	settingValue

RdbSchema

Overview

RdbSchema: Represents a database schema

Design

Super Type

Deployment

Role	Concrete. (Objects can be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name

Constraints

Allowed Child Dependencies

• RdbConfigFile¹
• RdbDataPackage ¹
• RdbExportDir¹
• RdbInstallRoot¹
• RdbSchemaExportParams ¹
• RdbSchemaName ¹
• RdbSchemaPassword ¹
• RdbSchemaPostImportSqlScript ¹
• RdbSchemaPreImportSqlScript ¹
• RdbSchemaUserName ¹
• RdbSqlPackage ¹
• RdbStrategyModule¹

¹: These types have a Singleton constraint. Only one instance may be added as a resource.

Allowed Parent Dependencies

• Node
• Rdb
• RdbDataBuilder

Attributes

Defaults for Imported Attributes

Name	Default
rdbInstallRoot	/path/to/rdb/installroot

Commands

assertSchemaIsDown

Confirm the schema is unavailable in the database instance.

Usage

assertSchemaIsDown [-config <>] -installroot <> [-instance <>] [-password <>] [-schema <>] [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

assertSchemaIsUp

Confirm the schema is available in the database instance.

Usage

assertSchemaIsUp [-config <>] -installroot <> [-instance <>] [-password <>] [-schema <>] [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

runSqlScript

Run the sql script.

Usage

runSqlScript [-buildstamp <>] [-config <>] [-failonwarnings <>] -installroot <> [-instance <>] [-password <>] [-schema <>] [-sqlscript <>] [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
failonwarnings	if arg true, fail if there are import warnings
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
sqlscript	sql script to run
strategy	Database strategy name
username	Schema user name

Export

Export the schema to a file.

Usage

Export -buildstamp <> [-config <>] [-exportfile <${entity.attribute.rdbExportDir}/${context.name}-${opts.buildstamp}.dmp>] -installroot <> [-instance <>] [-password <>] [-schema <>] [-strategy <>] [-targetdir <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
exportfile	Schema export file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
targetdir	target directory
username	Schema user name

runImport

Process the supplied exportfile and import it to the schema.

Usage

runImport -buildstamp <> [-config <>] [-export_user <>] [-exportfile <${entity.attribute.rdbDataPackageInstallroot}/${entity.attribute.rdbDataPackageFilename}>] [-failonwarnings <>] -installroot <> [-instance <>] [-password <>] [-schema <>] [-sqlscript <>] [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
export_user	from user
exportfile	dump file to import
failonwarnings	if arg true, fail if there are import warnings
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
sqlscript	sql script to run before import
strategy	Database strategy name
username	Schema user name

Deploy

Run the process to load a schema export file, executing the pre- and post-import Sql scripts.

Downloads the schema exportfile, runs a pre-import SQL script, loads the data from the exportfile, and then executes a post-import SQL script

Usage

Deploy -buildstamp <>

Workflow

1. Packages-Install
2. runPreImportSql
3. runImport
4. runPostImportSql

Options

Option	Description
buildstamp	Unique build identifier

runPreImportSql

Run sql script prior to import.

Usage

runPreImportSql -buildstamp <> [-command <runSqlScript>] [-sqlscript <>]

Workflow

1. runSqlScript

Options

Option	Description
buildstamp	Unique build identifier
command	Command to execute
sqlscript	Sql script to run

runPostImportSql

Run sql script post import.

Usage

runPostImportSql -buildstamp <> [-command <runSqlScript>] [-sqlscript <>]

Workflow

1. runSqlScript

Options

Option	Description
buildstamp	Unique build identifier
command	Command to execute
sqlscript	Sql script to run

Related Types

The following types are defined for use with RdbSchema.

RdbStrategy

Overview

RdbStrategy: A schema name

Design

Super Type

RdbSchemaSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbStrategy	settingValue

RdbSchemaName

Overview

RdbSchemaName: A schema name

Design

Super Type

RdbSchemaSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbSchemaName	settingValue

RdbSchemaUserName

Overview

RdbSchemaUserName: A user for a schema

Design

Super Type

RdbSchemaSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Attributes

Exported Attributes

Name	Property
rdbSchemaUserName	settingValue
schemaFromUser	settingType

RdbSchemaPassword

Overview

RdbSchemaPassword: A schema user's password

Design

Super Type

RdbSchemaSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Constraints

Attributes

Exported Attributes

Name	Property
rdbSchema	settingType
rdbSchemaPassword	settingValue

RdbSchemaPreImportSqlScript

Overview

RdbSchemaPreImportSqlScript: Sql script to run before runImport

Design

Super Type

RdbSchemaSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Constraints

Attributes

Exported Attributes

Name	Property
rdbSchemaPreImportSqlScript	settingValue

RdbSchemaPostImportSqlScript

Overview

RdbSchemaPostImportSqlScript: Sql script to run post runImport

Design

Super Type

RdbSchemaSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Constraints

Attributes

Exported Attributes

Name	Property
rdbSchemaPostImportSqlScript	settingValue

RdbSchemaExportParams

Overview

RdbSchemaExportParams: Sql import parameters

Design

Super Type

RdbSchemaSetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Constraints

Attributes

Exported Attributes

Name	Property
rdbSchemaImportParams	settingValue

RdbSchemaSetting

Overview

RdbSchemaSetting: an RdbSchema setting

Design

Super Type

Setting

Role	Abstract. (Objects cannot be created.)
Instance Names	Unique

Constraints

Allowed Parent Dependencies

• RdbSchema

RdbDataPackage

Overview

RdbDataPackage: A database schema export file generated by an RdbSchema

An RdbDataPackage is a simple Package interface to managing the upload and download of the export files generated by the Export command of an RdbSchema object. The export file is unmodified, without additional compression or encoding applied during the upload process.

The RdbDataPackage type is a trivial subtype of Package but does override the finish command (see below).

Building

Builds of the RdbDataPackage are coordinated via the RdbDataBuilder object.

Deploying

Deployment of the RdbDataPackage are coordinated via the Rdb object.

Design

Super Type

Package

Role	Concrete. (Objects can be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name	RdbDataPackage

Constraints

Allowed Child Dependencies

• RdbDataPackage

Allowed Parent Dependencies

• RdbSchema

Allowed Property Values

Property	Allowed Values	Default	Enforced
package-arch	noarch	noarch
package-filetype	dmp	dmp	true
package-repo-url	${framework.pkgRepo.uri}/${context.depot}/RdbDataPackage/dmps/FILENAME	${framework.pkgRepo.uri}/${context.depot}/RdbDataPackage/dmps/FILENAME	false
package-install-root	$${entity.instance.dir}/RdbDataPackage	$${entity.instance.dir}/RdbDataPackage	true
package-vendor			false

Attributes

Exported Attributes

Name	Property	Description
rdbDataPackageFilename	package-filename	Schema export filename
rdbDataPackageInstallroot	package-install-root	Directory where schema export file resides

Commands

finish

Perform post package extraction finish step.

Ordinarily, the finish command is responsibe to clean up after the installation process. This normally includes removing the downloaded archive file. RdbDataPackage does not remove the archive file leaving that task to the RdbSchema object after the export process completes.

Usage

finish [-filename <>] [-filtersfile <>] [-installroot <>]

Options

Option	Description
filename	path to package file
filtersfile	property file
installroot	installation root dir

RdbSqlPackage

Overview

RdbSqlPackage: A package containing build and deploy database sql scripts

An RdbSqlPackage is a zip archive of SQL scripts executed during the RdbSchema Deploy process.

The RdbSqlPackage type is a trivial subtype of zip.

Content Structure

A standard file layout within the package archive is encouraged. This will enable a simple configuration in the RdbSchema object setup.

The diagram below describes the suggested file layout for the zip archive:

	  
package-archive-root
	  |
	  +-import // directory containing pre- and post-import SQL scripts
	     |
             |- pre-import.sql  // file executed by RdbSchema->runPreImportSqlScript
             `- post-import.sql // file executed by RdbSchema->runPostImportSqlScript
	

In the future, there may be a second directory to store export SQL scripts.

Building

Builds of the RdbSqlPackage are coordinated via the RdbDataBuilder object.

Deploying

Deployment of the RdbSqlPackage are coordinated via the RdbSchema object.

Design

Super Type

zip

Role	Concrete. (Objects can be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name	RdbSqlPackage

Constraints

Allowed Child Dependencies

• RdbSqlPackage

Allowed Parent Dependencies

• RdbSchema

Allowed Property Values

Property	Allowed Values	Default	Enforced
package-arch	noarch	noarch
package-filetype	zip	zip	true
package-repo-url	${framework.pkgRepo.uri}/${context.depot}/RdbSqlPackage/zips/FILENAME	${framework.pkgRepo.uri}/${context.depot}/RdbSqlPackage/zips/FILENAME	false
package-install-root	$${entity.instance.dir}/RdbSqlPackage	$${entity.instance.dir}/RdbSqlPackage	false
package-vendor			false

Attributes

Exported Attributes

Name	Property	Description
rdbSqlPackageInstallroot	package-install-root	Directory where sql script code resides

Commands

RdbStrategy

Overview

RdbStrategy: Abstract RDB strategy

This is a abstract implementation defining various basic rdb management operations.

Design

Super Type

Deployment

Role	Abstract. (Objects cannot be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name

Constraints

Allowed Child Dependencies

• RdbStrategySetting

Allowed Parent Dependencies

• Rdb
• RdbSchema

Attributes

Commands

assertSchemaIsDown

Confirm schema is unavailable in the database instance.

Usage

assertSchemaIsDown [-config <>] -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

assertSchemaIsUp

Confirm schema is available in the database instance.

Usage

assertSchemaIsUp [-config <>] -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

assertServiceIsDown

Confirm the rdb service is down.

Usage

assertServiceIsDown [-config <>] -installroot <> [-instance <>] [-password <>] [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
strategy	Database strategy name
username	Schema user name

assertServiceIsUp

Confirm that rdb service is up.

Usage

assertServiceIsUp [-config <>] -installroot <> [-instance <>] [-password <>] [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
strategy	Database strategy name
username	Schema user name

runSqlScript

Run the sql script.

Usage

runSqlScript [-buildstamp <>] [-config <>] [-failonwarnings <>] -installroot <> [-instance <>] [-password <>] -schema <> [-sqlscript <>] [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
failonwarnings	if arg true, fail if there are import warnings
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
sqlscript	sql script to run
strategy	Database strategy name
username	Schema user name

Export

Export the schema to a file.

Usage

Export [-buildstamp <>] [-config <>] -exportfile <> -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
exportfile	Output file
installroot	path to database install
instance	Rdb server instance name
password	Schema user's password
schema	Rdb schema name
strategy	Database strategy name
username	Schema user name

runImport

Load the exportfile into the schema.

Usage

runImport [-buildstamp <>] [-config <>] [-export_user <>] -exportfile <> [-failonwarnings <>] -installroot <> [-instance <>] [-params <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
export_user	from user
exportfile	dump file to import
failonwarnings	if arg true, fail if there are import warnings
installroot	path to database install
instance	Database server instance name
params	import parameters
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

Related Types

The following types are defined for use with RdbStrategy.

RdbStrategySetting

Overview

RdbStrategySetting: an RdbStrategySetting setting

Design

Super Type

Setting

Role	Abstract. (Objects cannot be created.)
Instance Names	Unique

Constraints

Allowed Parent Dependencies

• RdbStrategySetting

RdbStrategyModule

Overview

RdbStrategyModule: Specifies the unique key value identifying which type database type is in use (e.g. "RdbMysqlStrategy" or "RdbOracleStrategy", etc)

Design

Super Type

RdbStrategySetting

Role	Concrete. (Objects can be created.)
Instance Names	Unique

Constraints

Allowed Parent Dependencies

• Rdb
• RdbSchema

Allowed Property Values

Property	Allowed Values	Default	Enforced	Description
settingValue	MssqlRdbStrategy RdbMysqlStrategy RdbOracleStrategy RdbStrategy	RdbMysqlStrategy RdbStrategy	false	Rdb specific strategy implementation

Attributes

Exported Attributes

Name	Property
rdbStrategy	settingValue

RdbMysqlStrategy

Overview

RdbMysqlStrategy: MySQL RDB strategy

This is a implementation defining various basic rdb management operations for MySQL.

Design

Super Type

RdbStrategy

Role	Concrete. (Objects can be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name

Constraints

Allowed Child Dependencies

• RdbStrategySetting

Allowed Parent Dependencies

• Rdb
• RdbSchema

Attributes

Commands

assertSchemaIsDown

Checks schema is unavailable in the designated instance

Usage

assertSchemaIsDown [-config <>] -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

assertSchemaIsUp

Checks schema is available in the designated instance

Usage

assertSchemaIsUp [-config <>] -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

assertServiceIsDown

Checks that rdb instance is down

Usage

assertServiceIsDown [-config <>] -installroot <> [-instance <>] [-password <>] [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
strategy	Database strategy name
username	Schema user name

assertServiceIsUp

Checks that rdb instance is up

Usage

assertServiceIsUp [-config <>] -installroot <> [-instance <>] [-password <>] [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
strategy	Database strategy name
username	Schema user name

runSqlScript

Runs the sql script

Usage

runSqlScript [-buildstamp <>] [-config <>] [-failonwarnings <>] -installroot <> [-instance <>] [-password <>] -schema <> [-sqlscript <>] [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
failonwarnings	if arg true, fail if there are import warnings
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
sqlscript	sql script to run
strategy	Database strategy name
username	Schema user name

Export

Exports the schema to a file

Usage

Export [-buildstamp <>] [-config <>] -exportfile <> -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
exportfile	Output file
installroot	path to database install
instance	Rdb server instance name
password	Schema user's password
schema	Rdb schema name
strategy	Database strategy name
username	Schema user name

runImport

runImports the schema

Usage

runImport [-buildstamp <>] [-config <>] [-export_user <>] -exportfile <> [-failonwarnings <>] -installroot <> [-instance <>] [-password <>] -schema <> [-sqlscript <>] [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
export_user	from user
exportfile	dump file to import
failonwarnings	if arg true, fail if there are import warnings
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
sqlscript	sql script to run before import
strategy	Database strategy name
username	Schema user name

createSchema

Creates the schema

Usage

createSchema -installroot <> [-instance <>] -password <> [-schema <>] -sqlscript <> -username <>

Options

Option	Description
installroot	Database server installation root directory
instance	Database server instance name
password	Schema user's password
schema	Database schema name
sqlscript	sql script to construct schema
username	Schema user name

grantSchema

Grants access to the schema

Usage

grantSchema -installroot <> [-instance <>] [-password <>] [-rdbclients <localhost>] -schema <> [-username <root>]

Options

Option	Description
installroot	Database server installation root directory
instance	Database server instance name
password	Schema user's password
rdbclients	allowed client nodes
schema	Database schema name
username	Schema user name

RdbOracleStrategy

Overview

RdbOracleStrategy: Oracle RDB strategy

This is a implementation defining various basic rdb management operations for MySQL.

Design

Super Type

RdbStrategy

Role	Concrete. (Objects can be created.)
Instance Names	Unique
Notification	false
Template Directory
Data View	Children, proximity: 1
Logger Name

Constraints

Allowed Child Dependencies

• RdbStrategySetting

Allowed Parent Dependencies

• Rdb
• RdbSchema

Attributes

Commands

assertSchemaIsDown

Checks schema is unavailable in the designated instance

Usage

assertSchemaIsDown [-config <>] -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

assertSchemaIsUp

Checks schema is available in the designated instance

Usage

assertSchemaIsUp [-config <>] -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
strategy	Database strategy name
username	Schema user name

assertServiceIsDown

Checks that rdb instance is down

Usage

assertServiceIsDown [-config <>] -installroot <> [-instance <>] [-password <>] [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
strategy	Database strategy name
username	Schema user name

assertServiceIsUp

Checks that rdb instance is up

Usage

assertServiceIsUp [-config <>] -installroot <> [-instance <>] [-password <>] [-strategy <>] [-username <>]

Options

Option	Description
config	Database configuration file
installroot	path to database install
instance	Database server instance name
password	Schema user's password
strategy	Database strategy name
username	Schema user name

Export

Exports the schema to a file

Usage

Export [-buildstamp <>] [-config <>] -exportfile <> -installroot <> [-instance <>] [-password <>] -schema <> [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
exportfile	Output file
installroot	path to database install
instance	Rdb server instance name
password	Schema user's password
schema	Rdb schema name
strategy	Database strategy name
username	Schema user name

runImport

runImports the schema

Usage

runImport [-buildstamp <>] [-config <>] [-export_user <>] -exportfile <> [-failonwarnings <>] -installroot <> [-instance <>] [-password <>] -schema <> [-sqlscript <>] [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
export_user	from user
exportfile	dump file to import
failonwarnings	if arg true, fail if there are import warnings
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
sqlscript	sql script to run before import
strategy	Database strategy name
username	Schema user name

runSqlScript

Runs the sql script

Usage

runSqlScript [-buildstamp <>] [-config <>] [-failonwarnings <>] -installroot <> [-instance <>] [-password <>] [-schema <>] [-sqlscript <>] [-strategy <>] [-username <>]

Options

Option	Description
buildstamp	build stamp
config	Database configuration file
failonwarnings	if arg true, fail if there are import warnings
installroot	path to database install
instance	Database server instance name
password	Schema user's password
schema	Database schema name
sqlscript	sql script to run
strategy	Database strategy name
username	Schema user name