60 lines
2.9 KiB
Text
60 lines
2.9 KiB
Text
|
---
|
||
|
|
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.
|