Most Popular
Recently Added
Recently Updated

How to Change a Node's Runtime Database

Applies to: SymmetricDS 3.x and later
Node types: Log-based capture, time-based capture, load-only (write-only)

Overview

When a node uses log-based capture, time-based capture, or is configured as load-only, SymmetricDS installs its own internal tables (channels, triggers, batches, etc.) in a separate runtime database. This keeps SymmetricDS system data isolated from the source or target data being replicated.

By default, SymmetricDS uses H2, a lightweight embedded database, as the runtime database. While H2 is convenient for getting started, it can become a bottleneck or source of instability in production environments — particularly under high load, after long uptimes, or when the node process is not shut down cleanly.

Switching to a more robust database such as PostgreSQL is straightforward and requires only a change to the node's .properties file and a clean restart.

Understanding the Runtime vs. Target Database

It is important to understand the distinction between two sets of database properties:

Property Prefix Purpose
db.* The runtime database in which SymmetricDS stores its system tables
target.db.* The target database which serves as the source being monitored and/or the destination where data loads

Changing the runtime database means changing the db properties. The target.db properties are unaffected.

Prerequisites

Before switching the runtime database:

  1. Export your configuration. Because replacing the runtime database discards all existing SymmetricDS tables, export your configuration beforehand so you can re-import it if needed. In the SymmetricDS Pro web console, go to Configure -> Details -> Overview and use the export option. Alternatively, use the open-source command-line tool:
bin/symadmin --engine my-node-000 export-config
  1. Ensure that synchronization is caught up. Switching the runtime database abandons all state in the existing H2 database, including any batches that have not yet been sent. Unsent data will be lost. If the node is not caught up, you will need to perform an initial load after the switch to recover any missing data.
  2. Disable automatic initial loads if necessary. The auto.reload and auto.reload.reverse parameters default to false. If either has been explicitly set to true in the sym_parameter table, the affected node will automatically trigger a full initial load when it re-registers with the new runtime database. In that case, temporarily set the parameter(s) to false via Configure -> Details -> Parameters in the SymmetricDS Pro web console (or manually update the sym_parameter table) before starting the node.
  3. Stop the SymmetricDS node completely. Do not attempt to migrate with the node running.
  4. Create a new, empty database on the target database server. SymmetricDS will create its own runtime tables on first startup (given proper permissions).
  5. Ensure the JDBC driver for the new database is available in the lib/ directory of your SymmetricDS installation.
  6. Ensure the database user has sufficient privileges to create and manage tables in the runtime database. See Appendix C of the SymmetricDS User Guide for the required permissions for each supported database platform.

Steps

  1. Locate the node's properties file

Node properties files are located in the engines/ directory of your SymmetricDS installation. The file is named after the node, for example:

engines/my-node-000.properties
  1. Update the runtime database properties

Open the .properties file and replace the db.* entries with the connection details for your new database.

Before (default H2):

db.driver=org.h2.Driver
db.url=jdbc:h2:file:my-node;LOCK_TIMEOUT=60000
db.user=
db.password=
db.validation.query=select 1

After (PostgreSQL):

db.driver=org.postgresql.Driver
db.url=jdbc:postgresql://localhost:5432/symmetric_runtime
db.user=symmetric_user
db.password=yourpassword
db.validation.query=select 1

▎ Tip: To avoid storing the password in plaintext, you can encrypt it. In SymmetricDS Pro, the easiest way is to temporarily specify the db.password in plaintext in the file, start the node, then navigate to the Manage -> Startup Parameters screen in the web console and enter the password there. It will be saved in encrypted form automatically. Alternatively, refer to the Encrypted Passwords section of the SymmetricDS User Guide for instructions on manually encrypting the value.

  1. Start the node

Start SymmetricDS normally. On first startup, it will detect the empty runtime database and create all required tables automatically:

bin/sym --engine my-node-000 start

Watch the log for confirmation that the runtime database initialized successfully. You should see output similar to:

INFO - Creating SymmetricDS tables in runtime database...
INFO - Node my-node-000 started successfully
  1. Verify registration

Before proceeding, confirm that the affected node has re-registered successfully with its registration server. If other nodes register with the affected node, confirm that those nodes have also re-registered. Pro users can verify registration status under Manage -> Nodes in the SymmetricDS Pro web console.

If you disabled auto.reload or auto.reload.reverse in Step 4, restore their original values after registration is complete.

  1. Perform an initial load if needed

If the node was not fully caught up before the switch, trigger an initial load to or from the affected node to restore any data that was lost when the H2 database was abandoned.

Troubleshooting

Node fails to connect to the runtime database
Verify the host, port, database name, and credentials in the db.url, db.user, and db.password parameters. Confirm that the database service is running and that the SymmetricDS host is permitted to connect.

Permission denied when creating tables
Refer to Appendix C of the SymmetricDS User Guide for the required database permissions for your platform.

Data is missing after the switch
The runtime database was re-initialized and unsent data was lost. If the node had unsent data at the time of the switch, perform an initial load to recover the missing data.

Reference: Runtime Database Properties

Property Description
db.driver Fully-qualified JDBC driver class name
db.url JDBC connection URL for the runtime database
db.user Runtime database username
db.password Runtime database password
db.validation.query Query used to validate the connection

See Also

  • Appendix C of the SymmetricDS User Guide: Database-specific configuration and required permissions for all supported platforms
  • Advanced Topics -> Encrypted Passwords section of the SymmetricDS User Guide: How to store database passwords in encrypted form
  • Manage -> Nodes -> Load data section of the SymmetricDS User Guide: How to trigger a full reload of data to a node

Properties ID: 000065   Views: 17   Updated: 5 days ago
Filed under: