Online Backup

An ObjectDB database can be backed up by simply copying or archiving the database file while the database is offline (i.e. when it is not open in an ObjectDB server and not in use by any application), since an ObjectDB database is stored as an ordinary file in the file system. 

ObjectDB supports also online backup, for backing up an ObjectDB database while it is in use. This is useful in applications that provide round the clock service (24/7/365) such as most web applications.

Starting Online Backup

The online backup can be started by executing a special query on an EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... (em) that represents the connection (local or remote) to the database:

    em.createQuery("objectdb backup").getSingleResult();

The backup query string is always exactly "objectdb backup".

The backup is created under the backup root directory, which by default is $objectdb/backup,
i.e. a subdirectory of the ObjectDB home directory (and in client-server mode a subdirectory of the ObjectDB home directory on the server side).

A new subdirectory with a name that reflects the current date and time (e.g. 201912312359) is created under the backup root directory and the backup database file itself is created in that subdirectory with the name of the original database file.

For example, backing up a test.odb database file using the code above could generate a backup whose full path is c:\objectdb\backup\201912312359\test.odb (if c:\objectdb is the ObjectDB home directory).

Custom Backup Target

A custom backup root directory can be specified by setting the target parameter before executing the backup query:

    Query backupQuery = em.createQuery("objectdb backup");
    backupQuery.setParameter("target", new java.io.File("c:\\backup"));
    backupQuery.getSingleResult();

The code above, for instance, could create a backup at c:\backup\201912312359\test.odb regardless of the ObjectDB home directory location.

Notice that if the target argument is specified as a java.io.File instance and em represents a client-server connection then the backup file will be downloaded to the client and will be stored on the client machine.

Alternatively, the backup target could be specified as a String value:

    Query backupQuery = em.createQuery("objectdb backup");
    backupQuery.setParameter("target", "backup");
    backupQuery.getSingleResult();

When a string is specified as a value for the target parameter it represents a path relative to the ObjectDB home directory, and in client-server mode, relative to the ObjectDB home directory on the server side.

For example, in client-server mode the code above could create the backup file on the server side at backup/201912312359/test.odb under the ObjectDB home directory.

Online Backup Thread

Executing the backup query starts the backup asynchronously. Therefore, the backup query returns after the backup is started but at that time the backup operation may still be in progress.

As a result, the backup query returns a Thread instance that represents the backup run. This thread can be used, for example, for waiting until the backup is completed.

    TypedQuery<Thread> backupQuery =
        em.createQuery("objectdb backup", Thread.class);
    Thread backupThread = backupQuery.getSingleResult();
    backupThread.join(); // Wait until the backup is completed.
    // Do something with the backup (e.g. upload it to Amazon S3).

Notice that in client-server mode the returned Thread is a local thread on the client side that represents the real thread on the server side. Therefore, some operations (e.g. changing the thread priority) will have no real effect in client-server mode.