Skip to content

Latest commit

 

History

History
221 lines (158 loc) · 5.97 KB

README.md

File metadata and controls

221 lines (158 loc) · 5.97 KB
Localhost Databases

SurrealDB is an innovative NewSQL cloud database .

About • Disclaimer • Getting Started • Download • How To Use

About

SurrealDB, is an innovative NewSQL cloud database suitable for serverless, jamstack, single-page, and traditional applications.

You can learn about SurrealDB in 100 Seconds by watching Fireship YouTube channel.

Disclaimer

Important

Localhost Databases is not affiliated with the databases' developers/owners and is not an official product.

Localhost Databases has been developed to run databases in a local Docker environment. To install a production instance, read the databases' respective installation guides.

Getting Started

You will need to make sure your system meets the following prerequisites:

  • Docker Engine >= 20.10.0

This repository utilizes Docker to run the SurrealDB sample. So, before using the SurrealDB, make sure you have Docker installed on your system.

Download

To use SurrealDB, you can clone the latest version of Localhost Databases repository for macOS, Linux and Windows.

# Clone this repository.
$ git clone git@github.com:luisaveiro/localhost-databases.git --branch main --single-branch

You can locate the Redis Docker configuration in the databases directory.

# Navigate to the SurrealDB folder.
$ cd localhost-databases/databases/surrealdb

How To Use

There are a few steps you need to follow before you can have an SurrealDB database set up and running in Docker container. I have outline the steps you would need to take to get started.

1. Environment Variables

Before you start a database in a Docker container, you will need to create a DotEnv file. The DotEnv file will allow you to configure your database's credentials and map a container's port.

Localhost Databases includes a .env.example file for SurrealDB Database. You can run the following command in the terminal to create your DotEnv file.

# Navigate to a database.
$ cd databases/surrealdb

# Create .env from .env.example.
$ cp .env.example .env

The SurrealDB Docker Compose file uses the follow variables from the DotEnv file.

#--------------------------------------------------------------------------
# Docker env
#--------------------------------------------------------------------------

# The project name. | default: surrealdb
APP_NAME="surrealdb"

#--------------------------------------------------------------------------
# Database (SurrealDB) env
#--------------------------------------------------------------------------

# The SurrealDB database container name. | default: surrealdb
DB_CONTAINER_NAME="${APP_NAME}"

# The SurrealDB database user credentials.
DB_USERNAME=""
DB_PASSWORD=""

#--------------------------------------------------------------------------
# Network env
#--------------------------------------------------------------------------

# Map the database container exposed port to the host port. | default: 8000
DB_PORT=8000

# The Docker network for the containers. | default: local_dbs_network
NETWORK_NAME="local_dbs_network"

#--------------------------------------------------------------------------
# Volume env
#--------------------------------------------------------------------------

# The database container data volume. | default: surrealdb_data
DB_VOLUME_DATA_NAME="${DB_CONTAINER_NAME}_data"

Note

The SurrealDB Docker image doesn't offer additional environment variables.

2. Start Docker container

To start the SurrealDB container, you can run the following command:

# Navigate to SurrealDB database.
$ cd databases/surrealdb

# Run Docker Compose command.
$ docker compose up -d
Expected result

To check the SurrealDB container is running and the port mapping is configured correctly, you can run the following command:

# List containers
$ docker ps

You should see a similar output.

CONTAINER ID   IMAGE                        COMMAND                  CREATED          STATUS          PORTS                    NAMES
0f216d93c518   surrealdb/surrealdb:latest   "/surreal start --lo…"   27 seconds ago   Up 26 seconds   0.0.0.0:8000->8000/tcp   surrealdb

3. Stop Docker container

To stop the SurrealDB container, you can run the following command:

$ docker compose down

4. Connect to Database

Note

TablePlus currently doesn't support SurrealDB. You can use Postman to run queries on SurrealDB.

To connect to your SurrealDB container from you HTTP request, you will need to provide the following settings:

PORT="${DB_PORT}"

USER="${DB_USERNAME}"
PASSWORD="${DB_PASSWORD}"

Below is a cURL request using the settings:

curl --request POST \
	--header "Content-Type: application/json" \
	--header "NS: test" \
	--header "DB: test" \
	--user "${DB_USERNAME}:${DB_PASSWORD}" \
	--data "INFO FOR DB;" \
	http://localhost:${DB_PORT}/sql
Expected result

Below is a screenshot of the settings used in Postman:

Postman settings for SurrealDB
Postman settings for SurrealDB.

GitHub • LinkedIn • Twitter