Reference
Run ALTER TABLE Through the Router and Wait for Every Router on Neki with the PlanetScale CLI
A native ALTER TABLE sent through a Neki router runs on every shard right away, but the other routers can briefly hold the old schema. This guide adds a column, waits with __neki.wait_for_ddl until every router has applied the change, confirms it per router, and shows what a router that has not caught up looks like. →
Run an Online Schema Change Across Neki Shards with the PlanetScale CLI
This guide adds a NOT NULL DEFAULT column to a 400,000-row table that is sharded across two Neki shards, using __neki.online_ddl_create while a writer keeps inserting rows. The workflow builds a shadow table on each data-bearing shard, then a single workflow_complete call cuts over; the writer paused for about five to six seconds around cutover and lost no rows. →
Scale Neki Router Groups Under Live Traffic with the PlanetScale CLI
This guide adds a dedicated router group for checkout traffic to a Neki database, connects through it, and resizes it with pscale branch router update while one long-lived connection and a stream of new connections keep querying. It records what a router resize does to open connections and how long it takes. →
See the Per-Shard Postgres Plan Behind a Routed Query on Neki
A query sent to a Neki router has two plans: the router's plan, which decides which shards to call and how to combine their results, and the Postgres plan each shard runs. This guide shows which EXPLAIN form returns which, uses EXPLAIN (NEKI_PG_PLAN) to read every shard's plan for a scatter query, and uses those plans to find and fix a missing index. →
Send Read-Only Reports to Replicas with a Freshness Requirement on Neki
On Neki, a session that sets __neki.target = 'REPLICA' reads from each shard's replicas instead of its primary, which keeps report queries off the nodes that serve writes. This guide builds a report script that only runs on replicas when they are fresh enough: it checks replica health and lag, bumps a heartbeat on the primaries, waits until its replica session sees the new heartbeat on every shard, and reports when the replicas are not fresh in time so the job can run on the primaries instead. →
Serialize a Nightly Job Across Neki Instances with Advisory Locks
Use a Postgres session advisory lock through the Neki router to make sure only one app instance runs a singleton nightly job, even though the database is sharded across multiple Postgres servers. →
Set Neki Router Size and Replicas per Environment
Create a Neki staging branch from production, shrink its default router and data-node replica count, and compare the per-environment sizing from live PlanetScale API responses. →
Shard a Table by a UUID Tenant Id on Neki
This guide shards a multi-tenant table by a uuid tenant id on Neki. The xxhash shard index accepts uuid columns directly, so tenants spread evenly across shards, and every way of writing a given UUID literal routes to the same shard. Generated ids, from gen_random_uuid() or uuidv7(), work as the shard key on insert. →
Shard a Table by an Expression Such as a Lowercased Email on Neki
A Neki shard index can hash an expression instead of a plain column. This guide shards a users table by lower(email), so every spelling of an address lands on the same shard. That makes email lookups single-shard whatever the case, and lets a unique index on lower(email) reject case-variant duplicates across the whole table. →
Shard IoT Telemetry by Device Id and Roll Up Hourly Aggregates on Neki
This guide shards raw IoT readings and an hourly rollup table by device_id on Neki. The rollup is one INSERT ... SELECT ... GROUP BY that the router pushes to every shard, and it replaces an hour with a DELETE and INSERT in one transaction because INSERT ... SELECT ... ON CONFLICT DO UPDATE is not supported yet. →
Shard Orders and Inventory by Different Keys on Neki with the PlanetScale CLI
This guide shards an ecommerce schema on Neki with two keys: orders and order items by user_id, products and inventory by product_id, in two shard groups that share the same two shards. It then tests an idempotent order insert, a checkout transaction under tx_mode = 'single', and a join that crosses the two groups. →
Shard Patient Records by Patient Id and Scope Access on Neki
This guide shards patient records by patient_id on Neki so a patient's chart is one shard, then limits what each database role can see: a read-only reporting role, a front-desk role restricted to some columns and to one clinic's rows with row-level security, and a role that expires on its own. It covers database access scoping only. It does not make a workload compliant with HIPAA or any other regulation, which also depends on agreements, encryption, auditing and application controls outside the schema. →
Spin Up and Tear Down a Neki Database per Pull Request with the PlanetScale CLI
This guide gives each pull request its own sharded Neki database for integration tests and deletes it when the pull request closes. One script creates a database named after the pull request, adds shards, applies the schema and the data topology, writes a connection file for the test job, and tears everything down. A second command removes databases whose pull requests are no longer open, so a job that never ran its teardown does not leave a database billing. →
Spread a Hot Account's Writes with a Suffixed Distribution Key
You will spread a very hot account's writes across shards by adding a small numeric suffix, called a salt, to its distribution key, and you will keep point lookups working by querying every salt bucket and merging the results. The example uses plain PostgreSQL SQL and a small Python script, so it runs against any sharded Postgres setup, including Neki, PlanetScale's sharded Postgres platform. →
Store the Neki Data Topology in Git and Apply It from CI with the PlanetScale CLI
This guide keeps the Neki data topology as a JSON file in git and applies it with a script that a CI job can run. Shard ids differ between databases, so the file in git names shards with placeholders, and the script fills them in from the database before it compares or applies anything. The script can show what would change, apply the file, and fail the job when the live topology has drifted from git. →
Switch Reads to New Shards Before Writes on Neki with the PlanetScale CLI
This guide reshards an orders table from two Neki shards onto two new ones and moves traffic in two stages: replica reads first, then writes. __neki.workflow_switch_reads moves only non-primary reads, the ones a session sends with __neki.target = 'REPLICA'. Primary reads and all writes stay on the source until __neki.workflow_switch_writes. The guide proves which shards serve which reads by pausing the workflow's replication for a moment. →
Test Neki Cross-Shard Transactions with __neki.tx_mode
A TypeScript probe that verifies Neki's documented cross-shard transaction behavior: a default multi transaction can commit rows on two different shards, while __neki.tx_mode = 'single' rejects the same cross-shard attempt with error code NK313. →
Trace a Slow-Query Regression to Changed Patterns After a Deploy on Neki
Use the PlanetScale Query Insights API to compare Neki query patterns before and after a deploy, surfacing the fingerprints whose p99 latency or row-read ratio worsened. →
Tune a Go pgx Connection Pool for the Neki Router
This guide configures a pgxpool pool (pgx v5.7.6) for a sharded Neki table, sizes it from the pool's own wait statistics, and keeps reads working while the router group is replaced during a resize. Router replacement closes pooled connections, pgx reports the resulting unexpected EOF errors as not safe to retry, and a small retry for idempotent reads absorbs them. →
Use Built-In Full-Text Search Instead of a Custom Configuration in Neki
A TypeScript example that shows Neki rejecting a user-defined text-search configuration and how to route full-text search with PostgreSQL's built-in english configuration, a generated tsvector column, and a GIN index. →
Use Declarative Table Partitioning Inside a Sharded Neki Table with the PlanetScale CLI
A Neki table can be sharded by one column and range-partitioned by another. This guide shards an events table by tenant_id, partitions it by month on created_at, adds a new month, and retires an old one. Rows inserted through the parent always reach the right shard. The partitions themselves also need entries in the data topology, or direct queries against them go to the wrong shard. →
Use SQLAlchemy with Neki and Keep the Shard Key in Every Query
This guide connects SQLAlchemy 2.1 and psycopg 3 to a sharded Neki table and makes the router reject any query that leaves out the shard key. Two session settings, __neki.fanout and __neki.tx_mode, are passed as connection options, so every connection in the pool has them before SQLAlchemy opens a transaction. →
Write a Checkout Saga with Compensating Steps Across Neki Shards
This guide writes a checkout as a saga on Neki: a sequence of single-shard transactions, each with an undo step, instead of one transaction across shards. The checkout creates an order on the customer's shard, reserves stock on the product's shard, and charges the customer's wallet. If a step fails, or the process dies halfway, the compensating steps release the stock, refund the charge and cancel the order. Every step can be repeated safely, so a recovery job can run them again. →