Reference
A Rollback-Safe Cutover: Switch Traffic While Your Source Tables Stay Online
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. →
Add a Foreign Key Constraint to a Large Sharded Table Without Blocking Writes on Neki
This guide adds a foreign key from a 2,000,000-row line_items table to customers on a sharded Neki database while a writer keeps inserting. It adds the constraint as NOT VALID, finds and fixes the rows that would fail validation, and then validates it. Both tables share a shard group and shard key, so every child row and its parent live on the same shard and each shard can check the constraint on its own. →
Allocate Ticketing Seats Without Double-Booking on Neki
This guide allocates seats on Neki with a conditional UPDATE that moves a seat from available to held in one statement, so two buyers can never hold the same seat. It also assigns any free seat with FOR UPDATE SKIP LOCKED, confirms a hold into a booking, and lets an expired hold be claimed again. →
Backfill a New Column in Batches While Serving Traffic on Neki
This guide adds a total_cents column to a 2,000,000-row line_items table on a sharded Neki database and fills it in batches of 100 customers while an application keeps inserting new rows and updating existing ones. Batching by the shard key keeps each UPDATE short, so an application update that touches a row the backfill is working on waits for one batch, not for the whole table. →
Build a Filterable, Exportable Audit Log for Administrative Actions in Postgres
After an outage, "who deleted the branch?" and "who changed that role?" are questions your database should be able to answer. You can build an audit trail of administrative actions with standard PostgreSQL features: an audit table, a trigger that records every insert, update, and delete on sensitive tables, and a pair of queries that filter by action and export the results to CSV. This walkthrough builds exactly that, and it runs on any Postgres 14+ server, including a Neki shard, because it uses nothing beyond plain SQL and psql. →
Cancel a Data Migration and Clean Up Copied Rows on Neki with the PlanetScale CLI
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. →
Change a Column Type on a Large Sharded Table Without Downtime on Neki
This guide widens a column from integer to bigint on a 2,000,000-row line_items table sharded across two Neki shards, using an online DDL workflow while a writer keeps inserting. Each data shard copies its rows into a shadow table with the new type and swaps it in at cutover. In this guide no insert failed, and one insert waited 6.3 seconds at cutover. →
Change Postgres Parameters for One Group of Shards on Neki with the PlanetScale CLI
This guide changes a Postgres parameter for one group of shards on Neki without touching the others. A configuration profile holds the settings for the shards that belong to it, so the guide puts one shard in a second profile, raises work_mem there, and reads the value back from every shard to show that only the new profile's shard changed. →
Choose Between Hash, Range, and Modulo Shard Keys for an Integer Id on Neki
Neki offers three shard index types for an integer column: xxhash, range and modulo. This guide shards the same 10,000-row table three ways and compares where rows land, where new sequential ids go, and how the router plans equality, IN and range queries. In this build all three route an equality lookup to one shard and scatter range predicates; they differ in placement. →
Complete a Cross-Shard Transfer Reliably with an Outbox Table on Neki
This guide moves money between two accounts that live on different shards of Neki without one transaction across shards. The debit and an outbox row commit together on the source shard, and a relay later applies the credit on the destination shard exactly once, using a table of applied transfer ids. →
Confirm Neki Router Plan-Cache Reuse and Detect Forced Replans
Run a TypeScript program against a live Neki database that uses EXPLAIN (NEKI_PLAN, FORMAT JSON) to show the router normalizes literals and reuses the same cached plan, then changes the data topology and shows the plan changes because Neki replans after topology invalidation. →
Connect a Java Spring Boot Service to Neki with HikariCP
This guide connects a Spring Boot 4.1 service to a sharded Neki table through its default HikariCP pool. The JDBC URL passes two router settings as startup options, so the router rejects any query without the shard key and any @Transactional method that reaches a second shard. →
Create a Neki Branch and Wait Until It Is Ready from a Script
Use the PlanetScale REST API to create a Neki database branch and poll it until state is ready and ready is true, from a TypeScript script. →
Create Extra Neki Server Groups with a Bigger Instance Size from the CLI
Use the PlanetScale CLI from a TypeScript script to add a dedicated Neki router group sized larger than the default group, then verify both groups report ready. →
Create Short-Lived Least-Privilege Roles for a Batch Job on Neki with the PlanetScale CLI
This guide gives a nightly batch job its own database role on Neki. The role has no inherited roles, so it starts with no access. The script grants it only what the job needs, gives it a time to live, and deletes it when the job ends, whether the job succeeds or fails. The guide tests what the role can and cannot do, and what happens to a session when the role is deleted. →
Delete a Shard Safely After Moving Its Data on Neki with the PlanetScale CLI
This guide consolidates a Neki shard group from two shards onto one new shard with a Reshard workflow, then deletes the two old shards with pscale branch shard delete. The CLI refuses to delete a shard that the data topology still references, but it does not check whether the shard still holds rows, so the guide checks every table on each shard before deleting it. →
Delete Stale Neki Development Branches on a Schedule
List Neki database branches with the PlanetScale API, filter non-production branches by age and name prefix, and delete the stale ones from a TypeScript CLI. →
Design an Ad Impression Table So Campaign Queries Stay Single-Shard on Neki
This guide shards an ad impression table by campaign_id on Neki, so every per-campaign report, join and spend total runs on one shard. It compares the same data sharded by impression_id, where each of those queries goes to every shard, and shows the one cost of the design: a very busy campaign makes its shard heavier than the others. →
Dry-Run a Table Move Before Creating the Workflow on Neki with the PlanetScale CLI
This guide validates a MoveTables plan on a Neki database by calling __neki.move_tables_create with {"dry_run": true}. The dry run returns a JSON preflight report with an overall ok flag and one finding per check per source shard, and it creates no workflow. The guide also shows what the report does not check, so you can add those checks yourself before creating the real workflow. →
Enforce Per-Tenant RLS on Sharded Postgres with Neki
Build a TypeScript workflow that shards tenant tables on Neki by tenant_id, applies Postgres row-level security and column-level grants, then proves that one tenant's role cannot read or write another tenant's rows. PlanetScale's shard-patient-records reference example walks the same idea for a healthcare schema; this walkthrough takes the generic tenant case and adds a scripted isolation proof. →
Erase One User's Data Across Several Shard Groups on Neki
This guide erases one user's personal data for a privacy request on Neki, where the user's rows are in several shard groups. The user's profile and sessions are sharded by user_id, the user's purchases are sharded by order_id, and a consent log is unsharded. The erasure script deletes or anonymizes the rows in each place, records a receipt, and can be run again safely. The guide then checks every shard directly to show that no row for the user is left. It covers the rows in the database. It does not cover backups, exports or logs. →
Export a Sharded Neki Table with COPY TO STDOUT for a Data Team
This guide exports a sharded table from Neki to CSV and binary files with COPY ... TO STDOUT, so a data team can load it into a warehouse. The router gathers the rows from every shard into one stream. The guide also covers the two things COPY does not do on Neki: it cannot export a query, and it cannot run on a session pinned to one shard. →
Force a Schema Change onto the Direct Path on Neki with the PlanetScale CLI
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. →
From Query Telemetry to a Verified Faster Plan: Applying an Index Recommendation End to End
You will take a slow query surfaced by production telemetry, apply the index it recommends, and prove the plan actually improved by running EXPLAIN (ANALYZE, BUFFERS) before and after the CREATE INDEX on a table seeded with 500,000 rows. Every plan shown below is real psql output captured from PostgreSQL 16.15, including the cleanup, so you can reproduce the exact same transition from a parallel Seq Scan to an Index Scan on your own database. →
Gapless Invoice Numbers on Sharded Postgres Without a Single Contended Node
Tax rules in many jurisdictions require invoice numbers to be issued with no gaps and no duplicates. Database sequences cannot guarantee that: they cache values, they skip numbers on rollback, and on a sharded platform each shard has its own sequence state. The direct answer to the question is that no distributed Postgres platform can make a native sequence gapless, because gapless allocation is inherently serialized. What you can do, and what this article builds, is a gapless invoice allocator that runs as ordinary SQL on Neki, PlanetScale's sharded Postgres platform. It uses a dedicated counter table with transactional row locking, so the serialization happens on one small row rather than on your whole database, and it works identically whether Neki routes it to one shard or many. →