Online Backup

Because an ObjectDB database is stored as a single file in the file system, you can back it up by copying or archiving the database file. This method only works when the database is offline, meaning it is not open in an ObjectDB server or in use by any application.

ObjectDB also supports online backups, which let you back up a database while it is in use. This feature is useful for applications that require continuous service (24/7), such as most web applications.

Starting an online backup

You can start an online backup by executing a special query on an EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. (em) instance that represents a local or remote connection to the database:

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

The backup query string is always "objectdb backup".

The backup is created in the backup root directory. By default, this is $objectdb/backup,
a subdirectory of the ObjectDB home directory. In client-server mode, this path is relative to the ObjectDB home directory on the server.

A new subdirectory is created in the backup root directory. The subdirectory's name reflects the current date and time (for example, 201912312359). The backup database file is then created in this new subdirectory with the same name as the original database file.

For example, backing up a test.odb database file by 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

You can specify a custom backup root directory by setting the target parameter before you execute the backup query:

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

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

If you specify the target argument as a java.io.File instance in a client-server connection, the backup file is downloaded and stored on the client machine.

Alternatively, you can specify the backup target as a String value:

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

When you specify a string for the target parameter, it represents a path relative to the ObjectDB home directory. In client-server mode, the path is relative to the ObjectDB home directory on the server.

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

Online Backup Thread

The backup query starts the backup process asynchronously. It returns immediately after the backup begins, but the operation might still be in progress.

The backup query returns a Thread instance that represents the backup operation. You can use this thread, for example, to wait for the backup to complete.

    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).

In client-server mode, the returned Thread is a local thread on the client that represents the actual backup thread on the server. Therefore, some thread operations, such as changing the thread priority, have no effect.