Migration and Backup
TypeDB (i.e. Grakn) version 1.7.3 and later include tools to backup and migrate data between versions of typedb that are not data-level compatible. Please note the chart below for which versions are data-level compatible:
|Data-level Versions||Versions at Data-level||Earliest Version With Migration Available|
|1.7||1.5.x, 1.6.x, 1.7.x||1.7.3|
The migration features describe beyond this point are designed for use with databases that can reasonably fit on a local disk multiple times (in the order of Gigabytes), as they make use of files to contain your data. If you have use cases for migrating data that will not fit onto disk, please reach out to us on our Discord community or Forums where we can advise you further.
You can backup your data in a version-independent file using:
typedb server export [database] [filename].typedb
You can import a backup using:
typedb server import [database] [filename].typedb
These paths are relative to the current working directory of the CLI. The CLI expands the relative path to an absolute path for the server, which does the file writing directly, so you must ensure that the path is writable by the server process and should avoid symblic links where possible.
Importing a backup will not delete existing data in the database, so you should clean the database using console and reload the schema prior to the operation.
The first step of migration is to migrate your schema. The
database schema my-database-name command in Console allows you to get the current schema of a database as a single
define query. This schema query can then be loaded via the Console to the new server.
Export the old schema:
old/typedb console database schema [database]
Copy the schema into a file named
You can skip the step of exporting schema if you already have a copy of your schema to import.
If migrating from TypeDB version <2.0 to version >=2.0 you need to update your schema to conform to 2.0 syntax.
Once conforming to the new syntax, import the new schema:
new/typedb console > create database [database] > transaction [database] schema write [database]::schema::write> source schema.tql
Data migration is performed using an export followed by an import.
old/typedb server export [database] data.typedb new/typedb server import [database] data.typedb
This requires your database in the new typedb to have a valid schema that is compatible with your data. If a failure occurs during import, please check your database has the schema you expect.
Once the data has been successfully imported, you can safely delete the temporary data file with
Dealing With Migration Issues
If you encounter migration errors, follow this checklist:
- Ensure that you are running the correct
typedbcommand (the binary in the TypeDB directory of the server you are exporting from or importing to.)
- Ensure that the schema has been imported correctly to the new database.
- Ensure that the correct data import path was specified.
- Ensure that the data was correctly exported by checking the filesize.
- Ensure that any changed labels are remapped in the import options.
If you have any further errors, please join one of our communities and ask for assistance.
Between versions, some schemas will become incompatible due to syntax change. Whilst most issues can be corrected in the schema before importing it, it is possible for a label to become invalid (if the label becomes a keyword in a new version). In order to handle this scenario, we have added an option to import from 1.8 onwards that allows you to remap labels during the import.
typedb server import <database> <file>.typedb <old_label>=<new_label>...
Schemas that use implicit relations in 1.7 and earlier (e.g.
@has-attribute) are not supported by migration tools since they were removed in 1.8. It is therefore recommended that you convert any usage of implicit relations to real relations before migrating to 1.8.