Skip to content
Skills Library
Programming · Building & coding

data-design

/data-design

Use when the user is designing a data layer or schema across PostgreSQL, MongoDB, Elasticsearch, or Typesense: data model, indexing, query patterns, consistency, or keeping several stores in sync.

Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when the user is designing a data layer or schema across PostgreSQL, MongoDB, Elasticsearch, or Typesense: data model, indexing, query patterns, consistency, or keeping several stores in sync.

Original author description

Use when the user is designing a data layer or schema across PostgreSQL, MongoDB, Elasticsearch, or Typesense: data model, indexing, query patterns, consistency, or keeping several stores in sync.

How it works

  1. Inputs (ask only if missing)
  2. Process
  3. PostgreSQL
  4. MongoDB
  5. Search stores (Elasticsearch, Typesense)
  6. Cross-store consistency
  7. Anti-patterns to flag
  8. Quality bar
  9. Workflow context
  10. Output contract
Original SKILL.md headings · 92 lines, 762 words
SKILL.md preview
---
name: data-design
description: "Use when the user is designing a data layer or schema across PostgreSQL, MongoDB, Elasticsearch, or Typesense: data model, indexing, query patterns, consistency, or keeping several stores in sync."
---

# Data design (polyglot)

> Delegation, model labels, and task tracking below use Claude Code notation. In Codex or another client, follow `../../references/cross-client.md`.

Designs the data layer for a feature: which store owns each entity, schemas, indexes, query
patterns, and cross-store consistency. Search mappings, analyzers, and relevance are `search-design`;
concrete changesets are `db-migration`; multi-deploy rollout of a schema change is `migration-plan`.

## Inputs (ask only if missing)
- Entities and relationships (or a handoff from `design-doc` or `prd`).
- Stores in use: check docker-compose services, connection config, and dependencies.
- Hot query patterns and their latency needs.
- Volume and growth estimates, with their source.
- Consistency needs: strong vs eventual, acceptable sync lag.

## Process
1. Map each entity to one home store and justify it. PostgreSQL is the source of truth unless there
   is a stated reason otherwise.
2. Design each store involved. Each store is a review lens: for one or two stores, do them inline in
   one pass. Fan out one agent per store (`opus` for PostgreSQL, `sonnet` for the others) only when
   three or more stores each need substantial design; never fan out by default.
3. Design cross-store sync and the consistency model once all store designs exist.

## PostgreSQL
- **Keys follow `db-migration`**: `id BIGINT PRIMARY KEY` holding an application-generated TSID;
  entities exposed outside the service add `public_id UUID NOT NULL UNIQUE` holding a UUIDv7. Never a
  UUID primary key, never `SERIAL` or `IDENTITY`, and the TSID never leaves the service.
- **Types**: money `NUMERIC` with scale from the currency or asset contract; instants `TIMESTAMPTZ`;
  closed enums `TEXT` plus `CHECK`.
- **Normalize by default**; denormalize only with measured query evidence.
- **Indexes** on every foreign key column and on the predicates of hot queries; composite indexes in
  leftmost-prefix order; partial indexes for filtered hot paths; GIN for JSONB containment. Check
  plans with `EXPLAIN (ANALYZE, BUFFERS)` on realistic volume for queries on large or hot tables.
- **Partitioning** only when volume evidence shows retention or scan problems (time-range for
  time-series, hash for very large tenant tables), decided before the table is large.
- **Tenant isolation** with RLS when the service relies on the database for it (see `db-migration`),
  and the tenant set per transaction with `SET LOCAL`.

## MongoDB
- **Embed** for 1:1 or 1:few data read and updated together; **reference** for 1:many, independently
  read data, or anything that could approach the 16MB document limit. No unbounded arrays.
- **JSON Schema validation** on every collection (`validationAction: "error"` in production).
- **Compound indexes** matching query shape (equality, sort, range); TTL indexes for expiring data.
- **Aggregations**: `$match` and `$project` early; heavy `$lookup` use signals a modeling problem.
- **Migrations** are idempotent scripts tracked in a migrations collection.
- **Change streams** for downstream sync, resuming from a stored resume token and handling
  `invalidate` events.
- **Money** as `Decimal128`, never double.

## Search stores (Elasticsearch, Typesense)
Here decide only what is indexed, from which source, and the acceptable lag. Mappings, analyzers,
autocomplete, facets, and relevance belong to `search-design`.

## Cross-store consistency
- **Source of truth** writes first; other stores are projections.
- **No synchronous dual writes.** Use a transactional outbox in PostgreSQL (or change streams from
  MongoDB) feeding an idempotent indexer keyed by entity ID and version.
- **Lag budget** stated per projection, monitored, and alerted.
- **Rebuild path**: every projection can be rebuilt from the source of truth, with a count or
  checksum comparison afterwards.
- **Routing**: exact lookups and transactions in PostgreSQL, full-text and faceted search in the
  search store, flexible per-tenant documents in MongoDB when the domain needs them.

## Anti-patterns to flag
- UUID or sequence primary keys, or internal IDs exposed outside the service.
- Floating-point money in any store.
- Synchronous dual writes across stores.
- Missing foreign key indexes; MongoDB collections without validation; unbounded arrays.
- Partitioning or sharding without volume evidence.

## Quality bar
- [ ] Every entity has one home store with justification.
- [ ] Schemas defined explicitly, with keys and types following house law.
- [ ] Indexes cover the stated hot queries, checked against plans on realistic data.
- [ ] Each projection has a sync path, lag budget, monitoring, and rebuild path.
- [ ] Volume projections and their source are stated where they drive partitioning or sharding.

## Workflow context
- Follows `design-doc` or `api-design`; feeds `spec-to-impl`, `migration-plan`, `verify-impl`.
- `search-design` owns search-engine internals; `db-migration` writes the changesets.

## Output contract
```yaml
produces:
  - type: data-design
    format: markdown
    path: "claudedocs/<feature>-data-design.md"
    sections: [entity_store_map, schemas, indexes, migrations, query_patterns, sync_strategy]
    handoff: "Write claudedocs/handoff-data-design-<timestamp>.yaml - suggest: spec-to-impl, migration-plan"
```

Versions

The database has no other skills named data-design.

Database snapshot: 13.11.2026 · package version e782418a954b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95postgresql-table-design
    Use this skill when designing or reviewing a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features
  • 100search-design
    Use when the user is designing search: Elasticsearch or Typesense indexes, mappings, analyzers, relevance tuning, autocomplete, faceting, full-text search, or syncing search from the source of truth.
  • 100typesense
    Typesense is an open-source, typo-tolerant search engine for instant search: sub-50ms queries, filters, facets, geo search and synonyms, self-hosted or in Typesense Cloud. Use when a user wants to run Typesense with Docker, define a collection schema, index documents, search…
  • 95database-expert
    Advanced database design and administration for PostgreSQL, MongoDB, and Redis. Use when designing schemas, optimizing queries, managing database performance, or implementing data patterns.
  • 90database-mongodb
    Apply MongoDB data-modeling, indexing, and query rules from access patterns. Use when designing schemas, choosing embed vs reference, or tuning MongoDB query behavior.
  • 100postgresql
    Design PostgreSQL-specific schemas covering best practices, data types, indexing, constraints, performance patterns, and advanced features. Use when designing or optimizing PostgreSQL databases.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.