PuzzleDB is a technology preview of a multi-protocol, multi-model database implemented in Go. It explores how PostgreSQL, MySQL, Redis, and MongoDB protocol frontends can share database services through a modular plugin architecture.
Use it to experiment with database internals, protocol adapters, and storage backends. Protocol support is incremental: accepting a client connection does not imply full query, command, transaction, or behavioral compatibility with the original database. This preview does not establish production readiness or performance guarantees.
- Query plugins implement PostgreSQL, MySQL, Redis, and MongoDB protocol frontends.
- Data-model and encoding layers support work on key-value, relational, and document data.
- Storage and coordination plugins include in-memory and FoundationDB implementations.
- Additional plugin services cover authentication, caching, metrics, and tracing.
- Server and CLI entrypoints live in
cmd/; core services and plugins live inpuzzledb/.
Requests enter through a protocol plugin and use shared model, encoding, and storage interfaces. The plugin boundaries allow backends and supporting services to evolve independently. Storage durability and transaction behavior depend on the selected backend and configuration; do not assume identical semantics across protocols.
With Docker installed, run the preview locally:
docker run --rm -it \
-p 127.0.0.1:6379:6379 \
-p 127.0.0.1:27017:27017 \
-p 127.0.0.1:3306:3306 \
-p 127.0.0.1:5432:5432 \
cybergarage/puzzledb:latestIn another terminal, try the Redis frontend with redis-cli installed:
redis-cli -h 127.0.0.1 -p 6379 SET mykey "Hello"
redis-cli -h 127.0.0.1 -p 6379 GET mykeyThis disposable container is for exploration. See configuration before choosing storage or persistence settings. The quick start includes SQL and document examples.
Use Go 1.25.0 or later, a C toolchain, and the FoundationDB client headers and library required by the Go bindings. The server imports FoundationDB plugins even when you intend to select an in-memory backend. See scripts/fdb_install and the platform build guides below for setup context.
git clone https://github.com/cybergarage/puzzledb-go.git
cd puzzledb-go
go build ./cmd/puzzledb-server ./cmd/puzzledb-cli
go run ./cmd/puzzledb-serverCheck the protocol-specific documentation before trying a workload:
| Frontend | Support details |
|---|---|
| PostgreSQL | Queries and compatibility |
| MySQL | Queries and compatibility |
| Redis | Commands and compatibility |
| MongoDB | Commands and compatibility |
After installing the build dependencies, run the Go suites directly:
go test -v -p 1 -timeout 60m ./puzzledb/... ./puzzledbtest/...Integration suites may require backend services and test certificates; see puzzledbtest/ and puzzledbtest/certs/Makefile. The repository's make unittest target also generates coverage reports. make test includes formatting and linting; its formatting prerequisite regenerates and commits the version file, so review the Makefile before using it in a working checkout.
- Design concepts and layers
- Data model and storage
- Consistency and coordination
- Authentication and plugins
The distributed plugin stack is under development. The roadmap describes direction rather than a promise that every illustrated capability is complete. Evaluate supported operations, failure behavior, and persistence for your own experiments.
-
Get Started
-
Operation
-
Benchmarking
-
Distribution
-
References
-
Contributing (Planning)
-
Building and Testing
-
Extending PuzzleDB
-
Specification
-
Store Specifications
-
Transverse Specifications
PuzzleDB is developed in collaboration with the following Cybergarage projects:



