> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Import and export

Move data in and out with surreal export and surreal import. Covers size limits and partial-import behaviour.

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](/docs/manage/instances/backups.md) cover the recover-this-instance case instead, and you cannot download them.

Both commands come from the [SurrealDB CLI](/docs/reference/cli/surrealdb-cli/overview.md), 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](https://studio.surrealdb.com).

## Exporting

[`surreal export`](/docs/reference/cli/surrealdb-cli/commands/export.md) writes the contents of one database to a `.surql` file:

```bash title="Export a database to a file"
surreal export \
  --endpoint 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.

By default an export contains everything in the database. To export only some tables or kinds of definition, such as the schema without its records, see [Choosing what to export](/docs/reference/cli/surrealdb-cli/commands/export.md#choosing-what-to-export). In SurrealDB Studio, the **Export database** dialog offers the same choices with checkboxes and shows the matching `surreal export` command.

## Importing

[`surreal import`](/docs/reference/cli/surrealdb-cli/commands/import.md) replays that file into a target database:

```bash title="Import a file into an instance"
surreal import \
  --endpoint 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](/docs/reference/rest-api/http-protocol.md#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](/docs/manage/instances/backups.md):** snapshots and in-platform restore.
- **[Migrating to SurrealDB](/docs/build/migrating.md):** moving from another database.
- **[surrealctl instances](/docs/manage/surrealctl/instances.md):** `surrealctl instance import` and `surrealctl instance export` wrap the same operations against an instance.