Upgrading from v1.0.0-beta.9 to v1.0.0-beta.10

Upgrading from v1.0.0-beta.9 to v1.0.0-beta.10

Because of a change in the underlying way that SurrealDB stores data in this update, there are extra steps required to migrate to v1.0.0-beta.10.

Introduction

Our latest beta.10 update introduces a set of internal data changes, which can cause panics and other types of unexpected behaviour. Besides that, we also introduced a set of behavioural changes which we will introduce in this upgrade guide.

Internal data changes

Because of the introduced internal data changes, we need to export our database(s) with beta-9, then import them back after we have upgraded to beta-10.

1. Start your old SurrealDB instance

You can start the instance just like you normally would.

surreal start -u root -p root myolddataset.db

2. Export your data

Please follow the export docs to run the export.

surreal export --conn http://localhost:8000 --ns ns --db db --user root --pass root mydata.surql

3. Stop the SurrealDB instance

Stop the v1.0.0-beta.9 database server, before continuing on to the next step.

4. Install SurrealDB v1.0.0-beta.10

Install v1.0.0-beta.10 database server, using the official docs before continuing on to the next step.

5. Start the v1.0.0-beta.10 SurrealDB instance

Start the new v1.0.0-beta.10 database server like you normally start SurrealDB, before importing your data.

surreal start -u root -p root mynewdataset.db

6. Import your data

Please follow the import docs to run the import. Make sure to install v1.0.0-beta.10 on your systems first.

surreal import --conn http://localhost:8000 --ns ns --db db --user root --pass root mydata.surql

Behaviour changes

We have introduces numerous improvements, bug fixes and other type of changes in v1.0.0-beta.10. We will go over the most important items here, but for a full list of changes, please refer to our release page for v1.0.0-beta.10.

Capabilities We have introduced capabilities in v1.0.0-beta.10. They allow you to allow or deny certain aspects of SurrealDB.

In our effort to deliver a security-first and water-tight database, all capabilities are disabled by default. This means that by default, you are not able to use any methods, embedded scripting functions, make outbound network calls, or access the database anonymously.

You can easily enable all these capabilties again with the --allow-all flag, or choose which capabilities to enable yourself. This is further documented in the Capabilities documentation.

Revamped root users

It is now possible to define multiple root users in SurrealDB. This change did require some changes in the way that you start your database however.

With this change, you will now only initially have to provide the --user and --pass flags to create the initial root user, but once the first root user exists, they will no longer by utilized.

For more information, check out the Authentication guide, and the surreal start and DEFINE USER documentation.

Command

# When you initially start the database, you can create the first root user.
surreal start --auth --user root --pass root file:database.db

# In the future, you don't need to specify the --user and --pass flags anymore
surreal start --auth file:database.db
# Afterwards, you are able to create multiple root users.
DEFINE USER tobie ON ROOT PASSWORD "SecurePassword!" ROLES OWNER;
DEFINE USER jaime ON ROOT PASSWORD "SecurePassword!" ROLES EDITOR;
DEFINE USER john  ON ROOT PASSWORD "SecurePassword!" ROLES VIEWER;

Stricter typing

Previously, when you defined a field of a certain type, you manually had to ASSERT that the value stored in that field, was not NONE or NULL.

We majorly improved the typing safety and strictness in v1.0.0-beta.10 which allows you to overcome this issue.

# This field is required, as indicated by it's type.
DEFINE FIELD age ON person TYPE number;

# This field can now optionally store the age.
# This means that the value can be either a number or NONE.
DEFINE FIELD age ON person TYPE option<number>;

# Notice how the previous example does not allow for NULL.
# This is because NULL is consider to be a value, but the option type allows either an empty field (NONE), or the passed type.
# If you want to allow NULL, we also introduced union types in v1.0.0-beta.10!
DEFINE FIELD age ON person TYPE number | null;          -- number and NULL
DEFINE FIELD age ON person TYPE option<number | null>;  -- number, NULL and NONE

Learn more

These are some highlights of behavioural changes. For a complete list, please refer to our release page for v1.0.0-beta.10.