Moving from DynamoDB to VeltrixDB in two sprints.

Two reasons, always the same.

Every team that walked us through a DynamoDB-to-VeltrixDB migration showed up with the same two concerns. The bill, and the tail.

If you're reading this guide, you probably already know your why. For the engineering manager you'll be selling this migration to, make the case with your own numbers:

• Cost · take your current DynamoDB invoice and compare it with the cost of self-hosted nodes with local NVMe sized for your RAM and disk needs. VeltrixDB keeps every key in RAM. With small values the index (~142 B/key, plus ~90 B/key for the ordered index unless disabled) is about as large as the data, so size RAM from your key count. The node-sizing rules give an estimate, not a measurement.
• Tail latency · measure DynamoDB's P99 for your access pattern, then measure VeltrixDB's during the shadow-read phase (§06). The only reproducible VeltrixDB read figure we publish is a cache-resident YCSB run (P99 2.77 ms). Its conditions are in the benchmark post.

The rest of this guide is the playbook. Two sprints. No big-bang cutover. Rollback at every stage.

Confirm you're in scope — before you book the project.

VeltrixDB is a scalpel, not a Swiss Army knife. Spend an hour validating fit before you spend two sprints validating performance.

Before you start, run the table through this checklist. If any row is a "no," talk to us before booking the migration — there's a good chance VeltrixDB is the wrong tool for that workload.

Two sprints. Five stages.

No big-bang cutover. Every stage runs DynamoDB in parallel until the very last hour. Rollback is one config flip away at every checkpoint.

Terraform you can paste into your repo.

Three resources, eight inputs. Drop into your existing EKS module, change the instance type to a local-NVMe SKU, run terraform apply.

This snippet provisions a 3-node EKS-hosted VeltrixDB cluster on i3en.6xlarge instances with local NVMe. Adjust node count and instance class, or swap the EKS parts for GKE/AKS modules. The Helm chart is not in the main VeltrixDB repo. Check the chart repository listed in the VeltrixDB README and pin a chart version that exists there. Your values.yaml.tpl has to use that chart's own value names.

# Helm release wrapping the VeltrixDB chart
resource "helm_release" "veltrixdb" {
  name       = "veltrixdb"
  repository = "https://charts.veltrixdb.io"
  chart      = "veltrixdb"
  # version = "…"  pin a chart version published in that repository
  namespace  = "veltrixdb"
  create_namespace = true

  values = [templatefile("./values.yaml.tpl", {
    nodes          = 3
    cache_mb       = 131072  # server flag -cache is in MB (default 256)
    nvme_gb        = 3000
    storage_class  = "veltrixdb-nvme"
    region         = "us-east-1"
  })]
}

# Local NVMe StorageClass (i3en family)
resource "kubernetes_storage_class" "nvme" {
  metadata { name = "veltrixdb-nvme" }
  storage_provisioner = "kubernetes.io/no-provisioner"
  volume_binding_mode = "WaitForFirstConsumer"
  parameters = {
    type = "local-ssd"
    fsType = "xfs"  # nvme-prep formats local SSDs as XFS
  }
}

# Node group: i3en.6xlarge — 24 vCPU, 192 GiB RAM, 2 × 7.5 TB local NVMe
module "veltrix_nodes" {
  source           = "terraform-aws-modules/eks/aws//modules/eks-managed-node-group"
  cluster_name     = var.eks_cluster_name
  name             = "veltrixdb-nodes"
  instance_types   = ["i3en.6xlarge"]
  desired_size     = 3
  min_size         = 3
  max_size         = 6
  labels = { workload = "veltrixdb" }
  taints = [{ key = "workload", value = "veltrixdb", effect = "NO_SCHEDULE" }]
}

Bulk-import from DynamoDB

There is no dedicated DynamoDB importer. The repo's veltrix-migrate import reads JSONL from stdin, one {"k": "<key>", "v": "<base64 value>"} per line, and PUTs each entry over the binary protocol. It's idempotent: re-runs overwrite, so it's safe to restart if it fails partway. The jq step below maps each DynamoDB item to a key (here, a partition key pk of string type) and stores the item's JSON as the value. Adapt it to your key schema, for example pk:sk for composite keys. It sends one PUT at a time and does not carry TTLs. Each single PUT takes a whole 4 KB VLog block, so for many small items a loader that batches with MPUT (e.g. the Go client's BinaryConn.MPut) packs ~26 × 128 B records per block instead. In --mode=raft, point --dst at the current leader, because followers reject writes with a MOVED redirect and veltrix-migrate does not follow it. In --mode=replicated any node accepts the write and replicates it to its peers (eventual by default).

$ aws dynamodb export-table-to-point-in-time \
    --table-arn arn:aws:dynamodb:us-east-1:123456789012:table/sessions \
    --s3-bucket veltrix-migration-staging \
    --export-format DYNAMODB_JSON

$ go build -o veltrix-migrate ./cmd/veltrix-migrate   # from the VeltrixDB repo

$ aws s3 cp --recursive \
    s3://veltrix-migration-staging/AWSDynamoDB/<export-id>/data/ ./export/

$ gunzip -c ./export/*.json.gz \
  | jq -c '{k: .Item.pk.S, v: (.Item | tojson | @base64)}' \
  | ./veltrix-migrate import --dst veltrixdb-0.veltrixdb:9000

Fan out writes, keep DynamoDB as the source of truth.

During sprint 1, every write goes to both databases synchronously. If divergence climbs above 0.1%, an alarm fires and you fix it before you ever flip reads.

The dual-write step is where most botched migrations go wrong. The temptation is to fan out writes asynchronously to keep latency down — don't. Async fan-out hides bugs that only surface during cutover. Run the writes synchronously, in parallel, and accept the latency cost during the migration window.

Reference implementation

The pattern, in pseudocode, looks like this. The key invariants: write to DynamoDB first (still source of truth), then write to VeltrixDB, then log any inconsistencies — but never roll back a successful DynamoDB write because the VeltrixDB write failed.

func (r *Repo) Put(ctx context.Context, k string, v []byte) error {
    // 1. Source of truth still wins
    if err := r.ddb.Put(ctx, k, v); err != nil {
        return err
    }
    // 2. Mirror to VeltrixDB · best-effort
    go func() {
        cctx, cancel := context.WithTimeout(ctx, 200*time.Millisecond)
        defer cancel()
        if err := r.veltrix.Put(cctx, k, v); err != nil {
            metrics.DualWriteFail.WithLabelValues("veltrix").Inc()
            log.Warn("veltrix mirror failed", "key", k, "err", err)
        }
    }()
    return nil
}

Read both. Trust neither. Compare everything.

Before flipping the read path, you spend 48 hours reading from both databases and comparing the answers byte-for-byte. This is where you catch the bugs that bulk-import didn't.

The shadow-read phase runs on the same dual-write pattern, inverted. For every read your application makes, fire a second read against VeltrixDB, compare, log mismatches, and surface the side-by-side P99 chart in Grafana. Your users still see DynamoDB's answer — VeltrixDB is on probation.

5 → 25 → 50 → 100. No big-bang flips.

Move the read traffic in four feature-flag controlled steps. Each step must be stable for four hours before the next. Rollback at any step is a single config change.

If shadow reads were clean this stage should be uneventful — walk through the cohorts anyway. Discipline here is what makes the postmortem boring.

Rollback

If anything goes wrong at any step, the rollback is a single feature-flag flip: read_source=dynamodb. Because writes are still going to both databases, DynamoDB never went stale. You lose nothing, and you debug at leisure.

Decommission, save the receipts.

A week after cutover, drop the dual-write fan-out and put the DynamoDB table into read-only mode. Keep it warm for a month as cold storage. Then archive it.

The decommission step is procedural — no surprises. Drop the dual_writer.go path from your repo, point the DynamoDB IAM role at a read-only policy, and schedule a calendar reminder for 30 days out to delete the table. Most teams keep the table around longer than they need to — that's fine, and the cost is trivial.

What's not trivial: save the DynamoDB invoice from the month before cutover. Compare it to the VeltrixDB invoice three months later. Remember that VeltrixDB's side of that comparison is your own infrastructure bill, since it is self-hosted. The delta is the receipt you bring to the next budget review, and the number your CFO will want to see in writing. (An earlier version quoted customer savings figures that we cannot source, so we have removed them.)