export

Dumps the database contents to a file.

Note

WebSocket connections currently do not support exports and imports. Be sure to use an HTTP endpoint and the protocol-http feature when using this method.

Method Syntax

db.export(target)

Arguments

Argument	Description
`resource`	The table name or a record ID to select. Will also accept a tuple of record name and ID.

Example usage

The .export() method can be used to save the contents of a database to a file.

use surrealdb::engine::any::connect;
use surrealdb::opt::auth::Root;
use surrealdb::opt::Resource;

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = connect("http://localhost:8000").await?;
    db.signin(Root {
        username: "root".to_string(),
        password: "secret".to_string(),
    })
    .await?;
    db.use_ns("main").use_db("main").await?;

    // Create a `person` record
    db.create(Resource::from("person")).await?;

    db.export("backup.surql").await?;
    Ok(())
}

If an empty tuple is passed in for the file name, the .export() method will instead return an async stream of bytes.

use futures::StreamExt;
use surrealdb::engine::any::connect;
use surrealdb::opt::auth::Root;
use surrealdb::opt::Resource;

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = connect("http://localhost:8000").await?;
    db.signin(Root {
        username: "root".to_string(),
        password: "secret".to_string(),
    })
    .await?;
    db.use_ns("main").use_db("main").await?;

    // Create a `person` record
    db.create(Resource::from("person")).await?;

    let mut stream = db.export(()).await?;

    while let Some(Ok(line)) = stream.next().await {
        let content = String::from_utf8(line).unwrap();
        println!("{content}");
    }
    Ok(())
}

The output for the above sample should look like the following.

-- ------------------------------

-- OPTION

-- ------------------------------


OPTION IMPORT;


-- ------------------------------

-- TABLE: person

-- ------------------------------


DEFINE TABLE person TYPE ANY SCHEMALESS PERMISSIONS NONE;


-- ------------------------------

-- TABLE DATA: person

-- ------------------------------


INSERT [ { id: person:bgq0b0rblnozrufizdjm } ];

Export configuration

The Export struct has a method called .with_config() that gives access to the configuration parameters for the export. These can be chained one after another inside a single line of code. The majority of these functions take a single bool:

.versions(): refused from SurrealDB 3.3.1, because an export holds only the current state of each record. SurrealDB 3.0.0 to 3.3.0 accepted it and ignored it.
.accesses(): whether to include DEFINE ACCESS statements
.analyzers(): whether to include DEFINE ANALYZER statements
.functions(): whether to include DEFINE FUNCTION statements
.apis(): whether to include API definitions in the export
.buckets(): whether to include bucket definitions
.modules(): whether to include DEFINE EXTENSION statements
.configs(): whether to include stored configuration definitions
.sequences(): whether to include DEFINE SEQUENCE statements
.database_definition(): whether to include the database's own definition, with its STRICT, COMMENT and CHANGEFEED clauses. Importing it rewrites those clauses on the target database, so an export of only some resources should leave it off. Over a gRPC connection, .database_definition(false) fails, because the gRPC export request has no field for it.
.records(): whether to include the existing records in the database
.params(): whether to include DEFINE PARAM statements
.users(): whether to include DEFINE USER statements

.tables() takes a Vec of strings in addition to a boolean.

.tables(): a list of tables to export, as opposed to all of the tables in the database.

Example of export configuration:

use surrealdb::engine::any::connect;
use surrealdb::opt::auth::Root;

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = connect("http://localhost:8000").await?;
    db.signin(Root {
        username: "root".to_string(),
        password: "secret".to_string(),
    })
    .await?;
    db.use_ns("ns").use_db("db").await?;

    db.query(
        "
    DEFINE FUNCTION fn::get_cats() -> array<object> { RETURN SELECT * FROM cat };
    DEFINE TABLE person SCHEMAFULL;
    DEFINE FIELD name ON person TYPE string;
    DEFINE FIELD age ON person TYPE int;
    CREATE person SET name = 'Aeon', age = 20;
    CREATE cat SET name = 'Cat of Aeon';
    ",
    )
    .await?;

    // Cat-related implementation is still experimental
    // so don't export the cat table or get_cats() function
    db.export("backup.surql")
        .with_config()
        .tables(vec!["person"])
        .functions(false)
        .await?;
    Ok(())
}

Arguments

Example usage

Export configuration

See also