Backing up and restoring databases is accomplished by using the TEDBSession Execute method to execute the BACKUP DATABASE, SET BACKUPS STORE, and RESTORE DATABASE statements. You can also attach event handlers to the TEDBSession OnStatusMessage and OnProgress events in order to track any status messages and progress during a backup or restore operation.

Backing up a database copies all or some of the tables within the database, along with (optionally) the database catalog, to a compressed or uncompressed backup file in a local store. Restoring a database copies all or some of the tables in a compressed or uncompressed backup file in a local store into the database, overwriting any tables with the same names that already exist in the database. You can also choose to restore the database catalog during a restore operation, if the database catalog was backed up originally with the tables.

Backing Up a Database

---

When the backup executes, it obtains a read lock for the entire database that prevents any sessions from performing any writes to any of the tables in the database until the backup completes. However, since the execution of a backup is quite fast, the time during which the tables cannot be changed is usually pretty small. To ensure that the database is available as much as possible for updating, it is recommended that you backup the database to a file in a local store on a fast hard drive and then copy the file to a store that references a CD, DVD, or other slower backup device outside of the scope of the database being locked instead of creating the backup file directly in the store on the slower backup device.

The following example shows how to backup a database called "MyDatabase" using the BACKUP DATABASE statement and the TEDBSession Execute method:

{
   MySession->Execute("BACKUP DATABASE \"MyDatabase\" "+
                      "AS \"MyDatabase-Backup-"+
                         Engine()->DateToSQLStr(Date())+"\" "+
                      "TO STORE \"Backups\" "+
                      "INCLUDE CATALOG");
}

Tracking the Backup Progress

---

To take care of tracking the progress of the backup we have provided the OnProgress and OnStatusMessage events within the TEDBSession component. The OnProgress event will report the progress of the backup operation and the OnStatusMessage event will report any status messages regarding the backup operation.

Retrieving Information from a Backup File

---

To retrieve information about the backup files in a specific store, you can use the SET BACKUPS STORE statement to specify the store where the backup files are located, and then use a SELECT statement to query the Backups Table in the Configuration Database. The Backups table contains information about all of the backup files in the store specified by the SET BACKUPS STORE statement, with one row per backup file. Please see the Executing SQL Statements for more information on executing a query.

Restoring a Database

---

When the restore executes, it obtains an exclusive lock for the entire database that prevents any sessions from opening the database until the restore completes. However, since the execution of a restore is quite fast, the time during which the database cannot be accessed is usually pretty small.


The following example shows how to restore a database called "MyDatabase" using the RESTORE DATABASE statement and the TEDBSession Execute method:

{
   MySession->Execute("RESTORE DATABASE \"MyDatabase\" "+
                      "FROM \"MyDatabase-Backup-"+
                         Engine()->DateToSQLStr(Date())+"\" "+
                      "IN STORE \"Backups\" "+
                      "INCLUDE CATALOG");
}

Tracking the Restore Progress

---

To take care of tracking the progress of the restore we have provided the OnProgress and OnStatusMessage events within the TEDBSession component. The OnProgress event will report the progress of the restore operation and the OnStatusMessage event will report any status messages regarding the restore operation.