Database Management Tool

The database management tool is distributed as a standalone JAR file named tools-database-manager-${corda_version}.jar. It is intended to be used by Corda Enterprise node administrators who want more control over database changes made in production environments.

The following sections document the available subcommands suitable for a node operator or database administrator.

Options

• -v, --verbose, --log-to-console: If set, prints logging to the console as well as to a file.
• --logging-level=<loggingLevel>: Enable logging at this level and higher.
  • Possible values: ERROR, WARN, INFO, DEBUG, TRACE.
  • Default: INFO.
• --config-obfuscation-passphrase[=<cliPassphrase>]: The passphrase used in the key derivation function when generating an AES key.
• --config-obfuscation-seed[=<cliSeed>]: The seed used in the key derivation function to create a salt.
• -h, --help: See a list of available commands and descriptions.
• -V, --version: Print version information.

Commands:

• dry-run Output the database migration to the specified output file.
• execute-migration Run the database migration on the configured database.
• sync-app-schemas Update the migration change log for all available CorDapps. When the tool runs with this sub-command against a node, the node will add entries to the Liquibase changelog for any CorDapp custom schema migrations that are available in the cordapps node folder and are not already present in the change log.
• create-migration-sql-for-cordapp Create migration files for a CorDapp.
• release-lock Releases whatever locks are on the database change log table, in case shutdown failed.
• install-shell-extensions Install alias and autocompletion for bash and zsh.

Allow obfuscated passwords

The DB Tool must be able to de-obfuscate the obfuscated fields. The following command line options are provided for setting the passphrase and seed if necessary.

• --config-obfuscation-passphrase.
• --config-obfuscation-seed.

Execute a dry run of the SQL migration scripts

The dry-run subcommand can be used to output the database migration to the specified output file or to the console. The output file is created relative to the current working directory.

Usage:

database-manager dry-run [-hvV] [--doorman-jar-path=<doormanJarPath>]
                         [--logging-level=<loggingLevel>] [--mode=<mode>]
                         -b=<baseDirectory> [-f=<configFile>] [<outputFile>]

The outputFile parameter can be optionally specified determine what file to output the generated SQL to, or use CONSOLE to output to the console.

Additional options:

• --base-directory, -b: (Required) The node working directory where all the files are kept. This defaults to the current working directory if not set.
• --config-file, -f: The path to the config file. Defaults to node.conf.
• --mode: The operating mode. Possible values: NODE, DOORMAN, JPA_NOTARY. Default: NODE.
• --doorman-jar-path=<doormanJarPath>: The path to the doorman (Identity Manager) JAR file.
• --verbose, --log-to-console, -v: If set, prints logging to the console as well as to a file.
• --logging-level=<loggingLevel>: Enable logging at this level and higher. Possible values: ERROR, WARN, INFO, DEBUG, TRACE. Default: INFO.
• --core-schemas: Output DB-specific DDL to apply the core node schema migrations.
• --app-schemas: Output DB-specific DDL to apply the migrations for custom CorDapp schemas.
• --help, -h: See a list of available commands and descriptions.
• --version, -V: Print version information.

Executing SQL migration scripts

The execute-migration subcommand runs migration scripts on the node’s database.

Usage:

database-manager execute-migration [-hvV] [--doorman-jar-path=<doormanJarPath>]
                                   [--logging-level=<loggingLevel>]
                                   [--mode=<mode>] -b=<baseDirectory>
                                   [-f=<configFile>]

• --base-directory, -b: (Required) The node working directory where all the files are kept. This defaults to the current working directory if not set.
• --config-file, -f: The path to the config file. Defaults to node.conf.
• --mode: The operating mode. Possible values: NODE, DOORMAN, JPA_NOTARY. Default: NODE.
• --doorman-jar-path=<doormanJarPath>: The path to the doorman (Identity Manager) JAR file.
• --verbose, --log-to-console, -v: If set, prints logging to the console as well as to a file.
• --logging-level=<loggingLevel>: Enable logging at this level and higher. Possible values: ERROR, WARN, INFO, DEBUG, TRACE. Default: INFO.
• --core-schemas: Run Liquibase migrations for the node core schema.
• --app-schemas: Run Liquibase migrations for custom CorDapp schemas.
• --db-admin-config <path/to/adminconfigfile>: Specify the location on disk of a configuration file holding elevated access credentials for the DB. The DB Management tool will use the credentials listed in the configuration file to connect to the node database and apply the changes. The configuration file supports the following fields:
  • dbAdminUser.
  • dbAdminPassword.
• --help, -h: See a list of available commands and descriptions.
• --version, -V: Print version information.

Releasing database locks

The release-lock subcommand forces the release of database locks. Sometimes, when a node or the database management tool crashes while running migrations, Liquibase will not release the lock. This can happen during some long database operations, or when an admin kills the process (this cannot happen during normal operation of a node, only during the migration process).

Usage:

database-manager release-lock [-hvV] [--doorman-jar-path=<doormanJarPath>]
                              [--logging-level=<loggingLevel>] [--mode=<mode>]
                              -b=<baseDirectory> [-f=<configFile>]

Additional options:

• --base-directory, -b: (Required) The node working directory where all the files are kept (default: .).
• --config-file, -f: The path to the config file. Defaults to node.conf.
• --mode: The operating mode. Possible values: NODE, DOORMAN, JPA_NOTARY. Default: NODE.
• --doorman-jar-path=<doormanJarPath>: The path to the doorman JAR.
• --verbose, --log-to-console, -v: If set, prints logging to the console as well as to a file.
• --logging-level=<loggingLevel>: Enable logging at this level and higher. Possible values: ERROR, WARN, INFO, DEBUG, TRACE. Default: INFO.
• --help, -h: See a list of available commands and descriptions.
• --version, -V: Print version information.

Database Manager shell extensions

The install-shell-extensions subcommand can be used to install the database-manager alias and auto completion for bash and zsh. See Shell extensions for CLI Applications for more info.

Troubleshooting

Symptom: Problems acquiring the lock, with output like this:

Waiting for changelog lock….
Waiting for changelog lock….
Waiting for changelog lock….
Waiting for changelog lock….
Waiting for changelog lock….
Waiting for changelog lock….
Waiting for changelog lock….
Liquibase Update Failed: Could not acquire change log lock.  Currently locked by SomeComputer (192.168.15.X) since 2013-03-20 13:39
SEVERE 2013-03-20 16:59:liquibase: Could not acquire change log lock.  Currently locked by SomeComputer (192.168.15.X) since 2013-03-20 13:39
liquibase.exception.LockException: Could not acquire change log lock.  Currently locked by SomeComputer (192.168.15.X) since 2013-03-20 13:39

at liquibase.lockservice.LockService.waitForLock(LockService.java:81)
at liquibase.Liquibase.tag(Liquibase.java:507)
at liquibase.integration.commandline.Main.doMigration(Main.java:643)
at liquibase.integration.commandline.Main.main(Main.java:116)

Advice: See this StackOverflow question. Run the following command to force Liquibase to give up the lock:

java -jar tools-database-manager-4.0.jar --base-directory /path/to/node --release-lock