Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 14 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,21 @@
# ExtendDB

> **ExtendDB is an independent open source project managed by Amazon Web Services. It is not Amazon DynamoDB and does
> not contain any DynamoDB source code.** "DynamoDB" is a trademark of Amazon.com, Inc. ExtendDB is a clean-room
> implementation that speaks the DynamoDB wire protocol. Behavioral differences from the real service are documented
> in [Differences from DynamoDB](docs/differences-from-dynamodb.md).
> **ExtendDB is an open source project under the Apache License 2.0, maintained by engineers at Amazon Web Services. It is not Amazon DynamoDB and contains no DynamoDB source code.** "DynamoDB" is a trademark of Amazon.com, Inc. ExtendDB is a clean-room implementation that speaks the DynamoDB wire protocol. Behavioral differences from the real service are documented in [Differences from DynamoDB](docs/differences-from-dynamodb.md).

A DynamoDB-compatible API adapter, ExtendDB speaks the DynamoDB wire protocol — any AWS SDK, CLI, or tool that works
with DynamoDB works with ExtendDB, unchanged.
ExtendDB is a DynamoDB-compatible API adapter. It speaks the DynamoDB wire protocol, so any AWS SDK, CLI, or tool that works with DynamoDB works with ExtendDB, unchanged.

## Use Cases

- **Local development** — run DynamoDB workloads on your laptop with zero cloud dependency
- **CI/CD pipelines** — deterministic integration tests against a DynamoDB-compatible backend
- **Self-hosted deployments** — run DynamoDB workloads on your own infrastructure (on-premises, private cloud, edge)
- **Multi-cloud** — use DynamoDB semantics on any cloud that runs an ExtendDB-supported database backend
- **Air-gapped environments** — DynamoDB functionality with no internet connectivity
- **Local development**: run DynamoDB workloads on your laptop with zero cloud dependency
- **CI/CD pipelines**: deterministic integration tests against a DynamoDB-compatible backend
- **Self-hosted deployments**: run DynamoDB workloads on your own infrastructure (on-premises, private cloud, edge)
- **Multi-cloud**: use DynamoDB semantics on any cloud that runs one of the supported databases
- **Air-gapped environments**: DynamoDB functionality with no internet connectivity

## Features

- Full DynamoDB wire protocol: CRUD, Query, Scan, Batch, Transactions, Streams, TTL, Import/Export
- Pluggable storage: PostgreSQL (default), SQLite, MongoDB, and Cassandra
- Pluggable storage: PostgreSQL (default), SQLite, MongoDB and Cassandra, with the database's own backup and replication tools
- SigV4 authentication with IAM compatibility: users, groups, roles, policies, permissions boundaries
- Web management console for account and credential administration
- TLS with automatic self-signed certificate generation (replaceable with CA-signed certs)
Expand All @@ -39,7 +35,7 @@ cargo build --release
# Start
./target/release/extenddb serve --config extenddb.toml

# Use with any AWS SDK (TLS with self-signed cert — trust via AWS_CA_BUNDLE)
# Use with any AWS SDK (TLS with a self-signed certificate; trust it via AWS_CA_BUNDLE)
export AWS_CA_BUNDLE=~/.extenddb/tls/cert.pem
aws dynamodb list-tables --endpoint-url https://127.0.0.1:18443 --region us-east-1
```
Expand Down Expand Up @@ -117,7 +113,7 @@ key_path = "/etc/extenddb/tls/key.pem"
The production images contain ExtendDB only. The storage backend runs as a separate service. See
[`docker/README.md`](docker/README.md) for the PostgreSQL image and [`docker/README-mongodb.md`](docker/README-mongodb.md) for the MongoDB image,
external database requirements, hardened local Compose stacks, smoke tests, and explicit init/migrate/serve
production lifecycle. The SQLite and Cassandra backends have no dedicated container guide yet.
production lifecycle. The SQLite and Cassandra backends have no dedicated container guide.

By default `extenddb serve` daemonizes itself, which doesn't play well with container runtimes and process supervisors that expect PID 1 to stay attached. Pass `--foreground` (alias `--no-daemon`) to keep the process in the foreground and stream logs to stderr instead of syslog:

Expand All @@ -130,7 +126,7 @@ Use this with Docker, Kubernetes, `systemd Type=simple`, runit, s6, or any other
In `--foreground` mode extenddb writes no PID file and never creates `run_dir`, so the container can run with a read-only root filesystem. Two consequences:

- `extenddb status` still works (it probes the port) but reports the PID as unknown.
- `extenddb stop` cannot signal the process — there is no PID file to read. Stop it through your supervisor, which delivers `SIGTERM` and triggers the same graceful shutdown.
- `extenddb stop` cannot signal the process, because there is no PID file to read. Stop it through your supervisor, which delivers `SIGTERM` and triggers the same graceful shutdown.

Pass `--write-pid-file` to opt back in when you do want `stop` and `status` to work against a foreground server, for example when running it from a shell rather than under a supervisor. The file goes to the usual `run_dir` path, so neither command needs extra arguments, and `run_dir` has to be writable.

Expand All @@ -144,19 +140,19 @@ extenddb healthcheck --endpoint https://127.0.0.1:18443 # explicit target
This is a liveness check, which is what a container `HEALTHCHECK` wants. The `/health` path does not query the storage
backend, so it will report healthy even if the storage backend becomes unreachable after startup. That is deliberate,
since a liveness probe that failed on a database outage would restart every replica at once. A backend that is
unreachable at startup does stop the server from listening. There is no separate readiness endpoint yet.
unreachable at startup does stop the server from listening. There is no separate readiness endpoint.

### One instance per database

Run one `extenddb serve` per catalog. On SQLite this is enforced: the server takes an exclusive lock on `<database>.lock`
next to the database file and a second server on the same file will refuse to start (`init`, `migrate`, and `destroy` take
the same lock while they run). On PostgreSQL, MongoDB and Cassandra nothing prevents a second ExtendDB instance from
running, but running more than one against the same catalog is not supported in this release: every instance runs every
running, but running more than one against the same catalog is not supported: every instance runs every
background worker, credential and policy caches are per instance with no cross-instance invalidation (a revoked key
stays valid on the other instance for up to the cache TTL), and `/health` does not check the database.
See the [deployment guide](docs/manuals/11-deployment-guide.md#multi-instance-considerations).

To make the generated self-signed certificate valid for the name clients use — an in-cluster service DNS name, for example — pass `--tls-san` to `init` (repeatable):
To make the generated self-signed certificate valid for the name clients use (an in-cluster service DNS name, for example), pass `--tls-san` to `init` (repeatable):

```bash
extenddb init --catalog-db extenddb_catalog \
Expand Down
2 changes: 1 addition & 1 deletion crates/server/src/console/pages/docs_page.rs
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ pub async fn docs_page(State(state): State<Arc<ConsoleState>>) -> Response {
let mut content = String::with_capacity(4096);
content.push_str(r#"<h1>Documentation</h1>
<div class="card card-warning">
<p style="margin:0;font-size:0.9rem"><strong>extenddb is not Amazon DynamoDB.</strong> It is an independent, clean-room implementation that speaks the DynamoDB wire protocol. It is not affiliated with, endorsed by, or sponsored by Amazon Web Services. &ldquo;DynamoDB&rdquo; is a trademark of Amazon.com, Inc.</p>
<p style="margin:0;font-size:0.9rem"><strong>ExtendDB is not Amazon DynamoDB.</strong> It is a clean-room implementation that speaks the DynamoDB wire protocol and contains no DynamoDB source code, an open source project under the Apache License 2.0, maintained by engineers at Amazon Web Services. &ldquo;DynamoDB&rdquo; is a trademark of Amazon.com, Inc.</p>
</div>"#);

let categories = [
Expand Down
2 changes: 1 addition & 1 deletion docker/dockerhub-overview-dev.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,6 @@ For a durable, TLS-terminated deployment, use [`extenddb/extenddb-postgres`](htt

This image is built for local development and CI. It serves plain HTTP and its authorization is open, so whoever holds the credential can do anything. Publish it to loopback only, as the command above does, and do not keep real data in it.

ExtendDB is an independent open source project managed by Amazon Web Services. It is not Amazon DynamoDB and does not contain any DynamoDB source code. "DynamoDB" is a trademark of Amazon.com, Inc. ExtendDB is a clean-room implementation that speaks the DynamoDB wire protocol; behavioral differences from the service are documented in [Differences from DynamoDB](https://github.com/ExtendDB/extenddb/blob/main/docs/differences-from-dynamodb.md).
ExtendDB is an open source project under the Apache License 2.0, maintained by engineers at Amazon Web Services. It is not Amazon DynamoDB and contains no DynamoDB source code. "DynamoDB" is a trademark of Amazon.com, Inc. ExtendDB is a clean-room implementation that speaks the DynamoDB wire protocol; behavioral differences from the service are documented in [Differences from DynamoDB](https://github.com/ExtendDB/extenddb/blob/main/docs/differences-from-dynamodb.md).

More at [extenddb.org](https://extenddb.org) and [github.com/ExtendDB/extenddb](https://github.com/ExtendDB/extenddb). Licensed under Apache-2.0.
4 changes: 1 addition & 3 deletions docker/dockerhub-overview-mongodb.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,7 @@ The same images and their signatures are mirrored by digest to

## Note

ExtendDB is an independent open source project managed by Amazon Web
Services. It is not Amazon DynamoDB and does not contain any DynamoDB source
code. "DynamoDB" is a trademark of Amazon.com, Inc. ExtendDB is a clean-room
ExtendDB is an open source project under the Apache License 2.0, maintained by engineers at Amazon Web Services. It is not Amazon DynamoDB and contains no DynamoDB source code. "DynamoDB" is a trademark of Amazon.com, Inc. ExtendDB is a clean-room
implementation that speaks the DynamoDB wire protocol; behavioral differences
from the service are documented in
[Differences from DynamoDB](https://github.com/ExtendDB/extenddb/blob/main/docs/differences-from-dynamodb.md).
Expand Down
2 changes: 1 addition & 1 deletion docker/dockerhub-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,6 @@ Every published image is signed with ExtendDB's release key, an ECDSA P-256 key

## Note

ExtendDB is an independent open source project managed by Amazon Web Services. It is not Amazon DynamoDB and does not contain any DynamoDB source code. "DynamoDB" is a trademark of Amazon.com, Inc. ExtendDB is a clean-room implementation that speaks the DynamoDB wire protocol; behavioral differences from the service are documented in [Differences from DynamoDB](https://github.com/ExtendDB/extenddb/blob/main/docs/differences-from-dynamodb.md).
ExtendDB is an open source project under the Apache License 2.0, maintained by engineers at Amazon Web Services. It is not Amazon DynamoDB and contains no DynamoDB source code. "DynamoDB" is a trademark of Amazon.com, Inc. ExtendDB is a clean-room implementation that speaks the DynamoDB wire protocol; behavioral differences from the service are documented in [Differences from DynamoDB](https://github.com/ExtendDB/extenddb/blob/main/docs/differences-from-dynamodb.md).

More at [extenddb.org](https://extenddb.org) and [github.com/ExtendDB/extenddb](https://github.com/ExtendDB/extenddb). Licensed under Apache-2.0.
6 changes: 3 additions & 3 deletions docs/NOTICE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@

## Notice

**ExtendDB (extenddb) is not Amazon DynamoDB.** This software is an independent, clean-room implementation that provides a DynamoDB-compatible API. It does not contain, derive from, or link to any Amazon DynamoDB source code, libraries, or proprietary components.
**ExtendDB is not Amazon DynamoDB.** This software is an independent, clean-room implementation that provides a DynamoDB-compatible API. It does not contain, derive from, or link to any Amazon DynamoDB source code, libraries, or proprietary components.

"DynamoDB", "Amazon DynamoDB", "AWS", and "Amazon Web Services" are trademarks of Amazon.com, Inc. or its affiliates. This project is not affiliated with, endorsed by, or sponsored by Amazon.com, Inc. or Amazon Web Services.
"DynamoDB", "Amazon DynamoDB", "AWS", and "Amazon Web Services" are trademarks of Amazon.com, Inc. or its affiliates. ExtendDB is an open source project under the Apache License 2.0, maintained by engineers at Amazon Web Services.

**No warranty.** This software is provided "as is" under the Apache License, Version 2.0, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. See [LICENSE](https://github.com/ExtendDB/extenddb/blob/main/LICENSE) for the full terms.

**No guarantee of compatibility.** While extenddb aims to faithfully reproduce DynamoDB behavior, it is a separate implementation with known differences. Applications tested against extenddb should be validated against real DynamoDB before production deployment on AWS. See [Differences from DynamoDB](differences-from-dynamodb.md) for the full list of known behavioral differences.
**No guarantee of compatibility.** While ExtendDB aims to faithfully reproduce DynamoDB behavior, it is a separate implementation with known differences. Applications tested against ExtendDB should be validated against real DynamoDB before production deployment on AWS. See [Differences from DynamoDB](differences-from-dynamodb.md) for the full list of known behavioral differences.
6 changes: 3 additions & 3 deletions docs/adr/0000-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,6 @@ feedback, dependency constraints, security review. One bullet per reason.
Copyright 2026 ExtendDB contributors. Licensed under the Apache License, Version 2.0.
See [LICENSE](https://github.com/ExtendDB/extenddb/blob/main/LICENSE) for the full text.

This software is provided "as is" without warranty of any kind. ExtendDB is not
affiliated with, endorsed by, or sponsored by Amazon Web Services. "DynamoDB" is
a trademark of Amazon.com, Inc.
This software is provided "as is" without warranty of any kind. ExtendDB is maintained by
engineers at Amazon Web Services. It is not Amazon DynamoDB and contains no DynamoDB source
code. "DynamoDB" is a trademark of Amazon.com, Inc.
16 changes: 8 additions & 8 deletions docs/adr/0001-documentation-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,21 @@

## Context

extenddb needs a standard format for all documentation: design docs, ADRs, getting-started guides, and troubleshooting references. The two candidates are Markdown and LaTeX.
ExtendDB needs a standard format for all documentation: design docs, ADRs, getting-started guides, and troubleshooting references. The two candidates are Markdown and LaTeX.

## Options Considered

1. **Markdown** — lightweight, renders natively on GitHub/GitLab, editable in any text editor, supported by all Rust documentation tooling (`rustdoc`, `mdbook`).
2. **LaTeX** — typesetting system designed for academic papers and technical documents. Produces high-quality PDF output but requires a TeX distribution to build.
1. **Markdown**: lightweight, renders natively on GitHub/GitLab, editable in any text editor, supported by all Rust documentation tooling (`rustdoc`, `mdbook`).
2. **LaTeX**: typesetting system designed for academic papers and technical documents. Produces high-quality PDF output but requires a TeX distribution to build.

## Decision

Markdown for all documentation.

## Rationale

- All existing extenddb documentation is already Markdown. Switching would require migrating dozens of files.
- Markdown renders in-place on code hosting platforms — no build step, no PDF artifacts to manage.
- All existing ExtendDB documentation is already Markdown. Switching would require migrating dozens of files.
- Markdown renders in-place on code hosting platforms: no build step, no PDF artifacts to manage.
- Rust's `rustdoc` uses Markdown natively. Keeping external docs in the same format reduces context switching.
- LaTeX adds a build dependency (TeX Live is ~4 GB) with no corresponding benefit for a software project's documentation needs.
- Contributors can edit Markdown with zero tooling beyond a text editor.
Expand All @@ -33,6 +33,6 @@ Markdown for all documentation.
Copyright 2026 ExtendDB contributors. Licensed under the Apache License, Version 2.0.
See [LICENSE](https://github.com/ExtendDB/extenddb/blob/main/LICENSE) for the full text.

This software is provided "as is" without warranty of any kind. ExtendDB is not
affiliated with, endorsed by, or sponsored by Amazon Web Services. "DynamoDB" is a trademark
of Amazon.com, Inc.
This software is provided "as is" without warranty of any kind. ExtendDB is maintained by
engineers at Amazon Web Services. It is not Amazon DynamoDB and contains no DynamoDB source
code. "DynamoDB" is a trademark of Amazon.com, Inc.
Loading
Loading