Home
Softono
s

surrealdb

Professional software vendor delivering innovative solutions on the Softono platform. Specialized in both open-source and proprietary software development.

Total Products
2

Software by surrealdb

surrealdb/surrealdb
Open Source

surrealdb/surrealdb

<a href="https://surrealdb.com#gh-dark-mode-only" target="_blank"> <img width="100%" src="/img/white/hero.png" alt="SurrealDB Hero"> </a> <a href="https://surrealdb.com#gh-light-mode-only" target="_blank"> <img width="100%" src="/img/black/hero.png" alt="SurrealDB Hero"> </a> <p align="center"> <a href="https://github.com/surrealdb/surrealdb"><img src="https://img.shields.io/github/v/release/surrealdb/surrealdb?color=ff00a0&include_prereleases&label=version&sort=semver&style=flat-square"></a> &nbsp; <a href="https://github.com/surrealdb/surrealdb"><img src="https://img.shields.io/badge/built_with-Rust-dca282.svg?style=flat-square"></a> &nbsp; <a href="https://github.com/surrealdb/surrealdb/actions"><img src="https://img.shields.io/github/actions/workflow/status/surrealdb/surrealdb/ci.yml?style=flat-square&branch=main"></a> &nbsp; <a href="https://github.com/surrealdb/license"><img src="https://img.shields.io/badge/license-BSL_1.1-00bfff.svg?style=flat-square"></a> </p> <p align="center"> <a href="https://hub.docker.com/repository/docker/surrealdb/surrealdb"><img src="https://img.shields.io/docker/pulls/surrealdb/surrealdb?label=docker%20pulls&style=flat-square"></a> &nbsp; <a href="https://crates.io/crates/surrealdb"><img src="https://img.shields.io/crates/d/surrealdb?color=dca282&label=rust&style=flat-square"></a> &nbsp; <a href="https://www.npmjs.com/package/surrealdb.js"><img src="https://img.shields.io/npm/dt/surrealdb.js?color=f7df1e&label=javascript&style=flat-square"></a> &nbsp; <a href="https://pypi.org/project/surrealdb/"><img src="https://img.shields.io/pepy/dt/surrealdb?color=426c99&label=python&style=flat-square"></a> &nbsp; <a href="https://www.nuget.org/packages/SurrealDb.Net"><img src="https://img.shields.io/nuget/dt/surrealdb.net?color=4c2dcc&label=.NET&style=flat-square"></a> &nbsp; <a href="https://packagist.org/packages/surrealdb/surrealdb.php"><img src="https://img.shields.io/packagist/dt/surrealdb/surrealdb.php?color=4d588b&label=php&style=flat-square"></a> &nbsp; <a href="https://hub.docker.com/repository/docker/surrealdb/surrealdb"><img src="https://img.shields.io/github/downloads/surrealdb/surrealdb/total?color=8259dd&label=github%20downloads&style=flat-square"></a> </p> <p align="center"> <a href="https://surrealdb.com/discord"><img src="https://img.shields.io/discord/902568124350599239?label=discord&style=flat-square&color=5a66f6" alt="Discord"></a> &nbsp; <a href="https://x.com/surrealdb"><img src="https://img.shields.io/badge/x-follow_us-222222.svg?style=flat-square" alt="X"></a> &nbsp; <a href="https://dev.to/surrealdb"><img src="https://img.shields.io/badge/dev-join_us-86f7b7.svg?style=flat-square" alt="Dev"></a> &nbsp; <a href="https://www.linkedin.com/company/surrealdb/"><img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=flat-square" alt="LinkedIn"></a> &nbsp; <a href="https://www.youtube.com/@surrealdb"><img src="https://img.shields.io/badge/youtube-subscribe-fc1c1c.svg?style=flat-square" alt="YouTube"></a> </p> <p align="center"> <a href="https://surrealdb.com/blog"><img height="25" src="./img/social/blog.svg" alt="Blog"></a> &nbsp; <a href="https://github.com/surrealdb/surrealdb"><img height="25" src="./img/social/github.svg" alt="Github"></a> &nbsp; <a href="https://www.linkedin.com/company/surrealdb/"><img height="25" src="./img/social/linkedin.svg" alt="LinkedIn"></a> &nbsp; <a href="https://x.com/surrealdb"><img height="25" src="./img/social/x.svg" alt="X"></a> &nbsp; <a href="https://www.youtube.com/@surrealdb"><img height="25" src="./img/social/youtube.svg" alt="YouTube"></a> &nbsp; <a href="https://dev.to/surrealdb"><img height="25" src="./img/social/dev.svg" alt="Dev"></a> &nbsp; <a href="https://surrealdb.com/discord"><img height="25" src="./img/social/discord.svg" alt="Discord"></a> &nbsp; <a href="https://stackoverflow.com/questions/tagged/surrealdb"><img height="25" src="./img/social/stack-overflow.svg" alt="Stack Overflow"></a> </p> <br> <h2><img height="20" src="./img/whatissurreal.svg">&nbsp;&nbsp;What is SurrealDB?</h2> SurrealDB is a multi-model database built in Rust designed to unify multiple data models into a single engine. SurrealDB combines document, graph, relational, time-series, geospatial and key-value data types with powerful search and retrieval functionalities (full-text, vector, hybrid) and real-time and event-driven capabilities, enabling developers to build powerful applications faster and more efficiently. SurrealDB can also be used as a backend-as-a-service given its support for end user authentication. Given that it’s a single Rust binary, SurrealDB can run embedded (in‐app), in the browser (via WebAssembly), in the edge, self-hosted as single backend node, or in a distributed cluster in the cloud. SurrealDB is used for data-intensive systems such as applications requiring multiple data types, data layer for AI agents, knowledge graphs, real-time apps (e.g. recommendation engines, fraud detection systems) and embedded/edge systems. With SurrealDB, you can simplify your database and API infrastructure, reduce development time, and build secure, performant apps quickly and cost-effectively. **Key features of SurrealDB include:** - **Reduces development time**: SurrealDB simplifies your database and API stack by removing the need for most server-side components, allowing you to build secure, performant apps faster and cheaper. - **Multi-model**: native multi-model support for document, graph, relational (enforcing schema and schemaless), time-series, geospatial and retrieval (full-text, vector, hybrid). This is offered natively through SurrealQL, SurrealDB's SQL-like intuitive query language. - **Real-time collaborative API backend service:** SurrealDB functions as both a database and an API backend service, enabling real-time collaboration. - **Support for multiple querying languages:** SurrealDB supports SQL querying from client devices, GraphQL, ACID transactions, WebSocket connections, structured and unstructured data, graph querying, full-text and vector indexing, and geospatial querying. - **Granular access control**: SurrealDB provides row-level permissions-based access control, giving you the ability to manage data access with precision. View the [features](https://surrealdb.com/features), the latest [releases](https://surrealdb.com/releases), and [documentation](https://surrealdb.com/docs). <img width="100%" src="./img/interface.png" alt="Surrealist"> <h2><img height="20" src="./img/contents.svg">&nbsp;&nbsp;Contents</h2> - [Database, API, and permissions](#database-api-and-permissions) - [Tables, documents, and graph](#tables-documents-and-graph) - [Advanced inter-document relations and analysis. No JOINs. No pain.](#advanced-inter-document-relations-and-analysis-no-joins-no-pain) - [Simple schema definition for frontend and backend development](#simple-schema-definition-for-frontend-and-backend-development) - [Connect and query directly from web-browsers and client devices](#connect-and-query-directly-from-web-browsers-and-client-devices) - [Query the database with the tools you want](#query-the-database-with-the-tools-you-want) - [Realtime live queries and data changes direct to application](#realtime-live-queries-and-data-changes-direct-to-application) - [Scale effortlessly to hundreds of nodes for high-availability and scalability](#scale-effortlessly-to-hundreds-of-nodes-for-high-availability-and-scalability) - [Extend your database with JavaScript functions](#extend-your-database-with-javascript-functions) - [Designed to be embedded or to run distributed in the cloud](#designed-to-be-embedded-or-to-run-distributed-in-the-cloud) <h2><img height="20" src="./img/features.svg">&nbsp;&nbsp;Features</h2> - [x] Database server, or embedded library - [x] Multi-row, multi-table ACID transactions - [x] Single-node, or highly-scalable distributed mode - [x] Record links and directed typed graph connections - [x] Store structured and unstructured data - [x] Incrementally computed views for pre-computed advanced analytics - [x] Realtime-API layer, and security permissions built in - [x] Store and model data in any way with tables, documents, and graph - [x] Simple schema definition for frontend and backend development - [x] Connect and query directly from web-browsers and client devices - [x] Use embedded JavaScript functions for custom advanced functionality - [x] MCP (Model Context Protocol) server for LLM and AI-agent integration <h2><img height="20" src="./img/documentation.svg">&nbsp;&nbsp;Documentation</h2> For guidance on installation, development, deployment, and administration, take a look at the following resources: - Documentation: https://surrealdb.com/docs - SurrealDB University: https://surrealdb.com/learn - Aeon's Surreal Renaissance (interactive book): https://surrealdb.com/learn/book <h2><img height="20" src="./img/gettingstarted.svg">&nbsp;&nbsp;Getting started</h2> Getting started with SurrealDB is as easy as starting up the SurrealDB database server, choosing your platform, and integrating its SDK into your code. You can easily get started with your platform of choice by reading one of our tutorials. **Server side code** <p> <a href="https://surrealdb.com/docs/integration/sdks/rust"><img width=60 title="Rust" src="https://raw.githubusercontent.com/surrealdb/icons/main/rust.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/javascript"><img width=60 title="JavaScript" src="https://raw.githubusercontent.com/surrealdb/icons/main/javascript.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/sdk/javascript/engines/wasm"><img width=60 title="WebAssembly" src="https://raw.githubusercontent.com/surrealdb/icons/main/webassembly.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/sdk/javascript/engines/node"><img width=60 title="Node.js" src="https://raw.githubusercontent.com/surrealdb/icons/main/nodejs.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/javascript"><img width=60 title="Deno" src="https://raw.githubusercontent.com/surrealdb/icons/main/deno.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/python"><img width=60 title="Python" src="https://raw.githubusercontent.com/surrealdb/icons/main/python.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/golang"><img width=60 title="Golang" src="https://raw.githubusercontent.com/surrealdb/icons/main/golang.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/dotnet"><img width=60 title=".NET" src="https://raw.githubusercontent.com/surrealdb/icons/main/dotnet.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/php"><img width=60 title="PHP" src="https://raw.githubusercontent.com/surrealdb/icons/main/php.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/java"><img width=60 title="Java" src="https://raw.githubusercontent.com/surrealdb/icons/main/java.svg" /></a> </p> **Client side apps** <p> <a href="https://surrealdb.com/docs/integration/sdks/javascript"><img width=60 title="JavaScript" src="https://raw.githubusercontent.com/surrealdb/icons/main/javascript.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/sdk/javascript/engines/wasm"><img width=60 title="WebAssembly" src="https://raw.githubusercontent.com/surrealdb/icons/main/webassembly.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/javascript"><img width=60 title="React" src="https://raw.githubusercontent.com/surrealdb/icons/main/reactjs.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/javascript"><img width=60 title="Next.js" src="https://raw.githubusercontent.com/surrealdb/icons/main/nextjs.svg" /></a> &nbsp; <a href="https://surrealdb.com/docs/integration/sdks/ember"><img width=60 title="Ember.js" src="https://raw.githubusercontent.com/surrealdb/icons/main/emberjs.svg" /></a> </p> <h2><img height="20" src="/img/cloud.svg?raw=true">&nbsp;&nbsp;SurrealDB Cloud</h2> <a href="https://surrealdb.com/cloud#gh-dark-mode-only" target="_blank"> <img width="100%" src="/img/white/cloud.png" alt="SurrealDB Cloud"> </a> <a href="https://surrealdb.com/cloud#gh-light-mode-only" target="_blank"> <img width="100%" src="/img/black/cloud.png" alt="SurrealDB Cloud"> </a> SurrealDB is available as a [managed cloud service](https://app.surrealdb.com/overview). Forget about infrastructure operations, monitoring, backups or capacity planning. [SurrealDB Cloud](https://surrealdb.com/cloud) allows you to focus on building great products using the power and flexibility of SurrealDB in just a few clicks. Grow from prototype to enterprise-scale. The SurrealDB Cloud scalable architecture allows your database to evolve as your application grows, ensuring you are always ahead of demand. However if you want to deploy SurrealDB yourself, keep reading below. <h2><img height="20" src="./img/installation.svg">&nbsp;&nbsp;Installation</h2> SurrealDB is designed to be simple to install and simple to run - using just one command from your terminal. In addition to traditional installation, SurrealDB can be installed and run with HomeBrew, Docker, or using any other container orchestration tool such as Docker Compose, Docker Swarm, Rancher, or in Kubernetes. <h4><a href="https://surrealdb.com/install"><img width="20" src="./img/apple.svg"></a>&nbsp;Install on macOS</h4> The quickest way to get going with SurrealDB on macOS is to use Homebrew. This will install both the command-line tools, and the SurrealDB server as a single executable. If you don't use Homebrew, follow the instructions for Linux below to install SurrealDB. ```bash brew install surrealdb/tap/surreal ``` If you want to test a version with the latest features, published every night, install the `nightly` version: ```bash brew install surrealdb/tap/surreal-nightly ``` <h4><a href="https://surrealdb.com/install"><img width="20" src="./img/linux.svg"></a>&nbsp;Install on Linux</h4> The easiest and preferred way to get going with SurrealDB on Unix operating systems is to install and use the SurrealDB command-line tool. Run the following command in your terminal and follow the on-screen instructions. ```bash curl --proto '=https' --tlsv1.2 -sSf https://install.surrealdb.com | sh ``` If you want to run a beta release, before the next version is released, the `beta` version: ```bash curl --proto '=https' --tlsv1.2 -sSf https://install.surrealdb.com | sh -s -- --beta ``` If you want to test a version with the latest features, published every night, install the `nightly` version: ```bash curl --proto '=https' --tlsv1.2 -sSf https://install.surrealdb.com | sh -s -- --nightly ``` <h4><a href="https://surrealdb.com/install"><img width="20" src="./img/windows.svg"></a>&nbsp;Install on Windows</h4> The easiest and preferred way to get going with SurrealDB on Windows is to install and use the SurrealDB command-line tool. Run the following command in your terminal and follow the on-screen instructions. ```ps1 iwr https://windows.surrealdb.com -useb | iex ``` If you want to test a version with the latest features, published every night, install the `nightly` version: ```ps1 iex "& { $(irm https://windows.surrealdb.com) } -Nightly" ``` <h4><a href="https://surrealdb.com/install"><img width="20" src="./img/docker.svg"></a>&nbsp;Run using Docker</h4> Docker can be used to manage and run SurrealDB database instances without the need to install any command-line tools. The SurrealDB docker container contains the full command-line tools for importing and exporting data from a running server, or for running a server itself. ```bash docker run --rm --pull always --name surrealdb -p 8000:8000 surrealdb/surrealdb:latest start ``` For just getting started with a development server running in memory, you can pass the container a basic initialization to set the user and password as root and enable logging. ```bash docker run --rm --pull always --name surrealdb -p 8000:8000 surrealdb/surrealdb:latest start --log info --user root --pass root memory ``` <h2><img height="20" src="./img/features.svg">&nbsp;&nbsp;Quick look</h2> With strongly-typed data types, data can be fully modelled right in the database. ```surrealql UPDATE person SET waist = <int> "34", height = <float> 201, score = <decimal> 0.3 + 0.3 + 0.3 + 0.1 ; ``` Store dynamically computed fields which are calculated when retrieved. ```surrealql DEFINE FIELD can_drive ON TABLE person COMPUTED time::now() > birthday + 18y; CREATE person SET birthday = d"2007-06-22"; ; ``` Easily work with unstructured or structured data, in schema-less or schema-full mode. ```surrealql -- Create a schemafull table DEFINE TABLE user SCHEMAFULL; -- Specify fields on the user table DEFINE FIELD name ON TABLE user TYPE object; DEFINE FIELD name.first ON TABLE user TYPE string; DEFINE FIELD name.last ON TABLE user TYPE string; DEFINE FIELD email ON TABLE user TYPE string ASSERT string::is_email($value); -- Add a unique index on the email field preventing duplicate values DEFINE INDEX email ON TABLE user COLUMNS email UNIQUE; -- Create a new event whenever a user changes their email address DEFINE EVENT email ON TABLE user WHEN $before.email != $after.email THEN ( CREATE event SET user = $value, time = time::now(), value = $after.email, action = 'email_changed' ); ``` Connect records together with fully directed graph edge connections. ```surrealql -- Add a graph edge between user:tobie and article:surreal RELATE user:tobie->write->article:surreal SET time.written = time::now() ; -- Add a graph edge between specific users and developers LET $from = (SELECT users FROM company:surrealdb); LET $devs = (SELECT * FROM user WHERE tags CONTAINS 'developer'); RELATE $from->like->$devs UNIQUE SET time.connected = time::now() ; ``` Query data flexibly with advanced expressions and graph queries. ```surrealql -- Select a nested array, and filter based on an attribute SELECT emails[WHERE active = true] FROM person; -- Select all 1st, 2nd, and 3rd level people who this specific person record knows, or likes, as separate outputs SELECT ->knows->(? AS f1)->knows->(? AS f2)->(knows, likes AS e3 WHERE influencer = true)->(? AS f3) FROM person:tobie; -- Select all person records (and their recipients), who have sent more than 5 emails SELECT *, ->sent->email->to->person FROM person WHERE count(->sent->email) > 5; -- Select other products purchased by people who purchased this laptop SELECT <-purchased<-person->purchased->product FROM product:laptop; -- Select products purchased by people in the last 3 weeks who have purchased the same products that we purchased SELECT ->purchased->product<-purchased<-person->(purchased WHERE created_at > time::now() - 3w)->product FROM person:tobie; ``` Store GeoJSON geographical data types, including points, lines and polygons. ```surrealql UPDATE city:london SET centre = (-0.118092, 51.509865), boundary = { type: "Polygon", coordinates: [[ [-0.38314819, 51.37692386], [0.1785278, 51.37692386], [0.1785278, 51.61460570], [-0.38314819, 51.61460570], [-0.38314819, 51.37692386] ]] } ; ``` Write custom embedded logic using JavaScript functions. ```surrealql CREATE film SET ratings = [ { rating: 6, user: user:bt8e39uh1ouhfm8ko8s0 }, { rating: 8, user: user:bsilfhu88j04rgs0ga70 }, ], featured = function() { return this.ratings.filter(r => { return r.rating >= 7; }).map(r => { return { ...r, rating: r.rating * 10 }; }); } ; ``` Specify granular access permissions for client and application access. ```surrealql -- Specify access permissions for the 'post' table DEFINE TABLE post SCHEMALESS PERMISSIONS FOR select -- Published posts can be selected WHERE published = true -- A user can select all their own posts OR user = $auth.id FOR create, update -- A user can create or update their own posts WHERE user = $auth.id FOR delete -- A user can delete their own posts WHERE user = $auth.id -- Or an admin can delete any posts OR $auth.admin = true ; ``` <h2><img height="20" src="./img/features.svg">&nbsp;&nbsp;Why SurrealDB?</h2> <p> <img width="49%" src="./img/illustrations/database-api-security.jpg" /> <img width="49%" src="./img/illustrations/multimodel-database.jpg" /> </p> ### Database, API, and permissions SurrealDB combines the database layer, the querying layer, and the API and authentication layer into one platform. Advanced table-based and row-based customisable access permissions allow for granular data access patterns for different types of users. There's no need for custom backend code and security rules with complicated database development. ### Tables, documents, and graph As a multi-model database, SurrealDB enables developers to use multiple techniques to store and model data, without having to choose a method in advance. With the use of tables, SurrealDB has similarities with relational databases, but with the added functionality and flexibility of advanced nested fields and arrays. Inter-document record links allow for simple to understand and highly-performant related queries without the use of JOINs, eliminating the N+1 query problem. <p> <img width="49%" src="./img/illustrations/graph-database.jpg" /> <img width="49%" src="./img/illustrations/schema-direct-to-client.jpg" /> </p> ### Advanced inter-document relations and analysis. No JOINs. No pain. With full graph database functionality SurrealDB enables more advanced querying and analysis. Records (or vertices) can be connected to one another with edges, each with its own record properties and metadata. Simple extensions to traditional SQL queries allow for multi-table, multi-depth document retrieval, efficiently in the database, without the use of complicated JOINs and without bringing the data down to the client. ### Simple schema definition for frontend and backend development With SurrealDB, specify your database and API schema in one place, and define column rules and constraints just once. Once a schema is defined, database access is automatically granted to the relevant users. No more custom API code, and no more GraphQL integration. Simple, flexible, and ready for production in minutes not months. <p> <img width="49%" src="./img/illustrations/browser-sync.jpg" /> <img width="49%" src="./img/illustrations/multiple-integrations.jpg" /> </p> ### Connect and query directly from web-browsers and client devices Connect directly to SurrealDB from any end-user client device. Run SurrealQL queries directly within web-browsers, ensuring that users can only view or modify the data that they are allowed to access. Highly-performant WebSocket connections allow for efficient bi-directional queries, responses and notifications. ### Query the database with the tools you want Your data, your choice. SurrealDB is designed to be flexible to use, with support for SurrealQL, GraphQL (coming soon), CRUD support over REST, and JSON-RPC querying and modification over WebSockets. With direct-to-client connection with in-built permissions, SurrealDB speeds up the development process, and fits in seamlessly into any tech stack. <p> <img width="49%" src="./img/illustrations/realtime-live-queries.jpg" /> <img width="49%" src="./img/illustrations/scale-up.jpg" /> </p> ### Realtime live queries and data changes direct to application SurrealDB keeps every client device in-sync with data modifications pushed in realtime to the clients, applications, end-user devices, and server-side libraries. Live SQL queries allow for advanced filtering of the changes to which a client subscribes, and efficient data formats, including DIFFing and PATCHing enable highly-performant web-based data syncing. ### Scale effortlessly to hundreds of nodes for high-availability and scalability SurrealDB can be run as a single in-memory node, or as part of a distributed cluster - offering highly-available and highly-scalable system characteristics. Designed from the ground up to run in a distributed environment, SurrealDB makes use of special techniques when handling multi-table transactions, and document record IDs - with no use of table or row locks. <p> <img width="49%" src="./img/illustrations/database-plugins.jpg" /> <img width="49%" src="./img/illustrations/cloud-or-embedded.jpg" /> </p> ### Extend your database with JavaScript functions Embedded JavaScript functions allow for advanced, custom functionality, with computation logic being moved to the data layer. This improves upon the traditional approach of moving data to the client devices before applying any computation logic, ensuring that only the necessary data is transferred remotely. These advanced JavaScript functions, with support for the ES2020 standard, allow any developer to analyse the data in ever more simple-yet-advanced ways. ### Designed to be embedded or to run distributed in the cloud Built entirely in Rust as a single library, SurrealDB is designed to be used as both an embedded database library with advanced querying functionality, and as a database server which can operate in a distributed cluster. With low memory usage and cpu requirements, the system requirements have been specifically thought through for running in all types of environment. <h2><img height="20" src="./img/community.svg">&nbsp;&nbsp;Community</h2> Join our growing community around the world, for help, ideas, and discussions regarding SurrealDB. - View our official [Blog](https://surrealdb.com/blog) - Chat live with us on [Discord](https://surrealdb.com/discord) - Follow us on [X](https://x.com/surrealdb) - Connect with us on [LinkedIn](https://www.linkedin.com/company/surrealdb/) - Join the discussion on [Reddit](https://www.reddit.com/r/surrealdb/) - Visit us on [YouTube](https://www.youtube.com/@surrealdb) - Join our [Dev community](https://dev.to/surrealdb) - Questions tagged #surrealdb on [Stack Overflow](https://stackoverflow.com/questions/tagged/surrealdb) <h2><img height="20" src="./img/contributing.svg">&nbsp;&nbsp;Contributing</h2> We would &nbsp;<img width="15" src="./img/love.svg">&nbsp; for you to get involved with SurrealDB development! If you wish to help, you can learn more about how you can contribute to this project in the [contribution guide](CONTRIBUTING.md). **For maintainers**: See the [release process documentation](doc/RELEASING.md) for information about performing releases. <h2><img height="20" src="./img/security.svg">&nbsp;&nbsp;Security</h2> For security issues, view our [vulnerability policy](https://github.com/surrealdb/surrealdb/security/policy), view our [Trust and Security page](https://surrealdb.com/legal/category/security), and kindly email us at [[email protected]](mailto:[email protected]) instead of posting a public issue on GitHub. <h2><img height="20" src="./img/license.svg">&nbsp;&nbsp;License</h2> Source code for SurrealDB is variously licensed under a number of different licenses. A copy of each license can be found in [each repository](https://github.com/surrealdb). - Libraries and SDKs, each located in its own distinct repository, are released under either the [Apache License 2.0](https://github.com/surrealdb/license/blob/main/APL.txt) or [MIT License](https://github.com/surrealdb/license/blob/main/MIT.txt). - Certain core database components, each located in its own distinct repository, are released under the [Apache License 2.0](https://github.com/surrealdb/license/blob/main/APL.txt). - Core database code for SurrealDB, located in [this repository](https://github.com/surrealdb/surrealdb), is released under the [Business Source License 1.1](/LICENSE). For more information, see the [licensing information](https://github.com/surrealdb/license).

Backend as a Service NoSQL Databases
32.3K Github Stars
n8n-nodes-surrealdb
Open Source

n8n-nodes-surrealdb

<br> <p align="center"> <img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/surreal.svg" /> &nbsp; <img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/n8n.svg" /> </p> <h3 align="center">The official n8n node for SurrealDB.</h3> <br> <p align="center"> <a href="https://github.com/surrealdb/surrealdb.js"><img src="https://img.shields.io/badge/status-beta-ff00bb.svg?style=flat-square"></a> &nbsp; <a href="https://surrealdb.com/docs/integrations/data-management/n8n"><img src="https://img.shields.io/badge/docs-view-44cc11.svg?style=flat-square"></a> &nbsp; <a href="https://www.npmjs.com/package/@surrealdb/n8n-nodes-surrealdb"><img src="https://img.shields.io/npm/v/@surrealdb/n8n-nodes-surrealdb?style=flat-square"></a> &nbsp; <a href="https://www.npmjs.com/package/@surrealdb/n8n-nodes-surrealdb"><img src="https://img.shields.io/npm/dm/@surrealdb/n8n-nodes-surrealdb?style=flat-square"></a> &nbsp; <a href="https://github.com/surrealdb/n8n-nodes-surrealdb/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-1d9bf0.svg?style=flat-square"></a> </p> <p align="center"> <a href="https://surrealdb.com/discord"><img src="https://img.shields.io/discord/902568124350599239?label=discord&style=flat-square&color=5a66f6"></a> &nbsp; <a href="https://twitter.com/surrealdb"><img src="https://img.shields.io/badge/twitter-follow_us-1d9bf0.svg?style=flat-square"></a> &nbsp; <a href="https://www.linkedin.com/company/surrealdb/"><img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=flat-square"></a> &nbsp; <a href="https://www.youtube.com/@SurrealDB"><img src="https://img.shields.io/badge/youtube-subscribe-fc1c1c.svg?style=flat-square"></a> </p> # n8n-nodes-surrealdb The official n8n node for SurrealDB. It provides both action and tool nodes to interact with a SurrealDB database, allowing you to create, read, update, and delete records, as well as execute custom SurrealQL queries. [n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform. <p align="center"> <img src="docs/images/node-screenshot.png" alt="SurrealDB node in n8n"> </p> ## Documentation View the node documentation [here](https://surrealdb.com/docs/integrations/data-management/n8n). ## Learn SurrealDB - SurrealDB University: https://surrealdb.com/learn/fundamentals - Aeon's Surreal Renaissance (Interative book): https://surrealdb.com/learn/book - Documentation: https://surrealdb.com/docs ## Table of Contents - [Important Notes](#important-notes) - [Features](#features) - [Installation](#installation) - [Configuration](#configuration) - [Operations](#operations) - [Error Handling](#error-handling) - [Understanding SurrealDB and n8n Integration](#understanding-surrealdb-and-n8n-integration) - [Resources](#resources) - [Development](#development) - [Contributing](#contributing) - [License](#license) ## Important Notes - **Self-Hosted Only**: As with all community nodes, this node works only with self-hosted n8n instances, not with n8n Cloud. - **HTTP/HTTPS Only**: Due to n8n's architecture, this node only supports HTTP/HTTPS connections to SurrealDB. WebSocket connections (WS/WSS) are not supported. - **Tool Node Support**: To use this node as a tool in AI workflows, you must set the environment variable `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true`. ## Features - **Dual Node Types**: Functions as both an action node and a tool node for AI workflows - **Complete CRUD Operations**: Create, read, update, and delete SurrealDB records - **Custom Queries**: Execute any SurrealQL query with full parameter support - **Enhanced Query Builder**: Visual interface for building SELECT queries with WHERE, ORDER BY, GROUP BY, and other clauses - **Table Operations**: List fields and explore table structure - **Relationship Support**: Query and manage record relationships - **Native Data Format**: Works with SurrealDB's native data formats - **Connection Pooling**: Configurable connection pooling for improved performance and resource management - **Enhanced Error Handling**: Comprehensive error classification, automatic retry logic, and connection recovery - **Intelligent Recovery**: Different error handling strategies for different operation types - **Detailed Error Reporting**: Rich error context with categorization and severity levels - **Pool Monitoring**: Built-in pool statistics and performance monitoring ## Installation ### Prerequisites 1. You need a self-hosted n8n instance (v0.214.0 or later recommended) 2. You need access to a SurrealDB instance (v1.0.0 or later recommended) ### Installation Steps 1. Open your n8n instance 2. Go to **Settings** > **Community Nodes** 3. Click **Install** 4. Enter `@surrealdb/n8n-nodes-surrealdb` and click **Install** 5. Restart your n8n instance if prompted ## Configuration ### Credentials To use the SurrealDB node, you need to create credentials with the following properties: * **Connection String** - The connection string to your SurrealDB instance (must start with `http://` or `https://`). WebSocket connections (`ws://` or `wss://`) are not supported. * **Authentication** - Choose the authentication scope: * **Root** - Full access to all namespaces and databases * **Namespace** - Access limited to a specific namespace * **Database** - Access limited to a specific database within a namespace * **Username** - Username for authentication * **Password** - Password for authentication * **Namespace** - Target namespace (required for Namespace and Database authentication) * **Database** - Target database (required for Database authentication) #### Authentication Types and Namespace/Database Handling The authentication type you choose affects how namespace and database information is handled: 1. **Root Authentication**: * Provides access to all namespaces and databases * Namespace and Database fields in credentials are optional * You can override namespace/database at the node level for each operation 2. **Namespace Authentication**: * Provides access to all databases within a specific namespace * Namespace field in credentials is required * Database field in credentials is optional * You can override the database at the node level for each operation 3. **Database Authentication**: * Provides access to a specific database within a specific namespace * Both Namespace and Database fields in credentials are required * You can still override these at the node level for specific operations #### Node-Level Namespace and Database Overrides For most operations, you can override the namespace and database settings from your credentials: 1. In the node configuration, expand the **Options** section 2. Enter values in the **Namespace** and/or **Database** fields 3. These values will take precedence over the credential settings for that specific operation 4. You will be required to provide a namespace when using Namespace authentication 5. You will be required to provide both a namespace and database when using Database authentication ## Operations The SurrealDB node provides a fairly comprehensive set of operations organized by resource type. For most anything not covered, you can use the Execute Query operation. ### Record Operations * **Create Record** - Create a single record in a table * **Get Record** - Retrieve a specific record by ID * **Update Record** - Update a specific record by ID * **Upsert Record** - Create or update a record (insert if not exists, update if exists) * **Delete Record** - Delete a specific record by ID ### Table Operations * **Get All Records** - Retrieve all records from a table * **Create Many** - Create multiple records in a table * **Get Many** - Retrieve multiple records by IDs * **Update All Records** - Update all records in a table * **Delete All Records** - Delete all records from a table * **Merge All Records** - Merge the same data into all records in a table * **Create Table** - Define a new table with optional schema * **Delete Table** - Remove a table from the database * **Get Table** - Retrieve information about a table ### Field Operations * **List Fields** - List all fields defined on a table * **Create Field** - Create a new field on a table * **Delete Field** - Delete a field from a table ### Index Operations * **Create Index** - Create a new index on a table * **Delete Index** - Delete an index from a table ### Relationship Operations * **Create Relationship** - Create a relationship between two records * **Delete Relationship** - Delete a relationship between records * **Query Relationships** - Query relationships between records ### Query Operations * **Execute Query** - Execute a raw SurrealQL query with parameters * **Build Select Query** - Build SELECT queries using a visual interface with WHERE, ORDER BY, GROUP BY, and other clauses ### System Operations * **Health Check** - Check if the database instance is responsive * **Version** - Get the version of the SurrealDB instance * **Get Pool Statistics** - Monitor connection pool performance and statistics ## Understanding SurrealDB and n8n Integration ### Connection Protocol **Important**: Due to n8n's architecture, this node only supports HTTP/HTTPS connections to SurrealDB. WebSocket connections (WS/WSS) are not supported. - Your connection string must start with `http://` or `https://` (not `ws://` or `wss://`) - When configuring your SurrealDB instance, ensure it's accessible via HTTP/HTTPS - If you're using SurrealDB Cloud or another instance that only offers WebSocket connections, you'll need to set up a self-hosted SurrealDB instance with HTTP enabled - This limitation is due to how n8n handles connections and executes node operations ### Connection Pooling The SurrealDB node includes comprehensive connection pooling to improve performance and resource management. Connection pooling allows the node to reuse database connections across multiple operations, reducing connection overhead and improving response times. #### Pool Configuration Options You can configure the connection pool through the "Connection Pooling" options in any node operation: - **Max Connections** (default: 10): Maximum number of connections in the pool - **Min Connections** (default: 2): Minimum number of connections to keep in the pool - **Acquire Timeout** (default: 30000ms): Maximum time to wait for a connection from the pool - **Health Check Interval** (default: 60000ms): Interval between health checks for pool connections - **Max Idle Time** (default: 300000ms): Maximum time a connection can remain idle before being closed - **Retry Attempts** (default: 3): Number of retry attempts for failed connection acquisitions - **Retry Delay** (default: 1000ms): Delay between retry attempts #### Pool Monitoring Use the **System > Get Pool Statistics** operation to monitor pool performance: ```json { "poolStatistics": { "totalConnections": 5, "activeConnections": 2, "idleConnections": 3, "waitingRequests": 0, "totalRequests": 150, "failedRequests": 2, "averageResponseTime": 45, "successRate": 99 }, "performance": { "averageResponseTimeMs": 45, "requestsPerSecond": 2, "errorRate": 1 }, "poolHealth": { "utilizationRate": 40, "availableConnections": 3, "waitingRequests": 0 } } ``` #### Benefits of Connection Pooling - **Improved Performance**: Reuses connections instead of creating new ones for each operation - **Resource Management**: Limits the number of concurrent connections to prevent database overload - **Automatic Health Checks**: Monitors connection health and removes unhealthy connections - **Connection Recovery**: Automatically retries failed connection acquisitions - **Idle Connection Cleanup**: Removes unused connections to free up resources #### Pool Lifecycle - **Initialization**: Pool is created when the first operation is executed - **Connection Acquisition**: Operations get connections from the pool or create new ones if needed - **Connection Release**: Connections are returned to the pool after each operation - **Health Monitoring**: Regular health checks ensure connections remain valid - **Cleanup**: Pool is automatically closed when the node is deactivated #### SurrealDB HTTP vs WebSocket SurrealDB supports both HTTP and WebSocket protocols: - **HTTP/HTTPS**: Used for stateless connections, ideal for individual queries - **WebSocket (WS/WSS)**: Used for stateful connections, better for real-time applications This node uses the HTTP/HTTPS protocol exclusively, which means: 1. Each operation creates a new connection to SurrealDB 2. The connection is closed after the operation completes 3. No persistent connection is maintained between operations ### SurrealDB Result Handling SurrealDB operations often return empty results rather than errors when no matching data is found. This behavior differs from many other databases and can be important to understand when building workflows: - **Empty Results vs. Errors**: A query for a non-existent record returns an empty result, not an error - **Always Output Data**: The "Always Output Data" option is particularly useful with SurrealDB to ensure your workflow continues even when no results are found ### Working with SurrealDB Data Types SurrealDB supports rich data types that map well to n8n's JSON handling: - **Records and IDs**: SurrealDB record IDs use the format `table:id` - **Relationships**: Relationships are first-class citizens in SurrealDB - **Arrays and Objects**: Nested data structures are fully supported ## Error Handling The SurrealDB node includes a comprehensive error handling and recovery system that automatically manages common database issues: ### Automatic Error Classification The system automatically categorizes errors into different types: - **Connection Errors**: Network issues, timeouts, connection refused - **Authentication Errors**: Invalid credentials, unauthorized access - **Query Errors**: Syntax errors, malformed queries - **Validation Errors**: Invalid data, missing required fields - **System Errors**: Database server issues, internal errors ### Intelligent Retry Logic - **Exponential Backoff**: Automatic retry with increasing delays - **Operation-Specific Retries**: Different retry strategies for read vs write operations - **Configurable Limits**: Adjustable retry counts and delays - **Smart Error Filtering**: Only retry on recoverable errors ### Connection Recovery - **Automatic Reconnection**: Reconnects to SurrealDB on connection failures - **Re-authentication**: Automatically re-authenticates after reconnection - **Connection Validation**: Verifies connection health before retrying operations ### Enhanced Error Reporting When `Continue on Fail` is enabled, errors include detailed information: ```json { "error": { "message": "Connection timeout", "category": "TIMEOUT_ERROR", "severity": "MEDIUM", "retryable": true, "context": { "operation": "executeQuery", "itemIndex": 0, "timestamp": "2024-01-15T10:30:00Z", "recoveryStrategy": "CONNECTION_RECOVERY" } } } ``` ### Error Handling Strategies Different operation types use different error handling strategies: - **Read Operations**: Faster retries, continue on low/medium errors - **Write Operations**: More retries, stop on medium+ errors - **Critical Operations**: Minimal retries, stop on any error - **Bulk Operations**: Moderate retries, handle rate limiting For detailed information about the error handling system, see [Error Handling Documentation](docs/ERROR_HANDLING.md). ## Compatibility **Requires SurrealDB server v3.0.0 or later.** For SurrealDB v1.x or v2.x servers, pin `@surrealdb/[email protected]`. Internally uses the `surrealdb` JavaScript SDK v2.x. Connects over HTTP/HTTPS only — WebSocket (`ws://` / `wss://`) is not supported, see [Connection Protocol](#connection-protocol) below. ## Resources * [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/) * [SurrealDB Documentation](https://surrealdb.com/docs) * [SurrealQL Reference](https://surrealdb.com/docs/surrealql) ## Development If you want to contribute to this node: 1. Clone the repository 2. Install dependencies: `npm install` 3. Build the node: `npm run build` 4. Link to your n8n installation for testing: `npm link` 5. In your n8n installation directory: `npm link @surrealdb/n8n-nodes-surrealdb` ### Debug Mode The node includes a centralized debug system that can be enabled via environment variable: ```bash # Enable debug logging export SURREAL_DEBUG=true # Or set to '1' to enable export SURREAL_DEBUG=1 # Disable debug logging (default) export SURREAL_DEBUG=false ``` When debug mode is enabled, the node will output detailed logging information including: - Operation execution details - Query preparation and execution - Parameter validation - Error handling details This is particularly useful for: - Troubleshooting connection issues - Understanding query execution - Debugging parameter handling - Development and testing The debug system is centralized in `src/nodes/SurrealDb/debug.ts` and automatically respects the environment variable setting. ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch: `git checkout -b feature/amazing-feature` 3. Commit your changes: `git commit -m 'Add some amazing feature'` 4. Push to the branch: `git push origin feature/amazing-feature` 5. Open a Pull Request ## Original This code is forked originally from [n8n-nodes-surrealdb](https://github.com/nsxdavid/n8n-nodes-surrealdb), licensed under the [MIT](https://choosealicense.com/licenses/mit/) license. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Storage & Backup Workflow Automation
16 Github Stars