.
Eloquence B.08.00 contact contact

Documentation / Database Backup

Database Backup

 
.
 

Contents


There are two supported procedures to perform a backup of the Eloquence database environment.

Off-line backup
The database server process is shut down in order to make a backup. Applications can no longer use the database until the backup is finished.

On-line backup
The backup is made while the database is active. Applications can access and modify the database. The Eloquence database supports on-line backup, allowing the database to be available during backup (at reduced performance).

Other backup procedures (besides the ones mentioned above) are likely to cause a corrupted backup or no backup at all (e.g. fbackup on HP-UX refuses to backup modified files).

In addition, there is a procedure to backup or restore a single database.

dbstore / dbrestore
The dbstore / dbrestore functionality allows transfer of a single database from a database environment to a file or tape device. This makes it easy to save a snapshot of a database or move a single database to another system.


Off-line backup

How to use off-line backup

An off-line backup takes place when the eloqdb is not active. You need to shut down the eloqdb process by either executing
  • /sbin/init.d/eloq8 stop on HP-UX
  • or /etc/init.d/eloq8 stop on Linux
  • or net stop eloqdb on Windows.

Note that "dbctl shutdown" does NOT wait until the requested eloqdb server shutdown has completed and is thus NOT suitable for backup scripting. In cases where you need to be sure the server has been stopped, before continuing, you must use the "eloq8 stop" command instead.

After the eloqdb server has been shut down you should consider to execute dblogreset before performing the backup. This resets the log volume to its minimum size and makes sure all transactions are applied.

If the database was not shutdown cleanly, the log volumes contain important data needed to recover the data base environment. Without the log information your databases may be lost. The dblogreset utility makes sure that the log information is applied to your data volume(s).

The backup should cover all data and log volumes which are part of the database environment. While it is possible to recreate a missing log volume if the server was shutdown cleanly (or dblogreset was executed) we do not recommend this.

Please note: The log volume(s) might contain important information (your data) and you should handle them with the same care as your data. Otherwise your database environment may become unusable.

Example backup script:

/sbin/init.d/eloq8 stop
/opt/eloquence/8.0/bin/dblogreset
tar -cf /dev/rmt/0m /data/db
/sbin/init.d/eloq8 start
This example performs a backup of the default database server environment. The eloqdb process is shut down, the log volumes are reset to initial state (optional), the volume files are backed up and the server process is restarted. This example assumes the volume files reside in the directory /data/db

Warning: Using fbackup on HP-UX to backup a database environment while the server is active will most likely not work and you may end up with no usable backup. Fbackup on HP-UX verifies that a file is not changed during backup and will take multiple attempts to backup the file. It will ultimately fail and the volume file is not backed up. Unless in on-line backup mode the eloqdb server may change the volume files at any time, even if no users are active.


How to recover from an off-line backup

To recover from an off-line backup, make sure the database server process is not active and restore all data and log volumes which are part of the database environment.

When recovering to a temporary location you may need to create a server configuration file (eloqdb.cfg) or modify an existing one. Please make sure the volume files in the configuration file refer to the recovered files.

If the log volumes are lost and your database was shut down cleanly, you can recreate any missing log volume with the dbvolextend command (see below).

Please note: If your database was not shut down cleanly and your log volume is lost your database may be damaged.


How to recreate your log volume(s)

If your log volumes are lost (e.g. due to a disk failure) and your database was shut down cleanly, you can recreate any missing log volume with the dbvolextend command.

The dbvolextend utility supports the -R command line option to conveniently recreate all missing log volumes in a single run.

For example:

dbvolextend -v -R

Since any previous log volume properties (like min. or max. size) are lost you may need to specify additional options to dbvolextend or use dbvolchange to modify the volume properties. You can use dbvoldump to display the volume information.

After the log volume(s) are recreated, you can start the eloqdb server process.


On-line backup

An on-line backup takes place when the eloqdb is active. The on-line backup is initiated with the dbctl backup start command which causes the eloqdb process to enter on-line backup mode.

When entering on-line backup mode, eloqdb creates a transaction consistent snapshot of the data volume(s) and makes sure the data volume(s) do not change during the backup. All changes to the data volume(s) are temporarily redirected to the log volume(s). The data volume(s) can then be backed up by an arbitrary backup tool (e.g. fbackup, tar, cp, etc.).

Once the backup is complete, the on-line backup mode is terminated by the dbctl backup stop command. This causes the eloqdb server process to update all pending data which was temporarily redirected to the log volume(s).

Please note: The eloqdb performance is reduced in on-line backup mode and the log volume(s) must provide sufficient space for all modifications during backup.

Log volumes do not need to (and should not) be backed up in an on-line backup. They are changing constantly and can not be used for recovery.

Please note: When using fbackup on HP-UX it is recommended to exclude the log volume(s) from the backup. Fbackup issues a warning note if a file is changed during backup. It may take multiple attempts to backup the log volume.

In case the eloqdb server is shut down during on-line backup mode (or a failure occurs) the data volume(s) are updated automatically when the server is restarted.


How to use on-line backup

Suppose you have data volume(s) located in the directory /db/data and log volume(s) located in the directory /db/log. Use the following commands to backup your data volume(s):
dbctl -u dba backup start
tar -cf /dev/rmt/0m /db/data
dbctl -u dba backup stop
Please note: You should consider to not backup your log volume(s) in on-line backup mode - they are not used to recover the database. They only take space on your backup media.

Please Note: If multiple eloqdb instances are active on one system, on-line backup must be activated for each database server environment separately.


How to recover from an on-line backup

To recover the database to the state when the on-line backup was started, please make sure the database server process is not active and recover the data volume(s) from the backup media.

It is recommended to remove and re-create any log volume(s). If the log volume is obtained from the backup or, is retained on disk when a backup stop has not been executed sucessfully since the backup, the log volume may be considered valid by the server process. This may result in a corruption of the volume files or an inconsistent recovery.

You may use dbvolextend to recreate your log volume(s).

The dbvolextend utility supports the -R command line option to conveniently recreate all missing log volumes in a single run.

For example:

dbvolextend -v -R

Since any previous log volume properties (like min. or max. size) are lost you may need to specify additional options to dbvolextend or use dbvolchange to modify the volume properties. You can use dbvoldump to display the volume information.

After the log volume(s) are recreated, you can start the eloqdb server process.


On-line backup and database utilities

Database utilities which modify the data volume can not be used immediately if the eloqdb server was shut down or crashed while in on-line backup mode. The log data (all committed transactions since entering on-line backup mode) has been temporarily stored in the log volume and must be recovered before database utilities are allowed to modify the data volume. Otherwise all transactions pending since starting the on-line backup would be lost.

The following message is output by the affected utilities:

NOTE: Database environment has been shutdown during 
      on-line backup. Please restart the database server 
      once in order to recover from on-line backup mode, 
      then reapply this command.
To recover the information from the log volume, please either run dblogreset or start the eloqdb server. Afterwards you can use the utility program as planned.

Affected tools are:

  • dbvolextend
  • dbvolchange
  • dbfsck (in write mode)
  • dbcfix (in write mode)


On-line backup and forward-logging

When on-line backup mode is activated and forward logging is active, a new log generation is started. In case the database server is configured to manage the forward log files, a new forward log file is created. This new forward log file covers all changes since the on-line backup has started. After the on-line backup has finished successfully, all previous forward log files (which existed before the on-line backup mode was started) can be removed as they are covered by the backup.


dbstore / dbrestore

The dbstore / dbrestore functionality allows transfer of a single database from a database environment to a file or tape device. This makes it convenient to save a snapshot of a database or move a single database to another system.

Please note: This is not a recommended strategy to backup your database environment for the following reasons:

  • The on-line backup and off-line backup methods presented above provide a consistent backup of your complete database environment which includes all your databases and additional configuration (users, passwords, database permission groups and user assignments).

  • In contrast, dbstore / dbrestore store or restore only single databases. If the databases contained in a database environment are related it is not easy to create a consistent backup with dbstore. Also, in case of a desaster it takes extra effort and time to restore a functional database environment with dbrestore.

  • A backup procedure that uses dbstore/dbrestore may not use forward-log files to perform a fast forward recovery. The forward-log files specify the changes since the last on-line backup or off-line backup. This functionality cannot be recreated using dbrestore / dbrestore.


How to use dbstore and dbrestore

The dbstore and dbrestore operation is executed by the database server and the archive files are written by the server process. The dbctl utility is only used to initiate the process.

Backup files are written to and read from pre-configured paths (called "server devices") to avoid unauthorized access to the server system. A "server device" could either be a single file, a directory or a device. When no server devices are configured, dbstore and dbrestore operation is refused by the server.

The example below defines two "server devices". The device "tape" points to a tape device file, the device "backup" points to a directory which is intended to hold the backup files.

[devices]
Tape = /dev/rmt/c1t0d0BEST
Backup = /data/backup
The dbctl utility is used to initiate a store or restore operation.
dbctl dbstore database target
dbctl dbrestore [/info] [/all] source [new_database_name]
The dbctl dbstore command transfers a single database to the target "device" which must be defined in the server configuration file. In order to store a database, database admin (dadmin) or server admin (dba) capabilities are required. Exclusive access to the database is required.

The target specification is either the name of a configured server device or the name of a server device and a filename separated by a slash.

Also see dbctl dbstore documentation for more info.

The dbctl dbrestore command restores a single database from a source device which must be defined in the server configuration file. The database may not already exist. Server administration (dba) capabilities are required in order to restore a database.

The source specification is either the name of a configured server device or the name of a server device and a filename separated by a slash. If the optional /info argument is present, information on the archive is returned and the archive is not restored.

If the optional /all argument is present, the association between database permission groups and server users ("sysmember") is retained. Usage of the /all argument is only safe if the database environment where the database is restored is the same or has identical server users as the environment where the database was stored.

If the optional new_database_name argument is present, the database is restored to the specified name instead of the original database name.

Also see dbctl dbrestore documentation for more info.


Limitations

Since dbstore copies the database to a binary archive, the archive occupies the same disk space as the database. The archive can only be restored to a system with the same byte order. For example, you cannot create an archive on Linux and restore it on a HP-UX system. You need to use dbexport/dbimport to move a database to a different architecture.

When a database is restored without the /all argument given, the association between database permission groups and server users ("sysmember") is deleted for all but the default "dba" and "public" users. Since the database could be restored on a different server this could otherwise lead to inconsistencies or unauthorized access to your data.


Saving a database with dbstore

Assumed you defined a server device "tape" in your server configuration file the command below dumps the database payrol to the tape device:
dbctl -u dba dbstore payrol tape
Assumed you defined a server device "backup" in your server configuration which refers to a directory the command below dumps the database payrol to the file payrol.bkup in the specified directory:
dbctl -u dba dbstore payrol backup/payrol.bkup


Using the standalone dbstore utility

The standalone dbstore utility is similar to the dbctl dbrestore command. The difference is that it allows to perform a dbstore operation when the database server is not active or while the database server is in on-line backup mode.

Another difference is that the database may be stored to any file, not only to the configured "server devices".

If the database server is in on-line backup mode the standalone dbstore utility does not require exclusive access and may be performed while the database is in use.

usage: dbstore [options] database archive_file|-
  options:
   -help   - show usage (this list)
   -u user - set user name
   -p pswd - set password
   -c cfg  - server configuration file
   -b size - Buffer cache size (MB)
The standalone dbstore utility supports the EQ_DBUSER and EQ_DBPASSWORD environment variables to specify the user and password.

The dbstore utility uses a default cache size of 5 MB unless a custom value is specified with the -b command line option. Previous dbstore versions used the cache size configured in the database configuration file.


Recovering a database with dbrestore

To restore the database from the tape (after it has been purged) the command below could be used:
dbctl -u dba dbrestore tape
The command below can be used to recover the database from the archive file payrol.bkup in the directory the "backup" device refers to:
dbpurge -u dba payrol
dbctl -u dba dbrestore backup/payrol.bkup
The command below displays the backup header instead of restoring the database:
dbctl -u dba dbrestore /info tape

The command below restores a previous backup to a new database. Because of the /all argument the association between database permission groups and server users ("sysmember") is retained:

dbctl -u dba dbrestore /all backup/payrol.bkup payrol-new


Compressed backups

The backup files can be compressed during dbstore and uncompressed during dbrestore. Add the following to the [Devices] section of your eloqdb.cfg file:
[devices]
zip = |gzip -c >/backup
unzip = |gzip -dc /backup
Please note: On HP-UX you may need to specify the path to gzip (/usr/contrib/bin/gzip) if the global path does not include the location of the gzip command.

When performing a backup to the "zip" destination this will cause the backup file to be compressed. A dbrestore from the "unzip" source is used to restore the compressed data.

dbctl -u dba dbstore payrol zip/payrol.bkup.gz
dbctl -u dba dbrestore unzip/payrol.bkup



 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2008-10-27  
  Copyright © 2006-2008 Marxmeier Software AG