VERSION 3.1

Introducing SurrealDB 3.1

Q: Why is 3.1 worth upgrading from 3.0 if we are already in production?

3.1 closes 108 bug fixes, 22 security fixes, and 46 broader improvements across the 3.1 series, alongside a unified observability pipeline, distributed trace context propagation, audit logging for Enterprise, and the DiskANN index. The catalog and on-disk layouts are unchanged from 3.0.x, so the upgrade is in place and can be rolled forward without a migration step.

Q: When should we choose DiskANN over HNSW?

HNSW remains the right choice when the index fits comfortably in memory and recall is the binding constraint. DiskANN is purpose built for larger than memory vector workloads, including agent corpora that grow continuously, billion scale retrieval, and long lived production indexes that cannot be sized around the host. Both share the same KNN operator, so the choice is per index rather than per query.

Q: What does the new audit logging pipeline cover, and what does it not?

The Enterprise audit pipeline is a queued, worker backed module that records authenticated operations to a configurable sink, with a redaction layer that strips sensitive fields before serialisation. The default sink is a size rotated, SHA-256 hash chained, optionally fsync'd file in append only 0600 mode. It is configured through 13 SURREAL_AUDIT_* environment variables covering sink, rotation, hashing, redaction, queue capacity, overflow strategy, and OTLP export. Slow query telemetry shares the same pipeline with a duration gate at the front of the observer.

Q: Why has SurrealDB moved development to a private repository?

To close security issues faster. Previously, every security response required a temporary private fork to embargo the fix. By developing on a private repository and syncing the public surrealdb/surrealdb repo about a week after each release, the team has a private window to triage and ship before the underlying commit is public. Issues, pull requests, discussions, and security reports continue on the public repo. This is the same model used by most database and infrastructure projects at comparable scale.

Q: How will the unified observability pipeline affect our existing dashboards?

The community metrics pipeline is reorganised under the surrealdb.* scope with a new /metrics allow list. Existing Prometheus dashboards and alerts that scrape metric names from 3.0.x will need updating. The release notes include the full migration table. New surrealdb.transaction.retries and surrealdb.transaction.conflicts counters give operators a direct view of retryable storage engine errors without inferring them from logs.

Q: Is the upgrade from 3.0 to 3.1 in place?

Yes. The catalog and KV on disk layouts are unchanged from 3.0.x, so an existing 3.0 deployment rolls forward in place. A handful of operational defaults have been tightened and a small set of public surfaces have changed, including GraphQL naming, RocksDB readahead, the /key request body contract, --allow-net resolution, filesystem bucket key casing, and the observability metrics surface. The release notes list each one with migration guidance.

Q: What about 2.x deployments?

Customers on 2.x should plan a 2.x to 3.0 upgrade first, then roll forward to 3.1 in place. The bulk of the 3.1 work continues stabilising the 3.0 line, so if a particular 2.x to 3.0 migration produced rough edges, there is a strong chance the relevant fix is in 3.1. Our team can scope the migration as part of a production readiness review.

Q: What additional enterprise tooling ships with 3.1 beyond audit and slow query?

Enterprise customers also get a FIPS build option that routes TLS through the AWS-LC FIPS module and installs the FIPS crypto provider at startup, alongside the existing enterprise feature surface: priority security patching, encryption at rest, object storage support, distributed live queries, and trusted execution environments. The 3.1 release strengthens the controls underneath SurrealDB's existing SOC 2, ISO 27001, GDPR, CCPA, and Cyber Essentials Plus posture.

The operational maturity release. Production stability, DiskANN for larger than memory vector search, audit logging and slow query observability for enterprise, and a new release process to close security issues faster.

01 |THE MILESTONE

3.0 was the foundation.
3.1 is the production line.

Three months after 3.0 went GA, SurrealDB 3.1 lands as the first minor in the 3.x series. The catalog and on-disk layouts are unchanged from 3.0.x, so existing deployments roll forward in place. What changes is the operational surface around the database: stability, security hardening, observability, and the day-two tooling that enterprise teams expect from a database they are betting their architecture on.

02 |WHAT 3.1 DELIVERS

A balance sheet for production

3.1 is deliberately a stability release on top of the 3.0 line. The headline numbers below are taken directly from the 3.1.0 release notes and describe the work that landed across the 3.1 series.

Read the full release notes

Highlight features

From DiskANN and the MCP server to a unified observability pipeline, Surrealism async functions, and durable distributed index builds.

Broader improvements

Performance, RocksDB tuning, SDK surface, GraphQL overhaul, scan path optimisations, and operational defaults.

108

Bug fixes

Across the query engine, planner, indexes, storage, RPC, transactions, auth, events, and logging.

Security fixes

A combination of issues reported by external researchers and findings from SurrealDB's internal security review process.

03 |VECTOR SEARCH AT SCALE

DiskANN, for vectors that no
longer fit in memory

DiskANN now ships as a second approximate nearest neighbour index alongside HNSW, under the same <|K, EF|> operator. HNSW remains the right choice when the working set fits comfortably in memory and recall is the binding constraint. DiskANN is purpose built for the workloads where it does not: large agent corpora, billion scale retrieval, and long lived production indexes that have to grow without rebuilding the host.

DEFINE INDEX

pts_idx ON pts FIELDS embedding DISKANN DIMENSION 768

KNN OPERATOR

<|K, EF|>

HNSW

in-memory

Recall first

DiskANN

larger than memory

Scale first

Both DiskANN and HNSW gain F16, U8, and I8 element types, plus inner product and cosine normalised distance metrics.
The warm lookup path is rewritten end to end. HNSW inherits the same caches and benefits from the change at no migration cost.
Concurrent builds and KNN queries are safe at release. A freshly defined index is immediately usable.

04 |OPERATIONAL MATURITY

Day two is now a first class concern

The observability surface, the retry budgets, the shutdown sequence, and the audit pipeline in 3.1 are designed for the people who run SurrealDB in production. Three signals on one OpenTelemetry pipeline. Trace context that survives every transport. Retry behaviour you can reason about under load.

Unified observability pipeline

One OpenTelemetry pipeline replaces the previous Prometheus path and parallel OtelObserver. Metrics families reorganised under the surrealdb.* scope; the /metrics endpoint enforces a render time allow list.

W3C trace context propagation

Inbound traceparent and tracestate honoured on every transport. HTTP, RPC, and WebSocket spans extend the caller's trace through the server, so the agent and the database share one tree.

Audit logging (Enterprise)

A queued, worker backed audit log with a redaction layer. Authentication events, schema changes, and other auditable actions land in a SHA-256 hash chained, optionally fsync'd file sink, configurable via 13 environment variables.

Slow query telemetry (Enterprise)

Structured records emitted for queries that cross the configured threshold, sharing the audit pipeline's sink, redaction, and rotation. The duration gate sits at the front of the observer.

Bounded retry and shutdown

Datastore initialisation wraps each attempt in its own timeout. The global retry budget is now 120 seconds, and shutdown work is bounded against the same deadline so a stuck task cannot delay teardown indefinitely.

Transaction retry and conflict signals

New surrealdb.transaction.retries and surrealdb.transaction.conflicts counters fire from the commit path. Operators can finally see retryable storage engine errors in their dashboards without inferring them from logs.

05 |SECURITY AND COMPLIANCE

A larger security section than usual, on purpose

3.1 closes a notably larger batch of security issues than previous releases. The increase is driven by a deliberate investment in internal security review, including LLM assisted review in line with wider industry practice. Most issues are reachable only by an authenticated caller with existing privileges, but every fix in this release ships enabled by default with no configuration required.

22 security fixes shipped

Vulnerabilities surfaced by internal review and external researchers, addressed across RPC, authorisation, graph traversal, live queries, and JSON parsing. All fixes enabled by default.

--allow-net DNS pinning

When a hostname permitted by --allow-net resolves to a private or special use IP, the resolved IP must also be covered. Closes the gap between hostname allowlists and what they actually reach on the network.

FIPS build option (Enterprise)

A FIPS Cargo feature routes TLS through the AWS-LC FIPS module and installs the FIPS crypto provider at startup. Built for regulated industries that require validated cryptography.

Hardened /key endpoint

Request bodies on /key endpoints are now inert values bound to $data, not executable SurrealQL. Closes arbitrary execution on deployments that expose /key only.

Permission enforcement on indexed paths

Indexed count and CONTAINS scans now refuse plans where the WHERE clause touches fields under non-Full SELECT permissions, so record users can no longer infer cardinality of values they cannot read.

Live query lifecycle hardening

Live queries terminate on session invalidation, TTL expiry, and principal changes. Subscribers can no longer read hidden records via captured $value, $before, $after, or $event.

USE no longer creates resources

USE NS and USE DB no longer auto create namespaces or databases without the same authorisation as DEFINE. A stale namespace token can no longer recreate a dropped parent as a side effect.

Compliance posture

SurrealDB Enterprise holds SOC 2 Type I and Type II, ISO 27001, GDPR, CCPA, and Cyber Essentials Plus. The 3.1 release strengthens the controls underneath each.

Learn more

06 |A NEW RELEASE PROCESS

Closing security issues faster, on the same cadence

Starting with 3.1, day to day development moves to a private repository. The public surrealdb/surrealdb repo remains the source of truth for releases, issues, and the source code that users read. The week between release and public sync gives the team a private window to triage and ship a fix before the underlying issue becomes visible. This is the same model used by most database and infrastructure projects at comparable scale.

Private development

Commits, security fixes, and pre-release work happen on the private repository.

Release

Binaries, Docker images, and the release notes ship on the usual public cadence.

Public sync

About a week later, commits and tags are synced back to surrealdb/surrealdb.

Issues, pull requests, and discussions continue on the public repo and are watched daily.
Security reports route through the public GitHub Security Advisory flow or security@surrealdb.com.
Public commits arrive as batched updates around each release rather than a continuous stream.

07 |EVERYTHING NEW

The broader 3.1 surface

Beyond the operational and security work, 3.1 introduces an MCP server, a GraphQL overhaul, expanded ALTER coverage, durable distributed index build coordination, predicate prefilter and scan path performance work, memory optimisations on the value layer, and async functions in Surrealism plugins.

See the complete change list

First party MCP server

A typed, structured tool surface for AI agents, exposed as the surreal mcp stdio subcommand and an HTTP /mcp endpoint guarded by the existing authentication middleware. Twelve typed tools, with read only and destructive hints.

GraphQL overhaul

Apollo conventions by default. Relay style cursor pagination with lazily evaluated totalCount. GRAPHQL_ALIAS and GRAPHQL_DEPRECATED clauses on definitions. Vector similarity, full text search, and aggregation filters reachable from one API.

Predicate prefilter and scan path work

WHERE predicates evaluated against raw RocksDB key/value pairs before revision decode. K-way merge for IN list with ORDER BY LIMIT. Single scan graph traversals via embedded adjacency keys. The 3.0 executor's scan throughput lifts again.

Memory work on the value layer

A 24 byte small string optimised Strand type replaces String through every core hot path. Object entries and Value::String shrink by 8 bytes each. The wire format is unchanged. Compounds at document scale.

Durable distributed index builds

Concurrently built indexes now keep their state in the catalog, not in process memory. Every node agrees on which node owns the build, which writes are admitted, when replay completes, and when the index becomes query eligible.

Async functions in Surrealism plugins

Plugin authors can mark exported functions as async and await host imports directly. Crates that depend on tokio::spawn for connection pools and timers, like reqwest and sqlx, are now usable inside SurrealQL.

08 |TALK TO US

See SurrealDB 3.1 in your stack

Book a walkthrough with our team. We will pressure test 3.1 against your production workload, scope a proof of concept, and map the migration path from 3.0 or 2.x.

A production readiness review covering observability, audit, and operational defaults
Vector workload sizing across HNSW and DiskANN for your corpus and recall targets
Compliance walkthrough across SOC 2, ISO 27001, FIPS, and the regulated deployment options
A migration plan from 3.0 or 2.x, with the breaking changes applied to your stack

FREQUENTLY ASKED QUESTIONS

Common questions from sales and platform teams

Why is 3.1 worth upgrading from 3.0 if we are already in production?

When should we choose DiskANN over HNSW?

What does the new audit logging pipeline cover, and what does it not?

Why has SurrealDB moved development to a private repository?

How will the unified observability pipeline affect our existing dashboards?

Is the upgrade from 3.0 to 3.1 in place?

What about 2.x deployments?

What additional enterprise tooling ships with 3.1 beyond audit and slow query?

GET STARTED

Run SurrealDB 3.1 in production

One vendor across context, memory, and storage. Production stability, enterprise observability, and a release process built to close issues quickly.

SOC 2 Type 2

GDPR

Cyber Essentials Plus

ISO 27001