Using the backup procedure to perform an online backup

Use the SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure to perform an online backup of a database to a specified location.

The SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure takes a string argument that represents the location in which to back up the database. Typically, you provide the full path to the backup directory. (Relative paths are interpreted as relative to the current directory, not to the derby.system.home directory.)

For example, to specify a backup location of c:/mybackups/2005-06-01 for a database that is currently open, use the following statement (forward slashes are used as path separators in SQL commands):

CALL SYSCS_UTIL.SYSCS_BACKUP_DATABASE('c:/mybackups/2005-06-01')

The SYSCS_UTIL.SYSCS_BACKUP_DATABASE() procedure puts the database into a state in which it can be safely copied, then copies the entire original database directory (including data files, online transaction log files, and jar files) to the specified backup directory. Files that are not within the original database directory (for example, derby.properties) are not copied.

The following example shows how to back up a database to a directory with a name that reflects the current date:

public static void backUpDatabase(Connection conn)throws SQLException
{
// Get today's date as a string:
java.text.SimpleDateFormat todaysDate = 
   new java.text.SimpleDateFormat("yyyy-MM-dd");
String backupdirectory = "c:/mybacksup/" +
   todaysDate.format((java.util.Calendar.getInstance()).getTime());

CallableStatement cs = conn.prepareCall("CALL SYSCS_UTIL.SYSCS_BACKUP_DATABASE(?)"); 
cs.setString(1, backupdirectory);
cs.execute(); 
cs.close();
System.out.println("backed up database to "+backupdirectory);
}

For a database that was backed up on 2005-06-01, the previous commands copy the current database to a directory of the same name in c:/mybackups/2005-06-01.

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.

The SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedure will issue an error if there are any unlogged operations in the same transaction as the backup procedure.

If any unlogged operations are in progress in other transactions in the system when the backup starts, this procedure will block until those transactions are complete before performing the backup.

Derby automatically converts unlogged operations to logged mode if they are started while the backup is in progress (except operations that maintain application jar files in the database). Procedures to install, replace, and remove jar files in a database are blocked while the backup is in progress.

If you do not want backup to block until unlogged operations in other transactions are complete, use the SYSCS_UTIL.SYSCS_BACKUP_DATABASE_NOWAIT procedure. This procedure issues an error immediately at the start of the backup if there are any transactions in progress with unlogged operations, instead of waiting for those transactions to complete.