Import and export

Export and import move data as SurrealQL text, so you get a portable copy of a database.

Use them for four cases:

• •

  Migrating from a self-hosted server.

• •

  Seeding a local development database.

• •

  Moving data between instances or regions.

• •

  Keeping an archive outside the platform.

Backups cover the recover-this-instance case instead, and you cannot download them.

Both commands come from the SurrealDB CLI, which you install once and point at any instance. The connection URL, namespace, and database are on the Connect menu of the instance in SurrealDB Studio.

Exporting

surreal export writes the contents of one database to a .surql file:

surreal export \
  --conn wss://<endpoint> \
  --user root --pass <password> \
  --ns main --db main \
  ./api-production.surql

The file contains the SurrealQL statements needed to rebuild the schema and the records. It is therefore readable, diffable, and safe to store in an artefact repository.

An export covers a single namespace and database. Export each one you need separately.

Importing

surreal import replays that file into a target database:

surreal import \
  --conn wss://<endpoint> \
  --user root --pass <password> \
  --ns main --db main \
  ./api-production.surql

The target namespace and database do not have to match the source. That is how you promote a staging dataset into a differently named database.

Size limits

An import is accepted up to 4 GiB per request. The limit applies to the whole request rather than to each statement, so you must split a larger file and import the parts in sequence.

The other endpoints have lower caps: 1 MiB on /sql and 4 MiB on /rpc. That is why bulk loading goes through import rather than through a large query. See request size limits for the full table.

A self-hosted server sets these caps with environment variables. Instances run the defaults.

Partial imports

An import is applied statement by statement as the file is parsed, and each statement commits as it goes. No single transaction wraps the file, so a failure partway through leaves the statements that already ran in place.

That matters for retries. Rerunning the same file against a half-populated database can produce duplicate records or conflicting definitions.

Import into a fresh namespace or database, verify the result, then switch the application over. If something fails, drop the target and start again from a known-empty state.

Related pages

• •

  Backups and recovery: snapshots and in-platform restore.

• •

  Migrating to SurrealDB: moving from another database.

• •

  surrealctl instances: surrealctl instance import and surrealctl instance export wrap the same operations against an instance.