Skip to content

About

PuzzleDB is a high-performance, distributed, cloud-native, multi-API, multi-model database.

Resources

Stars

7 stars

Watchers

3 watching

Forks

Repository files navigation

PuzzleDB

GitHub tag (latest SemVer) Go go-Reference go-Report Card codecov

PuzzleDB for Go

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.

Features and architecture

  • 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 in puzzledb/.

PuzzleDB concept

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.

PuzzleDB system architecture

Quick start

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:latest

In 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 mykey

This disposable container is for exploration. See configuration before choosing storage or persistence settings. The quick start includes SQL and document examples.

Build from source

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-server

Protocol scope

Check 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

Development and testing

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.

Architecture and design guides

Roadmap and limitations

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.

PuzzleDB roadmap

User Guides

Developer Guides

Related Projects

PuzzleDB is developed in collaboration with the following Cybergarage projects:

About

PuzzleDB is a high-performance, distributed, cloud-native, multi-API, multi-model database.

Resources

Stars

7 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages