Initializing a Replication Agent Instance

Initialize an instance of Replication Agent, and create the objects it needs in the primary database.


The Replication Agent instance must be running, and connectivity to the primary database must be established.

  1. Log in to the Replication Agent instance with the administrator login.
  2. Determine whether objects associated with this Replication Agent instance already exist in the primary database:

    If no Replication Agent objects exist, the ra_admin command returns no information. Continue this procedure to initialize Replication Agent. This procedure also creates objects in the primary database that support replication.


    The ra_admin command looks for Replication Agent for Microsoft SQL Server and Replication Agent for UDB objects based on the value of the ra_admin_instance_prefix configuration parameter and for Replication Agent for Oracle objects based on the value of the ra_admin_prefix parameter. If the value of the ra_admin_instance_prefix or ra_admin_prefix parameter changes after a transaction log was created, the ra_admin command cannot find the previously created objects.

    If Replication Agent objects exist in the primary database, the ra_admin command returns a list of objects.

    If objects exist for the Replication Agent instance, you do not need to complete this procedure.

  3. To use a particular string for the database object name prefix of the transaction log components, use the ra_config command to set the value of the ra_admin_instance_prefix (Microsoft SQL Server and UDB) or ra_admin_prefix (Oracle) parameter:
    ra_config ra_admin_instance_prefix, XXX

    where XXX is a one- to three-character string that is to be the new value of the ra_admin_instance_prefix or ra_admin_prefix parameter, and the prefix string used in the database object names when the objects are created. The default value is ra_.

    Note: The value of the ra_admin_prefix_chars parameter specifies the nonalphabetic characters that are allowed in the prefix string (the value of the ra_admin_instance_prefix or ra_admin_prefix parameter). The primary data server may restrict the characters that can be used in database object names. See the Replication Agent Primary Database Guide for information about which characters are available for which database.
    You can also use ra_config to determine the current value of the ra_admin_instance_prefix (Microsoft SQL Server and UDB) or ra_admin_prefix (Oracle) parameter:
    ra_config ra_admin_instance_prefix

    When you invoke ra_config and specify a configuration parameter with no value, it returns the current value of that parameter.

  4. If your Replication Agent has an RASD, you may have to quiesce the primary database.
    • (Replication Agent for Oracle) You can avoid having to quiesce the primary database if your replication system is configured for database resynchronization. For information on configuring database resynchronization, see the Replication Server Administration Guide.

    • (Replication Agent for Microsoft SQL Server) You must quiesce the primary database or otherwise prevent any DDL operations that can change the database objects or schema. Log in to the primary data server with a user login that has appropriate permissions or authority, and quiesce the primary database (or execute the commands necessary to prevent any DDL operations that change the database objects or schema).

    • (Replication Agent for UDB) No action is required because there is no RASD.

  5. Initialize the Replication Agent instance, and create its objects in the primary database.
    ra_admin init
    Note: When you invoke ra_admin with the init keyword, the command returns an error message if the Replication Agent objects (using the prefix string currently specified in the ra_admin_instance_prefix or ra_admin_prefix parameter) already exist in the primary database.
    When you invoke the ra_admin command with the init option, the Replication Agent:
    • Checks the primary database for compatible settings.

    • Generates a SQL script that is run in the primary database. This script creates the Replication Agent objects.

    For Replication Agents that use an RASD, the RASD is initialized with information from the primary database.

    Note: You can configure the Replication Agent to generate the script—but not execute it—by setting the value of the pdb_auto_run_scripts parameter to false before you invoke the ra_admin command. To complete the transaction log creation, you must set pdb_auto_run_scripts to true and re-run the ra_admin init command. This script is for informational purposes only. Executing it manually in the primary database does not initialize the Replication Agent instance.

If the initialization was successful, the script is stored in a file named partinit.sql in the scripts/xlog/installed directory.

If the initialization was not successful, the primary database is not changed, and the script is stored in a file named partinit.sql in the scripts/xlog directory. Check the Replication Agent error log and, if necessary, the primary database error log to determine why the initialization was not successful.

Related concepts
Replication Agent Connectivity Setup
Replication Agent Start-Up