PostgreSQL (self-managed)
Your own Postgres server, reached from your API. Not needed when a backend already provides one.
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
Where it may be used
Server-side only. No client application opens a database connection or holds a connection string — anything shipped to a device can be extracted from it, and that string grants full read and write access.
Queries
- Parameterised only:
WHERE id = $1. Never interpolate into SQL. - Name the columns; no
SELECT *. LIMITanything unbounded.- Index every column used in
WHERE,JOINorORDER BY, and confirm the planner uses it withEXPLAIN ANALYZE.
Connections
- One shared
Pool, never a connection per request. - Keep
maxlow on serverless and put a pooler in front — each instance opens its own pool, and the server's connection limit is shared. - Always release a client acquired from the pool, in a
finally.
Migrations
- Files in
db/migrations/, ordered, committed to git. - Backward-compatible with the deployed release. Add nullable, backfill, enforce later. Add the new column before dropping the old one.
CREATE INDEX CONCURRENTLYon live tables — a plain create takes a write lock and stalls the application.
Never
- Never disable SSL verification to make a connection work.
- Never run the application as a superuser.
- Never log a connection string or query parameters containing personal data.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: PostgreSQL conventions
globs: ["server/**", "api/**", "db/**", "**/*.sql"]
alwaysApply: false
---
# PostgreSQL
## Where it may be used
**Server-side only.** No client application opens a database connection or holds
a connection string — anything shipped to a device can be extracted from it, and
that string grants full read and write access.
## Queries
- Parameterised only: `WHERE id = $1`. Never interpolate into SQL.
- Name the columns; no `SELECT *`.
- `LIMIT` anything unbounded.
- Index every column used in `WHERE`, `JOIN` or `ORDER BY`, and confirm the
planner uses it with `EXPLAIN ANALYZE`.
## Connections
- One shared `Pool`, never a connection per request.
- Keep `max` low on serverless and put a pooler in front — each instance opens
its own pool, and the server's connection limit is shared.
- Always release a client acquired from the pool, in a `finally`.
## Migrations
- Files in `db/migrations/`, ordered, committed to git.
- **Backward-compatible with the deployed release.** Add nullable, backfill,
enforce later. Add the new column before dropping the old one.
- `CREATE INDEX CONCURRENTLY` on live tables — a plain create takes a write lock
and stalls the application.
## Never
- Never disable SSL verification to make a connection work.
- Never run the application as a superuser.
- Never log a connection string or query parameters containing personal data.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
What else this module writes
The rule is one file of several. Selecting PostgreSQL (self-managed) contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.
DATABASE_URLrequiredConnection string. Server-side only.PGSSLMODEoptionalSSL mode. Use `require` or stricter in production; never disable verification to make a connection work.PGPOOL_MAXoptionalMaximum pool size per instance. Keep low on serverless — every instance opens its own pool.Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →Rules people add alongside this one
The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.