Replication Deployment

A Look at the Tasks Involved in Replication Deployment

This chapter gives a brief tutorial example for how to deploy a database for replication between two machines. The chapter contains the following sections:

Deployment Process

Working with the Demodata Sample Database

Working with Your Database

The procedures in this tutorial are covered in more detail in Pervasive DataExchange User’s Guide.

Deployment Process

This chapter covers the simple deployment process to prepare your database for real-time backup between two machines. The process combines the use of the DataExchange utility DXdeploy and a file copying task that you perform manually.

The deployment process has four steps:

1	Edit the XML deployment descriptor file used by the DXdeploy utility.

2	Run DXdeploy on the First Site, specifying the XML descriptor file as a parameter.

3	Copy the replication-enabled files from the First Site to the Partner Site.

4	Run DXdeploy on the Partner Site, specifying the same XML descriptor file used for the First Site.

An optional fifth step involves setting up a replication schedule with DataExchange Manager.

The easiest way to understand the process is to perform an example deployment using the sample database Demodata. The example concentrates on what to do. You can then learn about why you perform certain actions by reading Working with Your Database.

Tip The deployment process described in this chapter can also be performed using the DataExchange Deployment Wizard. The Deployment Wizard is an interactive and automated method for quick and easy replication deployment.

Working with the Demodata Sample Database

This section describes how to deploy the sample database Demodata for replication. Demodata is provided with both Pervasive PSQL Server and Workgroup.

The procedures in this section present do not explain why you do things so that you can concentrate on what to do. The intent is to quickly deploy Demodata for replication. After you’ve seen what to do, read the next section, Working with Your Database to understand the why.

This section presents two procedures, each with several tasks:

Deploying Demodata for Replication

Task 1: Edit the XML descriptor file

Task 2: Run DXdeploy on the First Site

Task 3: Verify deployment on the First Site (optional)

Task 4: Copy the Template to the Partner Site

Task 5: Run DXdeploy on the Partner Site

Removing the Example Deployed Database

Task 1: Deactivate the example database on both sites

Task 2: Run Template Remover on the First Site

Task 3: Delete files on the First Site

Task 4: Delete the example database and files on the Partner Site

Since this deployment is only an example, you will not set up a replication schedule.

Note Pervasive PSQL contains security models for Btrieve applications. This section assumes that you deploy Demodata on sites with the Classic security model (the default model).

If DefaultDB uses either the Mixed or Database security model, you must ensure that Demodata can be deployed. The easiest way to do this is to temporarily remove the password for DefaultDB on each site for which security is set.

To do so, in PCC right-click DefaultDB and select Properties. Click the Security tab, select the checkbox Disable database security, and click Apply. If you’re not logged in to DefaultDB, provide the master password. Click OK. Remember to reenable security for DefaultDB after you complete the example deployment.

If you want to retain security and deploy Demodata, see Pervasive PSQL Security in Pervasive DataExchange User’s Guide.

Deploying Demodata for Replication

Before you work through this example, be sure you’ve already installed both a First Site and a Partner Site (backup site) as explained in Installing Pervasive DataExchange:

You will perform the following tasks for this example:

Task 1: Edit the XML descriptor file

Task 2: Run DXdeploy on the First Site

Task 3: Verify deployment on the First Site (optional)

Task 4: Copy the Template to the Partner Site

Task 5: Run DXdeploy on the Partner Site

Tip So that you can restore Demodata to its original state after this deployment exercise, we recommend saving a copy of the database files before proceeding with this example.

Task 1: Edit the XML descriptor file

1	On the First Site machine, open the folder C:\<Installation Directory >\Replication\Docs.

2	Open the XML descriptor file EXPRESS.XML in a text editor.

The file should resemble the following (comments excluded):

<?xml version="1.0"?>

<DXDeployment>

  <Configuration Project="DXProj" Network="DXNet"
   Release="1.0" Method="1-way">

    <Sites>

      <First
        ServerName="this.hostname"

        DSN="DXDatabase"

        DataDirectory="C:\MYDATA">

          <Files>

            <Include Path="*.mkd" />

            <Include Path="*.btr" />

            <Include Path="*.dat" />

            <Include Path="*.ddf" />

          </Files>

      </First>

      <Partner

        ServerName="remote.hostname"
        DSN="DXDatabase"
        DataDirectory="C:\MYDATA" />

    </Sites>

  </Configuration>

</DXDeployment>

3	Save EXPRESS.XML as ExampleRTB.xml.

You may save the file to the location you choose on your First Site machine. This example uses C:\<Installation Directory >\Replication\Docs.

4	Specify the machine name or IP address of your First Site. “Localhost” is not permitted as the machine name.

For example, if the name of your First Site is db_server1:

      <First
        ServerName="db_server1"

5	Specify the root directory path to the data files on the First Site.

For First Servername, change DataDirectory="C:\MYDATA"> to DataDirectory="C:\<Installation Directory >\Demodata">.

The information should read something similar to the following:

      <First
        ServerName="db_server1"
        DSN="DXDatabase"
        DataDirectory="C:\<Installation Directory >\Demodata">

 

Because this is just an example, leave the DSN as DXDatabase.

6	Specify the path to the data files that you want to replicate.

The Demodata data files contain a file extension .mkd. Therefore, keep the line <Include Path="*.mkd" />.

7	Delete the following lines:

            <Include Path="*.btr" />

            <Include Path="*.dat" />

 

Because Demodata has data dictionary files (DDFs), keep <Include Path="*.ddf" />. Typically you want to replicate DDFs. Note that the DSN created by DXdeploy does not use Demodata DDFs but uses its own in replication.

8	Specify the machine name or IP address of your Partner Site.

Change remote.hostname to your site name or IP address. For example, if the Partner Site machine is db_server2:

      <Partner
        ServerName="db_server2"

9	Specify the absolute path to the root directory of the data files on the Partner Site.

For partner server name, change DataDirectory="C:\MYDATA" /> to DataDirectory="C:\Demodata" />.

The information should now read something like the following:

      <Partner
        ServerName="db_server2"
        DSN="DXDatabase"
        DataDirectory="C:\Demodata" />

 

Note The data directory on the Partner Site could be C:\<Installation Directory >\Demodata if you want to overwrite the sample database. This example uses a different directory to preserve the Demodata sample database as installed by Pervasive PSQL.

10	Save and close the file ExampleRTB.xml.

Task 2: Run DXdeploy on the First Site

1	Open a command prompt on the First Site and type the following. The string is case-insensitive.

DXdeploy /Site=First C:\<Installation Directory >\Replication\Docs\ExampleRTB.xml

2	Press Enter.

As it runs, DXdeploy displays high-level status messages:

Starting the CreateDSN action

Starting the Design action

Starting the Activate action

Activation done, now synchronizing tables

More detailed messages are written to dxdeploy.log, located in the folder <Installation Directory >\Replication\LogFiles. To view these messages on-screen while DXdeploy runs, you can use the /LOGFILE= option. For example, DXdeploy /Site=First /LOGFILE= ExampleRTB.xml. A space follows the equal sign after LOGFILE=.

DXdeploy is complete when the command prompt reappears and when it enters the following message in the log file:

"Successfully completed all deployment actions."

Task 3: Verify deployment on the First Site (optional)

You can visually verify that deployment has succeeded.

1	Start PCC if it is not already running. (Select Control Center & Documentation from the operating system Start menu or Start screen.)

The name of the First Site appears under the Engines branch.

2	Expand the First Site branch and its list of databases.

DXDatabase is listed as a database.

3	Expand the DXDatabase branch.

The “A” icon shown on its Replication node indicates that the database is activated.

Figure 4-1 DXDatabase Activated on First Site

Task 4: Copy the Template to the Partner Site

After DXdeploy completes on the First Site, do the following:

1	From the First Site, copy the file C:\<Installation Directory >\Replication\Docs\ExampleRTB.xml to the same folder on the Partner Site.

2	On the Partner Site, create a folder C:\Demodata

3	Copy the contents of the First Site folder C:\<Installation Directory >\Replication\Templates\DXDatabase to C:\Demodata on the Partner Site.

Note Demodata files reside in a relative location that can be wherever you choose on the Partner Site. Your application may require absolute paths to certain data files. See File Copying for details.

Task 5: Run DXdeploy on the Partner Site

1	Open a command prompt on the Partner Site and type the following. The string is case-insensitive.

DXdeploy /Site=Partner C:\<Installation Directory >\Replication\Docs\ExampleRTB.xml

2	Press Enter.

As it runs, DXdeploy displays high-level status messages:

Starting the CreateDSN action

Starting the Design action

Starting the Activate action

Activation done, now synchronizing tables

More detailed messages are written to dxdeploy.log, located in the folder <Installation Directory >\Replication\LogFiles. To view these messages on-screen while DXdeploy runs, you can use the /LOGFILE= option. For example, DXdeploy /Site=Partner /LOGFILE= ExampleRTB.xml. A space follows the equal sign after LOGFILE=.

DXdeploy is complete when the command prompt reappears and when it enters the following message in the log file:

"Successfully completed all deployment actions."

When DXdeploy runs on the Partner Site, it also performs an initial replication between the First Site and the Partner Site. The initial replication populates the data on the Partner Site so that it is the same as on the First Site.

Congratulations! You’ve successfully deployed Demodata for replication.

Removing the Example Deployed Database

You do not need to keep the example deployed database. The following tasks explain how to remove it from the First Site and the Partner Site.

Task 1: Deactivate the example database on both sites

Task 2: Run Template Remover on the First Site

Task 3: Delete files on the First Site

Task 4: Delete the example database and files on the Partner Site

Task 1: Deactivate the example database on both sites

1	On the First Site machine, open a command prompt.

2	Type DXdeact DXDatabase

The command string is case-insensitive.

3	Press Enter.

The example database on the First Site is now deactivated.

4	Repeat these steps at a command prompt on the Partner Site.

Task 2: Run Template Remover on the First Site

1	On the First Site, do one of the following:

Select DX Template Remover from the operating system Start menu or Apps screen.

In PCC, select DataExchange  Template Remover.

The Template Remover Wizard displays its welcome dialog.

2	Click Next.

Template Remover asks you to choose a template to remove.

3	In the templates pane, click LOCAL:DXDATABASE.

4	Select Remove DataExchange System Tables and click Yes in the warning message to confirm that you wish to continue.

5	Select Remove DSN and database name.

The wizard should now resemble the following:

6	Click Next.

The wizard removes the template and presents a summary.

7	Click Close.

Task 3: Delete files on the First Site

1	On the First Site, find the DX_projectname directory under C:\<Installation Directory >\Demodata that was created during deployment.

DX_projectname is the name given to your replication project in the XML deployment file, in this case DXProj in the following line in ExampleRTB.xml:

<Configuration Project="DXProj" Network="DXNet" Release="1.0" Method="1-way">

2	Delete the folder \<Installation Directory >\Demodata\DX_DXProj.

3	Delete the DXDatabase folder under C:\<Installation Directory >\Replication\Templates.

Task 4: Delete the example database and files on the Partner Site

1	On the Partner Site, start PCC if it is not already running. (Select Control Center & Documentation from the operating system Start menu or Start screen.)

2	In the database list, right-click DXDatabase and select Delete.

A dialog box asks you to confirm the deletion.

3	Click Yes.

A dialog box asks you to confirm DSN removal.

4	Verify that DXDatabase is the database name selected.

5	For the option Always remove associated DSN entries, do one of the following:

To keep the database you were replicating, leave the checkbox clear.

To delete the database you were replicating, select the checkbox.

6

Click OK.

DXDatabase is removed from the database list in PCC.

7	To complete removal of the deployed replication database on the Partner Site, delete the directory C:\Demodata. This was the directory created in Task 4: Copy the Template to the Partner Site.

Working with Your Database

The Demodata example demonstrated the four-part deployment process:

1	Edit the XML deployment descriptor file that is used by the DXdeploy utility.

2	Run DXdeploy on the First Site, specifying the XML descriptor file as a parameter.

3	Copy the replication-enabled files from the First Site to the Partner Site.

4	Run DXdeploy on the Partner Site, specifying the same XML descriptor file used for the First Site.

This section discusses the process in more detail so that you can apply it to your own database. Before beginning the process, however, you need to determine which tables to replicate and ensure that they can be replicated.

What to Determine First

To deploy a database for replication, you need first to determine the following:

Decide which tables in which database(s) should be replicated

Ensure tables to be replicated contain system data and key

Which Tables To Replicate

Determine which tables need to be replicated. Consider any situations in which tables created dynamically also need to be replicated. See Adding Dynamic Tables to an Activated Database, in Pervasive DataExchange User’s Guide.

You specify the tables to be replicated in the XML deployment descriptor file. See XML Deployment Descriptor File.

System Data and Key

For real-time backup replication, DataExchange requires that each table to be replicated has a unique system key. The replication control tables track changes by using the unique keys.

You may use the Pervasive PSQL utility Butil to determine if a table contains system key and data. For example, suppose you want to check table mytable.mkd located in c:\mydata. You would enter the following on a command line:

butil -stat c:\mydata\mytable.mkd

Among other information, the statistics output informs you about system data and key. If the output shows that System Data = Yes and SYSKEY Status = Present, then system data and key is present.

If the existing database does not have system keys, you must add system data and keys with the Pervasive PSQL Rebuild utility. Refer to the Rebuild Utility chapter in the Pervasive PSQL Advanced Operations Guide.

Pervasive PSQL Security

Pervasive PSQL provides security models for Btrieve applications. However, the activated databases created by DXdeploy do not contain security, even if the source database does. You may add security to a replication database if you choose. See Pervasive PSQL Security in Pervasive DataExchange User’s Guide. For more details, see also the chapter on Pervasive PSQL Security in the Pervasive PSQL Advanced Operations Guide.

XML Deployment Descriptor File

The XML deployment descriptor file is a text file in which you specify information for the DXdeploy utility. For real-time backup between two machines, you use the descriptor file EXPRESS.XML. This file is located in the \<Installation Directory >\Replication\Docs folder.

You must edit the XML file for your situation. The following table explains the attributes in the XML file that may require editing. The default value for some of the attributes may be adequate as is. With the exception of Exclude Path, DXdeploy requires all of the attributes. DXdeploy is further discussed in Pervasive DataExchange User’s Guide. See dxdeploy.

 

Table 4-1

XML Attributes in Deployment Descriptor File

XML Attribute	Discussion
Project	A replication design requires that you provide names for the replication project, replication network, and the project release. These names are of your own choosing to help you identify your replication setup. Project often corresponds to a specific database. If your goal is to replicate a database named mydatabase, then you may want to call the project mydatabase project or something similar that helps you remember which database is involved. Note that the three names—project, network, and release—are added to a replication system database used by the replication engine. The replication utilities also use these names to allow or disallow certain actions. For example, designed databases that differ only by release are allowed to replicate together. The project names and network names must match to allow replication.
Network	The replication network is the grouping of replication sites that participate in replication. A name that helps you remember the grouping is very useful. For example, if machines A and B participate, you could name the network Sites A and B or something similar.
Release	The release is like a version number for the design of the replication database. Your first design could be version 1, for instance. If you choose to change the design later, then you would create a version 2 and so forth.
Include Path	This attribute specifies the files to deploy for replication. At least one Include Path attribute is required. The following properties apply to this attribute: • Relative paths are relative to DataDirectory listed in the <Sites> section of the XML file. • Absolute paths, if specified, must all start with the same drive letter, which must be the same drive letter specified by DataDirectory. • Paths must specify files, individually or by wildcard. The “?” and “*” wildcard characters are permitted. • Subdirectories must be explicitly listed in the paths (DXdeploy does not automatically process subdirectories from a given root). • Multiple attribute lines are permitted.
Exclude Path	This attribute specifies which files, among the included files, to exclude. The same properties apply as for Include Path.
First Servername	This attribute specifies the machine name or IP address of the First Site. "Localhost" is not permitted.
DSN	This attribute specifies the data source name (DSN) to be associated with the data files deployed for replication. The DSN must be unique on each site.
DataDirectory	This attribute specifies the root for relative paths in Include Path and Exclude Path. DataDirectory must begin with a drive letter. DataDirectory in First Servername applies to the First Site. DataDirectory in Partner Servername applies to the Partner Site.
Partner Servername	This attribute specifies the machine name or IP address of the Partner Site. "Localhost" is not permitted.

DXdeploy Utility on First Site

After you edit the XML descriptor file, you run the DXdeploy utility on the First Site. The utility creates a template of the source data files. (Hereafter, for ease of discussion, the source data files will be referred to collectively as the source database.)

A template is a special type of database specifically for use with the replication tools. It contains various types of control tables used for replication. A template may also contain the data from the source database. DXdeploy creates a template without source data. (In step four of the deployment process, the source data gets replicated from the First Site to the Partner Site.)

You use a template to activate a database. Activation is the process of enabling a database for replication and establishing it as belonging to a site. DXdeploy also activates the source database on the First Site.

The following table explains where DXdeploy places the deployment files.

Table 4-2

Location of Activated Databases and Templates

Activated Database

Template

An activated database is placed in a folder named DX_projectname, which is subordinate to the source database folder. For example, suppose your source database is located at C:\myfolder\mydatabase, and you named your project myproject. The activated database is placed in C:\myfolder\mydatabase\DX_myproject. Your source database is not altered.

All templates are placed in the <Installation Directory >\Replication\Templates folder. For example, if your activated database is named mydatabase, and its DSN is named mydbdsn, the template occupies the following folders: • <Installation Directory >\Replication\Templates\ mydbdsn — This folder contains the empty data files produced from the source data files. The empty files are considered part of the template. Also in this folder is a copy of the XML descriptor file. • <Installation Directory >\Replication\Templates\ mydbdsn\DX_myproject — This folder contains the remaining replication-enabled files, such as the control tables.

Note The activation process performed by DXdeploy may take from a few minutes to several hours depending on the size and number of data tables involved. However, you may proceed with the next step, copying the template files to the Partner Site, as soon as DXdeploy finishes creating the template.

Check for the following message on the screen: “Starting the Activate action . . .” After this message appears, you may copy the template files to the Partner Site. Typically, the template is created quite rapidly, even for a large number of data files.

File Copying

After DXdeploy creates the template on the First Site, you must manually copy the template to your Partner Site.

Example of What to Copy Where

DXdeploy creates template directories to help you determine where to copy the files on the Partner Site. For example, suppose your application’s DSN is mydbdsn and its database name is mydatabase. Mydatabase uses four data files located as follows on your First Site:

C:\myapp\data\table1.mkd

C:\myapp\data\table2.mkd

C:\myapp\data\other\table3.mkd

C:\employees\accting\table4.mkd

Your edited XML descriptor file would resemble the following:

<First
  ServerName="db_server1"
  DSN="Mydbdsn"
  DataDirectory="C:\myapp\data" >
    <Files>
     <Include Path="*.mkd" />
     <Include Path="other\*.mkd" />
     <Include Path="c:\employees\accting\table4.mkd"/>

The first and second Include Path statements are relative to DataDirectory. Assume that table4.mkd is a bound table and must be located at C:\employees\accting. It requires an absolute path.

Given this example, the following table explains where on the Partner Site you would copy the template files.

Directory on First Site	Contents	Where to Copy on Partner Site
\<Installation Directory >\Replication\ Templates\mydbdsn\ mydatabase\DX_myproject	Empty data files table1.mkd, table2.mkd, and table3.mkd The edited XML descriptor file DX_projectname subdirectory: <Installation Directory > Replication   Templates     mydbdsn       mydatabase          DX_projectname	Generally, to the same location as on the First Site. That is, to C:\myapp\data. However, the files can be located any where you choose provided that the location on the Partner Site matches the DataDirectory for Partner ServerName in the XML descriptor file. The DX_projectname subdirectory contains the remaining replication-enabled files, such as the control tables.
\<Installation Directory >\Replication\ Templates\mydbdsn\ mydatabase\c_drive\ employees\accting	Empty data file table4.mkd	C:\employees\accting

Note If you’ve installed your application on the Partner Site, its data files may already reside there. If so, overwrite them with the template files.

DXdeploy Utility on Partner Site

After the template is copied to the Partner Site and DXdeploy activates it on the First Site, activate the Partner Site. Run DXdeploy with the same XML deployment descriptor file used for the First Site. The edited file is found in the database directory under <Installation Directory >\Replication\Templates, which in the example above would be \<Installation Directory >\Replication\Templates\mydbdsn\mydatabase.

Caution DXdeploy must finish activation on the First Site before you run it on the Partner Site. On the First Site, check on-screen for the message: “Activation done, now synchronizing tables.” Once the message appears, run DXdeploy on the Partner Site.

Replication Schedule

After DXdeploy completes on the Partner Site, it performs an initial replication with the First Site. (DXdeploy must have completed on the First Site, also.) The initial replication between the sites fully populates the data tables on the Partner Site.

Following deployment, you may want to set up a replication schedule to initiate replication. A replication schedule periodically keeps the Partner Site data concurrent with the First Site data. See Schedule Tasks in Pervasive DataExchange User’s Guide for how to set up a replication schedule.

Note Ensure that you set up the schedule on the First Site. That way, data flows from the First Site to the Partner Site.

Disaster Recovery

If your First Site is catastrophically destroyed, you may restore your data from the Partner Site to a new First Site and reestablish your replication network. See Disaster Recovery in Pervasive DataExchange User’s Guide.