---
name: database-design
description: >
  Design schemas, migrations, and queries or diagnose query performance using the project database and measured workload.
scope: global
---

# Database design

1. Inspect the engine/version, existing models, migration tooling, queries, expected
   volume, concurrency, and durability requirements.
2. Define keys, constraints, relationships, deletion behavior, and transaction
   boundaries. Bind values using driver parameters; validate dynamic identifiers
   separately. Keep consistency-sensitive checks and writes in one transaction.
3. Design indexes around actual filters, joins, and ordering; inspect query plans
   when optimizing. Cardinality alone does not determine whether an index helps.
4. Bound interactive list queries using product-appropriate limits. Use stable
   keyset ordering for deep pagination; exports and internal batch jobs may stream
   larger datasets. Do not impose pagination on every query.
5. Use the existing migration mechanism and plan data/backward compatibility.
   Verify affected reads, constraints, and migration behavior under
   [shared verification](../../protocols/workflow.md#verification).

## SQLite when applicable

WAL can improve concurrent reads/writes on supported local storage; it is not a
universal engine choice or a promise of a particular write rate. Choose `FULL` for
power-loss durability, or `NORMAL` only when its durability tradeoff is acceptable.
Enable foreign keys per connection, use explicit connection lifetimes, and choose
busy handling/checkpoint behavior for the workload. Consult the installed version's
[pragma documentation](https://www.sqlite.org/pragma.html) for exact semantics.