Move your database¶

This page explains how to copy or move your intraday database (IDB) and historical database (HDB) to a new location and re-root their symlinks.

The IDB and HDB contain symlinks with absolute paths. After you copy or move a database its symlinks still point at the old location. Re-rooting rewrites them to match the new location.

Re-root your database when you:

move it to a new disk or mount point
restore a backup to a different path
clone it to build a test or staging system

For the layout of the link directories see HDB files and IDB files.

How re-rooting works¶

The re-root runs in two stages:

It builds a new link directory for the IDB and HDB with every symlink pointing at the new location. It also records the new HDB data location in the HdbStatus table.
It switches each current link to its new link directory and removes the old one.

The re-root switches nothing until both new link directories are complete. If the build fails the new link directories are discarded and the database is left as it was.

The re-root only changes the database at the new location. It never touches the old location or any table data. It's safe to run again on a database that has already been re-rooted.

Limitations¶

HDB tiering isn't supported. The re-root stops if any symlink points outside the IDB or HDB root.
Only the IDB and HDB are re-rooted. Other directories under the database root are left as they are.

Before you begin¶

Stop every process that uses the database. A copy taken while the system is writing is inconsistent.
Don't start the system at the new location before you re-root. Its symlinks still point at the old location. After a copy the processes would read and write the original database.
Let any interrupted end-of-interval (EOI) or end-of-day (EOD) process finish. If the system stopped partway through an EOI or EOD, start it at the old location so it can recover. The re-root refuses to run on a database with an unfinished EOI or EOD.
Complete any upgrade from KX Sensors 2.X. Start the upgraded system once at the old location before you copy or move it.
Check free space if you copy. The new location needs room for a full copy. A move within one filesystem needs no extra space.
Take a backup if you move. A move leaves no original to fall back on. See Recover your data.

Re-root your database¶

Run these steps on the node that holds the database. Repeat them on each node whose database you move.

Stop the system as described in Start and stop the system. Leave etcd running because the maintenance console needs it.
Copy or move the IDB and HDB directories.

To move them use mv. Within one filesystem this is instant.
```
mv /old/db/idb /old/db/hdb /new/db/
```
To copy them use a tool that keeps symlinks as links and keeps hard links together.
```
rsync -aH /old/db/idb /old/db/hdb /new/db/
```
cp -a also works but it copies hard-linked files more than once and so uses more space.

Warning

Never use an option that follows symlinks, such as cp -L or rsync -L. It copies table data into the link directories and breaks the database layout.
Set the idbDir and hdbDir system parameters to the new IDB and HDB roots. See System parameters systemParams.yaml.

The re-root reads these parameters to find the database and records the HDB location from them. They must name the new location before you continue.
Start a maintenance console on the node, then load and run the re-root.
```
kxsctl mc reroot

q).load.lq`:src/proc/storage/common/reroot.q
q).rr.reroot[]
```
The console logs each symlink it rewrites. A successful run ends with Completed.
Check that no symlink still points outside the new location. This command prints nothing when the re-root is complete.
```
find /new/db/idb /new/db/hdb -type l ! -lname '/new/db/*'
```
Start the system as described in Start and stop the system.

Troubleshooting¶

When the re-root stops it reports the problem in the console log and leaves the database as it was. Fix the cause and run it again.

Error	Meaning	What to do
`root`	`current` isn't a symlink.	The copy didn't keep symlinks. Copy the database again with `rsync -aH`.
`eox`	An EOI or EOD didn't finish.	Return the database to its old location and start the system to recover pending EOX. Stop it and repeat from step 2.
`link`	A symlink points outside the IDB and HDB roots. The log names the symlink.	The database uses tiering or a custom layout. Contact KX support.

The re-root logs any other failure as Re-root failed with the reason, for example a full disk or a missing HdbStatus table. The work in progress is discarded and the database is left unchanged.

Note

If the console stops while it switches the current links the database may be left partway. After a copy, delete the copy and start again from step 2. After a move, restore your backup and start again.