DEV Community: SurrealDB

Empower your agents with the new SurrealDB MCP

Matthew McFadden — Wed, 05 Aug 2026 14:12:49 +0000

Exactly a year ago we released SurrealMCP, a server you had to install and run in order to connect agents to your SurrealDB instance. Today, we're excited to announce the next evolution in agent intelligence with the new hosted SurrealDB MCP server.

With this new SurrealDB MCP server, all you need is to add one URL to your AI tool of choice, sign in with your SurrealDB account, and your assistant can work on your instances or contexts alongside you. Whether you want to deploy a new instance, spin up a new Spectron context, execute queries against your graph, or ask questions about your data, the new SurrealDB MCP server has you covered.

Let's dive into it! 🎉

Getting started

Adding the SurrealDB MCP to your agent

Previously, you would need to add an MCP configuration for every instance or context that you wanted to connect to, and there was no way to provision instances or contexts with an agent. With the new hosted SurrealDB MCP server, you can do all of this and much more by adding a single URL:

https://mcp.surrealdb.com

You can authorise the SurrealDB MCP Server either through signing in to your SurrealDB account, or for fine grained control, create a personal access token from the account portal. That is the whole setup. Once connected, your agent now has the ability to interact with your SurrealDB Cloud resources.

Looking to setup your agent? We have step-by-step guides for setting up with Claude and Cursor. For other configurations, please see our MCP docs.

Deploy and manage resources just by asking

Everything you would normally click through in the SurrealDB Studio dashboard is available in your conversations. Deploy a new instance or context, expand your resources as you grow, or upgrade to the latest version of SurrealDB. When deploying resources, the MCP server can put together a configuration, give you a cost estimation, and wait for your confirmation to kick off.

The same conversation can also cover the rest of the housekeeping such as inviting users to your organisation, managing their access level, checking your monthly spend, and updating your instances.

Ask questions about your data and build with ease

Note
Instance querying is only available on instances running SurrealDB 3.2.3 and above

The usual way to get an AI assistant to look at your database is to copy a schema or a query into a chat window, then paste the results back out again. SurrealDB MCP removes this loop. Simply ask a question in plain language and your assistant finds the right database, writes the query, runs it, and shows you both the query it wrote and what came back.

You don't have to describe the shape of your data first, because it can go and look. Ask how many orders you took last week grouped by status, and it will find the table, work out the fields, and write the aggregate itself. Ask what the customer table actually says, and it will describe the fields and indexes back to you. As a bonus, it's often faster than opening SurrealDB Studio to check for yourself.

It works the other way round too. While you're building something new, you can ask it to create a single table or an entire schema for an enterprise-level app.

Memory that outlasts the conversation

Every new chat normally starts from nothing. A decision your team made three weeks ago is gone unless someone remembers to paste it back in. My favorite feature of SurrealDB MCP is that you can interact directly with Spectron, our memory layer for AI agents, in order to keep a persistent brain related to your chats which can be shared with multiple users.

Simply ask your agent to save a memory or give it documents to read, and it will search through them by meaning rather than by keyword and store it for you. Then, ask your agent to retrieve something later:

Let us know what you think

We'd love to hear your thoughts! Join us on Discord to ask questions, share what you're building, or tell us what you'd like your assistant to be able to do next.

To learn even more about SurrealDB MCP, please check out our MCP docs.

Agentic retrieval for structured data with text-to-surql

Martin Schaer — Tue, 04 Aug 2026 14:00:00 +0000

RAG pipelines are commonly centred around processing unstructured data and indexing it with vectors or BM25. But when you have structured data, things change. You may still need semantic and full-text search, but the main challenge now is how to retrieve the structured data that sits in tables.

Yes, you could create an agent tool with a query to the DB to –for example– fetch the records in the products table that match a specific category. But then, you’ll need a new tool for each other query pattern, and unless you want your agent to have a very limited range of action, this is not the best solution.

This is where text-to-surql comes to help.

Using a retrieval tool

Give the agent tools that speak the language of your database, and you’ll support infinite types of questions from your users [1].

Here's the flow:

The agent, with the LLM doing the reasoning, decides when to hit the database using the retrieval tool, which generates a valid SurrealQL query, executes it, and returns structured results.

The SurrealQL generation tool

SurrealQL is uniquely well-suited for this because it’s a multi-model query language. In a single query, you can traverse graph relationships, filter document fields, and run relational aggregations. That means your agent doesn't need to orchestrate across multiple databases or data layers. One tool, one query, one result.

Let's walk through a real example first.

The tool itself is straightforward to build: a prompt template that includes the schema, a few-shot examples of good SurrealQL queries, and a SurrealDB client to execute the result. We'll cover that later.

User asks: "can you summarize the reviews of my top 3 best selling products?"

The tool generates:

LET $top = SELECT in.{id, name} AS product,
    math::sum(qty) AS total_sales
    FROM REL_PRODUCT_IN_ORDER
    GROUP BY product
    ORDER BY total_sales DESC
    LIMIT 3;

RETURN $top.map(
    |$p| {
        $p + {
            average_rating: (
                SELECT
                    product,
                    math::mean(score) AS avg_rating,
                    math::sum(1) AS review_count
                FROM review
                WHERE product = $p.product.id
                GROUP BY product
            )[0].avg_rating,
            review_count: (
                SELECT
                    product,
                    math::mean(score) AS avg_rating,
                    math::sum(1) AS review_count
                FROM review
                WHERE product = $p.product.id
                GROUP BY product
            )[0].review_count,
            sentiment_breakdown: (
                SELECT
                    sentiment,
                    math::sum(1) AS count
                FROM review
                WHERE product = $p.product.id
                GROUP BY sentiment
                ORDER BY count DESC
            ),
            recent_reviews: (
                SELECT
                    score AS rating,
                    created_at AS date,
                    text,
                    sentiment,
                    flow_sentiment
                FROM review
                WHERE product = $p.product.id
                ORDER BY created_at DESC
                LIMIT 10
            ),
        };
    }
);

Result returned to agent:

[
    {
        average_rating: 4.75f,
        product: {
            id: product:26,
            name: 'Yoga Mat Pro',
        },
        recent_reviews: [
            {
                date: d'2026-04-20T11:11:27.427351302Z',
                rating: 5,
                sentiment: 'possitive',
                text: "I bought this primarily for stretching and cool-down after lifting sessions rather than yoga proper. It does that job perfectly - thick enough that kneeling on a hard floor is comfortable, and it doesn't slide even on polished concrete. Rolled up it's compact enough to slip under my desk. No complaints whatsoever.",
            },
            {
                date: d'2026-04-20T11:11:27.427112844Z',
                rating: 4.5f,
                sentiment: 'possitive',
                text: "Non-slip is not an exaggeration - this mat grips the floor and my hands equally well even in sweaty hot yoga sessions. The 6mm thickness is the sweet spot between cushioning and stability for balance poses. TPE material doesn't have the chemical smell that cheaper PVC mats have. The carrying strap is a bit flimsy but functional.",
            },
        ],
        review_count: 2,
        sentiment_breakdown: [{ count: 2, sentiment: 'possitive' }],
        total_sales: 5,
    },
    {
        average_rating: 4.5f,
        product: {
            id: product:9,
            name: 'Canvas Tote Bag',
        },
        recent_reviews: [
            {
                date: d'2026-04-20T11:11:27.426732636Z',
                rating: 4.5f,
                sentiment: 'possitive',
                text: 'I use this as a daily carry and it holds everything - laptop, gym clothes, lunch, groceries. The interior zipper pocket is a lifesaver for keys and cards. Handles are reinforced and show no signs of wear after months of heavy use. The canvas has a slight stiffness that I actually like.',
            },
        ],
        review_count: 1,
        sentiment_breakdown: [{ count: 1, sentiment: 'possitive' }],
        total_sales: 3,
    },
    {
        average_rating: 5,
        product: {
            id: product:7,
            name: 'Linen Wrap Dress',
        },
        recent_reviews: [
            {
                date: d'2026-04-20T11:11:27.426633136Z',
                rating: 5,
                sentiment: 'possitive',
                text: 'This dress is exactly what summer dressing should be. The linen is lightweight and breathable, the wrap silhouette is flattering on multiple body types, and the tie actually stays put throughout the day. Ordered two in different colors.',
            },
        ],
        review_count: 1,
        sentiment_breakdown: [{ count: 1, sentiment: 'possitive' }],
        total_sales: 2,
    },
];

The agent now has exact numbers and reviews it can cite with confidence and trace back to a specific query against a specific table. That's what auditability looks like in production.

Built-in permissions

SurrealDB's record- and field-level permissions and RBAC model mean that agents only see the data they're supposed to see – enforced at the database layer, not bolted on in application code. Multi-tenant agent deployments become straightforward: each agent session operates within the appropriate permission scope automatically.

Learn more about SurrealDB’s security model.

How to build it

Here's how to put the pattern together from scratch.

Step 1: Define your schema and expose it to the agent

The SurrealQL generation tool needs schema context to know what tables, fields, and indexes it can play with. It needs this information to infer where to get the data from to answer the user’s question.

-- TABLE: product
DEFINE TABLE product SCHEMAFULL;
DEFINE FIELD category ON product TYPE record<category>;
DEFINE FIELD description ON product TYPE string;
DEFINE FIELD embedding ON product TYPE array<float> | none;
DEFINE FIELD name ON product TYPE string;
DEFINE FIELD price ON product TYPE float;

The schema context can be dynamically generated, see snippet below. But once your schema is stable, to avoid extra calls to the DB you can hardcode it (which also gives you more control on what to include in the context) or at least cache it.

-- example of how to dynamically generate your schema context
LET $db = INFO FOR DB;
$db.tables.values() +
$db.users.values() + 
$db.tables.keys().map(|$t| {
    LET $i = INFO FOR TABLE $t;
    $i.fields.?.values() + $i.indexes.?.values()
}).flatten().filter(|$v| !!$v);

Step 2: Build the SurrealQL generation tool

This is a function your agent can call. At minimum it needs:

A system prompt with schema context and a few-shot examples of valid SurrealQL queries.
A SurrealDB client to execute the query and return results
Optional but recommended: catch any errors when executing the query, and ask the LLM to fix them and try again. Without this retry logic within the tool, the agent may retry the tool altogether, but the LLM call that generates the SurrealQL won’t include the error as context, because it’s not a parameter of the tool.

Step 3: Wire up the agent tool

This pattern is framework-agnostic. It works with Pydantic AI agents, LangChain's tool-calling agents, LlamaIndex's ReAct agents, or a custom loop. The key is to provide the agent with a clear tool description so it knows when to use it, e.g. “Use this tool to answer questions about products, orders, reviews, or users”. In the following example, you can see a fine-tuned description that hints to LLM to leverage the vector embeddings when available. In my use case, this prevents the LLM from searching products or categories by matching keywords, preferring vector search instead [2].

async def query_db(context: RunContext[Deps], question: str) -> str:
    """Use this tool to answer questions about products, orders, reviews,
    or users.

    If required, you can do vector search against any table with an
    embeddings field.
    E.g: `WHERE embedding <|20,40|> fn::embed("text to embed")`.

    Args:
        question: The user question.
    """
    ...

PROMPT_GEN_SURQL = """
You are an expert in SurrealQL (surql, SurrealDB's query language).

Generate a valid surql query to get the information required to answer the user's prompt.

PROMPT: {prompt}

<schema>
{schema}
</schema>

<best-practices>
{notes}
</best-practices>

<examples>
{examples}
</examples>
"""

Find more in query_db.py and the prompt template in the Kai G repo. If you are new to prompt engineering –or want a good refresher, I recommend watching Prompting 101 by Anthropic.

Fine-tuning

LLMs are getting better and better at writing complex queries, but they don’t get it right all the time. This is why the prompt and few-shot examples are so important. The ones I shared above were the result of a few manual iterations. You can borrow them for your project, but your specific use case (and model) will require different hints.

Design your solution in a way that you have good observability to iterate quickly, and metrics to make sure you are moving forward. In my demo, I use Pydantic’s Logfire for observability, and store the results from the text-to-surql function and the query execution with a score. This allows me to capture queries that failed, identify the anti-pattern, and add a line to the tool prompt or a new example to avoid that mistake from surfacing again.

Some examples:

- don't use `math::avg`, the correct one is `math::mean`.
- always `OMIT` the `embedding` field from the final result to avoid large results.
- vector::distance::knn() must be in SELECT to use in ORDER BY

Conclusion

The next generation of production AI agents won't be distinguished by how good their embeddings are. They'll be distinguished by how precisely they can retrieve and present facts - with full auditability back to the source.

Agentic retrieval with a SurrealQL generation tool closes that gap. Instead of hoping a vector similarity search lands close enough, the agent reasons about your question, writes a precise query, and returns exactly the data you asked for. Every answer is traceable to a specific query against a specific table.

SurrealDB makes this pattern practical: multi-model queries mean the agent handles graph traversals, document lookups, and relational aggregations in a single round-trip, while record-level permissions keep data access secure by default.

If you're building agents that need to answer questions from structured data - and answer them correctly - this is the architecture worth building toward.

Footnotes

[1] You probably don’t want users to have such power. If you allow users to ask any question, they may ask “change the price of SKU-0042 to $0, and create an order with 10 of them ready to checkout”.

[2] A full-text index could be a better idea, if what you are searching for can effectively be retrieved by lexical means, rather than semantically. And for some use cases reranked hybrid search could be the right choice. Consider all alternatives based on your use case, and what you are optimising for.

Ready to try it?

Create a free SurrealDB Cloud instance
Explore the SurrealQL docs
Join the SurrealDB Discord - new here? The #all-ai and #surrealql channels are the best places to get started.

Using SurrealDB to understand how Buffalo buffalo buffalo Buffalo buffalo

Dave MacLeod — Thu, 09 Jul 2026 13:54:06 +0000

Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

That's technically a valid English sentence, one of the ones that has its own Wikipedia article to explain just how it works. What makes it work is that the word buffalo is also a (rarely used) verb to mean to bully or to fool someone. Here's an example of the verb in practice:

"If nonfiction is where you do your best writing, or your best teaching of writing, don't be buffaloed into the idea that it's an inferior species."

The other thing that makes the sentence confusing is that the word buffalo can also be the plural of buffalo. Fortunately, you can also pluralise it with an s - which is what we will do in this post from here on.

With a bit of rewriting and notes in parentheses, the sentence makes a little more sense.

Buffaloes from Buffalo that buffaloes from Buffalo buffalo (trick) buffalo (trick) buffaloes from Buffalo.

If that still only makes just a bit of sense, don't worry - because we can demonstrate the situation using SurrealQL instead.

Buffaloes that buffalo Buffalo buffaloes

To start: if we have Buffalo buffalo, that means that there should also be non-Buffalo buffalo: buffalo that don't come from the city of Buffalo. Let's make 50 of each. Two following two CREATE statements will create them with a sequential ID starting from 1 and ending at 100.

CREATE |buffalo:1..=50| SET from = "Buffalo";
CREATE |buffalo:51..=100| SET from = "Somewhere else";

Now we need to get the buffaloes to interact with each other.

Since the original sentence is talking about how a buffalo can buffalo another buffalo, that must mean that this sometimes happens and sometimes does not. To demonstrate this, let's go through each buffalo, randomly choose a buffalo (with the rand::enum() function) that is not the buffalo in question (array::complement() will do that), and then use rand::bool() to give it a 50% chance of buffaloing that buffalo.

FOR $buffalo IN SELECT * FROM buffalo {
    // We could do this in a single line but let's go one step at a time
    LET $all_buffalo = SELECT VALUE id FROM buffalo;
    LET $except_this_one = $all_buffalo.complement([$buffalo.id]);
    LET $other_buffalo = rand::enum($except_this_one);
    // Now that we have another buffalo, we'll flip a coin
    // to see if it gets 'buffaloed'
    IF rand::bool() {
        RELATE $buffalo->buffaloes->$other_buffalo;
    };
};

With that set up, we can do a query to see which Buffalo buffaloes are buffaloing Buffalo buffaloes, and who they are. To do that, we can use a WHERE clause to ensure that the buffalo in question is from Buffalo, and that the path ->buffaloes->buffalo.from (the buffalo(es) that are getting buffaloed) contains the word "Buffalo".

SELECT 
    id, 
    from, 
    ->buffaloes->buffalo AS buffaloes
FROM buffalo 
WHERE 
    from = "Buffalo" 
AND 
    "Buffalo" IN ->buffaloes->buffalo.from;

Because half of the buffaloes are from Buffalo and half of these have buffaloed another buffalo, the output should show...about 25? Not quite, because some unlucky buffaloes have been buffaloed by more than one buffalo. We can demonstrate that by doing a reverse graph query on the buffaloes to see which ones they are being buffaloed by, followed by a filter to only retain the ones that have been buffaloed more than once.

(SELECT <-buffaloes<-buffalo AS buffaloed_by FROM buffalo)
    .filter(
        |$b| $b.buffaloed_by.len() > 1
    );

Buffaloing back

Now it's time for justice to be done. Because the original sentence can actually be read as a decree.

"No buffalo from Buffalo shall be buffaloed by a buffalo from Buffalo without the chance to buffalo back. Henceforth, any buffalo from Buffalo that Buffalo buffalo buffalo shall also buffalo a Buffalo buffalo."

Sounds fair.

To enact this decree, we will need to have every buffalo that is buffaloed by a buffalo from Buffalo now also buffalo another buffalo from Buffalo.

To start, we'll use much of the same query as above but turn it around. And this time we won't use rand::bool() because the buffalo from Buffalo in question that has been buffaloed now has a 100% chance of buffaloing another buffalo from Buffalo.

FOR $buffalo IN SELECT VALUE
    id
FROM buffalo 
WHERE 
    from = "Buffalo" 
AND 
    "Buffalo" IN <-buffaloes<-buffalo.from {
         LET $all_buffalo = SELECT VALUE id FROM buffalo;
         LET $except_this_one = $all_buffalo.complement([$buffalo.id]);
        LET $other_buffalo = rand::enum($except_this_one);
        RELATE $buffalo->buffaloes->$other_buffalo;
};

Visualising all the buffaloing

We can finish this off by visualising the data to see all of the buffaloing that is going on, whether actively (buffaloing a buffalo) or passively (being buffaloed by a buffalo). The following two queries will show who is buffaloing and who they are being buffaloed by, depending on whether they are from Buffalo or not.

SELECT 
    id, 
    buffaloes->buffalo AS buffaloes, 
    <-buffaloes<-buffalo AS buffaloed_by
FROM buffalo 
WHERE from = "Buffalo";

SELECT 
    id, 
    buffaloes->buffalo AS buffaloes,
    <-buffaloes<-buffalo AS buffaloed_by
FROM buffalo 
WHERE from != "Buffalo";

The raw output of these queries is easy enough to read, but it's tough to get a top-level idea of what is going on here.

[
    {
        buffaloed_by: [
            buffalo:76
        ],
        buffaloes: NONE,
        id: buffalo:3
    },
    {
        buffaloed_by: [
            buffalo:45,
            buffalo:18
        ],
        buffaloes: NONE,
        id: buffalo:4
    },
    {
        buffaloed_by: [],
        buffaloes: NONE,
        id: buffalo:5
    },
//...
]

This is where Surrealist's graph visualisation comes into play. To use it, just click on the "Combined" button next to the button used to run a query and change it to "Graph". As long as a query contains the id of each record, it will be able to visually show which records are connected to which other ones.

You can also click on "Stray edges" to display records that aren't connected, which is what we will do here.

The output will differ every time these queries are executed and every time this functionality is used to generate a visual output in Surrealist, but for the most part you will notice that there is a lot more going on between the buffaloes from Buffalo than those from somewhere else. That makes sense, because the second RELATE operation that we used was only for, and between, buffaloes from Buffalo.

The first query between buffaloes from Buffalo should look somewhat busy with connections between quite a few, and a number of stray edges floating around in the middle.

The second query is a bit less so, with fewer connections between these buffaloes and a lot more stray edges.

Learn more

Interested in learning more? Here are some more links and blog posts to get started.

And for another technically correct mind-bending sentence, check out the page on James while John had had had had had had had had had had had a better effect on the teacher.

Ready to try it?

Detecting connections as they form: An introduction to streaming graph pattern matching

Dave MacLeod — Thu, 09 Jul 2026 12:58:27 +0000

Detecting connections as they form: An introduction to streaming graph pattern matching

Originally published by Cyril Scetbon on 13 April, 2026

In my previous posts, I explored how SurrealDB blends document, graph, relational, and vector models into a single engine, and how you can combine it with Rig.rs to build LLM-native agents in Rust. I've written about SurrealDB more than once because I genuinely believe it's one of the most exciting databases out there right now — and the more I use it, the more I find myself reaching for it as the obvious foundation whenever I need something flexible, expressive, and Rust-native. Its graph capabilities — RELATE, record IDs, graph traversals — kept nagging at me with a question: what if you could continuously watch a graph as it grows and fire off actions the moment a meaningful pattern completes?

That question sent me down a rabbit hole. This post is the first in a series where I'll walk you through the concept, the configuration I'd want for such a tool, the actual implementation, and where things could go from there.

Let's start at the beginning. 🔍

🕸️ What is a labeled property graph?

If you've read my SurrealDB deep-dive, you already know that SurrealDB natively models data as a labeled property graph. But let's make it concrete for this series.

A labeled property graph has two building blocks:

Vertices — entities with a type and properties. Think person:clint_eastwood with a name field, or movie:unforgiven with a title and year.
Edges — directed, typed relationships between vertices. Think person:clint_eastwood -> acted_in -> movie:unforgiven.

Edges are first-class citizens: they have their own type (e.g., acted_in, directed) and can carry their own properties (e.g., the role a person played).

This model is perfect for representing the kind of messy, interconnected real-world data that relational tables struggle with — social networks, supply chains, knowledge graphs, movie databases.

If you want to get a feel for how expressive SurrealDB's query language gets when working with this kind of data, take a look at the idioms page in the docs. It's a compact showcase of what SurrealQL can do — and honestly, reading through it is a big part of what got me thinking about building this in the first place.

⚡ What is streaming graph pattern matching?

A graph pattern is a template describing a subgraph you care about. For example:

"Find any person who both acted in and directed the same movie."

In a static graph, you'd run a query once and get your results. But what if the graph is continuously growing? Edges arrive one by one as events stream in. You want to know the moment that pattern becomes complete — not minutes later, not after a full scan.

That's streaming graph pattern matching: detecting when a pattern is satisfied in real time, incrementally, as new edges are added.

The classic use cases are things like:

Fraud detection — flag the moment a money flow completes a suspicious cycle
Recommendation engines — create a "you might also like" edge the second two users share enough common favorites
Knowledge graph enrichment — derive new facts automatically as raw data arrives
Event correlation — detect that a sequence of system events matches a known failure signature

The challenge is doing this without re-scanning the entire graph every time a single edge lands.

🎬 A running example: the movie database

Throughout this series I'll use a movie dataset. It's a flat CSV file where each row is tagged with an Entity type:

Entity,tmdbId,movieId,name,Work,role
Person,190,,Clint Eastwood,,
Person,192,,Morgan Freeman,,
Movie,,33,Unforgiven,,
Join,190,33,,Acting,William Munny
Join,192,33,,Acting,Ned Logan
Join,190,33,,Directing,

A few things to note:

Person rows describe people.
Movie rows describe films.
Join rows describe relationships — acting roles, directing credits — linking people to movies.

This flat structure is typical of real-world export formats. The goal is to lift it into a proper graph and then continuously match patterns against it.

The pattern I want to detect: a person who both acted in and directed the same movie. Clint Eastwood fits. Morgan Freeman does not.

🗂️ Imagining the configuration

If I were to design a tool for this, I'd want the entire thing controlled by a single YAML configuration file. Two top-level sections: sources to describe how raw data becomes a graph, and patterns to express what I'm looking for in that graph. Let me walk through both in detail.

Sources — loading the graph

The sources section describes where your data comes from and how to turn each row into graph elements. Each source entry points to a file and defines a format block with two optional scripts: filter and load.

For the scripting language, I'd reach for VRL — Vector Remap Language — a safe, sandboxed expression language originally built for the Vector observability pipeline. It's expressive enough for real data wrangling, and it could be extended with a handful of custom functions to express graph operations directly.

Here's what a complete sources block would look like for the movie dataset:

sources:
  # --- Source 1: Load Person vertices ---
  - type: file
    path: $movie_file          # resolved at runtime via --variable movie_file=...
    format:
      filter: msg.Entity == "Person"   # only process rows where Entity is "Person"
      load: |
        .id = record_id!("person", [msg.tmdbId])   # build a typed record ID: person:190
        .name = msg.name
        + @                            # mark this object as a vertex to be created

  # --- Source 2: Load Movie vertices ---
  - type: file
    path: $movie_file
    format:
      filter: msg.Entity == "Movie"
      load: |
        .id = record_id!("movie", [msg.movieId])   # e.g. movie:33
        .title = msg.name
        + @

  # --- Source 3: Acting edges ---
  - type: file
    path: $movie_file
    format:
      filter: msg.Entity == "Join" && msg.Work == "Acting"
      load: |
        .id = record_id!("acted_in", [msg.tmdbId, msg.movieId, msg.role])
        .role = msg.role
        .person.id = record_id!("person", [msg.tmdbId])
        .movie.id  = record_id!("movie",  [msg.movieId])
        + @person->@->@movie    # create the edge; the root object becomes the edge record

  # --- Source 4: Directing edges ---
  - type: file
    path: $movie_file
    format:
      filter: msg.Entity == "Join" && msg.Work == "Directing"
      load: |
        .person.id = record_id!("person", [msg.tmdbId])
        .movie.id  = record_id!("movie",  [msg.movieId])
        + @person->directed->@movie    # anonymous edge — no edge record object

Let me unpack each key concept.

`filter` — Row-level gating

filter: msg.Entity == "Person"

This is a VRL boolean expression evaluated against each incoming row. If it returns false, the row is skipped entirely. The raw CSV row is available as msg. Multiple sources can read the same file with different filters — that's intentional. The file would be read once and fanned out to all matching sources in parallel.

`record_id!()` — Typed identifiers

.id = record_id!("person", [msg.tmdbId])
# Produces: person:190

This custom VRL function would build a SurrealDB-style record ID from a table name and a list of key components. If you pass multiple components, they're combined into a composite key. The result is a strongly typed identifier like person:190 or acted_in:[190, 33, "William Munny"]. This ensures that re-ingesting the same data is idempotent — the same row always produces the same ID.

`+ @` — Creating a vertex

.id = record_id!("person", [msg.tmdbId])
.name = msg.name
+ @          # "upsert me as a vertex"

The @ symbol refers to the current root object — the thing you've been building up with .field = value assignments. Prefixing it with + marks it for creation in the graph.

One important thing to be explicit about: nested objects are not pushed automatically. If your root object has a .person sub-object, doing + @ only persists the root — .person is ignored. To push a nested object as its own vertex, you have to say so explicitly with + @person. This keeps the behaviour predictable and avoids accidentally creating vertices you didn't intend.

You can also push multiple nested objects in the same script — + @movie, + @genre, and so on — each as a separate vertex, containing only its own fields.

`+ @from->edge->@to` — Creating an edge

.person.id = record_id!("person", [msg.tmdbId])
.movie.id  = record_id!("movie",  [msg.movieId])
+ @person->directed->@movie

This creates a directed edge between two vertices. The vertices themselves don't have to be created in the same source entry — they can come from a different one. What matters is that @person and @movie resolve to objects with a valid .id field at execution time.

Worth knowing: an edge can be written to the database even if the vertices it points to don't exist yet. The edge record is created regardless, but any pattern that tries to traverse it will come back empty until both endpoints are actually present. This is why source order doesn't have to be strict — edges landing before their vertices are harmless, they just won't produce matches until the graph is complete enough to satisfy the pattern.

If you want the edge itself to carry properties (like a role name), you use the root object as the edge record:

.id    = record_id!("acted_in", [msg.tmdbId, msg.movieId, msg.role])
.role  = msg.role
.person.id = record_id!("person", [msg.tmdbId])
.movie.id  = record_id!("movie",  [msg.movieId])
+ @person->@->@movie    # @ in the middle = "use the root object as the edge record"

Direction is explicit: -> means left-to-right, <- means right-to-left. You can chain them:

+ @movie<-acted_in<-@person->directed->@movie
# Two edges created from a single line

Patterns — Matching the graph

The patterns section is where things get interesting. Each pattern entry has a match field containing a small DSL that describes the subgraph you're looking for.

patterns:
  - match: |-
      /
        m:movie<-acted_in<-p:person->directed->m:movie
        + p->acted_and_directed->m
      / -> m as movieId, m.title as movie, p as personId, p.name as actor

Let me break this apart piece by piece.

Aliases and join conditions

m:movie<-acted_in<-p:person->directed->m:movie

m:movie means: match any vertex from the movie table and call it m.
p:person means: match any vertex from the person table and call it p.
The same alias used in multiple places means the same vertex. Here m appears on both sides — so the movie that p acted in must be the exact same movie that p directed. That's your join condition, expressed naturally.

This single-line form is just a convenience. You can spread the same pattern across multiple lines and the meaning is identical — each line describes one edge, and shared aliases still enforce the join. All three of these are equivalent:

p:person->acted_in->m:movie
p:person->directed->m:movie

m:movie<-acted_in<-p:person
m:movie<-directed<-p:person

m:movie<-acted_in<-p:person
p:person->directed->m:movie

Pick the direction that reads most naturally for the relationship you're describing. The engine doesn't care — it resolves the aliases and finds the join either way.

This is the heart of the pattern language. You describe structure; the engine figures out the join.

Actions — Deriving new edges

+ p->acted_and_directed->m

When the full pattern is satisfied, this line fires. It creates a new acted_and_directed edge between the matched p and m vertices.

Duplicate prevention is built into the ID scheme: the derived edge gets a composite record ID based on the two endpoint vertices — something like acted_and_directed:[person:190, movie:33]. That ID is always the same for the same pair, so re-triggering the match (say, because new edges arrived and the checker ran again) produces the exact same record rather than a second one. The operation is naturally idempotent.

Output projections

/ -> m as movieId, m.title as movie, p as personId, p.name as actor

After the closing /, you declare what gets emitted when a match is found. You can project full vertices (m as movieId) or individual fields (m.title as movie). Omit this section entirely and all matched aliases come back.

More pattern expressiveness

The DSL could support more than simple linear paths. A few things worth being able to express:

Multiple edge types — match either rated or disliked:

p:person->(rated, disliked)->m:movie

Wildcard edge — match any edge type between two vertices:

p1:person->?->p2:person

Edge filters — only match edges that satisfy a property condition:

p:person->directed[WHERE award = "Oscar"]->m:movie

Vertex filters — only match vertices satisfying a condition:

p:person[WHERE birth_date >= "2000-01-01"]->acted_in->m:movie

Multiple independent patterns in a single block — all must be satisfied for the action to fire:

/
  p:person->acted_in->m:movie
  p:person->directed->m:movie
  + p->acted_and_directed->m
/ -> m.title as movie, p.name as actor

🔄 What would it look like to run this?

At a high level, the tool would:

Read the configuration file and resolve any $variable placeholders passed on the command line.

Stream data from each source into the graph — filtering rows, transforming them into vertices and edges via the load scripts, and persisting everything to the database.

Watch the graph for pattern completions — as edges land, the tool continuously checks whether any of the declared patterns are now fully satisfied.

Fire actions and print results immediately — the moment a match is found, the + edges are created and the projected output is flushed to stdout right away, without waiting for ingestion to finish.

This last point matters: matches don't accumulate and print at the end. They appear as soon as they're found, interleaved with ongoing ingestion. If you're streaming a large dataset, you'd start seeing output long before the last row is processed.

For the movie example, as soon as both the acted_in and directed edges involving Clint Eastwood and Unforgiven are present, the pattern is satisfied and a line appears on stdout. Morgan Freeman only acted, so he never completes the pattern — no false match, no output for him.

The system is also tolerant of edges arriving out of order. If a directed edge lands before the corresponding acted_in edge exists yet, the check is retried automatically once the missing piece shows up. You don't have to pre-sort your data or reason about arrival order.

The key design intent is that you never have to write a query. You declare the shape of what you're looking for and let the tool figure out when it exists.

🧠 Why this configuration style?

A few deliberate design choices worth calling out:

One file per source, multiple sources per file. The same CSV can produce vertices, edges, and genre tags all at once — by duplicating the source entry with different filters. No preprocessing step required.
VRL for transformations. It's expressive enough to handle type coercions, array splits, conditional logic, and nested structures, while being safe and sandboxed. No need to invent yet another mini-language for data wrangling.
Aliases as join keys. Using the same alias name to enforce vertex identity across pattern lines is a small syntax choice that turns out to be remarkably readable. The pattern says what you mean.
Declarative actions. The + syntax for derived edges mirrors the + syntax in the load scripts. Once you understand one, you understand the other.
Idempotent by construction. Derived edges get a deterministic ID from their endpoints, so running the same match twice is harmless. No deduplication logic to write, no risk of polluting the graph with duplicate relationships.
Results stream, they don't batch. Output is flushed to stdout the moment a match is confirmed. You can pipe the output, process it downstream, or just watch it in a terminal — it behaves like any other streaming Unix tool.

👉 TL;DR

Streaming graph pattern matching is about detecting when a meaningful subgraph completes — incrementally, as edges arrive, without scanning the whole graph.

A YAML config maps raw data to graph elements via VRL, and a declarative DSL expresses the patterns you care about. When a pattern matches, derived edges are created automatically.

In the next post, I'll show you the actual implementation: the tech stack, how the pieces fit together under the hood, and what the database looks like once everything is loaded. Stay tuned. 🛠️

Introducing Scale: SurrealDB Cloud, built for high availability and scale

Mark Gyles — Thu, 02 Jul 2026 15:53:29 +0000

Author: Tobie Morgan Hitchcock

Today we're launching Scale, a new tier of SurrealDB Cloud built for the workloads you can't afford to have go down.

Our first tier, Start, was designed for building and shipping fast. Scale is designed for what happens next: production traffic, uptime commitments, and the kind of resilience your users never notice because there are always available nodes. It's the tier for teams running SurrealDB as the scalable context layer behind real applications and AI agents in production.

What you get with Scale

Scale is about one thing: keeping your database available and consistent under real-world conditions.

Highly-available, fault-tolerant clusters. Scale runs your database as a multi-node cluster designed to survive node and infrastructure failures without dropping writes or losing consistency. A single point of failure is no longer a single point of downtime.

Multiple availability-zone deployment. Your cluster is distributed across multiple availability zones, so even the loss of an entire zone doesn't take your database with it. Traffic keeps flowing while the cluster recovers in the background.

Horizontal scale. As demand grows, Scale grows with it. Add capacity by scaling out across nodes rather than being capped by the size of a single machine. Start with three nodes, and keep adding to scale your application or agent's needs.

See more information about SurrealDB Cloud Scale architecture here.

Built on SurrealDS

Scale is powered by SurrealDS, SurrealDB's distributed storage engine and the foundation that makes all of this possible.

SurrealDS is a new generation distributed storage architecture, rethought from first principles. Instead of coupling storage to compute on a single box or to a proprietary cloud tier, SurrealDS embeds consensus directly in SurrealDB nodes and separates the two layers cleanly. Here's what that architecture gives you.

Architecture overview

Compute and storage separation. Scale compute for QPS and storage for capacity independently, so you provision for the dimension that's actually under pressure.
No single leader. Each availability-zone node writes locally, writes scale horizontally, and transactions commit once a quorum acknowledges them.
Multi-write nodes. Every write node in the cluster can accept and coordinate transactions - there's no bottleneck routing all writes through one leader.
Reduced operational overhead. Consensus is embedded directly in SurrealDB nodes, eliminating external coordination services.
Fewer network dependencies. A single broadcast replaces multi-hop coordination, reducing latency.
Lower latency than leader-based replication. With no single leader and each AZ node writing locally, transactions avoid the extra round trips of traditional leader-based systems.

Future roadmap

Several SurrealDS capabilities are on the near-term roadmap and will land in the Scale tier as they ship:

Object-storage backed. Persist transactional data directly to commodity object storage - storage costs drop and capacity scales far beyond any single disk.
Cross-region replication. Data flows through object storage rather than between nodes, significantly reducing data-transfer costs while keeping regions in sync.
Instant recovery. A crashed node restores from object storage, with recovery time almost instant regardless of dataset size.
Instant branching. Clone a petabyte-scale database in seconds for development, testing, or experimentation.

Get started

If you're running SurrealDB in production, or getting ready to, Scale gives you the availability and fault-tolerance your workloads need, on the storage architecture no one else has.

Explore the tier in SurrealDB Cloud, and dig into the engine underneath at SurrealDS.

Bring SurrealDB to your Replit Agent

itsezc — Thu, 02 Jul 2026 15:23:55 +0000

Replit Agent turns a prompt into a working app. SurrealDB is the one database behind that app, covering documents, graph, vectors, and SQL in a single engine. The piece that connects them is the Model Context Protocol (MCP).

Every SurrealDB instance running 3.1 or later can expose a first-party MCP server: a typed tool surface that AI agents call to inspect your schema and run queries safely. Replit Agent supports any MCP server as a connector, and adds them with a single click. Put the two together and Replit can build directly from the data you already have in SurrealDB.

This is vibe coding for teams that already own their data. Instead of letting an agentic coding tool improvise a throwaway backend, you point Replit at SurrealDB and build on a database you already trust, with the agent reading your real schema as it goes.

This guide is a hands-on quickstart. By the end you will have SurrealDB 3.1 running with its MCP server enabled, connected to a Replit project, and you will have prompted Replit Agent to generate a real interface on top of your data.

What you'll need

You need a few things before you start, and none of them take more than a few minutes to set up.

You need SurrealDB 3.1.0 or later. You also need a way to reach your instance from the internet, because Replit's connectors talk to your MCP server over HTTP and the server needs a public URL. A SurrealDB Cloud instance gives you one out of the box; for a local instance you can use a tunnel, which we cover below. You need a Replit account. Finally, you need some data. Even a handful of records is enough to see the workflow end to end, and we create a small schema below so you have something to build against.

It is worth noting how this differs from Replit's built-in database. Replit Agent provisions a managed Postgres instance for the app it builds, which it owns. With SurrealDB over MCP, you own the database. Replit connects to a SurrealDB instance you already run, reads its schema as context, and can query or mutate it through a typed, permissioned tool surface. This is the right pattern when SurrealDB is your system of record and you want to build interfaces on top of it rather than spin up a new backend.

How SurrealDB, MCP, and Replit fit together

There are three moving parts to understand before the steps.

SurrealDB 3.1 exposes a typed tool surface for AI agents. Rather than handing an agent a raw SQL console, the MCP server presents twelve defined tools: query, select, create, insert, upsert, update, delete, relate, info, list, use, and run. Each tool carries annotations (read_only_hint, destructive_hint, idempotent_hint) so an MCP client like Replit knows which operations are safe and which mutate data. The server also publishes self-describing schema resources at URIs like surrealdb://schema/ns/{ns}/db/{db}/table/{table}, so the agent discovers your tables and fields instead of guessing.

You can run that MCP server two ways. Locally, surreal mcp runs as a stdio subcommand, which suits IDE integrations on your own machine. For a remote client like Replit, the server is exposed over HTTP at /mcp, sitting behind SurrealDB's existing authentication middleware. We use the HTTP path here, because Replit needs to reach your server over the network.

Replit Agent treats MCP servers as connectors. Replit ships a curated list of MCP servers that install in one click, and lets you add any other server, including your SurrealDB instance, from the Integrations pane. All MCP traffic passes through Replit's security scanner, which inspects tool definitions and planned executions and blocks anything it judges unsafe before it runs. Once your SurrealDB endpoint is connected, the agent pulls your live schema and data into context while it builds.

Step 1: Install or upgrade to SurrealDB 3.1

If you are already on a 3.1.x release you can skip ahead. Otherwise, pick whichever install path matches your setup. Each pins to a specific version; drop the --version flag to always get the newest stable.

macOS (Homebrew), then upgrade in place:

surreal upgrade --version 3.1.5

Linux and macOS install script, which auto-detects your architecture:

curl -sSf https://install.surrealdb.com | sh -s -- --version 3.1.5

Windows (PowerShell), then upgrade in place:

surreal upgrade --version 3.1.5

Docker, to pull and run the exact image:

docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:v3.1.5 start

The surreal upgrade command can swap any existing install, whether Homebrew, install script, or manual binary, to the version you specify. Patch releases on the 3.1 line are drop-in upgrades.

If you are on SurrealDB Cloud, you can upgrade your instance in place from the Surrealist app, and you already have a public HTTPS endpoint, which makes the networking in Step 4 considerably simpler.

Verify your version:

surreal version

Step 2: Start your instance and create some data

For a local run, start a server with authentication enabled. The MCP HTTP endpoint sits behind the same auth middleware as the rest of SurrealDB, so credentials matter here.

surreal start \
  --user root --pass pass \
  rocksdb://mydata.db

This starts SurrealDB on http://localhost:8000 with a persistent RocksDB store and a root user. In production you would scope down to a namespace and database user rather than root, which we cover under permissions later.

Now give Replit something to build against. Use the CLI's surreal sql command to open a session, or use Surrealist, the visual query tool, and define a small schema. We model a simple product catalog with reviews, which is enough to show off SurrealDB's record links.

-- Pick a namespace and database to work in
USE NS shop DB catalog;

-- A products table
DEFINE TABLE product SCHEMAFULL;
DEFINE FIELD name        ON product TYPE string;
DEFINE FIELD price       ON product TYPE number;
DEFINE FIELD in_stock    ON product TYPE bool DEFAULT true;
DEFINE FIELD created_at  ON product TYPE datetime DEFAULT time::now();

-- A reviews table that links back to a product
DEFINE TABLE review SCHEMAFULL;
DEFINE FIELD product ON review TYPE record<product> REFERENCE;
DEFINE FIELD rating  ON review TYPE int ASSERT $value IN 0..=5;
DEFINE FIELD body    ON review TYPE string;

-- Seed a few records
CREATE product SET name = "Aeropress", price = 39.95;
CREATE product SET name = "Gooseneck Kettle", price = 64.00;
CREATE product SET name = "Burr Grinder", price = 129.00, in_stock = false;

A SCHEMAFULL table means SurrealDB enforces the field definitions, which is what you want when an AI agent is going to read and write the table. The schema becomes the contract the agent builds against. Because SurrealDB publishes that schema as an MCP resource, Replit reads these field types directly rather than inferring them from sample rows.

Step 3: Enable the MCP server over HTTP

In 3.1, the MCP HTTP surface is served at /mcp on the same port as the rest of the HTTP API, behind authentication. A handful of environment variables let you tune its limits. The defaults are sensible, but it is worth knowing they exist:

SURREAL_HTTP_MAX_MCP_BODY_SIZE: maximum request body size (default 4 MiB)
SURREAL_MCP_QUERY_TIMEOUT_SECS: per-query timeout (default 60 s)
SURREAL_MCP_MAX_RESULT_BYTES: maximum result payload (default 256 KiB)
SURREAL_MCP_RUN_MAX_ARGS: maximum arguments to the run tool (default 64)
SURREAL_MCP_PARAMS_MAX_KEYS: maximum bound parameters per call (default 256)

For example, to allow larger result payloads while keeping a tight query timeout:

SURREAL_MCP_MAX_RESULT_BYTES=1048576 \
SURREAL_MCP_QUERY_TIMEOUT_SECS=30 \
surreal start --user root --pass pass rocksdb://mydata.db

For PowerShell users on Windows:

$env:SURREAL_MCP_MAX_RESULT_BYTES = "1048576"
$env:SURREAL_MCP_QUERY_TIMEOUT_SECS = "30"
surreal start --user root --pass pass rocksdb://mydata.db

If instead you want to wire SurrealDB into a local IDE rather than Replit, run the stdio variant, surreal mcp, and point your editor's MCP client at that subcommand. For Replit, stick with the HTTP endpoint.

A good sanity check before involving Replit is to confirm the /mcp route is reachable and that requests without valid credentials are rejected, which tells you the auth middleware is doing its job.

Step 4: Make your instance reachable

Replit runs in the cloud, so it needs a public URL for your MCP endpoint. You have two clean options.

Option 1: SurrealDB Cloud. If your data lives in a SurrealDB Cloud instance, you already have a public HTTPS endpoint with managed TLS and authentication. Your MCP URL is simply that instance's address with the /mcp path appended. This is the lowest-friction path and the one we recommend for anything beyond local experimentation.

Option 2: A tunnel to a local instance. For local development, expose http://localhost:8000 through a tunneling service that gives you a temporary public HTTPS URL, such as ngrok or Cloudflare Tunnel. Your MCP URL is then https://<tunnel-host>/mcp. This works well for trying things out, but treat the URL as ephemeral and never point it at production data.

Either way, you end up with a single value to hand to Replit: an HTTPS URL ending in /mcp, plus the credentials needed to authenticate against it.

Security note: The MCP endpoint inherits SurrealDB's authentication and permissions. Before you expose anything, create a dedicated database user scoped to just the namespace and database you want Replit to touch, rather than handing over root. SurrealDB enforces record-level and field-level permissions on every query the agent runs, so a properly scoped user cannot read or write beyond what you have granted, even if the agent asks it to.

Connect SurrealDB to Replit

Now switch over to Replit. Because MCP is a standard, you add SurrealDB the same way you would any custom server.

Open your app in the Project Editor and open the Integrations pane (or go to replit.com/integrations).
Choose Add new integration, then add a custom MCP server.
Server URL: paste your MCP endpoint, for example https://your-instance.surrealdb.cloud/mcp or your tunnel URL ending in /mcp.
Authentication: Replit supports OAuth dynamic client registration where a server offers it, or custom headers for static tokens. For a SurrealDB instance, use a custom header with key Authorization and value Bearer <token> for your scoped database user. Reserve no-auth endpoints for a throwaway local demo, never for real data.
Authorize the connection. Replit's security scanner inspects the server's tools, and the connection persists across your apps once approved.

Build an app on your SurrealDB data with Replit

With the connector live, Replit Agent calls SurrealDB's tools to discover your schema and read your records, then generates UI that is wired to that data.

Start by pulling your data into context with a prompt like this:

Using my SurrealDB connector, list the tables in the shop/catalog database and show me the fields on the product table.

This prompts Replit to call the list and info tools and read the schema resource, then report back what it found. Behind the scenes, use selects the shop namespace and catalog database, and the schema resource at surrealdb://schema/ns/shop/db/catalog/table/product tells Replit that product has name, price, in_stock, and created_at with their exact types.

Once it understands your schema, ask it to build:

Build a product catalog page that shows every product from SurrealDB as a card with its name, price, and stock status. Add a filter to show only in-stock items.

Replit reads your live products via the select tool, scaffolds a front end, and binds the components to the real fields. Because the agent knows in_stock is a boolean from the schema, the filter it builds is correct on the first pass rather than a guess.

You can go further and let it traverse relationships, which uses SurrealDB's graph capabilities:

Add a detail view for each product that lists its reviews, the rating and body, pulled from the review table that links to the product.

Here SurrealDB's record links do the heavy lifting. A SurrealQL query like SELECT *, <~review.{ rating, body } AS reviews FROM product fetches each product together with its reviews in one round trip. The <~ operator walks incoming record references the same way graph queries do, and Replit issues exactly that through the query tool.

When you ask Replit to write data, such as adding a form to submit a new review, the agent reaches for the create or insert tool. Because those tools carry the non-read-only annotations, Replit knows they mutate state and can surface a confirmation before anything is written. Your SurrealDB permissions remain the backstop: if the connected user lacks CREATE permission on review, the write fails at the database regardless of what the agent attempts.

SurrealDB MCP tools reference

Knowing what each tool does tells you exactly what you can ask Replit to do with your data.

query: run arbitrary SurrealQL. The most powerful tool, and the one behind any complex read or graph traversal.
select: read records from a table, optionally filtered.
create and insert: add new records, with insert geared toward bulk.
upsert: create or update depending on whether the record exists.
update: modify existing records.
delete: remove records, which is a destructive operation.
relate: create graph edges between records, SurrealDB's relational strength.
info: describe the structure of a namespace, database, or table.
list: enumerate available namespaces, databases, or tables.
use: select the namespace and database to operate within.
run: invoke a defined function on the server.

The read-only tools (select, info, list) are safe to let an agent call freely. The mutating tools (create, insert, upsert, update, delete, relate) are the ones the hint annotations flag, and the ones your database permissions should govern most tightly.

Production considerations for SurrealDB with Replit

A few things are worth getting right before you let real users near a SurrealDB-backed Replit app.

Scope the connected user tightly. Create a database-level user with only the permissions the app needs. SurrealDB's permission model is enforced on every query, including record-level and field-level SELECT, CREATE, UPDATE, and DELETE permissions, so the agent is constrained by the database, not just by good behavior.

Use the limits. The MCP environment variables exist to keep a chatty agent from overwhelming your instance. Set a sensible SURREAL_MCP_QUERY_TIMEOUT_SECS and SURREAL_MCP_MAX_RESULT_BYTES for your workload.

Prefer Cloud or a stable endpoint over a dev tunnel. Tunnels work for trying this out, but they are ephemeral. For anything persistent, a SurrealDB Cloud instance, or your own properly secured deployment, is the right home.

Keep your token out of shared links. A Replit install link with an Authorization header baked in carries a real credential. Generate it for your own use and rotate the token if it leaks.

Where this leaves you

You now have a SurrealDB instance whose schema and data are first-class context for Replit Agent, exposed through a typed, permissioned, observable MCP surface. The same connection that lets Replit build a catalog page would let it scaffold an admin dashboard, a customer-facing storefront, or an internal tool, all reading from and writing to the one database you control.

That is the shape of the SurrealDB and Replit workflow: SurrealDB is the system of record and the source of truth for structure, and Replit is the interface layer that builds on top of it. MCP is the standard that makes the two speak the same language, with no bespoke integration to maintain on either side. It is what turns vibe coding and agentic coding from a demo trick into a workflow you can run against your own data.

From here, a few good next steps are to define a SurrealDB function and invoke it from Replit via the run tool, so business logic lives in the database where the agent can reuse it; to model a richer graph with RELATE and ask Replit to build views that traverse it; and to move from a dev tunnel to a Cloud instance and tighten your user permissions for a real deployment.

What's new in Surrealist 3.9

Matthew McFadden — Tue, 23 Jun 2026 17:10:31 +0000

We're excited to announce the release of Surrealist 3.9! This version introduces a complete design overhaul, a new datasets browser and data manager, an improved record inspector, and much more. Let's dive into what's new 🎉

Highlights

Complete design overhaul

Surrealist 3.9 introduces the most significant visual refresh since Surrealist 2.0. From the new sidebar and topbar to the fully revamped light theme, the entire interface has been redesigned to feel fresher, cleaner, more consistent, and easier to navigate.

Namespace and database selection has been unified into a single selection menu, making it faster to switch context without the need to navigate separate menus. Additionally, the new search input makes it easy to find what you need, even in large deployments.

Connection and instance settings have also been completely redesigned, and the overview page now includes search for both connections and organisations. These changes make it easier to find what you are looking for no matter how many instances you manage.

New datasets browser and data manager

Working with imports and exports of your database and trying out new features with official SurrealDB demo datasets has never been easier! Surrealist 3.9 introduces a data manager and dedicated datasets browser to make managing bulk data in your database faster and more intuitive.

Additionally, it is now easier than ever to discover, browse, and apply official SurrealDB datasets to your database or Sandbox instance so that you can learn about and try new SurrealDB features in an interactive manner without needing to scroll through docs.

Improved record inspector

The record inspector has been significantly enhanced to give you a deeper view of your data. The new References and Live tabs make it easier to explore record relationships and monitor real-time changes, while the new actions menu gives you more control over how you interact with individual records.

These improvements make the record inspector a more capable tool for day-to-day data exploration whether you are tracing graph relationships, inspecting linked records, or watching live query results update in real time.

Full changelog

Improved designer view to use ALTER statements in 3.x instances
Overhauled Surrealist design
- Improved brand icons
- Redesigned light theme
- Redesigned sidebar and topbar
- Added a toggle sidebar button to the topbar
- Moved settings button to a menu item in the topbar when logged out and account menu when logged in
- Unified the namespace and database selectors into a single selection menu
- Completely redesigned connection and instance settings
- Implemented new search functionality for connections and organisations on the overview page
- Revamped and re-enabled API Docs view
Implemented a new datasets browser and data manager (#1224)
Improved the record inspector with new references and live tabs, and new actions
Implemented VIM mode setting (#106)
Implemented the ability to toggle tables in the designer (#372)
Implemented default namespace and database functionality for 3.x instances
Implemented namespace and database comment editor
Added namespace and database comments to selection menu and database settings page
Added search inputs to the namespace and database selection lists
Added designer view LOD settings for zoom-based table simplification (#1222)
Added pagination to the newsletter drawer
Fixed title bar overlapping drawers on Windows and Linux
Fixed authentication redirect on session expiry
Fixed Windows install art not showing for new installations
Fixed Surrealist mini not allowing datasets other than surreal-deal-store
Fixed an error where imports always showed success, even when they failed
Fixed 2.x sample data datasets being applied to 3.x databases
Fixed explorer returning no rows when sorting on empty columns (#1194)
Fixed interface and designer zoom not applying on all platforms (#1188)
Clean up stale graph connections after deleting edge tables (#1147)
Fixed an issue where clicking a table in designer view would cause a crash (#1238)
Fixed an issue causing large conection urls to cause UI overflow in connection cards (#1225)
Fixed broken documentation links (#1217)
Fixed passing URLs through desktop launcher (#1179)
Fixed Designer exports including lower LOD levels
Fixed designer not showing links for complex ids (#1063)
Fixed UUID records not resolving correctly in graph (#974)
Fixed clipboard writes failing in some browsers (#994)
Fixed GraphQL view authentication (#1101)

We hope you enjoy these new features and improvements! As always, we appreciate your feedback and suggestions for future releases. Join the SurrealDB Discord to engage with the community and receive support.

Get started for free today at app.surrealdb.com

SurrealDB is now available on the Nebius AI Cloud Marketplace

Mark Gyles — Thu, 18 Jun 2026 15:33:29 +0000

Author: Tobie Morgan Hitchcock

We're excited to announce that SurrealDB is now officially available on the Nebius AI Cloud Marketplace.

This launch reflects our commitment to meeting developers and AI teams where they build, and deepens our partnership with Nebius to make SurrealDB easier to adopt, deploy, and scale on one of the fastest-growing AI cloud platforms in the world.

Why Nebius?

Nebius is a full-stack AI cloud built for the demands of modern AI workloads. Powered by the latest GPU and high-performance networking infrastructure, with managed platform, serverless AI, and storage built for the entire AI lifecycle, Nebius gives teams the infrastructure to train, tune, and serve models at scale.

As an NVIDIA Reference Platform Cloud Partner with infrastructure across Europe and the US, Nebius pairs bare-metal performance with the operational simplicity and cost efficiency that AI teams need to move from experiment to production. It's a natural home for SurrealDB - giving you a unified data layer right alongside the compute powering your AI and agentic applications.

Why SurrealDB?

SurrealDB combines document, graph, and relational capabilities in one unified database - designed for agent memory, context layers, modern applications, real-time systems, and AI-powered workloads.With flexible schema, SurrealQL, and built-in real-time features, SurrealDB enables you to build semantic and context layers powered by knowledge graphs for agent memory and multi-agentic workflows.

SurrealDB simplifies your technology stack, reduces Total Cost of Ownership and operational complexity, and allows you to ship products and features in days rather than weeks.

Get started

SurrealDB is available now on the Nebius AI Cloud Marketplace. We can't wait to see what you build, join our Discord community and let us know how you get on!

SurrealDB 3.x by the numbers

Mark Gyles — Fri, 29 May 2026 19:20:49 +0000

Author: Tobie Morgan Hitchcock

One engine, multi-workloads, full durability.

You can explore the full results, methodology, and per-database breakdowns at surrealdb.com/benchmarks.

Why we ran these

Database benchmarks are notoriously easy to game, and difficult to get right. Different hardware, different durability settings, different client libraries, a workload that happens to suit one engine's indexing strategy - any of those will tilt the numbers. So we did three things:

Ran every database on the same hardware - an AMD Ryzen Threadripper 9970X (32C/64T), 128 GiB DDR5, NVMe storage, Ubuntu 24.04.
Used the same open-source harness - crud-bench - with each workload translated into each engine's native query language so no database is penalised for an unfamiliar dialect.
Configured every engine for production-grade durability - fsync on, snapshot isolation, no in-memory shortcuts (except where explicitly noted for embedded comparisons).

We also went out of our way to give every database a fair shot. Rather than running each engine on its out-of-the-box defaults, we used optimised configurations across the board - the same kind of tuning a production team would apply before going live. That meant raising connection and worker pool limits to match the 128-client load, sizing buffer pools, page caches, and shared memory to take advantage of the available 128 GiB of RAM, enabling parallel query execution and prepared-statement caching where supported, setting WAL and checkpoint intervals to values recommended by each project's own performance guides, and turning on the indexes and storage engines (InnoDB, WiredTiger, RocksDB-backed stores, etc.) that each database's documentation recommends for OLTP workloads. The goal was to make sure no engine was held back by a conservative default - if a database underperforms here, it isn't because we left it on its laptop-friendly starter config.

Workloads run with 128 clients issuing 48 concurrent queries each, against datasets of a single table with 5 - 15 million rows of mixed-type records (strings, integers, floats, UUIDs, datetimes, booleans, large text fields, geospatial data, and nested objects and arrays).

About last time

We owe a word on durability. The previous round of benchmark results ran with fsync disabled for every engine - leaving each database's writes in the OS page cache rather than flushed to disk. Every database in the comparison ran with the same setting, so nothing was being "fudged" relative to the other engines, but we didn't make the setting explicit, and the headline numbers ended up describing a workload that most production deployments would not likely run.

This round is different. Every database in these benchmarks runs with full disk durability enabled - fsync on, WAL flushed on every commit, no buffered writes hiding behind the page cache. The configuration files for each engine are checked into the crud-bench repository so anyone can audit them. The numbers above are what each engine sustains when every committed transaction is on disk before the client gets an acknowledgement. That's slower than the cache-friendly numbers you'll find in some marketing posts, ours included, but it's the only honest way to compare databases that are going to outlive a power outage.

How far SurrealDB has come

The biggest story is internal. Across three major releases, we've fundamentally rebuilt the query, parser, and storage layers:

Between SurrealDB 2.x and 3.x alone:

31% faster mean CRUD throughput
58% faster batch operations
11,894% faster non-indexed full-table scans
136% faster indexed queries
Tail latency improvements of 27% (CRUD), 32% (batches), 59% (indexed), and 99% (scans)

The scan number is not a typo. The SurrealDB 3.x query planner and storage engine eliminates the per-row decoding overhead that dominated earlier versions, which is why a workload that used to take minutes now completes in seconds.

How we compare to other databases

SurrealDB is a durable, transactional, multi-model database, so the comparisons that matter most are against the primary databases people actually evaluate it against - Postgres for relational, MongoDB for document, Neo4j for graph. Here's how the same workload looks across those three categories, run on the same hardware with each engine on a tuned production-grade configuration.

vs. PostgreSQL (and MySQL)

CRUD throughput (ops/s) and bulk-read metrics:

SurrealDB is faster than Postgres on every write operation - roughly 1.5× faster creates, 1.3× faster updates, and 1.8× faster deletes - while Postgres still edges ahead on raw single-record reads. Against MySQL the gap widens dramatically: SurrealDB is 5 - 7× faster on writes.

Averaged across creates, updates, and deletes, SurrealDB delivers ~1.5× the write throughput of Postgres - the headline number the benchmarks page leads the Relational category with - and beats Postgres by ~1.5× on full-table counts. Postgres' query planner is 30 years old and still ahead on indexed predicate filtering; we're not pretending otherwise, and we're working on closing that gap in 3.1.

vs. MongoDB (and ArangoDB)

CRUD throughput (ops/s) and bulk-read metrics:

This is the closest race. MongoDB still leads on single-record writes, while SurrealDB is ~1.3× faster on reads - and the picture flips on heavier workloads. On predicate filter scans against unindexed tables - the headline figure the benchmarks page uses for the Document category - SurrealDB is roughly 2.7× faster than MongoDB, with consistently lower mean and p99 latency. Against ArangoDB's document engine, SurrealDB is between 100× and 150× faster on writes.

vs. Neo4j (and ArangoDB)

CRUD throughput (ops/s) and bulk-read metrics:

SurrealDB outperforms Neo4j across every CRUD operation - roughly 2 - 3.5× faster on writes and 1.5× faster on reads - while running the same graph traversals through the same engine that handles documents and tables.

The gap on filtered scans is even more dramatic. Across indexed predicate filter queries - the headline metric the benchmarks page uses for the Graph category - SurrealDB is roughly 35× faster than Neo4j. No separate database, no separate query language, no separate operational story.

Reference point: Redis and KeyDB

For raw key-value throughput, we also ran SurrealDB's in-memory engine (with append-only persistence) against Redis and KeyDB:

That's roughly 3× faster than Redis on writes, updates, and deletes, while offering durable, snapshot-isolated transactions and a full query language Redis doesn't have. Redis still wins on large 1,000-record batch operations and edges ahead on single-record reads.

Embedded mode (vs. SQLite)

SurrealDB's embedded engine runs the same SurrealQL on the same disk format as the server.

Against SQLite, SurrealDB is roughly 85× faster on creates, 110× faster on updates, and 75× faster on deletes, with single-record reads in the same ballpark. On predicate filter scans against unindexed tables it's around 6.5× faster than SQLite, and on indexed filter scans, around 3× faster.

The full breakdowns - including p50, p95, and p99 latencies, batch sizes from 100 to 1,000 rows, indexed and non-indexed predicate filters, and full-text search - are on the benchmarks page.

Closing the remaining gaps

The numbers above are an honest snapshot, not a finish line. There are still workloads where Redis, MongoDB, and Postgres beat us - large batch operations vs. Redis, single-record writes vs. Mongo, indexed predicate filtering vs. Postgres - and we know exactly where each gap comes from. Closing those gaps is the central focus of the SurrealDB 3.1 cycle.

What we're actively working on:

Batch path rewrites to bring 100-row and 1,000-row batched ops closer to Redis throughput, including better client-side pipelining and a leaner server-side batch executor.
A smarter query planner with cost-based optimisation, predicate pushdown into the storage engine, and richer index selectivity statistics - the work that gets us to parity with Postgres on indexed filter scans.
Storage layer improvements for the document workload - more compact in-place updates, sharper write amplification, and tighter integration between the key encoding and the document path resolver - which is where Mongo currently has the edge on single-record writes.
Vector and graph traversal optimisations as those workloads land in the benchmark suite, so the multi-model story holds up at the same rigour as CRUD.

The goal isn't "fastest at one thing." It's to be fastest, or competitive, across every workload that matters, while keeping the one property no specialist engine can match: a single query language - SurrealQL - that handles relational, document, graph, key-value, time-series, vector, and full-text search data in the same database, with the same transactional guarantees, on the same disk format - and the same engine, whether you're running it embedded inside an application, on a single server, at the edge close to your users, or distributed across hundreds of nodes for horizontal scale. We don't think you should have to choose between Postgres, Mongo, Neo4j, and Redis - or between a database that runs on a developer laptop and one that runs across a global fleet. We think a single database should run all four shapes of workload at production speed, anywhere it needs to live, and the SurrealDB 3.x numbers above are the strongest evidence yet that it can.

Why this matters for AI agents

There's a reason we keep pushing on this combination of data models, and it's not historical accident. Agent memory is multi-model by nature. A useful AI agent needs structured facts about the world (relational), semi-structured context and tool outputs (document), entity and event relationships (graph), embeddings for semantic recall (vector), keyword and BM25 retrieval over its corpus (full-text search), episodic and temporal context (time-series), and fast session and cache state (key-value) - and it needs all of that in a single transactionally consistent store, because the moment those shapes live in separate databases, you've built a glue-code problem that breaks every time the schema changes or the model is updated.

Agents also need that memory close to where they run. An agent reasoning inside a browser, a phone, an in-vehicle system, or a per-tenant edge worker can't afford a round trip to a central database for every retrieval. The fact that SurrealDB runs as an embedded engine on the same disk format as the distributed server - with the same query language and the same transactional guarantees - is what makes it usable as the memory layer for agents that move fluidly between local, edge, and centralised deployments. Faster CRUD, faster scans, and faster indexed lookups aren't just abstract benchmark wins; they're how many tools an agent can call, how much context it can recall per turn, and how many concurrent agents a single host can support. That's the workload SurrealDB 3.x is built for, and it's the workload the next round of benchmarks - covering vector search, graph traversal, and full-text retrieval - will measure head-on.

What's next

We intend to expand the benchmarks to also cover CockroachDB, TiDB, MongoDB, and Aerospike for distributed comparisons, which we'll publish in a future round. We also plan to expand the workload set to include graph traversals vector search, and full-text search, two areas where the single-engine, multi-model design of SurrealDB shows its biggest advantages.

Until then: the harness is open source, the results are reproducible, and we'd love for you to run them on your own hardware and tell us what you find.

See the full benchmarks.

SurrealDB 3.1: stability, DiskANN, and a new release process

Mark Gyles — Thu, 28 May 2026 08:43:39 +0000

Author: Tobie Morgan Hitchcock

Three months after 3.0 went GA, we're excited to announce that SurrealDB 3.1 is now available. This is the first minor release in the 3.x series. It builds on the foundations we shipped in 3.0 with a focus on stability, a second approximate-nearest-neighbour index in DiskANN, and a substantial round of security hardening. Alongside the release, we're also rolling out a change to how we develop and ship SurrealDB.

The full list of changes is in the 3.1 release notes. Below are the highlights.

What's new in 3.1

DiskANN approximate-nearest neighbour index

SurrealDB now ships DiskANN as a second ANN index type, sitting alongside HNSW. DiskANN trades a different set of memory and recall characteristics and is well suited to larger-than-memory vector workloads, which has been a recurring request from teams building production agent and search systems on SurrealDB.

The introduction of DiskANN also drove an end-to-end overhaul of the ANN warm-lookup path. Both HNSW and DiskANN benefit from this work, with measurable improvements to warm-cache latency on the existing HNSW index for free.

You can pick the index type at definition time with the new DEFINE INDEX ... DISKANN syntax. See the release notes for the full set of options.

GraphQL: aliases, cursor pagination, and multi-model filtering

SurrealDB v3.1 brings a significant upgrade to the GraphQL surface, making it more expressive, more predictable, and easier to integrate with modern GraphQL clients.

The generated schema now follows Apollo conventions by default, with singular fetch, plural list queries, and createX / updateX / deleteX mutations, so you always know what to expect without consulting per-database config. Fields and tables can now carry GRAPHQL_ALIAS and GRAPHQL_DEPRECATED clauses directly in their definitions, letting you decouple your SurrealQL identifiers from the names your API consumers see:

Schema

DEFINE FIELD first_name ON person TYPE string
  GRAPHQL_ALIAS "firstName";

DEFINE FIELD legacy_score ON player TYPE int
  GRAPHQL_DEPRECATED "Use `rank` instead";

Cursor pagination arrives in this release too. Each table now gets a <plural>Connection query returning edges, pageInfo, and a lazily-evaluated totalCount, so you only pay for the count when you ask for it. Offset pagination via limit and start remains fully supported alongside it.

On the multi-model side, GraphQL queries can now reach across SurrealDB's full data model. Full-text search, vector similarity, and time-series aggregation are all directly queryable through the GraphQL API, unlocking AI-native and analytics-heavy workloads without touching SurrealQL.

This release also closes a range of reported issues: stale schema caches after DDL changes, invalid filter identifiers on nested array fields, missing id range and in filters, and count()-based predicates in WHERE clauses, all resolved and covered by integration tests.

Improved in-memory performance

SurrealDB's in-memory backend now uses a datastore based on optimistic lock coupling. This improves performance by allowing readers to acquire lock-free access, only retrying at the end if a modification has occurred in the meantime. This allows readers to proceed without blocking writers, and vice versa.

Stability and correctness

The bulk of the 3.1 work is bug fixes and stabilisation of the 3.0 line. This continues the stream of fixes that shipped in v3.0.1 through v3.0.5, with a substantial number of additional issues addressed across the query engine, indexing, and storage layers. If you upgraded from 2.x to 3.0 and hit any rough edges, there's a strong chance the relevant fix is in 3.1.

Security hardening

3.1 closes a batch of previously reported security vulnerabilities, alongside a set of previously undiscovered issues that we found internally. The undiscovered ones come from an increased investment in LLM-assisted security review, in line with broader industry practice. Mozilla wrote a good summary of this approach recently. The combined result is a notably larger security section in this release than in previous ones.

The full security section is itemised in the release notes.

Enterprise: audit logging and slow-query pipeline

Customers on the Enterprise tier get two new operational tools in 3.1:

A structured audit log capturing authentication events, schema changes, and other actions of interest to compliance and security teams.
A slow-query pipeline that surfaces queries exceeding a configurable threshold, complete with their plan and execution metadata, to help diagnose performance issues in production.

Both have been on Enterprise customer wishlists for a while, and we're pleased to have them shipping in 3.1.

Other quality of life additions

Among the many changes mentioned in the 3.1 release notes, some of the changes that you won't want to miss are:

A built-in MCP server for AI tools and IDEs,Unified OpenTelemetry metrics and logging pipeline,
Unified OpenTelemetry metrics and logging pipeline,W3C trace propagation across HTTP and WebSocket,
W3C trace propagation across HTTP and WebSocket,Full ALTER coverage for every DEFINE statement,
Full ALTER coverage for every DEFINE statement,
And continued executor and index improvements beyond the in-memory engine.

A new release process

3.1 is also the first release we've shipped under a new development workflow, and we want to be transparent about what's changed and why.

For most of SurrealDB's history, we've developed in public on the main surrealdb/surrealdb repository. When a security vulnerability needed addressing, we'd cut a temporary private fork, fix the issue there, cut a release, patch the SurrealDB Cloud fleet, and then make the release public. The intent was good. Development happened where the community could see it, and security fixes were embargoed only as long as they needed to be. In practice, though, this added real overhead to every security response. Cutting a fresh private fork for each issue, keeping it in sync with main, and merging the fix back when going public all took time we'd rather have spent on the fix itself.

Starting with 3.1, we've moved all development to a private repository. The public surrealdb/surrealdb repo remains the source of truth for releases, issues, and the source code that users read. Day-to-day commits now happen privately.

The cadence looks like this:

We develop and tag releases in the private repository.
When a release is ready, we announce it publicly and ship binaries and Docker images on the usual schedule.
Roughly 1 week after each release, we sync the private repository back to the public surrealdb/surrealdb repo.

The week between release and public sync gives us a private window to triage any issues or vulnerabilities reported against the new version before the corresponding commits become visible. We can ship a fix and roll it out across SurrealDB Cloud before the underlying issue is public. This is the same model used by most database and infrastructure projects at comparable scale, and it lets us close security issues as quickly as they're reported.

A few practical notes:

Issues, PRs, and discussions stay on the public repo. Keep filing them on surrealdb/surrealdb. We watch and respond to them daily.
Security reports. Use the GitHub Security Advisory flow on the public repo, or email security@surrealdb.com. Both reach us privately, and are the right route for anything you don't want disclosed publicly.
Community PRs. We're still very keen for community contributions. They get reviewed against the public repo as before, and brought into the private tree as part of the normal cycle.

We don't expect this to be visible to most users in day-to-day use. If you follow commit-by-commit development on the public repo, the experience will change: you'll see batched updates around each release rather than a continuous stream. We think the security benefit is worth that tradeoff, and we plan to keep working this way for the foreseeable future.

Try it

SurrealDB 3.1 is available now. Head to the install page to grab it for your platform.

If you're running on SurrealDB Cloud, instances are being rolled to 3.1 as part of our standard release cycle. No action needed.

Read the full release notes for the complete list of changes, and come say hello on Discord if you hit anything along the way.

Kreuzberg & SurrealDB: from unstructured documents to hybrid retrieval

Mark Gyles — Tue, 12 May 2026 12:35:55 +0000

Author: Ignacio Paz

We’re excited to share a new partner integration: kreuzberg-surrealdb, a connector that bridges the Kreuzberg document intelligence framework directly into SurrealDB. This integration was created by the Kreuzberg team and we are excited to have this functionality available now in SurrealDB.

Kreuzberg extracts, chunks, and generates embeddings from 88+ document formats, while SurrealDB provides a multi-model database for AI applications, combining documents, graphs, vectors, and full-text search in a single system.

Together, they make it easy to build document search and RAG pipelines.

What the integration does

kreuzberg-surrealdb handles the full ingestion workflow:

Automatic schema setup
Content deduplication using SHA-256 hashing
Storage and indexing in SurrealDB
Documents ready for search immediately after ingest

The integration supports two modes:

DocumentConnector:indexes full documents for BM25 keyword search.
DocumentPipeline:chunks documents, generates embeddings, and enables semantic and hybrid search using HNSW vector indexes and Reciprocal Rank Fusion.

Why it matters

Building document search systems often requires combining multiple tools for extraction, chunking, embeddings, and storage.

With kreuzberg-surrealdb, the entire workflow runs through a single integration—no schema boilerplate, no duplicate ingestion, and built-in support for keyword, semantic, and hybrid search.

Get started

See how to get started in SurrealDB Docs: Kreuzberg Integration, and check out our example of How to build a knowledge graph for AI with SurrealDB and Kreuzberg.

Schema migrations in SurrealDB: A local dev workflow

Mark Gyles — Fri, 08 May 2026 12:42:16 +0000

Author: Chiru Boggavarapu

This post walks through a proper migration workflow for local development using SurrealKit, an official tool from the SurrealDB team that handles schema sync, rollouts, seeding, and testing.

If you've spent any time working with SurrealDB, you know that with great flexibility comes the responsibility of managing your schema carefully. You're iterating quickly, adding tables, refining field definitions, and removing what you no longer need, and before long your local database can drift out of sync with what your code expects.

What is SurrealKit?

SurrealKit is a CLI tool that manages your SurrealDB schema through .surql files. You define your schema as files, and SurrealKit keeps your database in sync with them.

It has two main modes:

Sync: a fast, declarative approach for local and dev environments. Your files are the source of truth. Add something and it gets created, change it and it gets updated, remove it and it gets deleted.
Rollout: a more controlled migration path for shared or production databases, with planning, staged execution, and rollback support.

For local dev, you'll mostly live in sync. Rollouts come into play when you're pushing to shared environments.

Getting Started

Cargo is the Rust package manager. It downloads a Rust package's dependencies, compiles the packages, and makes distributable packages.

Install via Cargo

cargo install surrealkit

Or grab a prebuilt binary from the GitHub releases page if you don't want to compile it.

Initialise a project

surrealkit init

This creates a /database directory with the scaffolding you need. SurrealKit connects to your database using environment variables, so add these to your .env:

.env

SURREALDB_HOST=localhost:8000
SURREALDB_NAME=myapp
SURREALDB_NAMESPACE=development
SURREALDB_USER=root
SURREALDB_PASSWORD=secret

It supports both DATABASE_HOST and PUBLIC_DATABASE_HOST variants, which is handy if you're working in a SvelteKit or similar setup where env vars are split by visibility.

The Local Dev Workflow

Writing Your Schema

Schema files live in database/schema/. Each file is a .surql file with your table definitions, indexes, access rules — whatever you'd normally write in SurrealQL.

The structure is entirely up to you. You might have one file per table, or group related things together. Either way, SurrealKit tracks what's in those files and reconciles it with what's actually in your database.

Syncing Changes

When you've made a change and want to apply it:

surrealkit sync

That's it. SurrealKit diffs your schema files against the current database state and applies what's changed. If you deleted a table definition from your files, it removes it from the database too. Everything stays in sync.

For active development sessions, watch mode is where you'll spend most of your time:

surrealkit sync --watch

This watches your database/schema/ directory and resyncs automatically whenever you save a file. It handles deletions too — if you remove a definition, it gets cleaned up. No manual intervention needed.

Moving to Shared Environments

The sync approach is great for local databases you own completely. But the moment you're working against a shared or staging database, you need more control. That's what rollouts are for.

Baseline First

Before your first rollout on an existing database:

surrealkit rollout baseline

This records the current state so SurrealKit knows what it's working from.

Plan → Start → Complete

When you're ready to ship a schema change:

surrealkit rollout plan --name add_user_indexes

This generates a TOML manifest in database/rollouts/ describing exactly what will change. You can review it, commit it, get it reviewed. Treat it like a pull request for your schema.

When you're ready to apply, you'll reference the manifest by its full filename. SurrealKit names these with a timestamp prefix: 20260302153045 translates to 2nd March 2026 at 15:30:45. This is the time the plan was generated, and it's there so rollouts always have a guaranteed sort order. If two people generate a plan on the same day, the timestamps keep them distinct and sequential. You'll see the full name in your database/rollouts/ directory after running plan.

When you're ready to apply:

surrealkit rollout start 20260302153045__add_user_indexes

This runs the non-destructive part of the migration. Once your application is deployed and you're confident everything is working:

surrealkit rollout complete 20260302153045__add_user_indexes

This finishes the migration, including any cleanup of legacy objects.

If something goes wrong mid-rollout:

surrealkit rollout rollback 20260302153045__add_user_indexes

You can also validate a manifest without touching the database:

surrealkit rollout lint 20260302153045__add_user_indexes

And check what state a rollout is in:

surrealkit rollout status

SurrealKit tracks rollout state in the database itself, so it's always resumable.

Seeding

SurrealKit has a built-in seeding system for populating your local database with test data:

surrealkit seed

Seed files live alongside your schema in the /database directory. Useful for onboarding new team members quickly — they clone the repo, init SurrealKit, run sync and seed, and they're good to go.

Testing

One of the more interesting features is the declarative testing framework. You write TOML test suites in database/tests/suites/ and run them with:

surrealkit test

Each suite runs in an isolated ephemeral namespace, so tests can't interfere with each other or your actual data. You can test SQL assertions, permission rules, schema metadata, and even HTTP API endpoints.

A simple example, checking that a guest can't create an order:

name = "security_smoke"

[[cases]]
name = "guest_cannot_create_order"
kind = "sql_expect"
actor = "guest"
sql = "CREATE order CONTENT { total: 10 };"
allow = false
error_contains = "permission"

You can also test permission matrices across a whole table at once, which is handy for verifying your access rules haven't regressed after a schema change.

For CI, add --json-out to get machine-readable output:

surrealkit test --json-out database/tests/report.json

The command exits non-zero on any failure, so it integrates cleanly with GitHub Actions and other CI/CD systems seamlessly.

Putting It Together

Here's what a typical day looks like with this setup:

Pull the latest changes
Run surrealkit sync to update your local DB
Edit schema files in database/schema/
Use surrealkit sync --watch while you work
When you're done, run surrealkit test to make sure nothing broke
Commit your schema files alongside your code

For production changes, swap step 4 for surrealkit rollout plan and follow the plan → start → complete flow.

Would love to hear how you get on with SurrealKit. Jump into Discord and let us know how it goes or if you need a hand along the way.

DEV Community: SurrealDB

Empower your agents with the new SurrealDB MCP

Getting started

Adding the SurrealDB MCP to your agent

Deploy and manage resources just by asking

Ask questions about your data and build with ease

Memory that outlasts the conversation

Let us know what you think

Agentic retrieval for structured data with text-to-surql

Using a retrieval tool

The SurrealQL generation tool

Built-in permissions

How to build it

Fine-tuning

Conclusion

Footnotes

Using SurrealDB to understand how Buffalo buffalo buffalo Buffalo buffalo

Buffaloes that buffalo Buffalo buffaloes

Buffaloing back

Visualising all the buffaloing

Learn more

Ready to try it?

Detecting connections as they form: An introduction to streaming graph pattern matching

Detecting connections as they form: An introduction to streaming graph pattern matching

🕸️ What is a labeled property graph?

⚡ What is streaming graph pattern matching?

🎬 A running example: the movie database

🗂️ Imagining the configuration

Sources — loading the graph

filter — Row-level gating

record_id!() — Typed identifiers

+ @ — Creating a vertex

+ @from->edge->@to — Creating an edge

Patterns — Matching the graph

Aliases and join conditions

Actions — Deriving new edges

Output projections

More pattern expressiveness

🔄 What would it look like to run this?

🧠 Why this configuration style?

👉 TL;DR

Introducing Scale: SurrealDB Cloud, built for high availability and scale

What you get with Scale

Built on SurrealDS

Architecture overview

Future roadmap

Get started

Bring SurrealDB to your Replit Agent

What you'll need

How SurrealDB, MCP, and Replit fit together

Step 1: Install or upgrade to SurrealDB 3.1

Step 2: Start your instance and create some data

Step 3: Enable the MCP server over HTTP

Step 4: Make your instance reachable

Connect SurrealDB to Replit

Build an app on your SurrealDB data with Replit

SurrealDB MCP tools reference

Production considerations for SurrealDB with Replit

Where this leaves you

What's new in Surrealist 3.9

Highlights

Complete design overhaul

New datasets browser and data manager

Improved record inspector

Full changelog

SurrealDB is now available on the Nebius AI Cloud Marketplace

Why Nebius?

Why SurrealDB?

Get started

SurrealDB 3.x by the numbers

One engine, multi-workloads, full durability.

Why we ran these

About last time

How far SurrealDB has come

How we compare to other databases

vs. PostgreSQL (and MySQL)

vs. MongoDB (and ArangoDB)

vs. Neo4j (and ArangoDB)

Reference point: Redis and KeyDB

Embedded mode (vs. SQLite)

`filter` — Row-level gating

`record_id!()` — Typed identifiers

`+ @` — Creating a vertex

`+ @from->edge->@to` — Creating an edge