Backing Up and Restoring Databases,
Page 2 of 4


[top]
[prev]
[next]
Index for This Book
Table of Contents
Documentation Top
Global Index

Backing Up a Database

Offline Backups

The easiest way to back up a database is to use operating system commands to copy the database. To do so, the database must be shut down.

For example, to back up the database toursDB (which has been shut down) from the directory d:\mydatabases to a directory d:\mybackups\1999-01-01:

xcopy d:\mydatabases\toursDB c:\mybackups\1999-01-02\toursDB /s /i

NOTE: This example uses commands specific to the Windows NT operating system. Use commands appropriate to your operating system to copy a directory and all contents to a new location.

For large systems, shutting down the database may not be convenient. System administrators should use the on-line backup facility where necessary.

On-line Backups

Cloudscape allows you to back up a database even if the database is booted. While the database is being backed up, writes to the database are temporarily blocked. Reads are allowed.

There are two ways to perform on-line backups:

With the backup Method

To back up a database, use the void method backup in the class COM.cloudscape.database.Database. When connected to the database you want to back up, you use the static method getDatabaseOfConnection in COM.cloudscape.database.Factory (aliased as Factory), to get a Database object for calling this method. The backup method takes a string argument that represents the location of the backup directory. Typically you provide the full path to the backup directory. (Relative paths are interpreted as relative to the current directory, not to the cloudscape.system.home directory.)

For example:

CALL Factory.getDatabaseOfConnection().backup(
    'c:/mybackups/1999-01-01')

NOTE: Use forward slashes for the path separator in SQL-J commands.

The backup method puts the database into a state in which it can be safely copied, then copies the entire original database directory, including data files, on-line transaction log files, and jar files, to the specified backup directory. Files not within the original database directory (for example, cloudscape.properties) are not copied.

Here is an excerpt from JBMSTours.AdminHelper, which backs up a database to a directory with a name that reflects the current date:

public static void backUpDatabase(Connection conn) throws SQLException {
    String backupdirectory = "c:/mybackups/" + JCalendar.getToday();
    PreparedStatement ps = conn.prepareStatement(
    "CALL Factory.getDatabaseOfConnection().backup(CAST (? AS java.lang.String))");
    ps.setString(1, backupdirectory);
    ps.executeUpdate();
    ps.close();
    System.out.println("backed up database to " + backupdirectory);
}

If the connection was to a database called toursDB and the current date was 1999-01-01, the database directory toursDB in c:/mybackups/1999-01-01 is now a copy of the original database.

Uncommitted transactions do not appear in the backed-up database.

NOTE: Do not back up different databases with the same name to the same backup directory. If a database of the same name already exists in the backup directory, it is assumed to be an older version and is overwritten.

With the freeze and unfreeze Methods and Operating System Commands

Some operating system commands (like the UNIX tar command) may provide faster backups than the backup method, since it uses the file copying routines in the JDK.

To use operating system commands for on-line database backups, use the freeze method in the class COM.cloudscape.database.Database, which puts the database into a state in which it can be safely copied. Once the copy is complete, use the unfreeze method to allow transactions to once again change the database. Read operations can proceed while the database is “frozen”.

As with the backup method, you use the static method getDatabaseOfConnection in COM.cloudscape.database.Factory (aliased as Factory), to get a Database object for calling these methods.

The following example shows when you could use the operating system commands:

String backupdirectory = "c:/mybackups/" + JCalendar.getToday();
Statement s = conn.createStatement();
s.executeUpdate(
    "CALL Factory.getDatabaseOfConnection().freeze()");
// here is where you would copy the database directory now
s.executeUpdate(
    "CALL Factory.getDatabaseOfConnection().unfreeze()");
s.close();

When the Log Is in a non-Default Location

NOTE: Read “Logging on a Separate Device” to find out about the default location of the database log.

If you put the log in a non-default location, pay attention to the following issues when backing up a database:

  • When you copy a database using the freeze/unfreeze command and an operating system command, make sure to copy the log as well.

    xcopy d:\mydatabases\toursDB c:\mybackups\1999-01-03\toursDB /s /i

    xcopy h:\janet\tourslog\log c:\mybackups\1999-01-03\toursDB\log /s /i

NOTE: This example uses commands specific to the Windows NT operating system. Use commands appropriate to your operating system to copy a directory and all contents to a new location.

  • Edit the logDevice entry in service.properties of the database backup so that it points to the correct location for the log. In the above example, the log was moved to the default location for a log, so you could remove the logDevice entry entirely, or leave the logDevice entry as is and wait until the database is restored to edit the entry.

See Chapter 13, “Logging on a Separate Device” for information about putting the log in a non-default location.

Backing Up Encrypted Databases

When you back up an encrypted database, both the backup and the log files remain encrypted. To restore an encrypted database, you must know the boot password.

NOTE: See the sample program JBMSTours.AdminHelper for an example of backing up a database.

[top]
[prev]
[next]


Cloudscape Version 3.0
For technical support, go to: www.cloudscape.com and click Support.
Copyright © 1998 and 1999 Cloudscape, Inc. All rights reserved.