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.
What you will build
A small TypeScript/Node.js script that connects to Neki, sets up a full-text searchable articles table, demonstrates the router's rejection of a custom text-search configuration, and runs a ranked full-text search using PostgreSQL's built-in english configuration.
Connect to Neki with pg -> CREATE TABLE with generated tsvector -> CREATE INDEX USING GIN -> attempt CREATE TEXT SEARCH CONFIGURATION and capture the not-implemented error -> SELECT ... WHERE search_vector @@ plainto_tsquery('english', $1) with ts_rank -> EXPLAIN (NEKI_PLAN) to confirm routing
AI prompt
Build a TypeScript code example for Neki that demonstrates why a custom text search configuration is rejected by the router and how to replace it with PostgreSQL's built-in full-text search using the english configuration, a generated tsvector column, a GIN index, and a routed query that returns ranked results.
Prerequisites
- Node.js 22 or later
- npm
- A Neki database branch with a ready state
- A PlanetScale role that inherits pg_read_all_data, pg_write_all_data, and neki_viewer so it can run DDL and EXPLAIN (NEKI_PLAN)
- A NEKI_DATABASE_URL connection string for that role
Platform Preview's restriction against user-defined text-search configurations is documented in the platform preview limitations guide; the full-text search features used here (generated tsvector columns, GIN indexes, built-in configurations) come from the Postgres search guide, and the connection flow follows the Neki connecting guide.
Environment variables
NEKI_DATABASE_URL(secret): Neki connection string from the PlanetScale dashboard (postgres://...?sslmode=verify-full)
1. Create the project and install dependencies
Initialize a fresh Node project and install the Postgres driver, TypeScript, and tsx.
mkdir neki-text-search && cd neki-text-search
npm init -y
npm install pg
npm install -D typescript tsx @types/node @types/pg
2. Implement the searchable articles table in src/search.ts
This script creates an articles table with a generated tsvector column that uses the built-in english text-search configuration, adds a GIN index, attempts a custom text-search configuration (which the router rejects), and then runs a routed ranked search while showing the Neki query plan.
import { Client } from "pg";
const databaseUrl = process.env.NEKI_DATABASE_URL;
if (!databaseUrl) {
throw new Error("NEKI_DATABASE_URL is not set");
}
const client = new Client({ connectionString: databaseUrl });
async function main() {
await client.connect();
// Clean start for a reproducible run.
await client.query(`DROP TABLE IF EXISTS articles`);
// Build a searchable articles table using Postgres's built-in 'english'
// text-search configuration. The generated column keeps the tsvector on the
// shard, and the GIN index lets the router route matching queries to the
// shard(s) that hold the data.
await client.query(`
CREATE TABLE articles (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
body TEXT NOT NULL,
search_vector TSVECTOR
GENERATED ALWAYS AS (
to_tsvector('english', coalesce(title, '') || ' ' || coalesce(body, ''))
) STORED
)
`);
await client.query(`
CREATE INDEX articles_search_idx ON articles USING GIN (search_vector)
`);
await client.query(`
INSERT INTO articles (title, body) VALUES
('Routing full-text search in Neki', 'Neki routes Postgres full-text search queries to the right shards.'),
('Custom text search configs', 'User-defined text search configurations are rejected by the Neki router during Platform Preview.'),
('Built-in configs work', 'Use a built-in configuration such as english so the router can evaluate and route the search.')
`);
// Demonstrate the limitation: a custom text-search configuration cannot be
// created through the router.
let customConfigError: string | null = null;
try {
await client.query(`
CREATE TEXT SEARCH CONFIGURATION custom_english ( COPY = pg_catalog.english )
`);
} catch (err: any) {
customConfigError = err.message;
}
// Use the built-in 'english' configuration for the application query.
const queryText = "router search";
const searchResult = await client.query(
`
SELECT
id,
title,
ts_rank(search_vector, plainto_tsquery('english', $1)) AS rank
FROM articles
WHERE search_vector @@ plainto_tsquery('english', $1)
ORDER BY rank DESC
`,
[queryText]
);
// Show how Neki plans the search query.
const planResult = await client.query(
`EXPLAIN (NEKI_PLAN, FORMAT TEXT)
SELECT id, title
FROM articles
WHERE search_vector @@ plainto_tsquery('english', $1)
ORDER BY ts_rank(search_vector, plainto_tsquery('english', $1)) DESC`,
[queryText]
);
const output = {
customConfigError,
matchedRows: searchResult.rows.map((row) => ({
id: row.id,
title: row.title,
rank: Number(row.rank),
})),
plan: planResult.rows.map((row) => row["QUERY PLAN"]),
};
console.log(JSON.stringify(output, null, 2));
await client.end();
}
main().catch(async (err) => {
console.error(err);
try {
await client.end();
} catch {}
process.exit(1);
});
3. Run the example against your Neki branch
Set the connection string in your environment and run the script. The output shows the router rejecting a custom text-search configuration and successfully routing a built-in full-text search query.
export NEKI_DATABASE_URL="$NEKI_DATABASE_URL"
npm install && npx tsx src/search.ts
Verify the result
Run against Neki Platform Preview on 2026-11-05.
npm install && npx tsx src/search.ts
Observed output:
up to date, audited 23 packages in 419ms
found 0 vulnerabilities
{
"customConfigError": "not implemented: [302] creating a text search configuration through the router is not supported; user-created configurations can reach joining shards, but router-side text-search evaluation supports only PostgreSQL built-ins, so a user-created configuration cannot be used by a routed text-search expression",
"matchedRows": [
{
"id": 2,
"title": "Custom text search configs",
"rank": 0.0907017
},
{
"id": 3,
"title": "Built-in configs work",
"rank": 0.085297264
}
],
"plan": [
"Route [AnyShard] (cost=0.00..2000.00 rows=1000 width=36)",
" Query: SELECT id, title FROM public.articles WHERE search_vector @@ plainto_tsquery('english', $1) ORDER BY ts_rank(articles.search_vector, plainto_tsquery('english', $1)) DESC",
" ShardGroup: sh7l2kdpar5z66"
]
}
Expected: A JSON object containing the router's rejection of a custom text-search configuration, ranked search results from the built-in english configuration, and a Neki query plan that routes to a shard group.
How it works
The script stores a pre-computed tsvector in a generated column by calling to_tsvector('english', ...). Because english is a built-in PostgreSQL text-search configuration, the Neki router can evaluate the expression and push the WHERE clause down to the shards. A GIN index on the tsvector column makes the match lookup fast. The attempted CREATE TEXT SEARCH CONFIGURATION is caught by the router and rejected with code 302, proving that custom configurations cannot be used for routed text-search evaluation during Platform Preview.
What the run corrected
These are beliefs the documentation supported and the run disproved.
Assumed: A role with the postgres inherited role could create a custom text-search configuration through the Neki router. Observed: The router rejects CREATE TEXT SEARCH CONFIGURATION with not implemented: [302] and explains that router-side text-search evaluation supports only PostgreSQL built-ins. Evidence: The live run captured the exact error message from the Neki router when the script tried CREATE TEXT SEARCH CONFIGURATION custom_english (COPY = pg_catalog.english).
Assumed: A query for 'postgres router' would return rows because both words appear in the sample data. Observed: The query returned no rows because no single document contained both stemmed lexemes 'postgr' and 'router' in its tsvector. Evidence: A diagnostic SELECT showed the stored tsvectors; changing the query to 'router search' matched rows 2 and 3, which both contain the lexemes 'router' and 'search'.
Common issues
CREATE TEXT SEARCH CONFIGURATION returns not implemented: [302]
Cause: Neki's router supports only PostgreSQL built-in text-search configurations during Platform Preview; user-defined configurations cannot be used for router-side text-search evaluation.
Fix: Use a built-in configuration such as english, spanish, or french in to_tsvector, plainto_tsquery, to_tsquery, and websearch_to_tsquery.
A search returns no rows even though the words are in the text
Cause: PostgreSQL stems words to lexemes (for example, 'routing' becomes 'rout'), and a multi-word query requires every term to match the same row's stored lexemes.
Fix: Inspect the generated tsvector values, choose query words that stem to lexemes that actually co-occur, or use websearch_to_tsquery for search-box syntax.
pg warns about sslmode=require being treated as verify-full
Cause: The Node pg driver treats require as verify-full before pg 9.
Fix: Use sslmode=verify-full in your NEKI_DATABASE_URL, or supply the ssl option that matches your application's libpq-compatibility needs.
Next steps
- Replace plainto_tsquery with websearch_to_tsquery and add per-row shard-key filters so the router can narrow the search to one shard
- Try the TIN extension (CREATE EXTENSION tin and USING tin index) when you need BM25 scoring, phrase/proximity matching, or fuzzy search
- Move the DROP TABLE/CREATE TABLE DDL into a PlanetScale deploy request with a migration role instead of running it from the application
- Add input validation and query-logging so user search strings do not accidentally produce zero-token queries that match nothing
verification:
status: verified
tested_at: "2026-11-05"
product_version: "Neki Platform Preview"
command: "create an articles table with a generated tsvector column and GIN index, attempt CREATE TEXT SEARCH CONFIGURATION through the router, then run a ranked plainto_tsquery search using the built-in english configuration and EXPLAIN (NEKI_PLAN)"
expected_result: "customConfigError contains 'not implemented: [302] creating a text search configuration through the router is not supported'; matchedRows returns id=2 'Custom text search configs' (rank ~0.0907) and id=3 'Built-in configs work' (rank ~0.085); plan shows Route [AnyShard] with the parameterized plainto_tsquery query routed to a shard group"