File-backed | Running

For the purposes of getting started with SurrealDB quickly, we will start a RocksDB database which persists data on the filesystem.

A single node of SurrealDB can be run with data persisted to the filesystem. This configuration can be done using either RocksDB or SurrealKV as the backend. Both use the same transaction and isolation semantics as every other SurrealDB deployment.

RocksDB

surreal start rocksdb://mydatabase.db

The default logging level for the database server is info. To control the logging verbosity, specify the --log argument. The following command starts the database with debug level logging, resulting in more logs being output to the terminal. If extra verbosity is not needed, specify a lower level or simply remove the flag, which will default to the info level.

surreal start --log debug rocksdb://mydatabase.db

The SurrealDB server runs with authentication enabled by default. To disable it, the --unauthenticated flag can be passed in.

surreal start --unauthenticated rocksdb://mydatabase.db

However, for anything but simple testing, it is better to configure your initial root-level user by setting the --user and --pass command-line arguments. The following command starts the database with a top-level user named root with a password set to secret. The root user will be persisted in storage, which means you don't have to include the command line arguments next time you start SurrealDB.

surreal start --user root --pass secret rocksdb://mydatabase.db

In order to change the default port that SurrealDB uses for web connections and from database clients you can use the --bind argument. The following command starts the database on port 8080.

surreal start --user root --pass secret --bind 0.0.0.0:8080 rocksdb://path/to/mydatabase

After running the above command, you should see the SurrealDB server start up successfully.

surreal start --user root --pass secret --bind 0.0.0.0:8080 rocksdb://mydatabase.db

Output

2025-08-30T15:06:34.788739Z  INFO surreal::dbs: ✅🔒 Authentication is enabled 🔒✅
2025-08-30T15:06:34.788821Z  INFO surrealdb::kvs::ds: Starting kvs store in file:mydatabase.db
2025-08-30T15:06:34.788859Z  INFO surrealdb::kvs::ds: Started kvs store in file:mydatabase.db
2025-08-30T15:06:34.789222Z  INFO surrealdb::kvs::ds: Initial credentials were provided and no existing root-level users were found: create the initial user 'root'.
2025-08-30T15:06:35.205123Z  INFO surrealdb::node: Started node agent
2025-08-30T15:06:35.205827Z  INFO surrealdb::net: Started web server on 0.0.0.0:8080

For details on the different commands available, visit the CLI tool documentation.

Parameters on startup

A number of parameters can be used on startup such as sync to set when to flush the database to the file system. For more details on these parameters, see this page for the start command or this page to set the same parameters using environment variables.

Run your first query

With the server running, open a second terminal and connect to it with the surreal sql command. This starts a SurrealQL REPL against the server, using the credentials from the step above.

surreal sql --endpoint http://localhost:8000 --username root --password secret --namespace main --database main --pretty

Create a record. There is no need to define the table first, because SurrealDB creates it on the first write.

CREATE person:tobie SET name = "Tobie", city = "London";

Output

[
	{
		city: 'London',
		id: person:tobie,
		name: 'Tobie'
	}
]

Select it back to confirm the round trip.

SELECT name, city FROM person;

Output

[
	{
		city: 'London',
		name: 'Tobie'
	}
]

When you finish, exit the REPL with Ctrl+C. The record persists on disk, so it is still there the next time you start the server against the same path.

Next steps

Query from your application with an SDK - each language guide starts with a connect-and-query walkthrough.
Try SurrealQL without a server in the Studio Sandbox.
Learn the query language, starting with the SELECT statement.