A practical data migration playbook for STACKIT

The sequence, store by store

1. 01

   1. List the stateful units

   Start from migration/data-movement.md. It lists every unit that holds data of its own: a database, a cache, a block volume, an object store. Queues and the system on a server's disk are not read as stateful. Provisioned capacity shown beside a unit is what was provisioned, not the size of the data.

2. 02

   2. State the numbers the source cannot

   Data size, change rate, bandwidth, recovery point, recovery time and tolerated downtime are never in the Terraform. The run marks each UNKNOWN until you supply it, and a duration it prints is only a lower bound of the transfer. Without these numbers no method can be shown to fit a window.

3. 03

   3. Choose one method per store

   The plan lists candidate methods for each unit and marks others unsupported, with the reason. The choice is a recorded decision, not a default. The table below shows the four stores of this run.

4. 04

   4. Preflight

   Close the prerequisites the preflight checks before anything is copied: extensions, roles and TLS on the database, versions and archived objects in the bucket, the file system and free space on the volume, the commands the copy needs and the client TLS settings on the cache. A few, such as object metadata, are closed by the rehearsal instead.

5. 05

   5. Rehearse

   Copy once into the empty target while the source stays in service, and measure the real throughput. The rehearsal is where a window estimate becomes a number you can defend.

6. 06

   6. Freeze writes, final sync

   Stop the writers, copy what changed since the last pass, and keep the source untouched. For object stores the plan sets out an initial copy and a delta sync before the freeze, so the frozen part is short.

7. 07

   7. Reconcile

   Compare both sides with the writers still stopped: row counts, checksums and sequences for the database, object counts and bytes for the bucket, key counts and key lists for the cache. Accept the move only on a recorded GO.

8. 08

   8. Switch, then clean up

   Point the clients at the target, keep the source for the period the owner records, and delete temporary keys, dump files and the move host afterwards. The Object Storage key matters most: a credential created in a project has access to every bucket in that project (docs).

Four stateful units, listed

An estate written for this page and assessed by StackToIT on 4 November 2026: a PostgreSQL database, a versioned bucket, a block volume and a cache. First two panes: the data-bearing blocks of the input as two verbatim line ranges of main.tf, the database to the volume and then the cache (the network, server and attachment blocks around them are left out). Last pane: the table at the top of migration/data-movement.md, unchanged; on a narrow screen it scrolls sideways.

resource "aws_db_instance" "orders" {
  identifier              = "orders-db"
  engine                  = "postgres"
  engine_version          = "15.7"
  instance_class          = "db.m5.large"
  allocated_storage       = 200
  storage_type            = "gp3"
  username                = "orders"
  password                = var.db_password
  db_subnet_group_name    = aws_db_subnet_group.main.name
  multi_az                = true
  backup_retention_period = 7
  skip_final_snapshot     = true
}

resource "aws_s3_bucket" "uploads" {
  bucket = "acme-orders-uploads"
}

resource "aws_s3_bucket_versioning" "uploads" {
  bucket = aws_s3_bucket.uploads.id
  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_ebs_volume" "reports" {
  availability_zone = "eu-central-1a"
  size              = 500
  type              = "gp3"
}

resource "aws_elasticache_cluster" "sessions" {
  cluster_id        = "sessions"
  engine            = "redis"
  engine_version    = "7.0"
  node_type         = "cache.t3.small"
  num_cache_nodes   = 1
  subnet_group_name = "sessions"
}

| Unit | Source service | Target service | Application | Mechanism | State | Data class | RPO | Downtime tolerance |
|---|---|---|---|---|---|---|---|---|
| aws_db_instance.orders | aws_db_instance | STACKIT PostgreSQL Flex |  | UNKNOWN | DECISION_REQUIRED | NOT_PROVIDED | NOT_PROVIDED | NOT_PROVIDED |
| aws_ebs_volume.reports | aws_ebs_volume | STACKIT Block Storage |  | UNKNOWN | DECISION_REQUIRED | NOT_PROVIDED | NOT_PROVIDED | NOT_PROVIDED |
| aws_elasticache_cluster.sessions | aws_elasticache_cluster | STACKIT Key Value Store (Valkey) |  | UNKNOWN | DECISION_REQUIRED | NOT_PROVIDED | NOT_PROVIDED | NOT_PROVIDED |
| aws_s3_bucket.uploads | aws_s3_bucket | STACKIT Object Storage |  | UNKNOWN | DECISION_REQUIRED | NOT_PROVIDED | NOT_PROVIDED | NOT_PROVIDED |

• Every mechanism starts as UNKNOWN

  Four units, four DECISION_REQUIRED states. The data class, recovery point and downtime tolerance come from the customer's applications file, word for word; without one they stay NOT_PROVIDED and no default is assumed.

• The volume has one open method

  For the block volume only a file-level copy between servers is offered, so the execution plan takes it. The other three units wait for your answer.

• Nothing is executed

  The file says it in its first lines: StackToIT never moves data. Every step in the plan is for a person.

Which method for which store

As the run lists them. Tools named in a method are the operator's own to install and run; the plan does not run or verify them.

The cache method is inferred from the tutorial's procedure and has not been run by StackToIT against a Key Value Store, as the plan itself states. The tutorial quotes about 50 seconds per gigabyte on average and warns that keys with line breaks can break its command-line pipe.

The steps and the checks of one move

From migration/data-movement-plan.json, for the dump-and-restore method of the database. Left: the six steps. Right: the row-count, checksum and sequence checks, with the exact command each one names.

          "steps": [
            {
              "kind": "preflight",
              "id": "MAN/data/aws_db_instance.orders/preflight",
              "in_plan": true
            },
            {
              "kind": "rehearsal",
              "id": "MAN/data/aws_db_instance.orders/rehearsal",
              "in_plan": true
            },
            {
              "kind": "write-freeze",
              "id": "MAN/data/aws_db_instance.orders/write-freeze/dump-restore",
              "in_plan": true
            },
            {
              "kind": "final-sync",
              "id": "MAN/data/aws_db_instance.orders/final-sync/dump-restore",
              "in_plan": true
            },
            {
              "kind": "reconcile",
              "id": "MAN/data/aws_db_instance.orders/reconcile/dump-restore",
              "in_plan": true
            },
            {
              "kind": "cleanup",
              "id": "MAN/data/aws_db_instance.orders/cleanup/dump-restore",
              "in_plan": true
            }
          ],

            {
              "id": "row-counts",
              "kind": "COUNT_COMPARISON",
              "mode": "COMMAND",
              "what": "Count the rows of every table on both sides, with the writers stopped (an exact count of each table; the estimates of pg_stat_user_tables are not counts).",
              "expected": "the same tables with the same number of rows on both sides",
              "command": "SELECT format('SELECT %L AS tbl, count(*) FROM %I.%I;', schemaname || '.' || tablename, schemaname, tablename) FROM pg_tables WHERE schemaname NOT IN ('pg_catalog', 'information_schema') \\gexec"
            },
            {
              "id": "table-checksums",
              "kind": "CONTENT_CHECK",
              "mode": "COMMAND",
              "what": "Take the md5 of the rows of every keyed table that matters on both sides, ordered by its key (a key range for a large table; DateStyle, TimeZone and extra_float_digits equal in both sessions).",
              "expected": "the row count and the md5 are equal on both sides for every table checked",
              "command": "SELECT count(*), md5(string_agg(t::text, ',' ORDER BY t.<key-column>)) FROM <schema>.<table> t;",
              "not_provided": [
                "the key column of each table (<key-column>)",
                "the tables that matter"
              ]
            },
            {
              "id": "sequences",
              "kind": "CONTENT_CHECK",
              "mode": "COMMAND",
              "what": "Compare the position of every sequence on both sides, so that the first insert on the target does not repeat a key.",
              "expected": "the positions are equal, or the target's is higher",
              "command": "SELECT sequencename, last_value FROM pg_sequences ORDER BY 1;"
            },

• Checks compare, they do not trust

  Each check states what it compares and what result counts as equal. Row counts use an exact count of every table, not the planner's estimates; checksums need a key column per table that you name.

• Some checks are yours by design

  The application check and the rollback limit are marked manual: the read and the write belong to the application, and how long the source is kept is the owner's decision. The plan names the limit and no date.

• Rollback is the untouched source

  On a NO-GO the clients still point at the source, which is current to the freeze. Until the target accepts its first write after the switch, a rollback is only the connection settings put back. After that, PostgreSQL Flex's own daily backups with transaction logs allow a point-in-time restore, but only into a new instance in the same project; there is no in-place restore, so clients are repointed again (docs).

Decisions the architect owns

• Method per store

  Dump and restore against logical replication is a trade between a longer freeze and a change to the source. Decide it once the size and the tolerated downtime are stated.

• Version history of the bucket

  Copy only current objects, or plan the procedure for versions and delete markers. The default copy does not carry history.

• Permissions and roles

  Roles, grants and extensions of the database are re-created on the target; the plan lists the queries that read them from the source.

• Sessions in the cache

  Whether a session cache is worth copying at all, or whether users sign in again, is a business call. That framing is practice, not a finding of the run.

• How long the source stays

  The date until which the source is kept, and whether writes made on the target are copied back or accepted as lost.

Data migration questions

Sources

• STACKIT Key Value Store: migrate data to a new instance
• STACKIT PostgreSQL Flex: backup and clone
• STACKIT Object Storage: concepts