SurrealDB data source plugin

[!IMPORTANT] Deprecation Notice: This plugin is deprecated and will only receive critical security updates. Support will end on June 1, 2026.

The SurrealDB datasource plugin enables you to query and visualize SurrealDB data directly within Grafana, offering seamless integration and exploration of SurrealDB datasets.

⚠️ SurrealDB v2.0 compatibility

Important: The Grafana SurrealDB datasource currently does not support SurrealDB v2.0. Please ensure you are using a compatible version of SurrealDB (v1.x) for full functionality. Follow the GitHub issue here for updates on compatibility.

What are Grafana data source plugins?

Grafana supports a wide range of data sources, including Prometheus, MySQL, and even Datadog. There’s a good chance you can already visualize metrics from the systems you have set up. In some cases, though, you already have an in-house metrics solution that you’d like to add to your Grafana dashboards. Grafana Data Source Plugins enables integrating such solutions with Grafana.

Usage

Installation

Please refer to our Data Source Management documentation for more information on installing the plugin to an instance of Grafana.

Configuration

Add a data source by filling in the following fields:

Basic fields

Authentication fields

We strongly recommend that you make your queries with a user account that has read-only access. This practice not only safeguards your data but also helps maintain system integrity.

Querying

The query editor allows you to write SurrealQL queries. For more information about writing SurrealQL queries, please refer to SurrealDB's documentation.

In this version, only a SurrealQL Editor is provided to write queries with. A Query Builder UI is planned for a later version of the plugin.

Development

This project requires at least Node.js v20 and at least Go 1.21.

Version management configuration for Node.js is provided for volta. It is recommended that you have this installed to automatically switch between Node.js versions when you enter the project directory. This allows for more deterministic and reproducible builds, which makes debugging easier.

You use volta to configure the project to use the latest LTS version of Node.js by running:

volta pin node@lts

You can run this command again to update the version.

Getting started

Backend

1. Update Grafana plugin SDK for Go dependency to the latest minor version:

   go get -u github.com/grafana/grafana-plugin-sdk-go
   go mod tidy
   

2. Build backend plugin binaries for Linux, Windows and Darwin:

   mage -v
   

3. List all available Mage targets for additional commands:

   mage -l
   

Frontend

1. Install dependencies

   npm install
   

2. Build plugin in development mode and run in watch mode

   npm run dev
   

3. Build plugin in production mode

   npm run build
   

4. Run the tests (using Jest)

   # Runs the tests and watches for changes, requires git init first
   npm run test
   Exits after running all the tests
   npm run test:ci
   

5. Spin up a Grafana instance and run the plugin inside it (using Docker)

   npm run server
   

6. Run the E2E tests (using Cypress)

   # Spins up a Grafana instance first that we tests against
   npm run server
   Starts the tests
   npm run e2e
   

7. Run the linter

   npm run lint
   or
   npm run lint:fix