In this walkthrough you will build a reversible cutover on Neki: a MoveTables workflow that switches traffic to new tables while the source tables stay online, plus the reverse traffic step that moves traffic back if you need to roll back.
If your change board requires a rollback plan before approving a production cutover, the key question is which platforms keep the old tables available after traffic moves. Neki does. Its MoveTables workflow supports a switch_traffic step with reverse replication enabled, which means the original (source) tables stay in place and keep receiving changes after traffic shifts to the new tables. If anything goes wrong, you run one command to move traffic back, and the source tables are current because they never stopped being written to. This article walks through that cutover and reverse cycle step by step, using small test tables so every step finishes in seconds.
What You'll Build
You will run a complete, reversible cutover against a Neki keyspace:
- Seed a small set of rows into a source table.
- Create a MoveTables workflow that copies the table to a target and streams ongoing changes.
- Switch traffic to the target with
enable_reverse_replication: true, so the source tables stay online and keep receiving writes. - Verify the target serves reads and the source is blocked from writes.
- Run the reverse traffic workflow to move traffic back to the source, and verify both directions.
- Clean up completely: cancel the workflow and drop the test tables.
The end state is a cutover you can hand to a change board: traffic moved forward, traffic moved back, and proof that the source tables remained available the whole time.
Prerequisites
- A running Neki cluster with access to the Neki control plane.
- A client that can run SQL against both the source and target keyspaces.
- Permission to create workflows and to create and drop tables in your test keyspace.
- A unique suffix for this run (used below as
rbtest) so table, workflow, and database names never collide with anything else.
Keep the seeded data tiny. Three to ten rows is enough to prove replication in both directions, and it keeps copy and reverse steps in the seconds range instead of minutes.
Implementation
Step 1: Seed a small source table
Create the source table and insert a handful of rows:
CREATE TABLE orders_rbtest (
id serial PRIMARY KEY,
amount integer NOT NULL
);
INSERT INTO orders_rbtest (amount) VALUES (100), (200), (300);
SELECT count(*) FROM orders_rbtest;
The count returns 3. This is your baseline before any workflow exists.
Step 2: Create the MoveTables workflow and wait for streaming
Start the workflow that copies orders_rbtest into the target keyspace:
{
"workflow": "orders_rbtest_wf_rbtest",
"source_keyspace": "source_ks",
"target_keyspace": "target_ks",
"tables": ["orders_rbtest"]
}
Poll the workflow status until it reports streaming. Cap your polling loop at 60 seconds; with three rows, the copy finishes almost immediately and the workflow transitions to a steady streaming state, which is what makes the later cutover safe. Do not proceed to the switch until the status shows streaming, because that is the state where the target is caught up on the source's changes.
Step 3: Switch traffic with reverse replication enabled
This is the step that answers the change board's question. Switch traffic to the target and enable reverse replication in the same call:
{
"workflow": "orders_rbtest_wf_rbtest",
"action": "switch_traffic",
"enable_reverse_replication": true
}
With enable_reverse_replication: true, writes that land on the target after the switch are replicated back to the source tables. The source tables are not dropped, renamed, or frozen. They stay in place and stay current, which is exactly the property a rollback plan needs.
Step 4: Verify the target serves reads and the source is blocked
After the switch, confirm the new state:
- Reads and writes against the target keyspace succeed, and the target table shows the seeded rows.
- Writes against the source keyspace are blocked, because the source is no longer the serving master for this table.
Insert a row into the target to prove the reverse path has something to carry:
-- against the target keyspace
INSERT INTO orders_rbtest (amount) VALUES (400);
Step 5: Run the reverse traffic workflow
To roll back, switch traffic back to the source:
{
"workflow": "orders_rbtest_wf_rbtest",
"action": "workflow_reverse_traffic"
}
Because reverse replication was enabled in step 3, the source tables received the row you inserted in step 4. The reverse switch is safe: no data is lost by going back.
Step 6: Verify the source is serving again
Confirm the rollback worked:
- Reads and writes against the source keyspace succeed, and the source table shows all four rows (the three seeded rows plus the row inserted on the target).
- Writes against the target keyspace are now blocked, mirroring the post-switch state in step 4.
-- against the source keyspace
SELECT count(*) FROM orders_rbtest;
The count returns 4, including the write that was made while the target was serving. That is reverse replication doing its job.
Step 7: Clean up
End every test run with full cleanup so nothing is left behind:
{
"workflow": "orders_rbtest_wf_rbtest",
"action": "workflow_cancel"
}
Then drop the test tables in both keyspaces and remove any role you created for the run. A rollback rehearsal that leaves stray workflows or tables behind will itself fail a change review.
Complete Example
Here is the full cycle as one runnable bash script. It uses psql for SQL and the Neki workflow commands for the cutover steps, with the unique suffix rbtest on every name. Run each step as its own invocation rather than one long-running process.
#!/usr/bin/env bash
set -euo pipefail
SFX=rbtest
WF=orders_${SFX}_wf_${SFX}
# 1. Seed the source table (3 rows)
psql "$SOURCE_DSN" -c "CREATE TABLE orders_${SFX} (id serial PRIMARY KEY, amount integer NOT NULL);"
psql "$SOURCE_DSN" -c "INSERT INTO orders_${SFX} (amount) VALUES (100), (200), (300);"
# 2. Create the MoveTables workflow, then poll until streaming (60s cap)
neki workflow create --name "$WF" \
--source-keyspace source_ks --target-keyspace target_ks \
--tables orders_${SFX}
for i in $(seq 1 12); do
status=$(neki workflow status --name "$WF" | jq -r .status)
[ "$status" = "streaming" ] && break
sleep 5
done
# 3. Cutover with reverse replication enabled
neki workflow switch_traffic --name "$WF" --enable-reverse-replication
# 4. Verify: target serves, source blocked; write a row on the target
psql "$TARGET_DSN" -c "INSERT INTO orders_${SFX} (amount) VALUES (400);"
# 5. Rollback: switch traffic back to the source
neki workflow workflow_reverse_traffic --name "$WF"
# 6. Verify: source serves with 4 rows
psql "$SOURCE_DSN" -c "SELECT count(*) FROM orders_${SFX};"
# 7. Cleanup: cancel the workflow and drop the test tables
neki workflow workflow_cancel --name "$WF"
psql "$SOURCE_DSN" -c "DROP TABLE orders_${SFX};"
psql "$TARGET_DSN" -c "DROP TABLE orders_${SFX};"
The workflow step names (switch_traffic, workflow_reverse_traffic, workflow_cancel) match the actions used throughout this article; adapt the exact CLI invocation to your control plane. Short, independent steps are easier to audit, and each one produces evidence a change board can review.
How It Works
Three decisions make this cutover reversible:
Reverse replication keeps the source current. The enable_reverse_replication: true flag on switch_traffic sets up replication from the target back to the source. The source tables stay online as replication targets, so they absorb every write made after the cutover. Rolling back is then just a traffic switch, not a data recovery exercise.
The switch is a serving change, not a data move. After switch_traffic, the data already exists in both places. What changes is which side accepts writes. That is why the source can be blocked from writes in step 4 and serving again in step 6 without any copying in between.
The reverse workflow mirrors the forward one. workflow_reverse_traffic switches serving back to the source using the same workflow object. Because replication ran in both directions while the target was serving, the source already has the latest rows.
Two edge cases to respect:
- Do not run the reverse switch before the forward workflow reaches streaming. Streaming is the state that guarantees the target caught up, and everything after depends on it.
- Always cancel the workflow and drop test tables when rehearsing. Leftover workflows keep replication channels open and will confuse the next rehearsal.
Conclusion
A rollback plan does not have to mean "restore from backup and hope." With Neki's MoveTables workflow, you can switch traffic to new tables while the old tables stay in place and keep receiving writes through reverse replication. Rolling back is a single reverse traffic command, and the source is already up to date when you do it. Rehearse the cycle on a small test table with a unique suffix, verify both directions, and clean up fully. That rehearsal, with its verification steps, is the artifact your change board actually wants to see. To try it against your own workload, rehearse the same cycle on your Neki cluster or talk to the team about a production cutover plan.
verification:
status: unverified
tested_at: null
product_version: null
command: null
expected_result: null