Skip to content

About

Database conventions for spec-driven work: naming, data-model design, constraints, data protection, performance, query safety, a schema-review checklist, and engine-specific references. ORM-agnostic.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

27 Commits

Folders and files

Repository files navigation

Database Standards preset

A Spec Kit preset that bakes database conventions into the spec-driven workflow. ORM-agnostic — the rules are about SQL schema design, not a particular framework.

What it provides

It appends to core templates and one command (your existing spec-kit templates and other presets keep working):

Target What is added Purpose
speckit.constitution (command) Database + Data protection confirmation step Forces confirming the target DB (engine, version, migration tool) and the security posture (roles, RLS) before the constitution is drafted
constitution-template Database + Data protection sections Records engine / version / migration tool and the project-wide security posture
spec-template Data Requirements What data the feature needs — entities, reads/writes, retention, consistency
plan-template Database Design Naming conventions, OLTP/OLAP classification, normalization (3NF for OLTP) & denormalization trade-offs, schema changes, constraints & integrity (DB-enforced invariants, NOT NULL, FK actions, CHECK, soft delete × UNIQUE, case-insensitive uniqueness), transactions & concurrency (locking strategy, retries, outbox, idempotency, timeouts), data protection (column classification, secrets, RLS, least-privilege), external identifier exposure, SQL portability (ANSI-first, vendor-feature flagging), query safety (SQL injection — bound params, allowlisted identifiers), SQL correctness (NULL semantics, join fan-out, deterministic order, half-open ranges, upsert over check-then-insert), indexing plan (selectivity, index-friendly predicates), N+1 / query-volume plan, performance diagnosis (baseline → waits → plan → statistics → re-measure)
tasks-template Schema Review Checklist Run before merging any migration — naming, integrity, transactions & concurrency, SQL correctness, normalization, performance, portability, query safety, migration safety, data handling

It also ships engine-specific reference files, not appended to any template — the plan's "Target database" line points at the matching one so it gets read during /speckit.plan instead of bloating every project's plan with guidance for engines it doesn't use:

File Covers
references/oracle.md Bind variables & the shared pool, NUMBER/VARCHAR2 semantics, IDENTITY vs SEQUENCE, bitmap indexes, when a PL/SQL package earns its place, materialized views
references/mysql.md InnoDB vs MyISAM, utf8mb4, PK choice vs InnoDB clustering, the pre-8.0.16 CHECK gap, online DDL, gap locks, replication format
references/postgres.md text/timestamptz/numeric/identity choices, exclusion constraints, un-indexed FKs, GIN/GiST/BRIN/partial indexes, CONCURRENTLY & lock-queue-safe DDL, MVCC/vacuum & autovacuum tuning, jsonb, RLS, pooling, version gates, schemas & partitioning
references/sqlserver.md Clustered index vs PK, covering/filtered indexes, READ_COMMITTED_SNAPSHOT, system-versioned temporal tables, parameter sniffing
references/dynamodb.md NoSQL — access-pattern-first design, single-table design, partition/sort key design, GSI/LSI, item limits, ConditionExpression/TransactWriteItems, TTL, Streams. Says plainly which generic sections don't apply.
references/mongodb.md NoSQL — embed vs. reference, document validation ($jsonSchema), index design (compound/multikey/text), operator injection, multi-document transactions, TTL indexes, change streams, sharding. Says plainly which generic sections don't apply.

On any other engine (SQLite, CockroachDB, …) there's no reference file to read — the generic plan-template sections are the default, not a fallback for the engines that lack dedicated guidance.

Install

specify preset add --from https://github.com/gdakuzak/spec-kit-preset-db-standards/archive/refs/heads/main.zip

Update an already-installed copy — add only appends, so remove first (one line):

specify preset remove db-standards && specify preset add --from https://github.com/gdakuzak/spec-kit-preset-db-standards/archive/refs/heads/main.zip

Install a specific released version instead of main:

specify preset add --from https://github.com/gdakuzak/spec-kit-preset-db-standards/archive/refs/tags/v0.8.2.zip

Local development:

specify preset add --dev ./spec-kit-preset-db-standards
specify preset resolve constitution-template   # verify the section appears
specify preset remove db-standards     # when done

When to use it

  • Any project with a relational database where schema quality matters.
  • Teams that want naming, indexing, and N+1 checks to be part of planning and review rather than caught in production.

When not to use it

  • No database at all.
  • A NoSQL store with no reference file yet (see references/) — the generic templates assume a relational engine; DynamoDB and MongoDB are the covered exceptions.
  • You already have a house preset covering the same templates with replace — stacking append on top still works, but check the combined output.

Contributing

Found a gap, a wrong default, or want another engine covered? Open an issue.

License

MIT

About

Database conventions for spec-driven work: naming, data-model design, constraints, data protection, performance, query safety, a schema-review checklist, and engine-specific references. ORM-agnostic.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Contributors