---
description: Neon Postgres conventions + the until-we-have-migrations workflow
globs: pages/api/**/*.js,lib/database.js,scripts/**/*.js
---

# DB + schema

## Clients

Two are installed (`@vercel/postgres` + `@neondatabase/serverless`); they point at the same Neon Postgres. New code uses `@vercel/postgres` (tagged-template SQL).

```js
import { sql } from '@vercel/postgres';

const { rows } = await sql`
  SELECT id, name, set_name
  FROM cards
  WHERE game = ${game}
    AND set_code = ${setCode}
  LIMIT 50
`;
```

**Never** use `lib/database.js`'s `db.query(string, params)` API for new code — it interpolates params into a string and then calls `sql.unsafe()`, which is a SQL-injection vector. Marked for removal in `.convoys/`.

## Schema source of truth

`scripts/setup-neon-db.js` is the bootstrap DDL — idempotent (`CREATE TABLE IF NOT EXISTS`). Real schema state lives in Neon. Until a proper migration tool is adopted:

- **Adding a column**: new dated script under `scripts/migrations/YYYY-MM-DD-<slug>.js` (folder TBD; until then, top-level `scripts/add-*.js` named for the change).
- **Document** the change in `docs/SCHEMA_MAP.md`.
- **Never** edit a script that has already been run in prod.

## Tables (current)

| Table | Owner | Notes |
| --- | --- | --- |
| `users` | core | `(id, email UNIQUE, password, role, created_at, …)` |
| `cards` | core | Big — `oracle_text TEXT`, `colors JSONB`. Don't `SELECT *`. |
| `user_cards` | per-user | `(user_id, card_id, quantity, condition, is_foil)` — UNIQUE on tuple |
| `collections` | per-user | `is_public BOOLEAN`, `slug`, `tags`, `image_url`, `system_collection` |
| `collection_cards` | join | `(collection_id, card_id, quantity)` UNIQUE |
| `collection_permissions` | per-user | `(collection_id, user_id, role, status)` — `viewer\|editor\|owner` |
| `collection_activity` | log | `(collection_id, user_id, action, details JSONB, created_at)` |
| `decks` / `deck_cards` | per-user | Mirror of collections |
| `favorites` | per-user | `(user_id, card_id)` |
| `invitations` | per-collection | Pending share requests |

Full map: [`docs/SCHEMA_MAP.md`](../../docs/SCHEMA_MAP.md). Regenerate by re-reading `setup-neon-db.js` + every `add-*.js` script that's been run.

## Indexing reminders

- `cards.scryfall_id` is UNIQUE — use it for dedupe on import.
- `users.email` is UNIQUE — case-insensitive collation NOT set; lowercase before query/insert.
- `collections.slug` should be UNIQUE per user; verify with `lib/slug-utils.js::generateUniqueSlug` before insert.

## Transactions

Neon HTTP doesn't support multi-statement transactions across separate `sql` calls — each call is its own connection. For multi-table writes that need atomicity, use Neon's `sql.transaction([query1, query2])` array form OR refactor to a single SQL statement with CTEs. The current codebase has several non-atomic multi-step inserts that should be flagged.