This is a first stab at a HowTo for FiBRE - the FireBird Replication Engine. This documentation is still very beta. Comments and patches are appreciated. Send them to rjmunro@users.sourceforge.net.
There are 2 mailing lists available, hosted at sourceforge. See http://fibre.sf.net/lists for the mailing list archives and to subscribe / unsubscribe.
It is assumed that you have a working knowledge of the FireBird database and tools for manipulating data etc. This document does not cover installing or operating the database system. You will also need an up to date Java Runtime Environment (JRE) installed, 1.4 or later. You can download this from http://java.sun.com/. You will need to install the "JayBird" JDBC driver for FireBird on your Java classpath. This can be downloaded from here, where it is called "firebird-jca-jdbc-driver". The easiest thing to do is to put it in the lib/ext folder of your JRE. See the documentation that comes with it for more details.
The main download page is http://fibre.sf.net/download. Unpack the file to a new folder on your system (c:\fibre is recommended for windows users). This folder will be referred to as the FiBRE root folder from now on in this document. You should find the following files included:
That's all you need to do to install the system. To check that it has installed properly, you can change to the directory that you have unpacked FiBRE to, and reproduce the following (the red text is the part you have to type):
C:\fibre\>fibre
No arguments specified
Usage:
fibre AddTables|AddPartitionedTables|AddTriggers|Export|Import|Help
[config file] [more arguments]
For full details type FiBRE help
C:\fibre\>fibre help
[large amount of help text]
|
If you cannot replicate this, there is probably a problem with your Java installation. E-mail rjmunro@users.sourceforge.net to report problems.
The first thing you will need to do is prepare the database you are going to replicate. The first time you try FiBRE, the best thing to do is to use the supplied sample-database.sql script. Use your favorite admin tool to create a database on your system (I called mine c:\fbdata\test.fdb), connect to it, and then run the script and it will create a simple 3 table database from which you can start replicating. For details of how to get an existing database ready for replication, see Appendix A.
You will need to add a user to your database called FIBRE. This is the user that FiBRE itself uses to read and write data to the database in normal operation.
Copy the file fibre-primary-sample.cfg.xml from the examples directory into the FiBRE root folder, and rename if fibre.cfg.xml. Open it with your favorite text or XML editor. Hopefully it's content should be fairly self explanatory.
In the <Database> section, change the <URL> to be the JDBC URL of your database. You probably only need to change the part after "localhost" to the path of the database file on your system. Change the <Password> to be the password of the FIBRE user that you created before. Changing the user name is not currently supported. No database drivers are currently supported, other than JayBird (org.firebirdsql.jdbc.FBDriver). In future versions, other databases may be supported, including heterogeneous operation.
In the <ThisServer> section, change the <Name> to be a name for your primary database server. This can be any arbitrary name for the server within the FiBRE system. It does not have to be the database server's host name or anything. You can also change the folders used for the import and export of data if you want.
You are now ready to add the FiBRE tables to your database. Make sure that you close any connections to the database from admin tools etc., then type the following:
C:\fibre\>fibre addtables fibre.cfg.xml [SYSDBA password] Adding FiBRE$ tables... Populating FiBRE$ tables... Done. |
This will add the following tables to your database:
Add the name of this server, as written in the config file, and the names of other servers you will be replicating with to the FiBRE$Servers table, using your favorite FireBird database admin tool. Give each server an integer ID. Leave the URL field null - This is for use by a future version of the system.
Next you need to edit the FiBRE$Tables table. You need to remove any tables that you don't want to be replicated, e.g. any that store data specific to that server, or any lookup tables that never change. You also need to change the order so as to reduce foreign key errors. The lowest numbers will be inserted first and deleted last, so these should be the parent records of the other tables. If you are using the example database, change the order for the address table to 4 and change the order of the person table to 1, so that the order goes PERSON, COMMUNICATION, ADDRESS. Note that you cannot have two tables with the same value in the order field, but you can leave gaps.
You can now add the logging triggers to the database. Again, make sure that you close any connections to the database from admin tools etc., then type the following:
C:\fibre\>fibre addtriggers fibre.cfg.xml [SYSDBA password] Adding triggers... Done. |
As soon as you have done this, you should take a backup of your database that you can use to make secondary servers. Keep this backup in a safe place.
To configure the database of a secondary server, you should restore the backup that you made while configuring the primary server. On the restored database, you will need to run the following SQL statements:
SET GENERATOR "ID" 10000000; SET GENERATOR "FiBRE$ChangeID" 10000000; |
These are needed to make sure that the secondary server does not generate IDs that clash with the primary server. Note that you will need to use a different number for each secondary server, if you have more than one.
A secondary server will also require the fibre program to be unpacked somewhere in its folder structure, and you will need to copy examples/fibre-secondary-sample.cfg.xml as fibre.cfg.xml in the FiBRE root folder, and edit it with the servers name and the URL of the database as before. You also need to put the name of the primary server in the <Primary> tag.
The database is now ready to be replicated, and you can start entering and editing data. If you are using the sample database, you can use the script exampledata.sql from the examples folder to populate a few entries on the primary server.
Exporting the changes from the primary database is as simple as typing:
C:\fibre\>fibre export fibre.cfg.xml [secondary server] Reading info about servers... Reading info about previous exports... Recording this export... Building export packet header... Removing unneccesary changes... Marking changes to be exported... Updates, BlobUpdates, Deletes, Inserts Reading list of tables... Processing table "[Table Name]"... Updates, Deletes [Repeat for all the tables] Processing table "[Table Name]"... Inserts Done. |
Where [secondary server] is the name of one of the servers that you have defined in the FiBRE$Servers table. This will generate a folder with the name of the secondary server in c:\fibre\outgoing, and put a file in that folder with the changes to the database. You now need to copy this file to the c:\fibre\incoming folder on the secondary database (or whatever you configured in fibre.cfg.xml), and type:
C:\fibre\>fibre import fibre.cfg.xml Importing [filename] Done |
On the secondary database, you can leave out all the parameters after the word "import" or "export" as it can only export to one place.
Changes that could not be imported due to database conflicts (or other reasons) are stored in a file in the folder specified with the <LogFolder> tag in the config. An application to process these files is currently being written that will be able to fix the conflicting data in the system.
The database needs a genrator and a domain called ID. The domain should be defined as numeric(18,0) as this forces the database to use 64 bit integers internally, which leaves plenty of numeric space for IDs from different servers, but does not take too much storage space.
Every table needs to have a field called ID, of domain ID, that is a unique row identifier across the whole system. It is sensible to also use this as the primary key. If this field is left null on an insert operation, it's value is filled from the ID generator by FiBRE's triggers. FiBRE uses this field to track rows in the database, so the value of it cannot be changed. FiBRE's update triggers will prevent this from happening.
© 2003 Viva Network
$Id: howto.html,v 1.3 2003/06/23 20:36:38 rjmunro Exp $