Neki is currently in Platform Preview. Platform Preview features are “Beta Features” under the PlanetScale Terms of Service or your applicable agreement with PlanetScale. Accordingly, Neki is subject to the limitations and disclaimers applicable to Beta Features and is not covered by any service level agreement.
NK013 and a message in
this form:
NK013 means the gap is one Neki intends to close. A limit that is a design
decision rather than a missing implementation is reported as not supported
instead, and the broad ones are listed in Platform preview
limitations. For how other Neki errors use
the DETAIL and HINT fields, see Error hints and
details.
How to read an entry
Each entry gives the code, the message sentence the router renders after the bracketed code, an example that triggers it, and a note on which part of the query causes the rejection. The examples use a small sharded schema:users, orders, and products are
sharded on user_id, as is user_tags; accounts is sharded on account_id and owns global
secondary indexes on
email and phone; notes is unsharded; and tables named ref_* are
reference tables. A few
entries name another small table whose own name describes the property that
matters to that code. Where a rejection depends on how the data topology places
the tables rather than on the SQL text, the note says so — the same statement
can plan successfully with a different topology.
Codes that only an internal invariant can raise are not listed, because no
query produces them. A code absent from this page is one an application is
unlikely to meet.
A single statement can be rejected by more than one of these codes. Which one
you see is the first gap the planner reaches, so fixing one can reveal
another.
Statements, transactions, and sessions
Codes raised while the router decides what a statement is and how the session should behave.1 — SELECT INTO statements are unavailable.
INTO clause is what Neki rejects. At the top level Postgres treats SELECT ... INTO as CREATE TABLE AS; write that form instead.
20 — This statement type is unavailable.
21 — Reading an inheritance parent without ONLY is unavailable.
inheritance_parent actually has child tables. Reading the parent without ONLY would have to expand to the children, so add ONLY to read just the parent.
22 — AND CHAIN is unavailable for this transaction command.
AND CHAIN clause is the rejected part. Issue the COMMIT (or ROLLBACK, END, ABORT) and start the next transaction explicitly.
23 — This transaction command is unavailable.
24 — This transaction isolation level is unavailable.
BEGIN itself.
25 — This transaction option is unavailable.
DEFERRABLE — is not accepted in the transaction characteristics.
26 — Atomic transaction mode is unavailable.
single or multi transaction mode.
27 — This SET statement variant is unavailable.
SET variant the router does not model, rather than an unsupported target variable.
28 — SET FROM CURRENT is unavailable.
FROM CURRENT form is rejected; give the parameter an explicit value.
29 — SET TRANSACTION SNAPSHOT is unavailable.
30 — This statement cannot be analyzed with EXPLAIN neki_plan.
EXPLAIN neki_plan has no router plan to show. The statement itself may still be supported when run directly.
31 — Data-modifying CTEs cannot be analyzed with EXPLAIN neki_plan.
EXPLAIN neki_plan does not render a plan for a statement whose CTE writes.
32 — This EXPLAIN option is unavailable.
EXPLAIN option list is not supported by the router’s EXPLAIN handling.
33 — This EXPLAIN format is unavailable.
FORMAT.
Topology and evaluation context
Codes that depend on how the data topology is configured, or on the context the router is evaluating in.2 — Replication from a replica is unavailable.
__neki.target session option. Remove the option or set it to primary. This code is fatal and ends the connection.
10 — Multi-column partitioning indexes are unavailable.
user_id + tenant_id. Any statement that has to route on that index is rejected.
11 — This shard index cannot route advisory locks.
40 — COPY TO is unavailable for sharded tables.
COPY TO is rejected because users is sharded — the direction of the copy plus the table’s placement, not the syntax. COPY TO supports unsharded tables only.
41 — File COPY is unavailable for sharded tables.
COPY against a sharded table. Use COPY ... FROM STDIN for a sharded table, or an unsharded table for file COPY.
42 — COPY TO is unavailable for reference tables.
43 — File COPY is unavailable for reference tables.
COPY into a reference table. Use COPY ... FROM STDIN instead.
44 — COPY FROM cannot maintain this table’s secondary index.
COPY FROM cannot maintain. Load the table with INSERT instead.
45 — COPY does not support a multi-column primary shard index.
COPY FROM into a sharded table needs a single-column shard key to route each row; a multi-column primary shard index is rejected.
46 — COPY FROM cannot evaluate this reference-table default consistently.
47 — COPY TO PROGRAM is unavailable.
TO PROGRAM destination is rejected; it would run a command on a Postgres host.
48 — COPY from a query is unavailable.
49 — COPY of a SELECT result is unavailable.
SELECT source is what is rejected. Copy a table, or run the query and handle the rows in your application.
50 — COPY FROM with a WHERE clause is unavailable.
WHERE clause on COPY FROM is rejected. Filter the data before feeding it to COPY.
51 — COPY FROM cannot evaluate this column default on the router.
id is omitted from the column list, and its default has to be drawn on the router per row. Include the column and supply its values.
52 — This COPY option is unavailable for sharded COPY.
COPY options such as ON_ERROR, REJECT_LIMIT, and LOG_VERBOSITY are rejected. The same option is accepted for an unsharded table.
53 — This input encoding is unavailable for sharded COPY.
COPY stream is what is rejected; send UTF-8.
54 — COPY is unavailable in a multi-statement query.
COPY must be the only statement in the query. The second statement in the batch is what makes this fail.
55 — COPY is unavailable in the extended query protocol.
COPY works over the simple query protocol.
56 — COPY FROM a materialized view is unavailable.
COPY FROM to write into.
Advisory locks
Codes raised when the router cannot place an advisory lock on a single shard, or take it at all.60 — A session cannot hold session advisory locks on multiple shards.
61 — Mixing session and transaction advisory locks is unavailable.
62 — Advisory locks are unavailable in this evaluation context.
139 — Advisory locks are unavailable in this plan position.
CREATE TABLE AS — where the router cannot take the lock. Take the lock in a separate statement.
PL/pgSQL
Codes raised while translating or executing a PL/pgSQL routine on the router.80 — Composite FOREACH targets are unavailable in PL/pgSQL.
FOREACH loop variable is a composite (record) type. Loop over a scalar target.
81 — This FOREACH target type is unavailable in PL/pgSQL.
FOREACH target is one the translator cannot use as a loop variable.
82 — Nested and array-slice assignment targets are unavailable in PL/pgSQL.
83 — Non-scalar assignment targets are unavailable in PL/pgSQL.
SELECT ... INTO, or keep the value scalar.
84 — Record-field references in embedded SQL are unavailable in PL/pgSQL.
85 — Composite INTO targets are unavailable in PL/pgSQL.
INTO target is a composite variable. Select into a list of scalar variables instead.
86 — Record fields with varying runtime types are unavailable in PL/pgSQL.
87 — Function configuration parameters are unavailable for router-side execution.
SET clause attached to the routine is what blocks it: a function with configuration parameters cannot be executed on the router.
88 — Polymorphic routines are unavailable for router-side execution.
anyelement, anyarray, and similar) is what is rejected for router-side execution. Declare concrete argument types.
90 — This PL/pgSQL statement is unavailable.
91 — EXIT to a block label is unavailable in PL/pgSQL.
EXIT naming a block label. EXIT from a loop, optionally naming the loop’s label.
92 — A bare RAISE is unavailable in PL/pgSQL.
RAISE, which re-raises the current exception, has no supported meaning without exception handlers (code 89). Raise a named condition explicitly.
93 — RAISE USING is unavailable in PL/pgSQL.
USING option list on RAISE is what is rejected; the plain RAISE EXCEPTION 'bad' form is fine.
94 — RETURN NEXT without an expression requires OUT parameters.
RETURN NEXT with no expression only has a meaning for a function with OUT parameters. Give RETURN NEXT a value, or declare OUT parameters.
95 — RETURN QUERY EXECUTE is unavailable in PL/pgSQL.
EXECUTE form of RETURN QUERY builds its query string at run time, which the router cannot plan. Use RETURN QUERY with a static query.
Query shapes and routing
The largest group: codes raised while the planner turns a query into routed work. Many depend on the data topology, and the same statement can plan against an unsharded table and be rejected against a sharded one.63 — This join type is unavailable.
67 — Array-slice and multidimensional array assignment are unavailable.
69 — Subqueries in VALUES are unavailable.
VALUES cell. Compute the value in a SELECT and feed it in, or use INSERT ... SELECT.
100 — Subqueries are unavailable in this DML clause.
SET value of an UPDATE ... FROM. Move the subquery into the FROM source and reference its column.
101 — Per-row router-only expression evaluation is unavailable here.
name is a column), so the router cannot compute it before the statement is routed.
102 — This RETURNING expression extraction is unavailable.
RETURNING mixes an OLD/NEW row alias with an expression the router must evaluate itself. Return the columns and compute the router-side expression in your application.
103 — This DML source join cannot be planned safely.
USING/FROM source is not something the planner can evaluate on one side, so the join cannot be executed safely.
104 — This mutation cannot maintain active secondary indexes.
accounts owns global secondary indexes, and this mutation shape cannot keep their lookup rows in step with the rows they point at.
105 — This CTE execution shape is unavailable on the router.
b reading a, then feeding a DML FROM — is a shape the router has no execution strategy for. Flatten the CTEs into one, or materialize the intermediate result in your application.
106 — This window-function shape is unavailable across shards.
107 — Expression extraction is unavailable in this clause.
now()) appears in a clause the planner cannot lift it out of — here GROUP BY. Compute the value in your application and pass it as a parameter.
108 — This subquery shape is unavailable in ORDER BY.
ORDER BY subquery cannot be evaluated once up front because the volatile WHERE expression forces per-row router evaluation. Remove the volatile predicate, or sort in your application.
109 — This quantified-subquery shape is unavailable.
ALL cannot be rewritten into a routable form. Compare a single column.
110 — This correlated-subquery shape cannot be decorrelated safely.
GROUP BY, so decorrelating it would change which groups exist. Rewrite it as an explicit join.
111 — This lateral or range-function shape is unavailable.
LATERAL item is a VALUES list referencing the outer row, which the planner cannot turn into a routable join input. Use a LATERAL (SELECT ...), or join on the expression directly.
112 — This full outer join has no usable equality key.
113 — This cross-shard join expression cannot be assigned to one input.
114 — This secondary-index routing shape is unavailable.
115 — Multiple routing-parameter values are unavailable.
116 — This INSERT subquery shape is unavailable.
VALUES cell rather than being the whole cell. Use INSERT ... SELECT.
117 — This INSERT SELECT shape is unavailable.
INSERT ... SELECT source with ON CONFLICT DO UPDATE against a sharded target is not implemented. Insert explicit VALUES, or drop the DO UPDATE.
118 — These INSERT values cannot be materialized on the router.
VALUES cell means the router cannot know the rows — and therefore the routing values — before executing. Expand the rows in your application, or use INSERT ... SELECT.
119 — This ON CONFLICT shape is unavailable.
ON CONFLICT arbiter index (order_id) does not cover the table’s shard key (user_id), so a conflict cannot be resolved on one shard. Arbitrate on an index that includes the shard key.
120 — This column default cannot be materialized on the router.
121 — This MERGE shape is unavailable.
MERGE source is a derived table, so the planner cannot route the merge to the target’s shards. Use a MERGE whose source is a table in the same shard group.
122 — This view cannot be routed safely.
123 — This materialized view cannot be routed safely.
124 — This set-operation shape is unavailable.
INTERSECT and EXCEPT are not planned for application tables; only UNION is. This limit does not apply to statements Neki forwards unchanged.
125 — This grouping-set form is unavailable.
GROUPING SETS (or ROLLUP/CUBE) form passes validation but has no cross-shard execution: each grouping set would need its own aggregation pass. Issue the grouping levels as separate queries.
126 — TABLESAMPLE is unavailable.
TABLESAMPLE clause is rejected; a per-shard sample would not be a sample of the whole table. Sample with a WHERE predicate such as random() < 0.5.
127 — Explicit derived-table column names are unavailable.
v(x) on the derived table is the rejected part. Alias the columns inside the subquery with AS instead.
128 — WHERE CURRENT OF is unavailable for DML.
WHERE CURRENT OF identifies a row by cursor position, which the router does not track across shards. Delete or update by key.
129 — DISTINCT cannot safely evaluate this volatile record expression.
DISTINCT would have to compare a record value built from a volatile function, whose result changes per evaluation, so duplicate elimination is not well defined.
130 — This combination of select-list subqueries is unavailable.
131 — TRUNCATE RESTART IDENTITY with CASCADE is unavailable.
RESTART IDENTITY together with CASCADE is rejected because the cascade set — and so the sequences to restart — is only known per shard. Truncate the tables explicitly.
132 — TRUNCATE RESTART IDENTITY cannot include descendant tables.
TRUNCATE would reach them and their sequences. Use TRUNCATE ONLY, or truncate each table separately.
133 — This whole-row reference is ambiguous to the SQL builder.
t.* is shadowed by a column also named t, so the SQL builder cannot tell which the query means. Rename the column or the alias.
135 — Aggregates over columns of an enclosing query are unavailable.
136 — Correlated column references are unavailable in this clause.
LIMIT (or OFFSET), a clause that is evaluated once rather than per outer row. Pass the limit as a parameter.
137 — Reading a sequence or index as a relation is unavailable.
FROM is a sequence (or an index), not a table. Read a sequence with nextval/currval, or query pg_catalog for its metadata.
138 — FETCH FIRST WITH TIES is unavailable across shards.
WITH TIES needs to know every row tied at the cut-off, which no single shard can determine. Use a plain LIMIT, or rank in a subquery and filter.
140 — Set-returning functions are unavailable in router-side ORDER BY.
ORDER BY must be expanded on the router, which cannot happen while merging sorted streams from several shards. Move the expansion into the FROM clause.
141 — INSERT OVERRIDING USER VALUE is unavailable.
OVERRIDING USER VALUE clause is the rejected part. Omit it, or use OVERRIDING SYSTEM VALUE where you need to write an ALWAYS identity column.
142 — Parameterized subscripts are unavailable in INSERT targets.
INSERT target list is a parameter, so the router does not know which element is being written at plan time. Use a literal subscript, or write the whole array.
143 — OLD and NEW references are unavailable in sharded INSERT ON CONFLICT RETURNING.
OLD/NEW aliases in the RETURNING of an ON CONFLICT statement are not available. Return plain columns.
144 — Router-only expressions are unavailable in sharded INSERT ON CONFLICT RETURNING.
OLD/NEW reference. Return columns and compute the expression in your application.
145 — Updating an index column is unavailable.
user_id, which is the table’s shard index column — changing it could move the row to another shard. Delete the row and insert the new one.
146 — This volatile router-only WHERE expression is unavailable.
WHERE, so the router cannot evaluate it once and route on the result. Compute the value first and pass it in.
147 — This volatile router-only UPDATE assignment is unavailable.
149 — Window functions inside aggregates are unavailable.
150 — This ORDER BY expression is unavailable for VALUES.
ORDER BY attached to a VALUES list is an expression rather than a plain column reference. Sort in the enclosing query instead.
151 — INTERSECT and EXCEPT subqueries are unavailable.
INTERSECT (or EXCEPT). Rewrite it as a join or an IN/NOT IN predicate, or use array functions.
152 — This subquery statement type is unavailable.
SELECT. Put a data-modifying statement in a CTE instead of a scalar subquery position.
153 — ARRAY subqueries are unavailable.
ARRAY(...) subquery constructor is the rejected part. Use array_agg over a normal subquery: SELECT array_agg(user_id) FROM ....
Evaluation engine
Codes raised when the router — rather than a shard — has to compute an expression and has no implementation for it. A query that a shard can evaluate on its own is unaffected.200 — This built-in function is unavailable in the evaluation engine.
202 — This built-in type input function is unavailable in the evaluation engine.
gtsvectorin, which the evaluation engine does not implement, so the router cannot build the value. brin_bloom_summary and brin_minmax_multi_summary behave the same way.
203 — This type cast is unavailable in the evaluation engine.
210 — User-defined functions are unavailable in the evaluation engine.
211 — User-defined operators are unavailable in the evaluation engine.
212 — User-defined aggregate transition functions are unavailable in the evaluation engine.
213 — User-defined aggregate final functions are unavailable in the evaluation engine.
214 — User-defined aggregate moving transition functions are unavailable in the evaluation engine.
215 — User-defined aggregate moving inverse functions are unavailable in the evaluation engine.
216 — User-defined aggregate moving final functions are unavailable in the evaluation engine.
DDL
Codes raised by the DDL surface, mostly for objects that are local to one Postgres host and so would not reach a shard that joins the cluster later.300 — Creating an operator class is unavailable.
301 — Creating an operator family is unavailable.
302 — Creating a text search configuration is unavailable.
303 — Creating a text search dictionary is unavailable.
304 — Event triggers are unavailable.
ALTER EVENT TRIGGER is rejected the same way.
305 — Rewrite rules are unavailable.
306 — Large objects are unavailable.
pg_largeobject and are not carried to a shard that joins later. Store the data in a Neki table or in object storage.
307 — Creating a procedural language is unavailable.
308 — Creating a tablespace is unavailable.
309 — Creating an access method is unavailable.
310 — Creating a collation is unavailable.
311 — Creating a conversion is unavailable.
312 — Foreign data wrappers are unavailable.
ALTER FOREIGN DATA WRAPPER is rejected the same way.
313 — Creating a foreign server is unavailable.
314 — Foreign tables are unavailable.
315 — User mappings are unavailable.
ALTER and DROP USER MAPPING are rejected the same way.
316 — Creating a text search parser is unavailable.
317 — Creating a text search template is unavailable.
318 — Creating a transform is unavailable.
319 — Changing composite-type attributes is unavailable.
320 — Shared library loading is unavailable.
LOAD loads a shared library into one Postgres backend, and it is not carried to a later-joining shard. Install the library on every shard host before starting Neki.
321 — IMPORT FOREIGN SCHEMA is unavailable.
IMPORT FOREIGN SCHEMA creates foreign tables, which Neki does not support (code 314).
323 — Per-column statistics overrides are unavailable.
324 — Per-column foreign-table options are unavailable.
325 — This function language is unavailable.
326 — This procedure language is unavailable.
CREATE PROCEDURE.
327 — CREATE LANGUAGE with a handler is unavailable.
HANDLER clause names a host-local C function. Install the language through a supported extension instead.
328 — Renaming a domain constraint is unavailable.
ALTER DOMAIN ... RENAME TO, SET SCHEMA, and OWNER TO are supported.
329 — ALTER DOMAIN is unavailable.
330 — The IS_TEMPLATE database option is unavailable.
IS_TEMPLATE option is what is rejected; ALTER DATABASE ... IS_TEMPLATE reports the same code.
331 — Database tablespace selection is unavailable.
TABLESPACE option on a database selects host-local storage (code 308). ALTER DATABASE ... SET TABLESPACE reports the same code.
332 — This database locale is unavailable to the router.
icu or builtin locale provider.
333 — Renaming an enum label used as a sharding key is unavailable.
334 — Column storage selection is unavailable.
SET STORAGE action is the rejected part: Neki cannot preserve a column’s storage setting for a shard that joins the cluster later, so the setting would not be uniform across shards.
335 — Column compression selection is unavailable.
336 — Changing a routing column’s generated expression is unavailable.
account_id is both a generated column and the shard key. Changing or dropping its generation expression could send existing rows to another shard without moving them. The same change is allowed for a generated column that does not drive routing.
338 — Temporary tables, views and sequences are unavailable.
CREATE TEMP TABLE ... AS, CREATE TEMP VIEW, CREATE TEMP SEQUENCE, and a name qualified with pg_temp report the same code. Create a regular relation and drop it when done.

