SymmetricDS: Common Parameters and What they Do
SymmetricDS is a highly configurable open source database replication tool. Most of the “configurability” of SymmetricDS is via a parameter subsystem that allows users to tweak the behavior of the software to meet their synchronization use cases. Overall there are approximately 320 parameters in SymmetricDS that can be modified. The shear number of available parameters can be daunting. This article will outline common parameters that the SymmetricDS team sees tweaked most often. SymmetricDS newbies might want to read Keeping Database in Sync “Open Source Style.”
Parameters effect a SymmetricDS node. A SymmetricDS node is a participant in database synchronization that represents an individual database. Nodes communicate with either other to pass data back and forth for replication.
There are two basic types of parameters: startup and runtime parameters. Startup parameters must exist in a properties file that a SymmetricDS node reads in at application startup. Startup parameters require a restart to take effect. Runtime parameters are parameters that can exist in either the same properties file or in a configuration table called sym_parameter. The sym_parameter table is synchronized to other nodes. Parameters configured in this table override those found in a properties file and can target one or more nodes in a network.
All parameters have default values. The default values are documented in the user guide which is generated from a properties file that is part of the code base called symmetric-default.properties. The SymmetricDS development team attempts to provide reasonable default values in hopes that they will work for most use cases. Sometimes there are scenarios that require that they be tweaked.
Startup Parameters
There are startup parameters that are required to define a node. Those are documented in the user guide and are fairly standard. All users of SymmetricDS should be very familiar with these values because they are required to configure a node.
One required parameter of note is db.url. This is the JDBC database url. SymmetricDS provides examples for recommended urls for supported databases. Users should be aware that all JDBC drivers have their own array of parameters that might or might not be relevant to your situation. Be sure to review the documentation for your JDBC driver and be aware of the different settings that are available.
Another set of startup parameters that might be relevant if your SymmetricDS deployment deals with many nodes are the db.pool.* settings. These are settings that are passed through to the DBCP database connection pool that SymmetricDS uses. The default settings are appropriate for SymmetricDS networks of several hundred nodes and have been tuned to work with a concurrent workload as dictated by http.concurrent.workers.max (20) and push.thread.per.server.count (10) and pull.thread.per.server.count (10).
SymmetricDS itself is a web server that communicates with other SymmetricDS nodes via HTTP/S. http.concurrent.workers.max dictates the number of concurrent http client threads that can synchronize with SymmetricDS. The two *.thread.per.server.count settings tell SymmetricDS how many concurrent client threads that will be allocated to push and pull data from/to unique server nodes. When these parameters are increased the db.pool.* parameters will also need adjusted. The more concurrent threads that are allowed to do work, the more database connections are needed. If a user had an under powered database they might scale back these parameters to allow less work to be done on the database concurrently thereby relieving the load on the database.
Another startup parameter that might need to be tweaked for a system under heavy load is db.sql.query.timeout.seconds. This parameter is the JDBC query timeout for all database tasks. If a query is executed by SymmetricDS and it takes longer than this parameter dictates then the query will be timed out by the software. The default timeout is 5 minutes. Note that many JDBC drivers have similar TCP/IP timeouts that might need to be adjusted as well.
Runtime Parameters
Some of the most frequent parameters that are modified are the parameters that control the schedule when different jobs run. The four most important jobs are the Route, Push, Pull and Purge Jobs. The routing job batches captured data. It runs every 10 seconds by default. Data is not available for synchronization until after this job runs. By default this jobs run periodically. All jobs follow a pattern where they can run on a cron schedule or periodically. The recommended “type” of schedule is the default. The job.routing.period.time.ms setting controls how frequent the routing job runs. This can be changed to a cron job by instead using the job.routing.cron setting. If a cron parameter is found it always takes precedence over periodic parameters.
The push and pull jobs are also periodic by default. It is a good idea to use periodic schedules for push and pull if there are many nodes in the SymmetricDS network. Scaling can better be achieved if the jobs run at random start times on a regular period versus all jobs on all nodes trying to do work at the same time on a cron schedule.
The default push and pull intervals are set to run every minute. Users frequently adjust job.pull.period.time.ms and job.push.period.time.ms. When a push or a pull occurs, the synchronization process will send batches according to the channel settings or up to transport.max.bytes.to.sync bytes of data of been sent. Sometimes users will have binary data that will require this parameter to be adjusted to a bigger value.
The purge job really is two different jobs. The incoming purge job and the outgoing purge job. The outgoing purge job usually has more work to do so it is the one that is tweaked more often. By default SymmetricDS keeps a retention of one days worth of captured data. The purge job runs by default at midnight according to the job.purge.outgoing.cron setting. The purge.retention.minutes setting controls how much data will be purged each run. The purge job only purges data that has been transmitted successfully.
In version 3.9 SymmetricDS was changed to keep previously extracted batches of data on the file system (called the staging area) until the batches have been purged from the database. This was done for convenience and to further relieve stress on the database by extracting once (when syncing to multiple nodes) instead of multiple times. A side effect of this was that more disk space was required when using the default purge settings. If a user runs into disk space issues sometime they will turn on purging of the staging area by the amount of time the staging files exist in the staging area instead of being controlled by the database purge settings. This is enabled by setting stream.to.file.purge.on.ttl.enabled to true. If this parameter is turned on then stream.to.file.ttl.ms controls the amount of time files in staging will be kept. Note that the job.stage.management.cron (once an hour) parameter controls how often attempts to purge the staging area will occur.
Registering a new SymmetricDS node requires manual intervention by default. Both registration and initial loading a new node can be automatic by setting auto.registration (false) and auto.reload (false).
Initial Load Parameters
There are a great number of parameters that affect how initial load will behave. As of version 3.8 a new version of initial load was turned on that extracts an initial load across multiple batches in the background. This allows multiple batches for bigger tables which enabled better initial load resiliency. The old initial load behavior of on the fly one batch per table per initial load behavior can be enabled by setting initial.load.use.extract.job.enabled to false.
The initial.load.block.channels (true) parameter indicates whether non-initial load channels should be sent while and initial load is a in progress. The initial.load.unblock.channels.on.error (false) parameter indicates whether other channels should be unblocked if an initial load errors out.
Wrap Up
While a great number of common parameters have been covered there are still a lot more than can be used to adjust the behavior of a SymmetricDS deployment. It is a good idea to read through the manual to become familiar with what options are out there. Questions can be posted at the open source forums.
