# import

A command that imports a file in SurrealQL format into a local or remote SurrealDB database server.

Import a SurrealQL script into an existing database, on a local or remote server.

> [!NOTE]
> **Before you start** - make sure you’ve [installed SurrealDB](/docs/running/installation.md).

<Synopsis>
surreal import [OPTIONS] --namespace <NAMESPACE> --database <DATABASE> <FILE>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<FILE>",
            "required": true,
            "description": "Path to the SurrealQL file to import."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--endpoint",
            "short": "-e",
            "value": "<ENDPOINT>",
            "default": "http://localhost:8000",
            "description": "Database endpoint to import to. Alias: `--conn`."
        },
        {
            "name": "--username",
            "short": "-u",
            "value": "<USERNAME>",
            "env": "SURREAL_USER",
            "description": "Database authentication username to use when connecting. Alias: `--user`."
        },
        {
            "name": "--password",
            "short": "-p",
            "value": "<PASSWORD>",
            "env": "SURREAL_PASS",
            "description": "Database authentication password to use when connecting. Alias: `--pass`."
        },
        {
            "name": "--token",
            "short": "-t",
            "value": "<TOKEN>",
            "env": "SURREAL_TOKEN",
            "description": "Authentication token in JWT format, used instead of a username and password."
        },
        {
            "name": "--auth-level",
            "value": "<AUTH_LEVEL>",
            "default": "root",
            "env": "SURREAL_AUTH_LEVEL",
            "description": "Level on which the authenticating user is defined. Possible values: `root`, `namespace` (`ns`), `database` (`db`)."
        },
        {
            "name": "--namespace",
            "value": "<NAMESPACE>",
            "env": "SURREAL_NAMESPACE",
            "required": true,
            "description": "The namespace to import into. Alias: `--ns`."
        },
        {
            "name": "--database",
            "value": "<DATABASE>",
            "env": "SURREAL_DATABASE",
            "required": true,
            "description": "The database to import into. Alias: `--db`."
        },
        {
            "name": "--log",
            "short": "-l",
            "value": "<LOG>",
            "default": "info",
            "env": "SURREAL_LOG",
            "description": "The logging level for the command-line tool. Possible values: `none`, `full`, `error`, `warn`, `info`, `debug`, `trace`."
        }
    ]}
/>

Authenticate with either `--username` and `--password`, or with `--token`. Neither is needed against a server started with `--unauthenticated`.

## Example usage

To perform a SurrealQL database import from a local file, in a terminal run the `surreal import` command with the required arguments.

```bash
surreal import --endpoint http://localhost:8000 --user root --pass secret \
  --ns main --db main downloads/surreal_deal_v1.surql
```

Using token-based authentication:

```bash
surreal import --endpoint http://localhost:8000 --token <token> --ns main \
  --db main downloads/surreal_deal_v1.surql
```

> [!NOTE]
> If you are using SurrealDB Studio, you can import files into your database by using the `Import database` button in the Explorer view. See the [SurrealDB Studio documentation](/docs/explore/studio.md) for more information.

## Size limits and partial imports

An import against a remote endpoint goes through the [`/import`](/docs/reference/rest-api/http-protocol.md#import) endpoint, which accepts up to 4 GiB per request by default. The limit is cumulative for the whole request rather than per chunk, so a single file larger than the cap fails no matter how it is transferred - split the dataset across several files instead.

The import is applied as it is parsed, statement by statement, and each statement commits as it goes. An import that exceeds the limit or is interrupted therefore leaves everything applied up to that point in the database, with nothing rolled back.

Before importing a large file, decide how a failed run would be retried. Either write the file so that running it twice is safe, or import into a fresh namespace or database and switch over once the import has completed.

See [request size limits](/docs/reference/rest-api/http-protocol.md#request-size-limits) for the caps on every endpoint, and [environment variables](/docs/reference/cli/surrealdb-cli/environment-variables.md#http-server-config) for changing them on a self-hosted server.

## Validating files before import

A good practice before importing for the first time is to use the [`surreal validate`](/docs/reference/cli/surrealdb-cli/commands/validate.md) command to ensure that the statements therein are valid SurrealQL. This allows you to save time by failing quickly on the command line if there is invalid SurrealQL instead of starting a full database instance that will eventually fail in the middle of the import process.

## Using environment variables

When using the `surreal import` command, you can also use environment variables to set the values for the command-line flags.

> [!IMPORTANT]
> Most of the flags above have a corresponding [environment variable](/docs/reference/cli/surrealdb-cli/environment-variables.md#command-environment-variables).
> For example, the `--username` flag can be configured with the `SURREAL_USER` environment variable instead.

For more on the environment variables available for CLI commands or SurrealDB instances in general, see the [environment variables](/docs/reference/cli/surrealdb-cli/environment-variables.md#command-environment-variables) page.

## Managing a Cloud instance

To import into a SurrealDB Cloud instance by name, [`surrealctl`](/docs/reference/cli/surrealctl/overview.md) resolves the endpoint and credentials for you and then runs this command. The size limits and partial-import behaviour described above apply there too.

## OPTION IMPORT

The output of a database export includes a line that contains the keywords `OPTION IMPORT`. This command is used internally to ensure that side effects do not run when the data is imported, such as [events](/docs/reference/query-language/statements/define/event.md) and [table views](/docs/reference/query-language/statements/define/table.md#pre-computed-table-views).

As of SurrealDB 3.0.4, this line must be present in order to use the `/import` endpoint. If side effects when importing a `.surql` file are desired, remove the `OPTION IMPORT` line and use the [`/sql`](/docs/reference/rest-api/http-protocol.md#sql) endpoint instead.

## Importing data from other databases and sources

To import data from other sources besides `.surql` files (such as PostgreSQL, MongoDB, CSV data, Kafka, etc.), see the [migrations](/docs/build/migrating.md) section of the documentation.

## Command help

To see the help information and usage instructions, in a terminal run the `surreal import --help` command without any further arguments. This command gives general information on the arguments, inputs, and additional options for the `import` command.

```bash
surreal import --help
```

The output of the above command:

```text
Import a SurrealQL script into an existing database

Usage: surreal import [OPTIONS] --namespace <NAMESPACE> --database <DATABASE> <FILE>

Arguments:
  <FILE>  Path to the SurrealQL file to import

Options:
  -e, --endpoint <ENDPOINT>      Database endpoint to import to [default: http://localhost:8000]
  -u, --username <USERNAME>      Database authentication username to use when connecting [env: SURREAL_USER=] [aliases: --user]
  -p, --password <PASSWORD>      Database authentication password to use when connecting [env: SURREAL_PASS=] [aliases: --pass]
  -t, --token <TOKEN>            Authentication token in JWT format to use when connecting [env: SURREAL_TOKEN=]
      --auth-level <AUTH_LEVEL>  Level on which the authenticating user is defined [env: SURREAL_AUTH_LEVEL=] [default: root] [possible
                                 values: root, namespace, ns, database, db]
      --namespace <NAMESPACE>    The namespace selected for the operation [env: SURREAL_NAMESPACE=] [aliases: --ns]
      --database <DATABASE>      The database selected for the operation [env: SURREAL_DATABASE=] [aliases: --db]
  -h, --help                     Print help

Logging:
  -l, --log <LOG>                              The logging level for the command-line tool [env: SURREAL_LOG=] [default: info] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>                The format for terminal log output [env: SURREAL_LOG_FORMAT=] [default: text] [possible
                                               values: text, json]
      --log-socket <LOG_SOCKET>                Send logs to the specified host:port [env: SURREAL_LOG_SOCKET=]
      --log-file-level <LOG_FILE_LEVEL>        Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL=] [possible values:
                                               none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>        Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL=] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>    Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL=] [possible
                                               values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>  The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT=] [default: text] [possible
                                               values: text, json]
      --log-file-enabled                       Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED=]
      --log-file-path <LOG_FILE_PATH>          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH=] [default: logs]
      --log-file-name <LOG_FILE_NAME>          The name of the log file [env: SURREAL_LOG_FILE_NAME=] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>      The format for log file output [env: SURREAL_LOG_FILE_FORMAT=] [default: text] [possible
                                               values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>  The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION=] [default: daily] [possible
                                               values: daily, hourly, never]
```