Join us Nov 24 to watch Insights Agent turn slow queries into PRs. RSVP
Navigation

Reference


Handle Router Not-Implemented Errors with Neki Error Codes and Hints

This guide handles the errors that the Neki router returns for statement shapes it does not implement yet. These errors carry SQLSTATE NK013 and a numeric code in square brackets, and the published Neki error codes page says what each code means and what to do instead. The guide writes a small wrapper that recognizes the code in an error, tells a not-implemented error apart from other failures, and shows the HINT when there is one. →


How to Set a Custom Backup Schedule with Longer Retention in Neki

Create a Neki backup policy through the PlanetScale API that runs daily at 02:00 UTC and retains backups for one year, then verify the policy exists and clean up. →


Import an Existing Postgres Database into Neki with the PlanetScale CLI

This guide moves a Postgres database into a new, unsharded PlanetScale Neki database with pg_dump and pg_restore, then checks the result with row counts and content checksums. The import is offline: source writes stay stopped from the start of the dump until cutover. →


Isolate a Large Tenant on Its Own Neki Shard with the PlanetScale CLI

This guide uses a range shard index on tenant_id to place one large tenant on a dedicated Neki shard while every other tenant shares a second shard, then moves the dedicated shard to a larger configuration profile while reads continue. The range key bounds are hexadecimal, which determines where the boundaries go. →


Keep a Direct-Message Conversation on One Shard in a Neki Social App

This guide shards conversations and their messages by conversation_id on Neki, so reading a thread and sending a message each run on one shard. A second table sharded by user_id holds each user's inbox, so listing a user's conversations is also a single-shard query. →


Keep a Multi-Tenant Audit Log Sharded by Tenant with a Retention Job on Neki

This guide shards an audit log by tenant_id on Neki and runs a retention job that deletes each tenant's expired rows with one single-shard DELETE at a time. Every tenant can have its own retention window, and the job can be re-run safely. →


Keep a Player's Wallet and Inventory in One Transaction on a Neki Game Backend

This guide keeps a player's wallet, inventory and purchase history on one shard of Neki, so a purchase is one ordinary single-shard Postgres transaction. Setting __neki.tx_mode=single makes the router reject any transaction that would touch a second shard. →


Keep Foreign-Key Related Tables on the Same Shard Group on Neki

When a parent table and its child tables share a Neki shard group and the same shard key, every child row lives on the same shard as its parent. This guide places customers, orders and order_items together, carries customer_id into each child's primary key, adds foreign keys that each shard enforces locally, and compares the join plans with a child table placed by a different key. →


Keep Ledger Transactions on One Neki Shard with the PlanetScale CLI

This guide shards a payments ledger by account_id on Neki and uses the __neki.tx_mode and __neki.fanout session settings so that a transaction touching a second shard, or a query that scatters across every shard, fails instead of running. A cross-account transfer is then written as two single-shard transactions linked by a transfer_id. →


Keep Neki Replica Reads in the Same Availability Zone as the Router

Route Neki read queries to replicas and require the chosen replica to live in the same availability zone (cell) as the router, cutting cross-zone latency. →


Keep updated_at Current on a Neki Distributed Table with a Trigger

Use standard Postgres DDL through the Neki router to add an updated_at column, create a BEFORE UPDATE trigger function, and attach the trigger to a table in a Neki shard group. The router sends the DDL to every shard, and the trigger fires on the shard that holds the row. →


Move Cold Archive Data to a Separate Shard Group on Cheaper Hardware on Neki

A Neki database can run shards from more than one configuration profile, and each profile sets its own cluster size and replica count. This guide adds an archive profile with a single-node PS-10 shard, binds an orders_archive table to a shard group on that shard, moves orders older than a cutoff out of the hot table in verified batches, and reads both tiers with single-shard queries. →


Move Selected Tables to Another Logical Database on Neki While the Application Stays Online with the PlanetScale CLI

This guide moves two sharded tables, orders and payments, from the postgres logical database to a new billing logical database on the same Neki database with a MoveTables workflow, while a writer keeps inserting. A third table, sessions, stays where it is. Switching traffic does not redirect queries to the new database: the source tables become blocked, and the application has to reconnect to billing. This guide measures that window. →


Paginate and Sort Results Across Neki Shards Without Scanning Every Shard

On a sharded Neki table, how you paginate decides how much work each page costs. This guide compares three patterns on a 5,000-row orders table using the router's own counters: keyset pagination within one customer, which touches one shard; OFFSET pagination across all customers, which makes every shard return every row up to the page; and keyset pagination across all customers, which makes each shard return at most one page. →


Predict Identity Gaps and Set the Sequence Cache Size on Neki with the PlanetScale CLI

On a Neki database, identity and sequence values come from routers, and each router reserves a block of values at a time. This guide measures the block size, shows how CACHE changes it, and predicts the gap a router restart leaves by comparing the sequence's last_value with the number of values actually used. →


Prevent Terraform from Destroying a Neki Database Branch

Use deletion_protected on the planetscale_neki_branch resource and verify the server-side block with a TypeScript probe. →


Rank Neki Queries by CPU Time and IO Time Before Upsizing

Use the PlanetScale Query Insights API to list the top Neki query fingerprints by CPU time and IO time, then merge them into a single prioritized list of queries to optimize before you increase cluster size. →


Rank Your Neki Tables by Read Cost, Rows-Read Ratio, and Index Usage

Use the PlanetScale Query Insights API to pull query-level stats for a Neki branch, then aggregate them by table to surface which tables dominate load, how many rows are read per row returned, and which indexes are used. The underlying signals come from the PlanetScale Query Insights docs; the broader Neki monitoring guide covers where each metric lives. →


Reserve Flash-Sale Inventory Without Overselling Hot Rows on Neki

This guide reserves limited stock for a flash sale on Neki with one conditional UPDATE ... WHERE stock > 0 RETURNING, so stock never goes below zero however many buyers arrive together. It then splits one product's stock across several rows that land on different shards, so a single hot row is not the only place buyers queue. →


Reshard a Live Table onto New Neki Shards with the PlanetScale CLI

This guide splits an existing, populated orders table across two new Neki shards while a writer keeps inserting rows, using a Reshard workflow driven from SQL on the Neki router. The workflow copies the rows, streams new writes, and moves traffic to the new shards in a cutover whose switch call took about three seconds. →


Restore a Backup into a Development Branch to Rehearse a Topology Change on Neki with the PlanetScale CLI

This guide restores a backup of a Neki database into a small branch, applies a proposed data topology change there, and checks whether the router still finds every row. On this data, the proposed change sent 12 of 50 customers' queries to the wrong shard without an error, and the production branch was never touched. →


Retire a Column in Two Steps on a Live Neki Table

This guide removes a NOT NULL column from a live sharded table on Neki without breaking either version of the application. Step one relaxes the column so the new application version can stop writing it; step two drops it once nothing reads it. Both steps are native DDL through the router, followed by a wait until every router has the change. →


Roll Up Daily Usage per Tenant in Neki with Co-Located Writes

Co-locate a usage_events table and a daily_usage summary table on tenant_id in a Neki data topology, then run an INSERT ... SELECT rollup and use EXPLAIN (NEKI_PLAN) to verify that every tenant's summary write routes to exactly one shard. →


Route Read-Only Queries to Neki Replicas from a TypeScript API

Build a TypeScript/Express API that writes to a Neki primary and reads from Neki replicas by setting __neki.target=REPLICA on the replica connection pool. →


Run a Debugging Query Against One Specific Neki Shard

The __neki.shard session setting sends every statement on a Neki connection straight to one shard, bypassing the router's planner. This guide uses it to count rows per shard, find which shard holds a key, read a shard's replica, and guard the session against writes, because a write on a pinned session skips routing and can put a row where the router will never look for it. →