How to Install and Use SurrealDB on Ubuntu 26.04 and 24.04

Share

To install SurrealDB on Ubuntu 26.04 or 24.04, run the official Linux installer as your regular user. SurrealDB stores records you can query with SurrealQL, its SQL-style query language.

You’ll run a local database on disk, add a task, and check that the task survives a restart.

Before you begin
  • Use Ubuntu 26.04 LTS or 24.04 LTS with Bash and internet access. You need sudo for Ubuntu packages only.
  • Check for a 64-bit x86_64 or aarch64 system.
  • Use a fresh practice directory. The examples bind to localhost for local development.

Install SurrealDB

Step 1. Check Ubuntu and install prerequisites

Check the release and CPU architecture, then install curl and the certificate bundle used for HTTPS. On a minimal image, install lsb-release if the first command is missing.

Ubuntu terminal
lsb_release -a
uname -m
sudo apt update && sudo apt install -y curl ca-certificates
Step 2. Run the official installer

Run the installer as your normal user. On a standard Ubuntu setup, your account cannot write to /usr/local/bin, so the installer falls back to ~/.surrealdb. The installer checks the downloads against published SHA-256 checksums and leaves your shell profiles untouched.

Ubuntu terminal
curl -sSf https://install.surrealdb.com | sh
Step 3. Add SurrealDB to Bash’s PATH

If the installer used ~/.surrealdb, add the first line below once at the end of ~/.bashrc. The remaining lines reload Bash settings and verify the installation.

~/.bashrc
export PATH="$HOME/.surrealdb:$PATH"

Run these commands in your terminal after saving the file. Expect the database component in the list and a database version such as 4.0.1, the stable release at review.

Ubuntu terminal
source ~/.bashrc
surreal list
surreal db version

Start a persistent local server

Step 4. Create a practice directory and start the server

SurrealDB 4.0 uses SurrealKV 1.0, its native Rust storage engine, for this on-disk database. The memory backend is useful for disposable experiments because records disappear when the process stops.

Open a Bash terminal and enter a strong, unique practice password when prompted. Reading it into a variable keeps it out of shell history. The process can still expose a password supplied as a command-line argument to other local users with sufficient access.

Ubuntu terminal
mkdir -p "$HOME/surrealdb-practice"
cd "$HOME/surrealdb-practice"
read -r -s -p 'SurrealDB password: ' SURREALDB_PASSWORD
printf '\n'
surreal db start --bind 127.0.0.1:8000 --username root --password "$SURREALDB_PASSWORD" surrealkv://project_data
unset SURREALDB_PASSWORD

Keep this terminal open. Binding to 127.0.0.1 limits connections to this computer. The username and password initialize a SurrealDB root account only when the datastore is new. Starting the same directory with different credentials leaves its existing password in place.

Run your first SurrealQL queries

Step 5. Connect from a second terminal

Check that the server is ready, then enter the same password. The interactive shell opens at main/main> by default with a new v4 datastore.

Ubuntu terminal
surreal db is-ready --endpoint http://127.0.0.1:8000
read -r -s -p 'SurrealDB password: ' SURREALDB_PASSWORD
printf '\n'
surreal db sql --endpoint http://127.0.0.1:8000 --username root --password "$SURREALDB_PASSWORD" --pretty
unset SURREALDB_PASSWORD
Step 6. Create a namespace, database and task

A namespace groups databases. A database holds tables and records. Define workspace first, then create the tracker database inside it. Enter these statements at the SurrealQL prompt.

SurrealQL shell
DEFINE NAMESPACE IF NOT EXISTS workspace;
USE NS workspace;
DEFINE DATABASE IF NOT EXISTS tracker;
USE NS workspace DB tracker;
CREATE task:install SET title = "Install SurrealDB", done = false;
SELECT * FROM task:install;

The result should include the record ID task:install and done: false. If you repeat the example, query or update the existing record instead of creating it again.

Step 7. Mark the task complete

Update the record by ID, then read it again. The done field should now be true.

SurrealQL shell
UPDATE task:install SET done = true;
SELECT * FROM task:install;

Verify the data survives a restart

Step 8. Stop and restart the server

Press Ctrl+D at the SQL prompt to return to Bash. In the server terminal, press Ctrl+C, then start it again from the same directory. The existing datastore already contains the root account.

Ubuntu terminal
cd "$HOME/surrealdb-practice"
surreal db start --bind 127.0.0.1:8000 surrealkv://project_data
Step 9. Read the saved task

Reconnect using the commands in the query section. After the SQL prompt opens, select the same namespace and database. Seeing done: true confirms that the update survived the restart.

SurrealQL shell
USE NS workspace DB tracker;
SELECT * FROM task:install;

Back up, update and remove SurrealDB

Step 10. Export the database while the server is running

In the second terminal, exit SurrealQL first. Export the tracker database to a separate, timestamped file and check that the export is nonempty. Store a copy separately if you plan to remove the practice directory. A database export covers the selected database. Keep the root credentials separately and test restores before relying on a backup.

Ubuntu terminal
umask 077
backup="$(mktemp "$HOME/surreal-tracker-$(date +%F)-XXXXXX.surql")"
read -r -s -p 'SurrealDB password: ' SURREALDB_PASSWORD
printf '\n'
surreal db export --endpoint http://127.0.0.1:8000 --username root --password "$SURREALDB_PASSWORD" --namespace workspace --database tracker "$backup" &&
  test -s "$backup" && printf 'Export saved to %s\n' "$backup"
unset SURREALDB_PASSWORD
Step 11. Upgrade from the launcher

After exporting your data, stop the server before upgrading. To update the launcher and installed components, run the first command. To update the database component only, run the second command instead. Check the database version afterward and restart from the same directory.

Ubuntu terminal
surreal upgrade

For the database component only, use this command.

Ubuntu terminal
surreal upgrade db

Confirm the version before restarting.

Ubuntu terminal
surreal db version
Step 12. Uninstall the database and remove the per-user launcher

Export anything you want to keep and stop the server with Ctrl+C. Uninstall the database component from the launcher.

Ubuntu terminal
surreal uninstall db

For a dedicated per-user install, move ~/.surrealdb aside so you can recover it if it contains other Surreal components. If the destination already exists, choose a different name before running the command. Remove the PATH line you added to ~/.bashrc and open a fresh terminal. You can delete the moved folder once you have checked its contents.

Ubuntu terminal
mv -iT -- "$HOME/.surrealdb" "$HOME/.surrealdb-removed"

Your SurrealKV datastore is separate at ~/surrealdb-practice/project_data. Keep it for later or delete the project_data folder through your file manager after verifying your backup. Deleting it permanently removes its local records and accounts.

Troubleshoot common errors

SurrealDB command not found

Reload ~/.bashrc and check which executable Bash can see. If an older executable appears first, confirm that the per-user install directory is at the front of your PATH.

Ubuntu terminal
source ~/.bashrc
type -a surreal
Port 8000 is already in use

Check which process is listening. If the port belongs to a service you need, choose another free port such as 8001. Use the new port for --bind and each client’s --endpoint.

Ubuntu terminal
ss -ltnp | grep 8000
Connection refused or authentication failed

For a refused connection, check that the first terminal still shows the running server and that your endpoint uses its port. For a login failure, enter the password used when the datastore was first initialized.

Frequently asked questions

Can I run SurrealDB without sudo?

Yes. You need sudo to install missing Ubuntu prerequisites. The official installer can put SurrealDB in your home directory, and the local server runs under your regular account.

Why does the SQL prompt show main/main?

Those are the default namespace and database on a new SurrealDB 4 datastore. Use USE NS workspace DB tracker; to switch to the project tracker after creating it.

Why did my tasks disappear after restarting?

Check that you started the SurrealKV server from the same working directory using surrealkv://project_data. Starting with memory or opening a different datastore gives you a different set of records.

Related Ubuntu guides

Source: SurrealDB’s official Linux installation documentation.