# Airbyte

The Airbyte connector allows you to sync data to SurrealDB from hundreds of sources.

This guide helps you configure SurrealDB as a destination in [Airbyte](https://airbyte.com) using the [official connector](https://github.com/surrealdb/airbyte-connector).

## Prerequisites
To connect SurrealDB to Airbyte, you need the following:

- An Airbyte deployment with access to the SurrealDB destination connector.
- SurrealDB `v2.2.0` or later.
- A SurrealDB instance (self-hosted or [SurrealDB Cloud](https://app.surrealdb.com/cloud)) reachable by Airbyte.
- Ensure your SurrealDB database can be accessed by Airbyte. If your database is within a VPC, you may need to allow access from the IP you're using to expose Airbyte.
- A token or user credentials with [`DEFINE TABLE`](/docs/reference/query-language/statements/define/table.md), [`DEFINE INDEX`](/docs/reference/query-language/statements/define/indexes.md), [`UPSERT`](/docs/reference/query-language/statements/upsert.md), [`SELECT`](/docs/reference/query-language/statements/select.md), and [`REMOVE`](/docs/reference/query-language/statements/remove.md) permissions.

## Setup instructions

Follow these steps to configure SurrealDB as a destination. You can use either a self-hosted instance or SurrealDB Cloud .

Before proceeding, ensure you have the endpoint URL and credentials for your SurrealDB instance and that Airbyte can reach it over the network.

#### Option 1: Self-hosted SurrealDB

1. Ensure your SurrealDB instance is reachable from Airbyte. This might involve opening network access or configuring an SSH tunnel.
2. Create a dedicated user or token in SurrealDB, for example:

```surql
DEFINE USER airbyte ON ROOT PASSWORD "YourPassword" ROLES OWNER;
```

Use the generated credentials when setting up the destination.

#### Option 2: SurrealDB Cloud

1. Visit the [Instances page](https://app.surrealdb.com/cloud/instances) and select your instance.
2. Click **Connect with Surreal CLI** to obtain a connection command containing the `--endpoint` and authentication details.
3. Verify you can connect using `surreal sql` with those parameters.

## Finish Airbyte configuration

1. Open the Airbyte dashboard and add a new **Destination**.
2. Select **SurrealDB** from the list of destination types.
3. Provide the host, port, namespace, database, and either the username/password or token you created earlier.
4. Click **Set up destination** and run the connection test.

Upon a successful test, you can start syncing data from your sources into SurrealDB tables. Each stream will be output into its own table in SurrealDB. Each table will contain 3 columns:

- `_airbyte_raw_id`: a uuid assigned by Airbyte to each event that is processed. The column type in SurrealDB is string. The connector use this as the ID of each record in the destination SurrealDB table.
- `_airbyte_extracted_at`: a timestamp representing when the event was pulled from the data source. The column type in SurrealDB is datetime.
- `_airbyte_data`: a json blob representing with the event data. The column type in SurrealDB is object.

## Known limitations
SurrealDB destination forces all identifier (table, schema and columns) names to be lowercase.

## Related links

- [Airbyte destination documentation](https://github.com/surrealdb/airbyte-connector)
- [Connect to airbyte via a dev container](https://github.com/surrealdb/airbyte-connector/blob/main/devcontainer.md)