fdb-record-layer: a relational database bolted onto FoundationDB

A relational model layered over a distributed key-value store

FoundationDB itself is a key-value store with strong transactional guarantees and no notion of tables, rows or a query language. The Record Layer is the piece that fills that gap, and it does so as a Java library rather than as a separate server. Applications reach it in two ways: through a SQL interface over JDBC, or through a lower-level record-oriented Java API when they want to work with records directly. The point of the design is that you get relational access, including joins, aggregation, grouping, sorting and correlated subqueries, without giving up the properties that make FoundationDB attractive in the first place. The documentation states that the layer inherits the full ACID transactional semantics of FoundationDB, and that the whole thing is meant for distributed, stateless deployments with millisecond-level store initialization and query execution, scaling to thousands of independent database instances. That last claim is the interesting one. It reframes a single logical database as a fleet of small ones, which is a very different operational shape from a classic relational server.

Schema templates exist so shared schemas can change under many tenants

The reusable schema templates are the feature aimed squarely at multi-tenant SaaS. The idea is that a set of tenants shares one logical schema, and that schema has to be able to evolve over time without a migration per tenant, because you cannot schedule downtime with a thousand customers independently. Templates let you define a schema once and reuse it across many independently initialised databases, which fits the stateless deployment model. The cost is that you are further from raw SQL DDL and from the tool chains that assume it. A team that wants to hand a schema to a reporting tool, or that expects standard migration scripts to work, will find the record-oriented model and its templates a different way of working. The documentation describes the templates as enabling massively multi-tenant architectures whose shared schemas can safely evolve, and that word safely is doing real work in the context of a store that has to keep serving traffic while the schema changes.

The type system extends relations with structs, arrays and vectors

Beyond the standard relational types, the type system allows user-defined nested structs, arrays, and fixed-dimension vectors. The reason the vector type exists is stated plainly in the documentation: it is there for machine learning embeddings and similarity search. That is a specific and modern motivation, and it changes what the library is for. A plain relational type system has no natural home for a 768-dimensional float array, so applications either flatten it into rows or store it outside the database, and the second option means losing transactional consistency with the record the vector belongs to. With a fixed-dimension vector type in the schema, the embedding and the row it describes live in the same transaction. The type system is extended rather than replaced, so the familiar relational types remain available, and the same type system serves both a conventional table and an embedding column.

The query planner favours streams over in-memory buffers

The planner is described as intelligent, and the list of what it handles is specific: joins, aggregation, grouping, sorting, and correlated subqueries. The interesting design claim is what it does with the results, namely that it favours stream-based processing over in-memory buffers. In a distributed store where the data is already spread across machines, holding an intermediate result in the memory of one process is both a bottleneck and a correctness risk, so a planner that pushes work down and streams results back is doing something structurally different from a classic single-node optimiser. The indexes it relies on are described as rich and incrementally maintained, which means the planner has statistics and structures to work with rather than scanning. The documentation does not publish numbers for any of this, and the README contains no benchmark, so claims about how well the planner performs on your particular queries are not something the project supports with evidence.

The repository is a Gradle build of many small modules

The tree shows a monorepo built with Gradle, and the module names describe the surface area better than the README does. The core pieces are fdb-record-layer-core, fdb-relational-core and fdb-relational-api. On top of them sit fdb-relational-jdbc for the JDBC path, fdb-relational-cli, fdb-relational-server and fdb-relational-grpc for the server and network side. Optional capabilities have their own modules: fdb-record-layer-spatial, fdb-record-layer-lucene, fdb-record-layer-icu and fdb-record-layer-jmh for benchmarking. There are also fdb-java-annotations, fdb-extensions, fdb-test-utils and fdb-record-layer-debugger. Two directories stand out for how the project is validated: yaml-tests/, which suggests test cases written as data, and docker-local/, which suggests a local environment assembled from containers. The examples/ directory is part of the build through examples.gradle. A repository that ships a debugger, a benchmark module and a containerised local environment is telling you it expects people to develop against it, not just consume a jar.

Getting the library onto your classpath

The library is published to Maven Central, and the central artifact is org.foundationdb.fdb-record-layer-core, which is what the build badge in the documentation points at. The documentation links a dedicated setup page for adding the Java library as a dependency of your build, and that page, together with the versioned documentation, is the place where the exact coordinate and version to use are given. The README itself does not print a dependency snippet, so the honest instruction is to follow the setup page rather than guess at a version string. The project publishes a nightly build workflow badge, which is a reasonable signal that artifacts are produced continuously, and the documentation carries a release notes page that logs user-visible changes across releases, which is the document to read before a major version bump. The repository itself has no GitHub releases, so tags and the release notes page are the two places to look.

Licence, maintenance signals and the gaps in the README

The code is Apache-2.0 licensed, which is a permissive licence with an explicit patent grant, and the repository carries the usual governance files including CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md and ACKNOWLEDGEMENTS. The repository is not archived and the last push was on 2026-10-20, so the library is being worked on. The README is short, and it is short in a way that matters for an evaluation. It does not state which FoundationDB versions are supported, it does not show a dependency declaration, it does not describe how a schema is defined in code, and it does not give any measurement for the millisecond-level claims or for the planner's behaviour on a given query shape. The linked documentation, the release notes and the examples directory are where those answers live. There is also a version of the repository that has been reorganised around agent instructions, with AGENTS.md, CLAUDE.md, GEMINI.md and a .teamscale.toml file present, which is a signal about how the maintainers work as much as about the code.

Editorial conclusion

fdb-record-layer fits teams that have standardised on FoundationDB and want relational access, multi-tenant schema templates and vector types without running a second database for each tenant, since it inherits FoundationDB's ACID guarantees. Do not reach for it if you need a conventional SQL engine with mature tooling, or if your workload is small enough that a single node database is simpler. Before you commit, read the release notes page and check the FoundationDB version your deployment runs, because the README states neither, and confirm the query planner covers the join and subquery shapes your application actually issues.

Frequently asked questions

Official sources

1. FoundationDB/fdb-record-layer on GitHub
2. Issues
3. License: Apache-2.0
4. README