Databases and migration

DartRelay keeps its configuration and session records in a database. This page helps you choose the right database engine before you start, explains how to move to another engine, how DartRelay keeps the database structure up to date when you upgrade, and lists what to back up.

What the database holds

Almost everything you set up in the console lives in the database: hosts and the accounts used to reach them, Resources, users and groups, administrator roles, themes, tenants and their addresses, Agreements, Announcements, email templates, security and load balancer settings, the licence terms, and the record of sessions and seats used by the Seats page and reports.

A few things are kept beside the database in the data directory instead: the server configuration file, and the encryption keys that protect saved host passwords. See Backing up.

Supported database engines

DartRelay behaves the same on all four. The choice is about where you want the data to live and who looks after it.

Choosing an engine

Ask two questions:

1. Will you ever run more than one DartRelay server behind a load balancer? A pool needs one database that every server can reach, which means SQL Server, MySQL or PostgreSQL. See Running several servers (pools).
2. Does your organisation already run and back up one of those engines? If so, use it. Your existing backups, monitoring and database administrators then cover DartRelay too.

If the answer to both is no, SQLite is a sensible choice: there is nothing extra to install or maintain, and backing it up is part of backing up the data directory.

Setting the database up

You choose the database in the setup wizard's database step, the first time you open the console after installing. See Installing DartRelay for the whole sequence.

Using SQLite

Choose SQLite in the database step. DartRelay creates the database file in its data directory. There is nothing else to prepare.

Using SQL Server, MySQL or PostgreSQL

1. Create an empty database on your database server for DartRelay, with a login that can create and alter tables in it. DartRelay creates its own tables and adds to them on upgrade, so it needs that right, not only read and write.
2. Make sure the DartRelay server can reach the database server on its port, through any firewall between them.
3. In the setup wizard's database step, choose the engine and enter the server, database name and login.
4. Finish the wizard. DartRelay creates its tables in the empty database and applies the change itself.

The database connection is saved in the data directory of that server. In a pool, each server keeps its own copy of the connection details, written by the installer when it joins; the rest of the configuration is shared through the database itself.

How the database is kept up to date

New versions of DartRelay sometimes need new tables or columns. You do not run any scripts for this: when an upgraded DartRelay starts, it checks the database and adds whatever is missing, in the right form for your engine. Existing data is kept.

• The login needs permission to alter tables for this to work. If your database administrators prefer to remove that right after installation, it must be restored before each upgrade.
• In a pool, upgrade every server together. All the servers share one database, and every server must run the same version. See Upgrading DartRelay.
• Take a backup first. Back up the database (and the data directory) before any upgrade, so you can go back if you need to.

Moving to a different engine

An installation that started on SQLite can be moved to SQL Server, MySQL or PostgreSQL without setting it up again. The console has a Database page in its settings that copies the whole configuration from the current database into a new one and then switches the installation over to it. This is the usual step before adding a second server, because a pool needs a database every server can reach.

1. Take a backup. Back up the data directory (which holds the SQLite file) before you start. See Backing up.
2. Prepare the new database as described in Setting the database up: an empty database and a login that can create and alter tables.
3. Choose a quiet time. The switch-over ends open sessions, so pick a moment when few people are working.
4. Open the Database page in the console's settings, choose the new engine and enter the server, database name and login.
5. Start the move. DartRelay creates its tables in the new database, copies your configuration and records across, and then uses the new database from then on.
6. Check the result. Sign in to the console and confirm your hosts, Resources, users and themes are all present, then open an application from the portal.
7. Keep the old SQLite file from your backup until you are satisfied that nothing was missed.

Backing up

A complete backup of a DartRelay installation has two parts.

The data directory is locked down so that only the system and administrators can read it. Leave those permissions as they are.

Worked example

A charity starts DartRelay as a trial on one server with SQLite. The trial goes well and they decide to keep it, with a second server planned next year for maintenance headroom. Because their IT partner already looks after a SQL Server instance with nightly backups, they move now: they create an empty DartRelay database on SQL Server, take a backup of the data directory, and use the Database page to copy the installation across one evening. Their hosts, twelve Resources and custom theme arrive unchanged. A year later, adding the second server is a matter of running the installer and choosing to join the pool.

If something goes wrong

The setup wizard cannot connect to the database server

Check the server name and port, that the database exists, that the login is correct, and that a firewall is not blocking the DartRelay server from reaching the database server.

DartRelay starts with an empty configuration after a change

It is pointed at a different, empty database rather than one it was moved to. Check the connection details, or restore the data directory from before the change and use the Database page to move again.

After an upgrade, a new feature's page is missing or shows an error

DartRelay could not add the new tables or columns, usually because the login has lost permission to alter tables. Restore that permission, then run the upgrade again so DartRelay can finish adding them.

Saved host credentials stopped working after a restore

The database was restored without the matching encryption keys from the data directory. Restore the data directory from the same backup, or enter the hosts' credentials again.

Related pages