TypeDB 3.0 is live! Get started for free.

TypeDB 2.x to TypeDB 3.x: migration process

This page gives recommendations for server and driver upgrades between the two major versions of TypeDB, as well as a step-by-step example of such a migration.

Migration plan

  1. Understand the scope of changes by referring to the major changes page.

  2. Review the missing features list before starting your migration. Some features might not yet be available in 3.x, and you may need to wait for a newer version to proceed.

  3. (Optional) Refresh your knowledge and adjust to the new versions of TypeDB and TypeQL by following the updated Quickstart Guide.

  4. Set up TypeDB 3.x by following the Configuration Manual.

  5. Migrate your TypeDB 2.x database following the step-by-step instructions below. The setup process remains largely unchanged from 2.x.

  6. (Optional) Update your supporting queries using the Schema and CRUD manuals.

  7. (Optional) Update your drivers. Consult the Drivers Manual and the major driver changes list for details.

Step-by-step example

This section showcases a step-by-step example of migrating a database between TypeDB 2.x and TypeDB 3.x using major changes[export and import].

This example uses a database called social-network. It contains an arbitrary set of data and the 2.x schema provided below.

social-network’s 2.x schema
social-network.typeql
define
  content sub entity, abstract,
    owns id @key;
  page sub content, abstract,
    owns name,
    owns bio,
    plays posting:page,
    plays following:page;
  profile sub page,
    owns profile-id as id,
    plays content-engagement:author,
    plays following:follower;
  group sub page,
    owns group-id as id;
  post sub content,
    abstract,
    owns post-id as id,
    owns post-text,
    owns creation-timestamp,
    plays posting:post,
    plays commenting:parent,
    plays reaction:parent;
  text-post sub post;
  image-post sub post,
    owns post-image;
  comment sub content,
    owns comment-id as id,
    owns comment-text,
    owns creation-timestamp,
    plays commenting:comment,
    plays commenting:parent,
    plays reaction:parent;

  interaction sub relation, abstract,
    relates subject,
    relates content;
  content-engagement sub interaction, abstract,
    relates author as subject;
  posting sub content-engagement,
    relates page as content,
    relates post;
  commenting sub content-engagement,
    relates parent as content,
    relates comment;
  reaction sub content-engagement,
    relates parent as content,
    owns emoji,
    owns creation-timestamp;
  following sub relation,
    relates follower,
    relates page;

  name sub attribute,
    value string;
  id sub attribute, abstract,
    value string;
  post-id sub id;
  profile-id sub id;
  group-id sub id;
  comment-id sub id;
  creation-timestamp sub attribute,
    value datetime;
  emoji sub attribute,
    value string;
  post-image sub attribute,
    value string, regex ".*\.png$";
  payload sub attribute, abstract,
    value string;
  text-payload sub payload, abstract;
  image-payload sub payload;
  bio sub text-payload,
    owns bio-version;
  comment-text sub text-payload;
  post-text sub text-payload;
  version sub attribute, abstract,
    value long;
  bio-version sub version;

Optional: resolve data conflicts

While most of the changes in TypeDB 3.x affect only the schema, there is also one very important change in data, which can lead to errors on the import stage of this guide.

Attributes can no longer own attributes in TypeDB 3.x. If your data contains attributes owning attributes, you will see an error like:

Invalid migration item received: attributes cannot own attributes in this version of TypeDB (deprecated).

In this situation, an additional step is required before proceeding, and it will require modifications of the original 2.x’s database.

Move attributed owned by attributes

This is an example of migration of attributes owned by attributes for the referenced schema.

Our goal is to move bio-version from bio to page owning the bio attributes. This way, both bio and bio-version will be attached to the same entity (note that it’s only one of the ways to redesign this schema).

First, using a schema write transaction, define the additional required trait of page:

define
  page owns bio-version;

Then, using a data write transaction, perform the data moving between `bio`s and `page`s:

match
  $version isa bio-version;
  $attribute has $version;
  $entity has $attribute;
delete
  $attribute has $version;
insert
  $entity has $version;

Finally, verify that the data is moved correctly. As an additional step of verification, you can try undefining the original ownership to verify that it’s now redundant:

undefine
  bio owns bio-version;

Now your data is ready to get migrated to TypeDB 3.x!

Export the database from TypeDB 2.x

Use 2.x export to export your TypeDB 2.x database as a schema definition file and a data file.

While your server is running, execute typedb server export using the same server binary:

typedb server export --database=social-network --port=1729 --schema=social-network.typeql --data=social-network.typedb

Prepare the new schema

Manually update your schema definition file.

  • The major changes page highlights the most common updates needed.

  • For simplicity, rules can be completely removed. Additional queries can be run to define functions as their replacements later.

This step can require a couple of iterations until you reach the final state of your new schema you will be satisfied with. Use error messages during application to guide adjustments.

This is a sample example of the updated social-network's schema, written in TypeQL 3.x:

social-network’s 3.x schema
social-network-3x.typeql
define
  entity content @abstract,
    owns id @key;
  entity page @abstract, sub content,
    owns name @card(0..),
    owns bio @card(1),
    owns bio-version @card(1),
    plays posting:page,
    plays following:page;
  entity profile sub page,
    owns name @card(1..3),
    owns profile-id,
    plays content-engagement:author,
    plays following:follower;
  entity group sub page,
    owns name @card(1),
    owns group-id;
  entity post @abstract, sub content,
      owns post-id,
      owns post-text,
      owns creation-timestamp @card(1),
      plays posting:post @card(1),
      plays commenting:parent,
      plays reaction:parent;
  entity text-post sub post,
    owns post-text @card(1);
  entity image-post sub post,
    owns post-image @card(1..10);
  entity comment sub content,
    owns comment-id,
    owns comment-text,
    owns creation-timestamp @card(1),
    plays commenting:comment,
    plays commenting:parent,
    plays reaction:parent;

  relation interaction @abstract,
      relates subject @card(1),
      relates content @card(1);
  relation content-engagement @abstract, sub interaction,
    relates author as subject;
  relation posting, sub content-engagement,
    relates page as content,
    relates post @card(1);
  relation commenting, sub content-engagement,
    relates parent as content,
    relates comment @card(1);
  relation reaction, sub content-engagement,
    relates parent as content,
    owns emoji @card(0..9),
    owns creation-timestamp @card(1);
  relation following,
    relates follower @card(1),
    relates page @card(1);

  attribute name,
    value string;
  attribute id @abstract,
    value string;
  attribute post-id sub id;
  attribute profile-id sub id;
  attribute group-id sub id;
  attribute comment-id sub id;
  attribute creation-timestamp,
    value datetime;
  attribute emoji,
    value string @values("like", "love", "funny", "surprise", "sad", "angry");
  attribute post-image,
    value string @regex(".*\.png$");
  attribute payload @abstract,
    value string;
  attribute text-payload @abstract, sub payload;
  attribute image-payload @abstract, sub payload;
  attribute bio sub text-payload;
  attribute comment-text sub text-payload;
  attribute post-text sub text-payload;
  attribute version, value integer;
  attribute bio-version sub version;

Noticeable highlights:

  • Attribute types can be subtyped even if they are not abstract.

  • Attributes can no longer own attributes. See bio-version for an example of such redesign.

  • long is now integer.

  • We can restrict cardinalities of relates, owns, and plays using the @card annotation. Default cardinality values protect your data, but they may not suite your needs. Consider overriding them explicitly.

  • We can redeclare traits like owns on subtypes to put additional constraints on them.

  • While there are no as keyword for owns and plays, in most cases, like ours, it’s not needed. E.g., the previously overridden owns id does not require overriding in 3.x as it’s an ownership of an abstract attribute, so it cannot be instantiated without type specialization (e.g., owns post-id).

  • More constraints can be moved from your application logic to the schema: see the implication of @values, an enum-like constraint of TypeQL.

If you want to put data constraints, but your data does not yet satisfy them, you can start with a relaxed schema and then add the constraints required via additional define queries.

Import the database into TypeDB 3.x

Launch a TypeDB 3.x server and connect to it using a compatible TypeDB Console.

In TypeDB Console, execute a database import command:

database import social-network /path-to-updated-schema/social-network-3x.typeql /path-to-2.x-export/social-network.typedb

You can operate other server’s databases without restrictions while the new database is being imported.

In case of successful migration, you will see:

Successfully imported database.

Otherwise, a descriptive error will be shown. After fixing this error, retry the same command.

After import

From this point, your database is completely functional. Its schema and data are synchronized and technically correct.

We recommend running a few read queries to verify that the migration was logically successful and familiarize yourself with the updated TypeQL and your new schema.

If necessary, define TypeQL functions and update any queries that previously relied on the removed rules to use the new functions instead.

Visit TypeDB 2.x to TypeDB 3.x: what’s changed and TypeDB Manual to learn more about TypeDB 3.x. Enjoy your journey!

Having troubles?

For troubleshooting tips and guidance, refer to the Troubleshooting Manual.