Configuring and running the EDB DMS agent v1.4.1 (LTS)

The EDB DMS agent connects to your Postgres source and works with the Data Migration Service (DMS) to perform data migrations. Before running it, create migration credentials in HM and configure the agent with your source database details.

Prerequisites

• Ensure the machine where you're running the DMS agent has Java/OpenJDK 17 or later installed.

• Install the EDB DMS agent.

Creating migration credentials

Migration credentials authenticate the DMS agent to Hybrid Manager (HM). You need one set of credentials per HM project.

1. In the HM console, select the project you're using for your migration.

2. Select Migrate > Credentials.

3. Select Create Migration Credential, enter a name, and select Create Migration Credential. A credentials.zip file is downloaded to your machine.

   Note

   Store the credentials safely. If you lose them, you'll need to revoke this set and create new ones.

4. Unzip the downloaded file and copy the credentials folder to the machine where you installed the DMS agent — for example, to $HOME/credentials/. If you use a different path, update CREDENTIAL_DIRECTORY_PATH in the script to match.

   The folder contains:

   • int.crt
   • int.truststore.p12
   • client.keystore.p12
   • client-key.pem
   • client-cert.pem

Configuring the DMS agent

1. Open /opt/cdcagent/run-cdcagent.sh with write permissions.

2. Set the required variables. Optional parameters are commented out by default — uncomment and configure any that apply to your environment.

   See the parameter reference for details.

   Required for the Schema and data and Schema only migration scopes

   DBCONFIG_DATABASES_<N>__RESOURCEID is required if you plan to use the Schema and data or Schema only migration scope. The value must match the resource_id set for this database in the EDB Postgres AI agent's beacon_agent.yaml. Without it, HM can't resolve the Migration Portal project for the source database and the migration will fail.

   → WrapCopy

   #!/bin/bash -e
   # run-cdcagent.sh
   #
   # This script provides a convenient place to specify
   # environment variables used to configure the
   # EDB Data Migration Service Agent.
   #
   
   ##########################################
   # DMS Agent General Configuration       #
   ##########################################
   
   # This ID is used to identify DMS Agent
   # and is specified by the user.
   export DBCONFIG_ID=<source_name_of_choice>
   
   # Determine the run mode of the DMS Agent
   # The run mode can be set to either 'reader' or 'writer'
   # 'reader' mode is used to read changes from a source database
   # 'writer' mode is used to write changes to a target database
   export RUN_MODE=reader
   
   # This is the DMS backend service used by the Agent
   # Obtain this value from the HM console Sources or Destinations migration pages
   export RW_SERVICE_HOST=<rw_service_host>
   
   ##########################################
   # DMS Agent TLS Configuration           #
   ##########################################
   
   # You need to create migration credentials in EDB Postgres AI platform
   # and set the path of the credentials directory
   export CREDENTIAL_DIRECTORY_PATH=$HOME/credentials
   
   ##########################################
   # DMS Agent DB Configuration            #
   ##########################################
   
   # A sample configuration to create a single Postgres database connection:
   export DBCONFIG_DATABASES_0__TYPE=POSTGRES
   export DBCONFIG_DATABASES_0__HOSTNAME=<localhost/host>
   export DBCONFIG_DATABASES_0__PORT=<5432>
   # The CATALOG is the database name
   export DBCONFIG_DATABASES_0__CATALOG=<source>
   export DBCONFIG_DATABASES_0__USERNAME=<postgres>
   # The password env can be set without specifying it here
   # but the env structure looks like this
   export DBCONFIG_DATABASES_0__PASSWORD=<password>
   # Required for 'Schema and data' or 'Schema only' scope.
   # Must match resource_id in beacon_agent.yaml.
   #export DBCONFIG_DATABASES_0__RESOURCEID=<resource_id>
   
   # You can increase the index to configure more than
   # one database for the DMS Agent
   #export DBCONFIG_DATABASES_1__TYPE=POSTGRES
   #export DBCONFIG_DATABASES_1__HOSTNAME=<localhost/host>
   #export DBCONFIG_DATABASES_1__PORT=<5432>
   #export DBCONFIG_DATABASES_1__CATALOG=<source>
   #export DBCONFIG_DATABASES_1__USERNAME=<postgres>
   #export DBCONFIG_DATABASES_1__PASSWORD=<password>
   #export DBCONFIG_DATABASES_1__RESOURCEID=<resource_id>
   
   ##########################################
   # Optional Parameters Below              #
   ##########################################
   
   # FIPS mode can be enabled by setting the FIPS_MODE env variable to true
   #export FIPS_MODE=true
   
   # Configure logging
   # Loglevel for the entire Quarkus application and underlying components
   # WARNING: Enabling this loglevel is extremely verbose
   #export QUARKUS_LOG_LEVEL=DEBUG
   # Loglevel for the EDB package
   # Preferred mode for debugging issues related to the logic of the agent
   #export QUARKUS_LOG_CATEGORY__COM_ENTERPRISEDB__LEVEL=DEBUG
   
   cd "$(dirname "$0")"
   
   echo "Starting in mode: $RUN_MODE"
   
   case "$RUN_MODE" in
     reader)
       java -jar ./reader/quarkus-run.jar
       ;;
     writer)
       java -jar ./writer/quarkus-run.jar
       ;;
     *)
       echo "Unknown RUN_MODE: $RUN_MODE"
       exit 1
       ;;
   esac

Running the DMS agent

Navigate to the DMS agent directory and run the configuration script:

cd /opt/cdcagent
./run-cdcagent.sh

The script exports all required environment variables and starts the agent process. Once running, the agent registers your Postgres database as a source in HM. Continue to the next section to verify it appears correctly.

Verifying the source in HM

Once the agent is running, verify that your Postgres database appears as a source in HM:

1. In the HM console, select your project.

2. Select Migrate > Sources.

Your database is listed with its name, type, agent ID, and status. For a description of all fields on this page, see Sources.

Next step

Migrate your data