Skip to content

Latest commit

 

History

History
executable file
·
1526 lines (1130 loc) · 53.3 KB

getting-started.md

File metadata and controls

executable file
·
1526 lines (1130 loc) · 53.3 KB

Getting Started with extenddb

See NOTICE for important disclaimers.

This guide walks you through initializing a extenddb deployment, starting the server, and running your first DynamoDB commands against it.

Platform-specific installation guides

Installer scripts

The fastest way to build extenddb from source is the platform installer script. It checks dependencies, builds the binary, sets up a Python venv, and generates PDF documentation:

# Linux
scripts/install-linux.sh

# macOS
scripts/install-macos.sh

The scripts report missing dependencies and exit — they never install software on your behalf. After the script completes, continue from Step 2: Initialize the deployment below.

Quick start with Docker Compose

If you have Docker, the fastest way to get a local ExtendDB stack running is with the included docker-compose.yml. It wires the official image to a PostgreSQL container and handles initialization automatically — no build or manual init required. See Local Development with Docker Compose.

Prerequisites

  • Storage backend (one of):
    • PostgreSQL 14+ running locally (see docs/local-postgres-setup.md)
    • SQLite (embedded; nothing to install)
    • MongoDB 7.0+ with replica set (see docs/local-mongodb-setup.md)
    • Cassandra 4.1+ running locally (see docs/cassandra-setup.md)
  • Rust toolchain (1.91.1+)
  • AWS CLI v2 (for testing)
  • Python 3.10+ with virtual environment (see Python Environment Setup in the README)

1. Build extenddb

# PostgreSQL backend (default)
cargo build --release

# MongoDB backend
# (backends are mutually exclusive; disable the default postgres feature)
cargo build --release --no-default-features --features mongodb

# Cassandra backend
cargo build --release --no-default-features --features cassandra

# SQLite backend (developer mode, see "SQLite backend (developer mode)" below)
cargo build --release --no-default-features --features sqlite

Each build produces a single-backend binary. The postgres, mongodb, sqlite, and cassandra features are mutually exclusive — a build enabling more than one is rejected at compile time — so to run two backends, build one binary per backend.

The binary is at target/release/extenddb.

2. Initialize the deployment

Run extenddb init to create the catalog and data databases:

# PostgreSQL (default)
./target/release/extenddb init

# MongoDB
./target/release/extenddb init --backend mongodb

# Cassandra
./target/release/extenddb init --backend cassandra

This will:

  • Create the extenddb_catalog database/keyspace (catalog metadata)
  • Create the data database/keyspace (user item data)
  • Generate an AES-256-GCM encryption key (for access key storage)
  • Create a default account and print the account ID
  • Create an admin user and print the credentials once
  • Generate a self-signed TLS certificate at ~/.extenddb/tls/
  • Generate extenddb.toml

Important: Save the admin credentials printed during init. They are shown once and cannot be retrieved later. These credentials are used to authenticate to the management API.

Re-initialization: extenddb init will abort if either the catalog or data database already exists. To re-initialize, first run extenddb destroy --config extenddb.toml --yes to drop the existing databases, then run extenddb init again. On Cassandra, init aborts if the catalog is already initialized. If an earlier init stopped partway, init finishes it, when its --replication-factor and --datacenter match the ones the earlier init used. If init stops because its --replication-factor is larger than the number of nodes, an init with the same --replication-factor stops the same way. To go on, see "Keyspace replication" in cassandra-setup.md.

To use a custom catalog database name:

./target/release/extenddb init --catalog-db my_catalog

To use a custom data database name:

./target/release/extenddb init --data-db my_data_db

Remote PostgreSQL / Aurora

For remote PostgreSQL or Aurora, supply the admin password with --pg-pass:

# Pass the password inline:
./target/release/extenddb init \
  --pg-host my-aurora-cluster.cluster-xxxx.us-east-1.rds.amazonaws.com \
  --pg-user postgres --pg-pass <admin-password>

When --pg-pass is omitted entirely, extenddb init connects without a password, relying on PostgreSQL peer/ident authentication (works only on localhost via Unix socket).

Note: When using Unix socket connections, specify the socket directory with --pg-host using an absolute path (e.g., --pg-host /var/run/postgresql). Relative paths are not supported.

Custom bind address

To bind the server to a specific address (e.g., for remote access), pass --bind-addr during init. The address is included as a SAN in the self-signed certificate and written to the generated config file:

./target/release/extenddb init --bind-addr 10.0.1.5

This generates a certificate with SANs: localhost, 127.0.0.1, and 10.0.1.5.

SQLite backend (developer mode)

For local development and CI, extenddb can run against a SQLite backend instead of PostgreSQL. It requires its own build (the postgres, mongodb, and sqlite backends are mutually exclusive, each compiled into a single-backend binary — see Build extenddb above):

cargo build --release --no-default-features --features sqlite

Then select it at init time with --backend sqlite:

./target/release/extenddb init --backend sqlite

This writes a config with a [storage.sqlite] section where the database location is configured (default extenddb.sqlite):

[storage.sqlite]
path = "extenddb.sqlite"   # or ":memory:" for an ephemeral in-memory database

At init time the path can be chosen with --sqlite-path, which also writes it into the generated config. At serve time the path comes from [storage.sqlite].path in the config, or the EXTENDDB__STORAGE__SQLITE__PATH environment variable, which overrides the config:

./target/release/extenddb init --backend sqlite --sqlite-path /data/extenddb.sqlite
./target/release/extenddb serve --config extenddb.toml
# or, overriding at serve time:
EXTENDDB__STORAGE__SQLITE__PATH=/data/other.sqlite ./target/release/extenddb serve --config extenddb.toml

Use :memory: (in the config, the environment variable, or init --sqlite-path) for an ephemeral database that is discarded on shutdown.

Cassandra backend

ExtendDB can run against an Apache Cassandra cluster. The Cassandra backend is experimental; see Cassandra setup for its current limitations and the full walkthrough. Select it at init time with --backend cassandra:

./target/release/extenddb init \
    --backend cassandra \
    --cassandra-contact-points 127.0.0.1:9042 \
    --cassandra-user cassandra \
    --cassandra-pass cassandra

The node must run PasswordAuthenticator. init always creates its application role with a password, so it fails against a stock node using the default AllowAllAuthenticator — there is no credential-free path. Pass the Cassandra admin credentials with --cassandra-user / --cassandra-pass; init uses them to create the keyspaces and the application role. init writes a [storage.cassandra] section to the config, with the application credentials.

[storage.cassandra]
contact_points = ["127.0.0.1:9042"]
username = <extenddb-user>      # From extenddb init args
password = <extenddb-pass>      # From extenddb init args
keyspace_prefix = "extenddb"
replication_factor = 1           # From --replication-factor (default 1)
datacenter = "datacenter1"       # From --datacenter (default datacenter1)
max_connections = 10

To override a default, pass the matching flag at init time:

  • --cassandra-contact-points host1:9042,host2:9042 — one or more contact points for a remote or multi-node cluster.
  • --cassandra-user and --cassandra-pass — the admin credentials init uses to create the keyspaces and the application role (required).
  • --extenddb-user and --extenddb-pass — override the application role's name and password (default extenddb / extenddb-local-dev).
  • --keyspace-prefix myapp — a different keyspace prefix, so one cluster can host more than one deployment.
  • --replication-factor 3 — the replication factor of the keyspaces (default 1, for a single node). Use 3 or more for a multi-node cluster.
  • --datacenter dc1 — the datacenter the keyspaces replicate in (default datacenter1); use the name nodetool status prints.

For replication strategy, datacenter topology, authentication, authorization, and the fact that connections are unencrypted, see docs/cassandra-setup.md.

Generating a self-signed certificate manually

extenddb init auto-generates a self-signed TLS certificate at ~/.extenddb/tls/. If you need a certificate with different SANs (e.g., binding to 0.0.0.0 and connecting via a specific hostname), generate one manually with openssl:

# Create the TLS directory
mkdir -p ~/.extenddb/tls

# Generate a certificate with custom SANs
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout ~/.extenddb/tls/key.pem \
  -out ~/.extenddb/tls/cert.pem \
  -days 3650 \
  -subj "/CN=extenddb self-signed/O=extenddb" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1,DNS:myhost.example.com,IP:10.0.1.5"

# Restrict key file permissions
chmod 600 ~/.extenddb/tls/key.pem

Adjust the -addext SANs to match the hostnames and IP addresses clients will use to connect. Every address that appears in endpoint_url must be listed as a SAN, or TLS verification will fail.

If the certificate already exists when extenddb init runs, it is preserved — init only generates a certificate when ~/.extenddb/tls/cert.pem and ~/.extenddb/tls/key.pem are both absent. To regenerate, delete the existing files first:

rm ~/.extenddb/tls/cert.pem ~/.extenddb/tls/key.pem
./target/release/extenddb init --bind-addr 10.0.1.5

3. Verify the deployment

./target/release/extenddb verify --config extenddb.toml

You should see all checks pass:

=== extenddb verify ===
Config:           extenddb.toml
Catalog database: extenddb_catalog

--- Checking catalog migrations...
  OK: Current: the catalog is at migration 12
--- Checking catalog connection...
  OK: Connected to catalog.
--- Checking data database...
  OK: Connected to data database 'extenddb'.
--- Enumerating tables...
  Tables: 0
  Indexes: 0

=== HEALTHY: All checks passed ===

4. Start the server

extenddb runs as a daemon (background process) and logs to syslog. On startup it prints a two-line banner to stdout, the version, catalog version and bind address followed by the storage backend and its redacted connection string, then forks to background. It says "starting", not "listening": the socket is not accepting connections yet at that point.

./target/release/extenddb serve --config extenddb.toml
# extenddb 1.0.0 (catalog migration 12) starting on 127.0.0.1:18443
#   storage: postgres (postgresql://extenddb:***@localhost:5432/extenddb_catalog)

Check status (includes the daemon PID):

./target/release/extenddb status --config extenddb.toml
# extenddb is running on port 18443 (pid 12345)

Read logs:

# Linux
journalctl -t extenddb -f           # follow live
journalctl -t extenddb -n 50        # last 50 lines
journalctl -t extenddb --no-pager -o cat  # plain output, no metadata

# macOS
log stream --predicate 'processImagePath ENDSWITH "extenddb"' --level info
log show --predicate 'processImagePath ENDSWITH "extenddb"' --last 5m

Change the log level at runtime (takes effect within 30 seconds):

./target/release/extenddb settings --config extenddb.toml set log_level debug

sqlx Log Separation

sqlx query traces are suppressed by default (level warn) so they don't flood the main log stream. The sqlx log level is independently configurable via the sqlx_log_level runtime setting:

# Enable sqlx debug logging for query troubleshooting
./target/release/extenddb settings --config extenddb.toml set sqlx_log_level debug

# Restore default (suppress most sqlx output)
./target/release/extenddb settings --config extenddb.toml set sqlx_log_level warn

When sqlx logging is enabled, messages appear in the extenddb syslog with sqlx::query as the target. Filter them:

# Exclude sqlx messages
journalctl -t extenddb | grep -v sqlx

# Show only sqlx messages
journalctl -t extenddb | grep sqlx

Control Plane Delay

By default, control plane operations (CreateTable, DeleteTable) emulate real DynamoDB's async behavior — tables transition through CREATING → ACTIVE and DELETING → removed states over a configurable delay (default: 5 seconds). Adjust with:

# Set to 0 for instant transitions (useful for fast test cycles)
./target/release/extenddb settings --config extenddb.toml set \
    control_plane_delay_seconds 0

# Set to 10 seconds for more realistic behavior
./target/release/extenddb settings --config extenddb.toml set \
    control_plane_delay_seconds 10

Warm Throughput

WarmThroughput on CreateTable, UpdateTable and GlobalSecondaryIndexUpdates is stored and reported on DescribeTable with the shape, defaults (12000 read and 4000 write units on an on-demand table, the provisioned units on a provisioned one) and validation of Amazon DynamoDB, and Status reads UPDATING for the control plane delay after a change, then ACTIVE. Nothing acts on the values: there is no pre-warming and no scaling at the database level, and they have no effect on throughput, throttling or storage.

Credential Import

Controls whether extenddb manage import-access-key is allowed (default: false). An import stores an access key ID and secret that the caller chooses, so only a deployment that sets this to true accepts imported keys.

# Enable credential import
./target/release/extenddb settings --config extenddb.toml set \
    allow_credential_import true

# Disable it again
./target/release/extenddb settings --config extenddb.toml set \
    allow_credential_import false

GSI Propagation Delay

GSI updates are applied asynchronously with a configurable delay, simulating real DynamoDB's eventually consistent GSI behavior. The system-wide default is 10ms. Each GSI can override this with a per-index propagation_delay_ms stored in the catalog.

# Set system-wide default to 0 for synchronous GSI updates (fast tests)
./target/release/extenddb settings --config extenddb.toml set \
    index_propagation_delay_ms 0

# Set to 50ms for more realistic eventual consistency
./target/release/extenddb settings --config extenddb.toml set \
    index_propagation_delay_ms 50

Throttling

extenddb enforces provisioned throughput limits using a token bucket per table and partition, matching DynamoDB's burst and refill behavior. Throttling is enabled by default.

# Disable throttling (useful for bulk loading)
./target/release/extenddb settings --config extenddb.toml set \
    throttling_enabled false

# Re-enable throttling
./target/release/extenddb settings --config extenddb.toml set \
    throttling_enabled true

TTL Deletion Target

Controls the target maximum time (in seconds) between an item's TTL expiry and its actual deletion. The TTL sweeper uses an indexed scan and runs every 60 seconds. Default: 300 seconds.

# Set to 60 seconds for faster TTL cleanup
./target/release/extenddb settings --config extenddb.toml set \
    ttl_deletion_target_seconds 60

# Set to 600 seconds for less aggressive cleanup
./target/release/extenddb settings --config extenddb.toml set \
    ttl_deletion_target_seconds 600

Stop the server:

./target/release/extenddb stop --config extenddb.toml

If extenddb stop is unavailable (e.g., older binary), fall back to manual process management:

  1. Find the process listening on the extenddb port (default 18443):
    ss -tlnp | grep :18443
  2. Kill it:
    kill <pid>

5. Configure AWS CLI

extenddb uses TLS with a self-signed certificate. To make AWS CLI and SDKs trust it, set AWS_CA_BUNDLE to the generated certificate:

export AWS_CA_BUNDLE=~/.extenddb/tls/cert.pem

Option A: Environment variables (simplest)

export AWS_CA_BUNDLE=~/.extenddb/tls/cert.pem
export AWS_ENDPOINT_URL_DYNAMODB=https://127.0.0.1:18443
export AWS_ACCESS_KEY_ID=<access-key-from-create-access-key>
export AWS_SECRET_ACCESS_KEY=<secret-key-from-create-access-key>
export AWS_DEFAULT_REGION=us-east-1

Option B: AWS config profile

Add to ~/.aws/config:

[profile extenddb]
region = us-east-1
ca_bundle = ~/.extenddb/tls/cert.pem
services = extenddb-services

[services extenddb-services]
dynamodb =
  endpoint_url = https://127.0.0.1:18443

Add to ~/.aws/credentials:

[extenddb]
aws_access_key_id = <access-key-from-create-access-key>
aws_secret_access_key = <secret-key-from-create-access-key>

Then: export AWS_PROFILE=extenddb

Option C: Explicit --endpoint-url per command

export AWS_CA_BUNDLE=~/.extenddb/tls/cert.pem
aws dynamodb list-tables --endpoint-url https://127.0.0.1:18443

Post-init workflow

After extenddb init, create an IAM user and access key for SDK use:

# Create an account (use the account ID printed during init, or create a new one)
./target/release/extenddb manage --user admin --password <admin-pw> \
    create-account --account-name dev-team

# Create an IAM user with a console password
./target/release/extenddb manage --user admin --password <admin-pw> \
    create-user --account-id <account-id> \
    --user-name alice --user-password secret

# Attach a policy granting DynamoDB access
./target/release/extenddb manage --user admin --password <admin-pw> \
    put-user-policy --account-id <account-id> --user-name alice \
    --policy-name FullAccess \
    --policy-document '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "dynamodb:*",
        "Resource": "*"
      }]
    }'

# Create an access key (shown once — save it)
./target/release/extenddb manage --user <account-id>/alice --password secret \
    create-access-key

Then configure your SDK with the access key ID and secret access key returned by create-access-key.

6. Try it out

Create a table

aws dynamodb create-table \
    --table-name MyTable \
    --attribute-definitions AttributeName=pk,AttributeType=S \
    --key-schema AttributeName=pk,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

List tables

aws dynamodb list-tables

Describe a table

aws dynamodb describe-table --table-name MyTable

Delete a table

aws dynamodb delete-table --table-name MyTable

Put an item

aws dynamodb put-item \
    --table-name MyTable \
    --item '{"pk": {"S": "user-1"}, "name": {"S": "Alice"}, "age": {"N": "30"}}'

Get an item

aws dynamodb get-item \
    --table-name MyTable \
    --key '{"pk": {"S": "user-1"}}'

Delete an item

aws dynamodb delete-item \
    --table-name MyTable \
    --key '{"pk": {"S": "user-1"}}' \
    --return-values ALL_OLD

Update an item

aws dynamodb update-item \
    --table-name MyTable \
    --key '{"pk": {"S": "user-1"}}' \
    --update-expression "SET age = :newage" \
    --expression-attribute-values '{":newage": {"N": "31"}}' \
    --return-values ALL_NEW

Query items

aws dynamodb query \
    --table-name MyTable \
    --key-condition-expression "pk = :pk" \
    --expression-attribute-values '{":pk": {"S": "user-1"}}'

Scan a table

aws dynamodb scan --table-name MyTable

Batch write items

aws dynamodb batch-write-item \
    --request-items '{
        "MyTable": [
            {
              "PutRequest": {
                "Item": {
                  "pk": {"S": "user-2"},
                  "name": {"S": "Bob"}
                }
              }
            },
            {
              "PutRequest": {
                "Item": {
                  "pk": {"S": "user-3"},
                  "name": {"S": "Carol"}
                }
              }
            }
        ]
    }'

Batch get items

aws dynamodb batch-get-item \
    --request-items '{
        "MyTable": {
            "Keys": [
                {"pk": {"S": "user-1"}},
                {"pk": {"S": "user-2"}}
            ]
        }
    }'

Transactional write

aws dynamodb transact-write-items \
    --transact-items '[
        {
          "Put": {
            "TableName": "MyTable",
            "Item": {
              "pk": {"S": "tx-1"},
              "data": {"S": "hello"}
            }
          }
        },
        {
          "ConditionCheck": {
            "TableName": "MyTable",
            "Key": {"pk": {"S": "user-1"}},
            "ConditionExpression":
              "attribute_exists(pk)"
          }
        }
    ]'

Transactional get

aws dynamodb transact-get-items \
    --transact-items '[
        {
          "Get": {
            "TableName": "MyTable",
            "Key": {"pk": {"S": "tx-1"}}
          }
        },
        {
          "Get": {
            "TableName": "MyTable",
            "Key": {"pk": {"S": "user-1"}}
          }
        }
    ]'

DynamoDB Streams

extenddb supports DynamoDB Streams for change data capture. Enable streams when creating a table:

aws dynamodb create-table \
    --table-name StreamTable \
    --attribute-definitions AttributeName=pk,AttributeType=S \
    --key-schema AttributeName=pk,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST \
    --stream-specification StreamEnabled=true,StreamViewType=NEW_AND_OLD_IMAGES

Important: SDK users need a separate dynamodbstreams client. In every AWS SDK, DynamoDB and DynamoDB Streams are separate services. Both clients must point at the same extenddb endpoint URL:

import boto3

# Trust the self-signed certificate
import os
os.environ["AWS_CA_BUNDLE"] = os.path.expanduser("~/.extenddb/tls/cert.pem")

# DynamoDB client — for table/item operations
dynamodb = boto3.client("dynamodb", endpoint_url="https://127.0.0.1:18443")

# DynamoDB Streams client — for stream operations
streams = boto3.client("dynamodbstreams", endpoint_url="https://127.0.0.1:18443")

List streams:

aws dynamodbstreams list-streams \
    --endpoint-url https://127.0.0.1:18443

Describe a stream (use the LatestStreamArn from DescribeTable):

aws dynamodbstreams describe-stream \
    --endpoint-url https://127.0.0.1:18443 \
    --stream-arn \
      "arn:aws:dynamodb:us-east-1:<account-id>:table/StreamTable/stream/2026-04-08T07:00:00"

Get a shard iterator and read records:

# Get iterator for a shard (use ShardId from DescribeStream)
aws dynamodbstreams get-shard-iterator \
    --endpoint-url https://127.0.0.1:18443 \
    --stream-arn \
      "arn:aws:dynamodb:us-east-1:<account-id>:table/StreamTable/stream/2026-04-08T07:00:00" \
    --shard-id "shard-0" \
    --shard-iterator-type TRIM_HORIZON

# Read records using the iterator
aws dynamodbstreams get-records \
    --endpoint-url https://127.0.0.1:18443 \
    --shard-iterator "<iterator-from-above>"

Streams polling pattern

The standard pattern for consuming a DynamoDB stream is a polling loop:

import time
import boto3

streams = boto3.client("dynamodbstreams", endpoint_url="https://127.0.0.1:18443")
dynamodb = boto3.client("dynamodb", endpoint_url="https://127.0.0.1:18443")

# Get stream ARN from the table.
table = dynamodb.describe_table(TableName="StreamTable")
stream_arn = table["Table"]["LatestStreamArn"]

# Discover shards.
desc = streams.describe_stream(StreamArn=stream_arn)
shards = desc["StreamDescription"]["Shards"]

# Get iterators for each shard.
iterators = {}
for shard in shards:
    resp = streams.get_shard_iterator(
        StreamArn=stream_arn,
        ShardId=shard["ShardId"],
        ShardIteratorType="TRIM_HORIZON",
    )
    iterators[shard["ShardId"]] = resp["ShardIterator"]

# Poll loop.
while True:
    for shard_id, iterator in list(iterators.items()):
        if not iterator:
            continue
        resp = streams.get_records(ShardIterator=iterator, Limit=100)
        for record in resp.get("Records", []):
            print(f"{record['eventName']}: {record['dynamodb']['Keys']}")
        iterators[shard_id] = resp.get("NextShardIterator")
    time.sleep(1)

See samples/stream_consumer.py for a complete working example with concurrent writer and poller threads.

Stream records are retained for 24 hours. A background worker cleans up expired records every hour.

Health check

curl --cacert ~/.extenddb/tls/cert.pem https://127.0.0.1:18443/health
# {"status":"healthy"}

7. Manage admin users and accounts

The management API is available at /management/* on the running extenddb server. The extenddb manage CLI subcommand is a thin client that calls these endpoints.

Admin commands require admin credentials (the username and password printed during extenddb init). IAM user self-service commands accept account_id/user_name as the --user value.

Note: The --password flag is visible in process listings (ps aux) and shell history. For sensitive environments, leave out --password and set the EXTENDDB_PASSWORD environment variable instead, with read -rs EXTENDDB_PASSWORD && export EXTENDDB_PASSWORD, which keeps the password out of shell history. extenddb manage reads the password from EXTENDDB_PASSWORD, and it prints a warning on stderr when it gets --password. --admin-password, --new-password, --user-password and --secret-access-key have no environment variable.

List admin users

./target/release/extenddb manage --user admin --password <pw> list-admins

Create another admin user

./target/release/extenddb manage --user admin --password <pw> \
    create-admin --admin-name ops --admin-password secret123

Change an admin password

./target/release/extenddb manage --user admin --password <pw> \
    change-admin-password --admin-name admin --new-password newpw

Delete an admin user

./target/release/extenddb manage --user admin --password <pw> \
    delete-admin --admin-name ops

Create an account

Account IDs must be 12-digit numeric strings (matching AWS account ID format):

./target/release/extenddb manage --user admin --password <pw> \
    create-account --account-id 123456789012 --account-name dev-team

List accounts

./target/release/extenddb manage --user admin --password <pw> list-accounts

Delete an account

Accounts with existing tables cannot be deleted. Delete all tables first.

Deleting an account also deletes its users, groups and roles with everything they hold, so their access keys and sessions stop working and its users cannot log in. An account created later with the same ID starts empty.

./target/release/extenddb manage --user admin --password <pw> \
    delete-account --account-id 123456789012

Create an IAM user

Create an IAM user with optional console password. If --user-password is provided, the user can authenticate to the management API for self-service operations.

./target/release/extenddb manage --user admin --password <pw> \
    create-user --account-id 123456789012 \
    --user-name alice --user-password secret

A default self-service policy is automatically attached, allowing the user to manage their own access keys and change their own password.

List IAM users

./target/release/extenddb manage --user admin --password <pw> \
    list-users --account-id 123456789012

Delete an IAM user

Deleting a user also removes its access keys, group memberships, tags, inline policies, permissions boundary and failed login attempts. A user created later with the same name starts with only the default SelfServicePolicy, and is not refused for the failed logins of the deleted one.

./target/release/extenddb manage --user admin --password <pw> \
    delete-user --account-id 123456789012 --user-name alice

Create an access key (self-service)

IAM users create their own access keys by authenticating with account_id/user_name:password. When authenticating as an IAM user, --account-id and --user-name are inferred automatically. The secret key is shown once and cannot be retrieved later.

Generated access keys are branded with extenddb-specific prefixes to distinguish them from real AWS credentials:

  • Long-lived keys: AKIAEXTENDDB + 8 random chars (20 total)
  • Temporary credentials (AssumeRole): ASIAEXTENDDB + 8 random chars (20 total)
  • Secret keys: extenddb + 32 random chars (40 total)
# Self-service: account_id and user_name inferred from --user
./target/release/extenddb manage --user 123456789012/alice --password secret \
    create-access-key

Admins can also create access keys on behalf of any user:

./target/release/extenddb manage --user admin --password <pw> \
    create-access-key --account-id 123456789012 --user-name alice

List access keys

./target/release/extenddb manage --user 123456789012/alice --password secret \
    list-access-keys --account-id 123456789012 --user-name alice

Delete an access key

./target/release/extenddb manage --user 123456789012/alice --password secret \
    delete-access-key --account-id 123456789012 \
    --user-name alice --access-key-id AKIAEXTENDDB...

Import an existing access key

Import real AWS credentials (or any AKIA* key) into extenddb. This enables the "just change the endpoint URL" workflow — use the same credentials against both extenddb and real DynamoDB.

The allow_credential_import runtime setting gates credential import (default: false). Enable it before the first import:

./target/release/extenddb settings --config extenddb.toml set \
    allow_credential_import true

Both --secret-access-key and --yes are required:

./target/release/extenddb manage --user admin --password <pw> \
    import-access-key --account-id 123456789012 --user-name alice \
    --access-key-id AKIAIOSFODNN7EXAMPLE \
    --secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
    --yes

Security note: --secret-access-key and --password are visible in ps output and shell history. For sensitive environments, set the password with read -rs EXTENDDB_PASSWORD && export EXTENDDB_PASSWORD and leave out --password. --secret-access-key has no environment variable.

Set allow_credential_import back to false to refuse further imports. Keys already imported keep working.

Credential import is not audit-logged. See 9. Audit logging.

Change IAM user password

./target/release/extenddb manage --user 123456789012/alice --password secret \
    change-user-password --account-id 123456789012 \
    --user-name alice --new-password newsecret

Create an IAM group

./target/release/extenddb manage --user admin --password <pw> \
    create-group --account-id 123456789012 --group-name developers

Add a user to a group

./target/release/extenddb manage --user admin --password <pw> \
    add-group-member --account-id 123456789012 \
    --group-name developers --user-name alice

Remove a user from a group

./target/release/extenddb manage --user admin --password <pw> \
    remove-group-member --account-id 123456789012 \
    --group-name developers --user-name alice

List groups

./target/release/extenddb manage --user admin --password <pw> \
    list-groups --account-id 123456789012

Delete a group

Deleting a group also removes its inline policies and its memberships. A group created later with the same name starts with no policies and no members.

./target/release/extenddb manage --user admin --password <pw> \
    delete-group --account-id 123456789012 --group-name developers

Put a user policy

Creates or replaces a named policy on an IAM user. The policy document must be valid JSON with Version and Statement fields. The user must exist; a policy put on a user that does not exist is refused with HTTP 404 IAM user not found. The same holds for group and role policies and for permissions boundaries.

./target/release/extenddb manage --user admin --password <pw> \
    put-user-policy --account-id 123456789012 \
    --user-name alice \
    --policy-name ReadOnly \
    --policy-document '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "dynamodb:GetItem",
        "Resource": "*"
      }]
    }'

List user policies

./target/release/extenddb manage --user admin --password <pw> \
    list-user-policies --account-id 123456789012 --user-name alice

Delete a user policy

./target/release/extenddb manage --user admin --password <pw> \
    delete-user-policy --account-id 123456789012 \
    --user-name alice --policy-name ReadOnly

Put a group policy

./target/release/extenddb manage --user admin --password <pw> \
    put-group-policy --account-id 123456789012 \
    --group-name developers \
    --policy-name FullAccess \
    --policy-document '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "dynamodb:*",
        "Resource": "*"
      }]
    }'

List group policies

./target/release/extenddb manage --user admin --password <pw> \
    list-group-policies --account-id 123456789012 --group-name developers

Delete a group policy

./target/release/extenddb manage --user admin --password <pw> \
    delete-group-policy --account-id 123456789012 \
    --group-name developers \
    --policy-name FullAccess

Tag an IAM user

./target/release/extenddb manage --user admin --password <pw> \
    tag-user --account-id 123456789012 --user-name alice \
    --tags '[{"key":"Department","value":"Engineering"}]'

List user tags

./target/release/extenddb manage --user admin --password <pw> \
    list-user-tags --account-id 123456789012 --user-name alice

Untag an IAM user

./target/release/extenddb manage --user admin --password <pw> \
    untag-user --account-id 123456789012 --user-name alice --tag-keys Department

Create an IAM role

./target/release/extenddb manage --user admin --password <pw> \
    create-role --account-id 123456789012 --role-name data-reader \
    --trust-policy '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Principal": {"AWS": "arn:aws:iam::123456789012:user/alice"},
        "Action": "sts:AssumeRole"
      }]
    }'

List roles

./target/release/extenddb manage --user admin --password <pw> \
    list-roles --account-id 123456789012

Delete a role

Deleting a role also removes its inline policies, permissions boundary, tags and sessions: credentials issued by assume-role stop working. A role created later with the same name starts with none of them.

./target/release/extenddb manage --user admin --password <pw> \
    delete-role --account-id 123456789012 --role-name data-reader

Put a role policy

./target/release/extenddb manage --user admin --password <pw> \
    put-role-policy --account-id 123456789012 \
    --role-name data-reader \
    --policy-name ReadOnly \
    --policy-document '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "dynamodb:GetItem",
        "Resource": "*"
      }]
    }'

List role policies

./target/release/extenddb manage --user admin --password <pw> \
    list-role-policies --account-id 123456789012 --role-name data-reader

Delete a role policy

./target/release/extenddb manage --user admin --password <pw> \
    delete-role-policy --account-id 123456789012 \
    --role-name data-reader --policy-name ReadOnly

Tag an IAM role

./target/release/extenddb manage --user admin --password <pw> \
    tag-role --account-id 123456789012 --role-name data-reader \
    --tags '[{"key":"Team","value":"Backend"}]'

List role tags

./target/release/extenddb manage --user admin --password <pw> \
    list-role-tags --account-id 123456789012 --role-name data-reader

Untag an IAM role

./target/release/extenddb manage --user admin --password <pw> \
    untag-role --account-id 123456789012 --role-name data-reader --tag-keys Team

Assume a role

Generates temporary ASIA* credentials for the specified role. The trust policy must allow the caller ARN.

./target/release/extenddb manage --user admin --password <pw> \
    assume-role --account-id 123456789012 --role-name data-reader \
    --caller-arn arn:aws:iam::123456789012:user/alice \
    --session-name test-session

With optional session tags and session policy:

./target/release/extenddb manage --user admin --password <pw> \
    assume-role --account-id 123456789012 --role-name data-reader \
    --caller-arn arn:aws:iam::123456789012:user/alice \
    --session-name test-session \
    --session-tags '{"Project":"Alpha"}' \
    --session-policy '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "dynamodb:GetItem",
        "Resource": "*"
      }]
    }' \
    --duration-seconds 1800

Set a user permissions boundary

./target/release/extenddb manage --user admin --password <pw> \
    set-user-boundary --account-id 123456789012 \
    --user-name alice \
    --policy-document '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "dynamodb:*",
        "Resource": "*"
      }]
    }'

Get a user permissions boundary

./target/release/extenddb manage --user admin --password <pw> \
    get-user-boundary --account-id 123456789012 --user-name alice

Delete a user permissions boundary

./target/release/extenddb manage --user admin --password <pw> \
    delete-user-boundary --account-id 123456789012 --user-name alice

Set a role permissions boundary

./target/release/extenddb manage --user admin --password <pw> \
    set-role-boundary --account-id 123456789012 \
    --role-name data-reader \
    --policy-document '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "dynamodb:GetItem",
        "Resource": "*"
      }]
    }'

Get a role permissions boundary

./target/release/extenddb manage --user admin --password <pw> \
    get-role-boundary --account-id 123456789012 --role-name data-reader

Delete a role permissions boundary

./target/release/extenddb manage --user admin --password <pw> \
    delete-role-boundary --account-id 123456789012 --role-name data-reader

Using a custom endpoint

By default, extenddb manage reads the server address from extenddb.toml. To target a different server:

./target/release/extenddb manage --user admin --password <pw> \
    --endpoint 127.0.0.1:9000 list-admins

8. Management web console

extenddb includes a built-in web console for managing accounts, users, groups, roles, and policies through a browser. The console is served at /console/ on the same port as the DynamoDB API.

Accessing the console

Navigate to https://127.0.0.1:18443/console/ in your browser (adjust the host and port to match your extenddb.toml configuration). Accept the self-signed certificate warning on first visit.

Login

  • Admin users: Enter your admin username and password (the credentials printed during extenddb init).
  • IAM users: Enter account_id/user_name as the username and your console password.

Features

  • Dashboard: Overview of accounts and admin users (admin sessions only; an IAM-user session gets a link to its own user page).
  • Account management: Create, view, and delete accounts (admin only).
  • User management: Create and delete IAM users, view access keys, policies, tags, and group memberships.
  • Access key management: Create and delete access keys. The secret key is shown once at creation time.
  • Group management: Create and delete groups, add and remove members.
  • Role management: Create and delete roles, view trust policies.
  • Policy management: Add and delete inline policies for users, groups, and roles. Includes a JSON editor with a default policy template.
  • Metrics dashboard: Operation metrics for every account, with charts (admin only).

Admin users have full access to all management operations. IAM users open their own user page, which lists their access keys, and create and delete their own access keys there. These are the access key reads and writes the management API gives an IAM user. The console has no form to change the password or import a key. Every other page under /console/accounts, the account list included, redirects an IAM-user session to the dashboard.

Sessions end 8 hours after login. Click "Logout" to end a session immediately. Deleting a user or changing its password ends that user's sessions at their next request.

9. Audit logging

The server writes audit entries at WARN level to its log: syslog when it runs as a daemon, and stderr with --foreground. Two targets cover some management operations and the settings changes made through the management API:

  • extenddb::audit::manage: DeleteAdmin, user and role tag changes, and AssumeRole, both granted and refused by the role's trust policy.
  • extenddb::audit::settings: each settings change made through the management API (PUT /management/settings/{key}).

extenddb settings set changes the catalog without the server and prints its extenddb::audit::settings entry on its own standard output, so the server writes no audit entry for that change. A running server logs, under no audit target, when it applies a new log_level, sqlx_log_level or throttling_enabled value.

Other management changes are not audit-logged. These include creating admin users, group membership and permissions boundary changes, password changes and credential import. Creating and deleting accounts, IAM users, groups, roles, access keys and policies are not audit-logged either.

Audit entries are WARN events, so the server writes none of them while the log level (logging.level, or the log_level setting, which overrides it) is error, or while logging.level is off or a filter that turns the extenddb::audit targets off.

Secrets (passwords, secret keys) are never included in audit log entries.

View audit entries:

# Linux
journalctl -t extenddb | grep 'extenddb::audit'

# macOS
log show --predicate 'processImagePath ENDSWITH "extenddb"' --last 1d | grep 'extenddb::audit'

# Docker Compose (--foreground)
docker compose logs extenddb | grep 'extenddb::audit'

10. External test suites

extenddb supports running external test suites (e.g., Java/JUnit, Python/pytest) against a running instance. Suites are registered in external-suites.toml at the project root and referenced by path — never copied into the repo.

Running external suites

# Start extenddb first
./target/release/extenddb serve --config extenddb.toml

# Set GSI propagation delay to 0 for external tests.
# External suites expect synchronous GSI behavior (matching real DynamoDB's
# typical sub-millisecond propagation). The async GSI path is tested
# separately by the extenddb-specific test_gsi_async.py suite.
./target/release/extenddb settings --config extenddb.toml set index_propagation_delay_ms 0

# Run all registered suites
python3 devtools/run-external-tests

# Dry run — show what would execute without running
python3 devtools/run-external-tests --dry-run

# Run a specific suite by name
python3 devtools/run-external-tests \
    --suite "DynamoDB PostgreSQL Extension Functional Tests"

# Override the endpoint
python3 devtools/run-external-tests --endpoint http://localhost:9000

# Generate a JSON report
python3 devtools/run-external-tests --report results.json

# Show full test output
python3 devtools/run-external-tests --verbose

Registering a new suite

Add a [[suite]] entry to external-suites.toml:

[[suite]]
name = "My Test Suite"
path = "~/source/my-test-suite"
runner = "maven"       # maven, gradle, pytest, or cargo
enabled = true

[suite.env]
DDB_ENDPOINT = "${EXTENDDB_ENDPOINT}"

The ${EXTENDDB_ENDPOINT} placeholder is replaced with the --endpoint value at runtime.

Supported runners: maven (mvn test), gradle (gradle test), pytest (python3 -m pytest), cargo (cargo test).

Prerequisites

Each runner requires its tools to be installed. The runner checks prerequisites before executing and skips suites with missing tools:

  • maven: java, mvn
  • gradle: java, gradle
  • pytest: python3, pytest
  • cargo: cargo

11. Check version

./target/release/extenddb version
# extenddb 1.0.0
# catalog migration 12 (postgres)
# commit abc1234
# built 2026-04-17T12:00:00Z
# test-hooks disabled

The -V flag prints the same output:

./target/release/extenddb -V

12. Tear down

To completely remove a deployment:

./target/release/extenddb destroy --config extenddb.toml --yes

The --yes flag is required to confirm destruction. Without it, the command exits with an error.

Performance Tuning

Connection pool size

The storage.postgres.pool_size setting (default: 20, minimum: 10) sizes the connections used for DynamoDB data operations. It sizes two pools, not one: a deployment created by extenddb init keeps its catalog and its data in separate databases, and the engine opens a pool of pool_size against each. Both count against the same server-wide max_connections, because that limit is per cluster rather than per database. Each in-flight request that touches the database holds one connection for the duration of its transaction. Values below 10 are clamped at startup with a warning.

The storage.postgres.catalog_pool_size setting controls the maximum number of concurrent connections for the management/catalog pool (authorization queries, IAM operations, console). Defaults to pool_size if not set, minimum: 10. With auth enabled (provider = "builtin"), each DynamoDB request makes concurrent authorization queries against this pool — size it to match expected concurrency. Values below 10 are clamped at startup with a warning.

When to increase: If you see elevated latency under concurrent load, the pool may be saturated. Requests queue at the pool level when all connections are in use. Increase pool_size (and catalog_pool_size if auth is enabled) to allow more concurrent transactions.

Relationship to PostgreSQL max_connections: The total connection footprint is 2 * pool_size + catalog_pool_size + [backup] max_concurrent_jobs, plus one connection per vector index build running on the server and one while a schema migration runs. The max_concurrent_jobs term (default 4) is one dedicated connection per running backup or restore job, outside every pool, which holds the job's session-level advisory lock (its claim). The doubled term is the catalog pool and the data pool, both sized by pool_size; the third pool is the management pool sized by catalog_pool_size. A deployment whose catalog and data share one database is the only shape where the two pool_size pools collapse into one, and extenddb init does not produce it. Those extra sessions are opened outside both pools on purpose, for two different reasons. A build's ownership lock is session-scoped, so it needs a session that ends when the build does: a pooled connection would return to the pool still holding the lock. The migration lock is transaction-scoped, and needs a pinned connection because its explicit transaction has to retain one PostgreSQL backend until COMMIT, which is what stops a transaction-pooling proxy from letting the lock move between backends. PostgreSQL's default max_connections is 100, and the defaults already need 64 of it. Ensure 2 * pool_size + catalog_pool_size + max_concurrent_jobs, plus the number of vector index builds you expect to overlap, does not exceed your PostgreSQL max_connections setting.

Example: To support 50 concurrent data operations with auth enabled, set both pools to 50 in extenddb.toml. That configuration can open 154 connections (the default max_concurrent_jobs of 4 included), so PostgreSQL needs max_connections raised to at least 154 plus headroom for overlapping vector index builds. The default of 100 is not enough for it: an operator who sizes for 100 here meets FATAL: sorry, too many clients already at exactly the concurrency the setting was chosen to support.

[storage.postgres]
pool_size = 50
catalog_pool_size = 50

Contention characteristics

  • Different items: Fully concurrent up to pool_size. No contention.
  • Same item: Concurrent writes to the same item serialize on PostgreSQL's row lock (SELECT ... FOR UPDATE). All updates succeed, but throughput for a single hot item is bounded by single-row transaction rate.
  • Reads: GetItem and Query do not acquire row locks and proceed concurrently with writes.

Auth/authz caching

Each DynamoDB request normally issues ~6 catalog queries during auth/authz (credential lookup, identity policies, group policies, permissions boundary, principal tags, resource tags) plus a 7th for the table's key schema. ExtendDB layers an in-memory stale-while-revalidate cache over each of these to eliminate the round-trip in steady state.

Configured via [auth.cache]:

[auth.cache]
enabled            = true   # master kill switch
ttl_seconds        = 60     # hard TTL — entries older than this are full misses
soft_ttl_seconds   = 30     # entries older than this serve cached AND trigger
                            #   a background refresh (request does not block)
negative_ttl_seconds = 5    # how long "not found" results are remembered
max_entries        = 10000  # maximum entries per cache

Self-induced changes (admin API and console mutations: CreateAccessKey, PutUserPolicy, TagResource, CreateTable, etc.) propagate instantly via write-through invalidation on the local instance.

Fanout invalidations (DeleteAccount, DeleteRole session sweep, DeleteGroup member fanout) also take effect when the API returns. If a group change cannot list the group's members, those members' entries wait for ttl_seconds.

Off-instance changes (multi-node deployments, or direct DB writes outside the management API) take up to ttl_seconds to propagate.

Cache statistics are exposed at /management/auth-cache-metrics (JSON, admin-authenticated): hit / stale-hit / miss counts, refresh successes and failures, current entry counts per cache, and a pass_through flag per cache (distinguishes "disabled" from "cold").

Troubleshooting

See docs/troubleshooting.md for common errors and fixes.

Sample Application

A complete Python sample application is included at samples/sample_app.py. It demonstrates the full extenddb lifecycle:

  1. Create tables — simple PK, PK+SK with GSI, and multi-part GSI keys (tournament pattern)
  2. Poll for ACTIVE — wait for all tables to reach ACTIVE status
  3. Load data — PutItem and BatchWriteItem
  4. Query — Query on base tables and GSIs (including multi-part GSI keys), Scan
  5. Update — UpdateItem with update expressions and conditions
  6. Batch read — BatchGetItem across multiple keys
  7. Transactions — TransactWriteItems and TransactGetItems across tables
  8. Delete — DeleteItem to remove individual items
  9. Drop tables — DeleteTable to tear down all tables

Running the sample application

# Start extenddb
./target/release/extenddb serve --config extenddb.toml

# Create an IAM user with DynamoDB access (use account ID from init)
./target/release/extenddb manage --user admin --password '<admin-password>' \
  create-user --account-id <account-id> \
  --user-name sampleuser --user-password 'SamplePass1!'

./target/release/extenddb manage --user admin --password '<admin-password>' \
  put-user-policy --account-id <account-id> \
  --user-name sampleuser --policy-name FullAccess \
  --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"dynamodb:*","Resource":"*"}]}'

# Create an access key (self-service)
./target/release/extenddb manage --user <account-id>/sampleuser --password 'SamplePass1!' \
  create-access-key

# Run the sample with the access key from create-access-key output
export AWS_CA_BUNDLE=~/.extenddb/tls/cert.pem
export EXTENDDB_ENDPOINT=https://127.0.0.1:18443
export AWS_ACCESS_KEY_ID=<access-key-id>
export AWS_SECRET_ACCESS_KEY=<secret-access-key>
python3 samples/sample_app.py

The sample creates three tables (SampleUsers, SampleOrders, SampleTournamentMatches), exercises all major DynamoDB operations, and cleans up after itself.


License

Copyright 2026 ExtendDB contributors. Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

This software is provided "as is" without warranty of any kind. ExtendDB is an open source project maintained by AWS. It is not Amazon DynamoDB or an AWS service. "DynamoDB" is a trademark of Amazon.com, Inc. or its affiliates.