An online DDL workflow on Neki normally applies a single-table ALTER TABLE by copying the table into a shadow table on each data shard. For a change that does not need a copy, such as adding a nullable column, the apply_direct option runs the statement on each shard instead. This guide runs the same kind of change both ways on a 200,000-row table and compares the time, the per-shard path, and what each leaves behind.
What you will build
online_ddl_create(..., options = NULL) -> data shards: copy to shadow table, cutover
online_ddl_create(..., options = '{"apply_direct": true}') -> every shard: run the ALTER TABLE directly
online_ddl_status(...).status_by_shard.<shard>.direct_apply -> false / true per shard
AI Prompt
Using the PlanetScale CLI (pscale 0.344.0) and psql, run a schema change on a sharded Neki table as an online DDL workflow on the direct path instead of the copy path.
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.
- Call __neki.online_ddl_create(workflow, database, ddl, migration_id, options). Pass '{"apply_direct": true}' as the fifth argument to force the direct path. Double single quotes inside the DDL string, and pass '' as migration_id to have one generated.
- Read online_ddl_status(workflow).status_by_shard: each shard reports direct_apply, current_readiness, ddl_status and controller_state. Complete only when every shard has current_readiness true.
- Complete with __neki.workflow_complete(workflow). Run __neki.online_ddl_cleanup(workflow) after a copy-path workflow to drop the retained original tables.
- Force the direct path only for changes Postgres applies without rewriting the table. A forced rewrite holds a lock on each shard for as long as the rewrite takes.
- 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 shipping --engine neki --org "$PLANETSCALE_ORG" \
--region us-east --cluster-size PS-10-AWS-ARM-NEKI --replicas 2 --wait
pscale role create shipping 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 shipping 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 integer 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": "orders_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": "orders_by_customer" }
} } } } },
"default_shard_group": "$SHARD_1",
"authoritative_shard_group": "$SHARD_1"
}
JSON
pscale branch data-topology update shipping 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 shipping --force --org "$PLANETSCALE_ORG".
1. Write a helper that runs a workflow to completion
cat > run-ddl.sh <<'EOF'
#!/bin/bash
# usage: run-ddl.sh <workflow> <ddl> [options-json]
if [ -n "$3" ]; then opts="'$3'"; else opts="NULL"; fi
t0=$(date +%s)
psql -At -c "SELECT workflow FROM __neki.online_ddl_create('$1', 'postgres', '$2', '', $opts)" > /dev/null
until [ "$(psql -At -c "SELECT bool_and((e.value->>'current_readiness')::boolean) FROM __neki.online_ddl_status('$1'), jsonb_each(status_by_shard) e")" = "t" ]; do sleep 3; done
t1=$(date +%s)
psql -At -c "SELECT e.key || ' direct_apply=' || (e.value->>'direct_apply') FROM __neki.online_ddl_status('$1'), jsonb_each(status_by_shard) e ORDER BY 1"
psql -At -c "SELECT * FROM __neki.workflow_complete('$1')" > /dev/null
t2=$(date +%s)
echo "$1: ready after $((t1 - t0)) s, complete took $((t2 - t1)) s, status $(psql -At -c "SELECT status FROM __neki.online_ddl_status('$1')")"
EOF
chmod +x run-ddl.sh
cat > shadow.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 "$n: "
psql -At -c "SET __neki.shard='$u';" -c "SELECT coalesce(string_agg(relname, ','), '(none)') FROM pg_class WHERE relname LIKE '\_\_neki\_\_%shdw%'" | tail -1
done
EOF
chmod +x shadow.sh
psql -At -c "SELECT name || ' ' || uid FROM __neki.list_shards() ORDER BY name"
Real output (shard ids differ per database):
sh1 shz3zkjnermle8
sh2 shpauxal9j063l
sh3 shlanihte9i2l3
2. Add a column on the default path
./run-ddl.sh add_gift_copy "ALTER TABLE public.orders ADD COLUMN gift boolean"
./shadow.sh
Real output:
shlanihte9i2l3 direct_apply=false
shpauxal9j063l direct_apply=false
shz3zkjnermle8 direct_apply=true
add_gift_copy: ready after 9 s, complete took 3 s, status completed
sh1: (none)
sh2: __neki__03h4v5bfs1pz5727uo2rqawg1_000000_shdw_20261028215502_
sh3: __neki__03h4v5bfs1pz5727uo2rqawg1_000000_shdw_20261028215502_
The two data shards (sh2 and sh3) report direct_apply=false: they copied all of their rows into a shadow table, then cut over. The authoritative shard, which holds no rows of this table, applied the change directly. Each data shard still has the original table, kept under the shadow name, until cleanup removes it:
psql -At -c "SELECT * FROM __neki.online_ddl_cleanup('add_gift_copy')"
./shadow.sh
Real output:
add_gift_copy
sh1: (none)
sh2: (none)
sh3: (none)
3. Add a column on the direct path
./run-ddl.sh add_note_direct "ALTER TABLE public.orders ADD COLUMN gift_note text" '{"apply_direct": true}'
./shadow.sh
Real output:
shlanihte9i2l3 direct_apply=true
shpauxal9j063l direct_apply=true
shz3zkjnermle8 direct_apply=true
add_note_direct: ready after 1 s, complete took 2 s, status completed
sh1: (none)
sh2: (none)
sh3: (none)
Every shard reports direct_apply=true, the workflow was ready after 1 second instead of 9, and no shadow table was created, so there is nothing to clean up.
Verify the result
psql -At -c "SELECT string_agg(attname, ',' ORDER BY attnum) FROM pg_attribute WHERE attrelid = 'orders'::regclass AND attnum > 0 AND NOT attisdropped"
psql -At -c "SELECT bool_and((e.value->>'direct_apply')::boolean) FROM __neki.online_ddl_status('add_note_direct'), jsonb_each(status_by_shard) e"
./shadow.sh
Expected: customer_id,order_id,total_cents,gift,gift_note, then t, then (none) on every shard.
How it works
On the copy path, each data shard builds a shadow table with the new definition, copies its rows into it, streams later writes into it, and swaps it in at cutover; the original table is retained until online_ddl_cleanup. On the direct path, the workflow runs the ALTER TABLE itself on each shard, so it takes whatever lock that statement takes in Postgres, for as long as Postgres needs it. Adding a nullable column without a default changes only the catalog, so the direct path finishes in moments; a change that rewrites rows, such as most column type changes, holds its lock for the whole rewrite. The workflow functions are described on the Neki schema changes page.
Common issues
Forcing a rewrite onto the direct path
In testing, a type change forced onto the direct path on a 2,000,000-row table (about a million rows per data shard) delayed a concurrent insert by up to 2.3 seconds, while it was 0.86 seconds on 200,000 rows. The delay grows with the number of rows per shard. Leave rewriting changes on the copy path.
applyDirect and apply_direct
The schema changes page spells the option applyDirect, while __neki.list_metafuncs() lists apply_direct. In testing both spellings set direct_apply to true on every shard.
A completed workflow can be completed again
After workflow_complete, online_ddl_status still returns the workflow with status completed, and a second workflow_complete call returned without an error.
Single quotes in the DDL
The DDL is a string argument, so a literal such as a default value needs doubled quotes: 'ALTER TABLE public.orders ADD COLUMN state text DEFAULT ''new'''.
Next steps
- Delete the database with
pscale database delete shipping --force --org "$PLANETSCALE_ORG". - Read the Neki schema changes guide for which statements use each path by default.
verification:
status: verified
tested_at: "2026-10-28"
product_version: "pscale 0.344.0, Neki PostgreSQL 18.6 (Platform Preview)"
command: "online_ddl_status('add_note_direct') direct_apply on every shard; shadow tables per shard"
expected_result: "Both columns exist, direct_apply is true on every shard, and no shadow table remains on any shard."