This guide starts a MoveTables workflow on a Neki database, lets it copy 200,000 rows into a second logical database, and then cancels it before any traffic moves. __neki.workflow_cancel removes the copied table from every shard by default; with keep_data it leaves the rows for you to inspect and drop. The guide also covers the two things cancel does not do on its own: it refuses once reads have switched, and it leaves the target database's entry in the data topology.
What you will build
move_tables_create(postgres.orders -> archive.orders) -> copy + stream
workflow_cancel(wf) -> archive.orders removed on every shard
workflow_cancel(wf, {"keep_data":true}) -> archive.orders kept, readable; DROP TABLE yourself
after workflow_switch_reads: cancel refused -> workflow_reverse_reads -> cancel
data topology: remove the leftover "archive" entry
AI Prompt
Using the PlanetScale CLI (pscale 0.344.0) and psql, cancel a Neki MoveTables data migration before traffic moves and clean up everything it copied.
Requirements:
- Create the Neki database with --engine neki, --cluster-size PS-10-AWS-ARM-NEKI and --replicas 2, add two shards, shard the table, load it with COPY, and wait until every shard answers a direct SELECT 1 with SET __neki.shard. Use one database role for every step.
- Create the target logical database, start __neki.move_tables_create(...), and wait for phase streaming.
- __neki.workflow_cancel(workflow) removes the copied tables from every shard and deletes the workflow. With options '{"keep_data": true}' it keeps them; drop them with DROP TABLE in the target database.
- workflow_cancel is refused after workflow_switch_reads. Run __neki.workflow_reverse_reads(workflow) first.
- Check each shard with SET __neki.shard and to_regclass in the target database; the router's view is not enough.
- Cancel leaves the target database in the data topology. Remove it with pscale branch data-topology update.
- Run the verification step below before finishing.
Prerequisites
A PlanetScale organization with access to the Neki Platform Preview. Create an account if you do not have one, and see Neki availability and access for how an organization administrator joins the preview.
pscale0.344.0 with a service token that can create databases,psql18.6,jq, andpython3:
export PLANETSCALE_SERVICE_TOKEN_ID="<token id>"
export PLANETSCALE_SERVICE_TOKEN="<token>"
export PLANETSCALE_ORG="<organization name>"
pscale version
- A Neki database with three shards and an
orderstable holding 200,000 rows, sharded bycustomer_id. Create them with these commands:
pscale database create warehouse --engine neki --org "$PLANETSCALE_ORG" \
--region us-east --cluster-size PS-10-AWS-ARM-NEKI --replicas 2 --wait
pscale role create warehouse main admin --inherited-roles postgres --org "$PLANETSCALE_ORG" --format json > role.json
export PGHOST=$(jq -r .access_host_url role.json) PGUSER=$(jq -r .username role.json) \
PGPASSWORD=$(jq -r .password role.json) PGPORT=5432 PGDATABASE=postgres PGSSLMODE=require
rm role.json
until psql -At -c "SELECT 1" >/dev/null 2>&1; do sleep 5; done
pscale branch shard create warehouse main --config-profile default --count 2 --org "$PLANETSCALE_ORG"
until [ "$(psql -At -c 'SELECT count(*) FROM __neki.list_shards()')" = "3" ]; do sleep 10; done
for u in $(psql -At -c "SELECT uid FROM __neki.list_shards()"); do
until psql -At -c "SET __neki.shard='$u';" -c "SELECT 1" >/dev/null 2>&1; do sleep 5; done
done
psql -q -v ON_ERROR_STOP=1 \
-c "CREATE TABLE orders (customer_id bigint NOT NULL, order_id bigint NOT NULL, total_cents bigint NOT NULL, PRIMARY KEY (customer_id, order_id))" \
2>&1 | grep -v NOTICE
SHARD_1=$(psql -At -c "SELECT uid FROM __neki.list_shards() WHERE name='sh1'")
SHARD_2=$(psql -At -c "SELECT uid FROM __neki.list_shards() WHERE name='sh2'")
SHARD_3=$(psql -At -c "SELECT uid FROM __neki.list_shards() WHERE name='sh3'")
cat > data-topology.json <<JSON
{
"shard_indexes": { "xxhash_customer_id": { "type": "xxhash", "columns": ["customer_id"] } },
"shard_groups": [
{ "uid": "$SHARD_1", "key_ranges": [ { "shard_uid": "$SHARD_1" } ] },
{ "uid": "by_customer", "default_shard_index": "xxhash_customer_id",
"key_ranges": [ { "shard_uid": "$SHARD_2", "end": "80" }, { "shard_uid": "$SHARD_3", "start": "80" } ] }
],
"databases": { "postgres": { "schemas": { "public": { "tables": {
"orders": { "shard_group": "by_customer" }
} } } } },
"default_shard_group": "$SHARD_1",
"authoritative_shard_group": "$SHARD_1"
}
JSON
pscale branch data-topology update warehouse main --org "$PLANETSCALE_ORG" --format json < data-topology.json > /dev/null
sleep 10
python3 -c "
for i in range(1, 200001): print(f'{(i*7919)%5000+1},{i},{(i*31)%100000}')" > orders.csv
psql -c "\copy orders (customer_id, order_id, total_cents) FROM 'orders.csv' WITH (FORMAT csv)"
The COPY prints COPY 200000.
Note: Output samples are trimmed to the relevant lines. Each shard bills as a three-node cluster.
PS-10-AWS-ARM-NEKIlists at $30 per month per shard, prorated to the millisecond. Current rates are on the Neki pricing page. Delete the database when you finish withpscale database delete warehouse --force --org "$PLANETSCALE_ORG".
1. Write two helpers
start-move.sh creates a MoveTables workflow from postgres.orders to archive.orders and waits until it streams. target-check.sh reports, for each shard, whether archive.orders exists there.
psql -q -c "CREATE DATABASE archive" 2>&1 | grep -v NOTICE
cat > start-move.sh <<'EOF'
#!/bin/bash
psql -At -v w="$1" -v t='{"schemas":{"public":{"tables":{"orders":{"shard_group":"by_customer"}}}}}' > /dev/null <<'SQL'
SELECT workflow FROM __neki.move_tables_create(:'w', 'postgres', :'t', 'archive', :'t', '{public.orders}', '{public.orders}', '{}');
SQL
until [ "$(psql -At -c "SELECT phase FROM __neki.list_workflows() WHERE workflow = '$1'")" = "streaming" ]; do sleep 5; done
psql -At -c "SELECT workflow || ' ' || phase || ' ' || traffic_state || ' rows_copied=' || rows_copied FROM __neki.list_workflows() WHERE workflow = '$1'"
EOF
cat > target-check.sh <<'EOF'
#!/bin/bash
for n in sh1 sh2 sh3; do
u=$(psql -At -c "SELECT uid FROM __neki.list_shards() WHERE name='$n'")
echo -n "archive.orders on $n: "
PGDATABASE=archive psql -At -c "SET __neki.shard='$u';" -c "SELECT CASE WHEN to_regclass('public.orders') IS NULL THEN 'absent' ELSE 'present' END" | tail -1
done
EOF
chmod +x start-move.sh target-check.sh
2. Start a migration and cancel it
./start-move.sh move_archive
./target-check.sh
psql -At -c "SELECT * FROM __neki.workflow_cancel('move_archive')"
sleep 3
./target-check.sh
psql -At -c "SELECT count(*) FROM __neki.list_workflows() WHERE type = 'move_tables'"
psql -At -c "SELECT count(*) FROM orders"
Real output:
move_archive streaming not_switched rows_copied=200000
archive.orders on sh1: present
archive.orders on sh2: present
archive.orders on sh3: present
archive.orders on sh1: absent
archive.orders on sh2: absent
archive.orders on sh3: absent
0
200000
workflow_cancel prints an empty line. The copied table was on every shard, including the authoritative shard where it held no rows, and after the cancel it is gone from all of them, the workflow no longer exists, and the source still has all 200,000 rows.
3. Cancel but keep the copied rows
./start-move.sh move_archive_keep
psql -At -c "SELECT * FROM __neki.workflow_cancel('move_archive_keep', '{\"keep_data\": true}')"
sleep 3
./target-check.sh
PGDATABASE=archive psql -At -c "SELECT count(*) FROM orders"
Real output:
move_archive_keep streaming not_switched rows_copied=200000
archive.orders on sh1: present
archive.orders on sh2: present
archive.orders on sh3: present
200000
With keep_data, the copied rows stay, and with the workflow gone they are readable through the router. Drop them when you are done with them:
PGDATABASE=archive psql -At -c "DROP TABLE orders" 2>&1 | grep -v NOTICE
./target-check.sh
Real output:
DROP TABLE
archive.orders on sh1: absent
archive.orders on sh2: absent
archive.orders on sh3: absent
4. Cancel after reads have switched
./start-move.sh move_archive_reads
psql -At -c "SELECT message FROM __neki.workflow_switch_reads('move_archive_reads')"
psql -At -c "SELECT * FROM __neki.workflow_cancel('move_archive_reads')" 2>&1 | head -1
psql -At -c "SELECT message || ' / ' || traffic_state FROM __neki.workflow_reverse_reads('move_archive_reads')"
psql -At -c "SELECT * FROM __neki.workflow_cancel('move_archive_reads')"
./target-check.sh
Real output:
move_archive_reads streaming not_switched rows_copied=200000
Reads switched for workflow move_archive_reads
ERROR: mark workflow teardown in progress: workflow move_archive_reads has traffic_state=READS_SWITCHED; reverse traffic to the source before cancelling
Reads reverted for workflow move_archive_reads / not_switched
archive.orders on sh1: absent
archive.orders on sh2: absent
archive.orders on sh3: absent
Cancel refuses while any traffic points at the target. Reversing the read switch returns the workflow to not_switched, and the cancel then succeeds and removes the copied table.
5. Remove the leftover topology entry
psql -At -c "SELECT data_topology_json FROM __neki.get_data_topology()" | jq -c '.databases | keys'
pscale branch data-topology get warehouse main --org "$PLANETSCALE_ORG" --format json \
| jq '.data_topology | del(.databases.archive)' > topology-clean.json
pscale branch data-topology update warehouse main --org "$PLANETSCALE_ORG" --format json < topology-clean.json | jq -r '.status // "applied"'
sleep 10
psql -At -c "SELECT data_topology_json FROM __neki.get_data_topology()" | jq -c '.databases | keys'
Real output:
["archive","postgres"]
applied
["postgres"]
Verify the result
psql -At -c "SELECT count(*) FROM __neki.list_workflows() WHERE type = 'move_tables'"
./target-check.sh
psql -At -c "SELECT data_topology_json FROM __neki.get_data_topology()" | jq -c '.databases | keys'
psql -At -c "SELECT count(*) FROM orders"
Expected: 0, absent on every shard, ["postgres"], and 200000.
How it works
A MoveTables workflow creates the target tables on each shard, copies rows into them and streams later changes, while the target tables stay blocked to clients. workflow_cancel stops the streams, deletes the workflow and, unless keep_data or keep_schema is passed, drops what it created on the target. Cancel also requires every kind of traffic to point at the source again, so a read switch has to be reversed first. The cancel options are listed by SELECT * FROM __neki.list_metafuncs(), and the workflow functions are described on the Neki data migration page.
Common issues
Cancel removed a table you created
Cancel drops the target table without checking whether it existed before the workflow. In testing, a target table that already held a row was dropped, row included, when the workflow that failed on it was cancelled. Use keep_data, or start migrations only into tables the workflow creates.
The router reports a table that is gone
Right after a cancel, to_regclass('public.orders') through the router in the target database has been seen to report the table while every shard reported it absent. Check per shard, as target-check.sh does.
drop_target_database_topology
list_metafuncs lists a drop_target_database_topology cancel option for MoveTables and says a move within one database refuses it, which is why step 5 removes the entry with a topology update.
Next steps
- Delete the database with
pscale database delete warehouse --force --org "$PLANETSCALE_ORG". - Read the Neki data migration guide for completing a workflow instead of cancelling it.
verification:
status: verified
tested_at: "2026-10-28"
product_version: "pscale 0.344.0, Neki PostgreSQL 18.6 (Platform Preview)"
command: "list_workflows count, per-shard to_regclass in archive, topology database keys, source row count"
expected_result: "0, absent on every shard, [\"postgres\"], 200000"