Skip to content

Getting started

fdyno is a single Go binary that talks to a FoundationDB cluster. To run it you need FoundationDB installed and a cluster file.

1. Run FoundationDB

Install the FoundationDB client and server packages for your platform. A fresh single-node install starts a local cluster and writes a cluster file to /etc/foundationdb/fdb.cluster.

Verify it is up:

fdbcli --exec "status minimal"

2. Build and run fdyno

git clone https://github.com/pratikgajjar/fdyno
cd fdyno
go build -o dynodb ./cmd/dynodb

# Point it at your cluster and choose a listen address.
FDB_CLUSTER_FILE=/etc/foundationdb/fdb.cluster \
DYNODB_LISTEN_ADDR=":8000" \
  ./dynodb

fdyno is now serving the DynamoDB wire protocol on :8000.

3. Point an SDK at it

fdyno verifies AWS SigV4 signatures, so use any access-key/secret pair your server is configured to accept. The built-in development credentials are local/local.

import boto3

ddb = boto3.client(
    "dynamodb",
    endpoint_url="http://localhost:8000",
    region_name="us-east-1",
    aws_access_key_id="local",
    aws_secret_access_key="local",
)

ddb.create_table(
    TableName="users",
    AttributeDefinitions=[{"AttributeName": "id", "AttributeType": "S"}],
    KeySchema=[{"AttributeName": "id", "KeyType": "HASH"}],
    BillingMode="PAY_PER_REQUEST",
)
ddb.get_waiter("table_exists").wait(TableName="users")

ddb.put_item(TableName="users", Item={"id": {"S": "u1"}, "name": {"S": "Ada"}})
print(ddb.get_item(TableName="users", Key={"id": {"S": "u1"}})["Item"])

cfg, _ := config.LoadDefaultConfig(ctx,
    config.WithRegion("us-east-1"),
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("local", "local", "")),
)
ddb := dynamodb.NewFromConfig(cfg, func(o *dynamodb.Options) {
    o.BaseEndpoint = aws.String("http://localhost:8000")
})

ddb.PutItem(ctx, &dynamodb.PutItemInput{
    TableName: aws.String("users"),
    Item: map[string]types.AttributeValue{
        "id":   &types.AttributeValueMemberS{Value: "u1"},
        "name": &types.AttributeValueMemberS{Value: "Ada"},
    },
})

export AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local AWS_DEFAULT_REGION=us-east-1
aws dynamodb list-tables --endpoint-url http://localhost:8000

Set your own credentials in production

The built-in local credentials are development defaults and are not secret. Supply real credentials with DYNODB_CREDENTIALS and run fdyno behind a TLS terminator. See Operations & security.

Run the conformance suites

The three black-box suites run against a freshly-built server backed by a local FoundationDB cluster:

scripts/ci/run-conformance.sh alternator
scripts/ci/run-conformance.sh nubo
scripts/ci/run-conformance.sh extenddb

They also run in parallel on every push via GitHub Actions.