Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migration guide improvements #963

Merged
merged 1 commit into from
Oct 23, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,24 @@ title: Upgrading from 1.x to 2.x | Upgrading | Installation
description: This guide will help you upgrade your current SurrealDB installation to the latest `2.x` release.
---

# Upgrading from `1.x` to `2.x`
# Upgrading from `1.x` to `2.x`

The `2.0.0` release of SurrealDB includes [many new features, improvements, and bug fixes](https://surrealdb.com/releases#v2-0-0). However, due to this there are some breaking changes that you should be aware of when upgrading.

This guide will help you upgrade your current SurrealDB installation to the latest `2.x` release.

## Breaking changes

### Datastore
### Datastore
- The underlying approach for storing record ids and ranges has changed
- [Record IDs now support storing UUIDs instead of strings](https://github.com/surrealdb/surrealdb/pull/4491)
- [Value::Range stored as just a range instead of a string](https://github.com/surrealdb/surrealdb/pull/4506)
- [Ranges are now their own value as suppose to being available as just record id ranges](https://github.com/surrealdb/surrealdb/pull/4506)

### SurrealQL
- The `UPDATE` statement no longer creates records if these are missing. Instead, use the new [UPSERT](https://deploy-preview-945--surrealdb-docs.netlify.app/docs/surrealql/statements/upsert) statement for this behaviour.
- The `file://` connection protocol has been deprecated in favour of the more explicit `rocksdb://` protocol.
- The `DEFINE SCOPE` statement has been dropped in favor for the new [`DEFINE ACCESS TYPE RECORD`](/docs/surrealql/statements/define/access/record) statement
- `DEFINE TOKEN` definitions defined under scopes are now integrated into `DEFINE ACCESS TYPE RECORD`.
- Some functions have been renamed for clarity
- `meta::tb()` -> [`record::tb()`](/docs/surrealql/functions/database/record/#recordtb)
- `meta::id()` -> [`record::id()`](/docs/surrealql/functions/database/record/#recordid)
Expand Down Expand Up @@ -48,7 +50,7 @@ surreal fix rocksdb:somedatabase

### Limitations of the surreal fix command

Although the `surreal fix` command is a quick way to migrate your data, it is not without its drawbacks:
Although the `surreal fix` command is a quick way to migrate your data, it is not without its drawbacks:

- If you have used the now deprecated [`DEFINE TOKEN`](/docs/surrealql/statements/define/token) command to define a token on a Scope with the also deprecated [`DEFINE SCOPE`](/docs/surrealql/statements/define/scope) command, you will have to update your access management rules to use the new [`DEFINE ACCESS`](/docs/surrealql/statements/define/access) which supports creating permissions using [TYPE JWT](/docs/surrealql/statements/define/access/jwt) and [TYPE RECORD](/docs/surrealql/statements/define/access/record) rules.

Expand All @@ -64,7 +66,7 @@ The `surreal fix` command above has been created specifically for 1.x instances.
```bash
# Example export command to export data to a file called `export.surql` in the downloads directory.
surreal export --conn http://localhost:8000 --user root --pass root --ns test --db test downloads/export.surql
```
```

2. This will create a file called `export.surql` in the current directory.

Expand All @@ -88,4 +90,3 @@ error: Storage version is out-of-date.
## Read the full changelog

There have been major improvements to SurrealDB in `2.0.0` release both in alpha and beta. Check out the changes on the [release page](https://surrealdb.com/releases).