Installation

Two installation methods are supported: an automated method, which fetches and installs the module from within SurrealDB itself, and a manual method, which installs a binary you have downloaded yourself.

Prerequisites

Regardless of method, the SurrealDB process must be started with the following:

SURREAL_CAPS_ALLOW_EXPERIMENTAL=files,surrealism set in its environment
--allow-net (see Configuration for details on network-access requirements)

Each method below adds further requirements of its own.

In addition to the prerequisites above, --allow-eval-query must be passed to SurrealDB.

Define $s3_module_config as described in Configuration.

Run the following query to fetch the installer and install the module:

-- Import fn::install_s3
eval::surql(<string>http::get("https://surreal-s3.yuuna.dev/setup.surql"));

-- Arguments:
--   version: Option<String> - Specify a version, or none for latest
--   db_url:  Option<String> - The URL the db can be reached at locally;
--                             defaults to http://127.0.0.1:8000
fn::install_s3(none, none);

In addition to the prerequisites above, SURREAL_BUCKET_FOLDER_ALLOWLIST must be set to the directory the module binary is placed in.

Download s3.surli from GitHub Releases and place it in a directory of your choice, e.g. dir/containing/s3.surli.
Set SURREAL_BUCKET_FOLDER_ALLOWLIST="dir/containing/s3.surli".
Define $s3_module_config as described in Configuration:
```
DEFINE PARAM $s3_module_config ...
```

Define a bucket backed by that directory:

DEFINE BUCKET s3_module_bucket BACKEND "file:/dir/containing/s3";

Install the module.

Before SurrealDB 3.3:

DEFINE MODULE mod::s3 AS f"s3_module_bucket:/s3.surli";

SurrealDB 3.3 and later:

DEFINE MODULE mod::s3 FROM f"s3_module_bucket:/s3.surli" UNSIGNED;