Skip to content
NamiDB NamiDB

AWS S3

AWS S3 is the primary path for NamiDB. The engine was designed against S3’s conditional-write semantics; every other S3-compatible backend (R2, MinIO, LocalStack, Tigris) is validated against the same test suite.

Open a namespace

import namidb as tg


client = tg.Client("s3://my-bucket/data?ns=prod&region=us-east-1")
let (store, paths) = parse_uri("s3://my-bucket/data?ns=prod&region=us-east-1")?;

Credentials

Credentials read from the standard AWS env vars:

Terminal window
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...        # if using temporary creds
export AWS_DEFAULT_REGION=us-east-1

IAM roles on EC2 / EKS / Lambda / ECS work transparently — no NamiDB-specific auth to wire. The Rust object_store crate uses the standard provider chain.

Query-string region=… overrides AWS_DEFAULT_REGION.

IAM permissions

The minimum IAM permissions NamiDB needs on the bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::my-bucket/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::my-bucket"
    }
  ]
}

That’s it. No DynamoDB lock table. No separate metadata service.

Cross-region considerations

  • Pick the region closest to your readers. Cross-region GET latency is the dominant factor in cold-read time.
  • NamiDB caches (RFC-018, RFC-019, RFC-020) hide most of the cost for warm working sets.
  • For multi-region read replicas, run a namidb-server per region pointed at the same bucket — only one will be allowed to commit writes; the rest serve reads.

Pricing knobs

  • Storage: standard S3 storage class. Cold tenants can be moved to S3 Intelligent-Tiering or Glacier IR (re-warmup latency applies).
  • Egress: NamiDB issues only as many GETs as the working set requires. Cache hits cost nothing.
  • Requests: writes do 1 WAL PUT + 1 manifest PUT per commit batch. Compaction adds background PUTs.

See also