Database Export & Import

Use TypeDB’s built-in export functionality to export a database as a complete TypeQL schema file and a binary containing the instances in the database.

The built-in import functionality can be used to create a database from an exported data binary and a complete schema.

Exported binary data is designed to be identical across any version of TypeDB. This means you can reload your database in versions of TypeDB that are no longer compatible on the data layer (such as moving from TypeDB 2.x to 3.x).

This feature is introduced in TypeDB 3.4.0. If you want to export or import a database from earlier versions of TypeDB 3.x, simply update your server and client and follow this manual.

You can import your databases exported from TypeDB 2.x following this guide.

Understanding export and import

TypeDB database can be represented as two files:

  1. A text file with its TypeQL schema description: a complete define query for the whole schema.

  2. A binary file with its data.

An exported database can be imported into another version of TypeDB using these two files. This is the best tool you can use to migrate a database between two incompatible versions of TypeDB (e.g., a migration from TypeDB 2.x to TypeDB 3.x).

Both operations are performed through the network, but the server and the client can be used on the same host.

Examples below use TypeDB Console as the most accessible client for these operations. Please check the gRPC Drivers API to explore available programmatic commands.

Export

Database export allows a client to download database schema and data files from a TypeDB server for future import to the same or higher TypeDB version.

The files are created on the client side. The exported binary file might be up to two times larger than the original database. If the client connects to a remote host, the server’s disk remains unchanged, thus introducing zero risks to the stability of the server. Please ensure the client’s disk has enough free capacity to store a file of this size.

While the database data is being exported, parallel transactions are allowed, but none of them will affect the exported data thanks to TypeDB’s transactional nature. However, the database will not be available for operations such as deletion.

The files can be incomplete and corrupted if the export operation is interrupted by the user. Please restart and obtain a complete data file in one attempt.

Using TypeDB Console

  1. Make sure that your TypeDB Server is running.

  2. Follow Console page to set up a connection.

  3. Execute database export database-name schema.typeql data.typedb, where

    • database-name is the name of the exported database;

    • schema.typeql is the exported schema definition file path;

    • data.typedb is the exported data file path.

  4. The result (either Successfully exported database or an error) will be printed to the Console.

Import

Database import allows a client to upload previously exported database schema and data files to a TypeDB server.

For your safety, the imported database should not exist on the target server. It is possible to assign any new name to the imported database.

The database will be incomplete (and thus not recommended for usage) if the import operation is interrupted. It is expected to be automatically removed from the disk, but a small number of unexpected technical issues can prevent this from happening. A server restart will resolve any related issues.

Using TypeDB Console

  1. Make sure that your TypeDB Server is running.

  2. Follow Console page to set up a connection.

  3. Execute database import database-name schema.typeql data.typedb, where

    • database-name is the new name of the imported database;

    • schema.typeql is the imported schema definition file path;

    • data.typedb is the imported data file path.

  4. The result (either Successfully imported database or an error) will be printed to the Console.

Troubleshooting

Follow this checklist if any errors occur:

  • Ensure that you use compatible TypeDB Server and TypeDB Console.

  • Ensure that the correct file paths were specified for the operations.

  • If you import a TypeDB 2.x database, some errors may be expected. Check out this page for a detailed guide.

If any errors persist, please join one of our communities and ask for assistance.