SurrealDB Destination Setup Guide Partner-Built Private Preview

Follow our setup guide to connect SurrealDB to Fivetran.

This destination is partner-built. For any questions related to self-hosted SurrealDB destination and its documentation, contact SurrealDB Support. For SurrealDB Cloud, refer to Surreal Cloud Suppoort.

Prerequisites

To connect SurrealDB to Fivetran, you need the following:

A Fivetran role with the Create Destinations or Manage Destinations permissions.
A SurrealDB token.
A SurrealDB instance (self-hosted or Cloud) that is accessible by Fivetran.

Setup instructions

Get URL and token

Option 1: Self-hosted SurrealDB

For self-hosted SurrealDB, ensure your SurrealDB instance is accessible by Fivetran according to your Fivetran deployment:
- For Fivetran SaaS Deployment, ensure your SurrealDB is accessible via Internet.
- For Fivetran Hybrid Deployment, ensure your SurrealDB is accessible by the Fivetran Hybrid Deployment Agent.
- For Fivetran Self-Hosted Deployment, ensure your SurrealDB is accessible by the Fivetran HVR Agent.
Run the surreal sql --endpoint wss://YOUR_INSTANCE_HOSTNAME --user $YOUR_USER --pass $YOUR_PASS command, and set up your own ACCESS or USER.
The example below works for testing purposes:
```
DEFINE USER your_user ON ROOT PASSWORD "YourPassword" ROLES OWNER;
```
Make sure that the user is defined at the root level for this example, not in the database or namespace.
Refer to Namespace-level sign-in and Token authentication for more advanced authentication scenarios.

Ensure that the user/pass is working by running:

surreal sql --endpoint wss://YOUR_INSTANCE_HOSTNAME --user your_user --pass YourPassword --ns your_ns --db your_db

Make a note of the endpoint, user, and pass parameters. You will need them to configure Fivetran.

Option 2: Surreal Cloud

Ensure your SurrealDB instance is up and running and accessible via the Internet.
Browse the Instances page and select your chosen instance.
Click Connect with Surreal CLI and locate the surreal sql --endpoint wss://YOUR_INSTANCE_HOSTNAME --token YOUR_TOKEN command.
Run the command, and set up your own ACCESS or USER.
The example below works for testing purposes:
```
DEFINE USER your_user ON ROOT PASSWORD "YourPassword" ROLES OWNER;
```
Make sure that the user is defined at the root level for this example, not in the database or namespace.
Refer to Namespace-level sign-in and Token authentication for more advanced authentication scenarios.

Finish Fivetran configuration

Log in to your Fivetran account.
Go to the Destinations page and click Add destination.
Enter a Destination name of your choice.
Click Add.
Select SurrealDB as the destination type.
Enter the url, user and pass (or token) you verified in the previous step.
The url setting corresponds to the endpoint parameter you verified in the previous step.
Click Save & Test.

Fivetran tests and validates the SurrealDB connection. Upon successfully completing the setup tests, you can sync your data using Fivetran connectors to the SurrealDB destination.

In addition, Fivetran automatically configures a Fivetran Platform Connector to transfer the connector logs and account metadata to a schema in this destination. The Fivetran Platform Connector enables you to monitor your connectors, track your usage, and audit changes. The connector sends all these details at the destination level.

If you are an Account Administrator, you can manually add the Fivetran Platform Connector on an account level so that it syncs all the metadata and logs for all the destinations in your account to a single destination. If an account-level Fivetran Platform Connector is already configured in a destination in your Fivetran account, then we don't add destination-level Fivetran Platform Connectors to the new destinations you create.

Setup tests

Fivetran performs the following SurrealDB connection tests:

The Database Connection test checks if we can connect to your SurrealDB database using the provided URL and token.

The test should complete in a few seconds if your Fivetran deployment can access the target SurrealDB instance.

Namespace-level sign-in

The connector supports signing in to the destination SurrealDB as a namespace-level user.

To enable it:

Set auth_level configuration for this connector on Fivetran to namespace
Create a namespace-level user by executing the following query:

USE NS your_ns;
DEFINE USER your_user ON NAMESPACE PASSWORD "YourPassword" ROLES OWNER;

Ensure the namespace-level user is properly configured by running:

surreal sql --endpoint wss://YOUR_INSTANCE_HOSTNAME --user your_user --pass YourPassword --ns your_ns --db your_db --auth-level namespace

Token authentication

The connector authenticates to the destination SurrealDB using a token.

First, see [SurrealDB's Authentication documentation] (https://surrealdb.com/docs/surrealdb/security/authentication#token) to learn about supported token types.

We recommend DEFINE ACCESS ... TYPE JWT. See the DEFINE ACCESS > JWT documentation to set up JWT access. Configure the destination SurrealDB to verify the provided token. Note that SurrealDB does not generate or sign the JWT token.

Once you've successfully set up the JWT authentication method and created a token that is valid for a while, since JWT tokens expire in a few seconds or minutes, they would be useless for this use case. Ensure it works by running the following commands.

If you've generated a JWT token for root-level authentication:

surreal sql --endpoint wss://YOUR_INSTANCE_HOSTNAME --token $YOUR_TOKEN

If you've generated a token for namespace-level authentication:

surreal sql --endpoint wss://YOUR_INSTANCE_HOSTNAME --token $YOUR_TOKEN --ns your_ns --auth-level namespace

Destination Overview

API Destination Configuration

Documentation Home