SymmetricDS Documentation

SymmetricDS is a Java-based, platform-independent, and database-agnostic platform designed for asynchronous data synchronization across distributed, heterogeneous database environments.

Key features include:

• Database Replication & File Synchronization: Synchronizes data across different database types.
• Resilience: Handles conflict resolution, bandwidth constraints, intermittent connectivity, and firewalls.
• Scalability: Supports horizontal scaling for massive data volumes and hundreds of nodes, including bi-directional replication.
• Editions:
  • Open Source: Provides the robust core foundation.
  • PRO Edition: Adds enterprise features such as a web UI for configuration/management, clustering support, bulk load performance, and enhanced security. It is backwards compatible with the open-source version.

Before publishing to Maven Central, you should test the publication process by publishing to a local repository. This creates a publishMymoduleToProjectLocalRepository task (replacing mymodule with your module name). The output is located in build/project-local-repository.

../symmetric-assemble/gradlew clean jar publishMymoduleToProjectLocalRepository

To work on this project using Eclipse, run the following command from the project root to generate the necessary Eclipse configuration files, then import the project via File -> Import -> Existing Projects into Workspace.

../symmetric-assemble/gradlew eclipse

To add a new module, you must define a new entry in the publications section of the build.gradle file. After defining the publication, place the resulting module JAR file into one of the following sub-directories:

• jdbc
• lib
• tools

Note: These sub-directories do not need to be checked into the code repository, but updating build.gradle is required to track active modules.

mymodule(MavenPublication) {
    artifact "build/assemble/mymodule-1.0.jar"
    groupId "org.jumpmind.symmetric.module"; artifactId "mymodule"; version "1.0"
    artifact tasks.named('sourcesJar'); artifact tasks.named('javadocJar')
}

To develop on SymmetricDS, you must have Java JDK 17 or later and Eclipse IDE installed. You can use the provided Gradle task to generate Eclipse projects for your workspace.

Follow these steps:

1. Navigate to the symmetric-assemble directory.
2. Run the ./gradlew develop command to generate the necessary Eclipse project files.

cd symmetric-assemble
./gradlew develop

If you need to compile the sym_udf library from source, the following files are provided:

Source Files:

• sym_udf.c: The C implementation of the user-defined functions.
• sym_udf.h: Header file containing function declarations.

Build Instructions by Platform:

• Unix/Linux: Run the provided build.sh shell script to compile and link the library.
• Windows: Use Microsoft Visual Studio to open and build the sym_udf.sln solution file or the sym_udf.vcproj project file. The sym_udf.def file is provided for DLL definition.

To use the SQL Explorer component in your Vaadin application, add the dependency to your build.gradle file. Note that including this component requires the Vaadin widgetset to be compiled, as it depends on other addons that necessitate widgetset compilation.

Ensure you have the necessary repositories configured, including the Vaadin addons repository.

repositories {
  mavenCentral()    
  jcenter()        
  maven { url "http://maven.vaadin.com/vaadin-addons" }
}

dependencies {
  compile 'org.jumpmind.symmetric:symmetric-sqlexplorer:3.9.x-SNAPSHOT'
}

To publish a module to the Sonatype Maven Central repository, run the clean, jar, and release tasks. Note that it can take between 10 minutes and an hour for the publication to become available. You can monitor the status at the Sonatype Portal.

../symmetric-assemble/gradlew clean jar publishMymoduleToProjectLocalRepository releaseMavenCentralPortalPublication

If you need to compile the sym_udf library yourself, the source files and build scripts are provided in this directory.

Source Files

• sym_udf.c: The C implementation of the user-defined functions.
• sym_udf.h: Header file containing function declarations.

Build Instructions by Platform

Unix/Linux

Use the provided shell script to compile and link the library:

./build.sh

Windows

Use Microsoft Visual Studio with the provided project files:

• sym_udf.sln: Solution file
• sym_udf.vcproj: Project file
• sym_udf.def: DLL definition file

bash
# Unix build command
./build.sh

The SQL Explorer is a component designed for Vaadin applications (used in Metl and SymmetricDS Pro). For a concrete implementation example, refer to the DemoUI.java source file, which demonstrates how to integrate and use the component within a Vaadin UI.

// See src/test/java/org/jumpmind/vaadin/ui/sqlexplorer/DemoUI.java for a full implementation example

To ensure SymmetricDS works properly with Interbase 9.0, you must install the sym_udf library. This library provides the sym_escape() and sym_hex() functions required by database triggers to escape strings and BLOBs.

Installation Steps

1. Copy the appropriate library file to the Interbase UDF folder:
   • Linux: Copy sym_udf.so to /opt/interbase/UDF
   • Windows: Copy sym_udf.dll to C:\CodeGear\InterBase\UDF
2. Start SymmetricDS. On its first startup, SymmetricDS will automatically attempt to enable the functions using the create external function command and verify they are working.

# Example for Linux
cp sym_udf.so /opt/interbase/UDF

# Example for Windows
copy sym_udf.dll C:\CodeGear\InterBase\UDF