Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-database

hyper-database

Verified

[Hyper] Use this skill when the user asks for database work - designing a data model or schema, reviewing or writing migrations, tuning slow queries and indexes, choosing an engine, or DBA operations such as backup and restore, replication and failover, connection pooling, security, upgrades, and monitoring - on PostgreSQL, MySQL or MariaDB, SQLite, Redis, Valkey, MongoDB, DynamoDB, Cassandra or ScyllaDB, or distributed and serverless SQL. It detects the engines from repository files, applies the matching engine guide bundled in this skill, and saves a report under `.hyper/database/[slug]/`. Do not use it for application code that changes no schema, query, index, or database setting.

rules/data-modeling.ko.md

View on GitHub
# 데이터 모델링

design, review, choose 모드에서, 그리고 키, 제약, 테넌시, 저장소 간 일관성 질문이 나올 때마다 이 규칙을 사용합니다. 엔진 중립이며, 각 엔진 가이드가 그 엔진의 타입, 한도, 문법을 더합니다. 발견 사항은 아래 `DM-*` ID를 인용합니다.

## 1. 방법

다음 순서로 작업하고 각 단계의 결과를 보고서에 씁니다.

1. **접근 패턴 표.** 모든 읽기와 쓰기를 적습니다. 누가 호출하는지, 필터, 정렬, 페이지 크기, 빈도, 지연 시간 목표입니다. 이 표가 없는 설계는 추측입니다(DM-01).
2. **엔티티와 불변 조건.** 엔티티마다 식별자, 다른 엔티티와의 기수, 절대 깨지면 안 되는 규칙(테넌트별 이메일 유일, 활성 구독 하나, 잔액은 음수가 되지 않음)을 적습니다.
3. **엔진 적합성.** 엔진을 확정하기 전에 표를 §7과 대조합니다. 하드 요구 사항이 실패하지 않는 한 기존 엔진을 유지합니다.
4. **논리 모델.** 먼저 제3정규형(또는 BCNF)으로 정규화하고, 그 뒤 이를 필요로 하는 명시된 접근 패턴에만 비정규화하며, 어느 사본이 원본인지 적습니다(DM-02).
5. **물리 모델.** 타입, 키, 제약, 인덱스, 파티셔닝 또는 키 배치, 보존, 1년 뒤 각 테이블 또는 키 계열의 예상 크기입니다.
6. **운영 영향.** 백업 크기, 복구 시간, 핫스팟 위험, 새 구조마다 필요한 모니터링입니다(`rules/operations.md`).

키-값, 문서, 와이드 컬럼 엔진에서는 4~5단계가 뒤집힙니다. 접근 패턴 표가 곧 모델입니다. 한 요청이 한 접근 패턴에 필요한 것만 읽도록 각 항목, 문서, 파티션을 구성합니다(DM-03).

리뷰에서 표시할 정규화 냄새입니다(DM-04). 한 컬럼에 쉼표로 나열한 ID 목록이나 외래 키 JSON 배열, 번호 붙은 컬럼(`phone1`, `phone2`), 복합 키의 일부에 의존하는 비키 컬럼, 사본을 쓰는 주체를 밝히지 않은 채 두 테이블에 중복 저장한 같은 사실입니다.

## 2. 식별자

| ID | Severity | Rule |
|---|---|---|
| DM-10 | high | 모든 테이블 또는 컬렉션은 절대 바뀌지 않는 기본 키를 갖습니다. 자연 키가 바뀔 수 있으면(이메일, 전화번호, 이름) 대리 키를 쓰고, 자연 키는 별도 유일 제약으로 강제합니다. |
| DM-11 | medium | 내부용이고 쓰는 주체가 하나이며 쓰기가 많은 테이블에는 64비트 정수 식별자를 권장합니다. 8바이트, 정렬된 삽입, 작은 보조 인덱스입니다. |
| DM-12 | medium | ID를 클라이언트나 여러 쓰는 주체가 생성하거나, 시스템 간에 병합하거나, URL에 노출하면 무작위 UUIDv4보다 시간 순서 UUID(UUIDv7, RFC 9562)를 권장합니다. 무작위 v4 키는 B-tree 삽입을 흩뜨려 인덱스 크기와 쓰기 I/O를 키우고, v7은 삽입을 오른쪽 가장자리 근처에 유지합니다. |
| DM-13 | medium | 순차 정수가 열거로 비즈니스 데이터를 흘리거나 스크레이핑을 가능하게 하는 자리에는 노출하지 않습니다. 내부 키 옆에 UUID 또는 불투명한 공개 ID를 노출합니다. 이는 정보 은닉일 뿐이며, ID는 인가 수단이 아니므로 모든 접근을 여전히 검사합니다. UUIDv7은 밀리초 타임스탬프를 담으므로 생성 시점이 민감한 곳에는 쓰지 않습니다. |
| DM-14 | high | 분산 또는 파티션 저장소에서 단조 증가 키(타임스탬프, 시퀀스, *파티션* 키로서의 UUIDv7)는 쓰기를 한 샤드나 파티션에 몰아넣습니다. 해시된 카디널리티 높은 파티션 키를 쓰고 시간은 정렬 키나 클러스터링 키에 둡니다. |
| DM-15 | medium | UUID를 36자 텍스트가 아니라 네이티브 16바이트 타입(`uuid`, `BINARY(16)`)으로 저장합니다. |

## 3. 무결성

| ID | Severity | Rule |
|---|---|---|
| DM-20 | high | 엔진이 할 수 있으면 모든 불변 조건을 데이터베이스에서 강제합니다. `NOT NULL`, `UNIQUE`, `CHECK`, 외래 키, 배타 제약입니다. 애플리케이션 검사는 동시성 아래에서 경쟁합니다. |
| DM-21 | high | 상태에 의존하는 유일 규칙(사용자당 활성 행 하나)은 애플리케이션 검사가 아니라 부분 또는 필터된 유일 인덱스가 필요합니다. `UNIQUE`는 기본적으로 `NULL`을 서로 다른 값으로 보고, `CHECK`는 식이 `NULL`이면 통과한다는 점을 기억합니다. 그게 문제되는 곳에는 `NOT NULL`이나 `NULLS NOT DISTINCT`를 더합니다. |
| DM-22 | medium | 인덱스를 만들지 않는 엔진(PostgreSQL)에서 외래 키는 참조하는 컬럼에 인덱스가 필요합니다. 없으면 부모 삭제가 자식을 스캔합니다. |
| DM-23 | medium | 외래 키를 강제하지 않는 곳(대부분의 샤딩된 MySQL 구성, NoSQL)에서는 누가 참조를 보장하는지, 고아를 어떻게 찾고 정리하는지 밝힙니다. |
| DM-24 | high | 금액은 정확한 타입입니다. 고정 스케일의 `numeric`/`DECIMAL`, 또는 통화를 옆에 둔 최소 단위 정수입니다. 절대 이진 부동소수점을 쓰지 않습니다. |
| DM-25 | high | 시점은 시간대를 아는 타입(`timestamptz`)의 UTC로 저장하거나, 관례를 문서화한 채 UTC로 저장합니다. 현지 시간이 중요하면 사용자의 시간대 이름을 따로 저장합니다. |
| DM-26 | medium | 늘어나거나 속성을 갖는 값에는 조회 테이블이나 `CHECK` 목록을 씁니다. 네이티브 enum은 작고 안정적이며 변경을 마이그레이션으로 배포할 수 있는 집합에만 허용합니다. |
| DM-27 | medium | 소프트 삭제(`deleted_at`)는 기본값이 아니라 비용이 따르는 결정입니다. 유일 제약, 집계, 페이지네이션을 깨고, 삭제 요청과 충돌하며, 테이블을 키웁니다. 부분 유일 인덱스와 뷰 또는 기본 범위를 함께 쓸 때만 쓰거나, 삭제한 행을 아카이브 테이블로 옮깁니다. |
| DM-28 | medium | JSON 컬럼은 통째로 읽는 선택적이고 희소하거나 스키마가 없는 속성에 적합합니다. 필터, 조인, 제약, 잦은 갱신의 대상이 되는 필드는 실제 컬럼이 됩니다. |
| DM-29 | low | 일관되게 이름 짓습니다. 대소문자 스타일 하나, 단수 또는 복수를 한 번 정해 유지, 참조에는 `<entity>_id`, 해당하는 모든 곳에 `created_at`/`updated_at`입니다. |

## 4. 트랜잭션과 동시성

| ID | Severity | Rule |
|---|---|---|
| DM-30 | high | 여러 문장을 쓰는 쓰기마다 필요한 격리 수준과 그것이 막는 이상 현상(갱신 손실, 쓰기 왜곡, 팬텀)을 밝힙니다. 기본 `READ COMMITTED`는 쓰기 왜곡을 막지 못합니다. |
| DM-31 | high | 경쟁이 있는 행의 읽기-수정-쓰기는 `SELECT ... FOR UPDATE`, 원자적 `UPDATE ... SET x = x + 1`, 조건부 갱신을 쓰는 버전 컬럼 중 하나를 씁니다. 읽고, 앱에서 계산하고, 보호 없이 다시 쓰지 않습니다. |
| DM-32 | high | 외부에서 재시도되는 모든 쓰기(결제, 웹훅, 큐 소비자)는 유일 제약을 건 멱등 키를 가집니다. |
| DM-33 | high | 데이터베이스 트랜잭션 안에서 외부 서비스를 호출하지 않고, 트랜잭션을 짧게 유지합니다. 쓰기와 함께 이벤트를 발행하려면 릴레이가 읽는 트랜잭션 아웃박스 테이블을 씁니다. |
| DM-34 | medium | `SERIALIZABLE`에서, 또는 충돌 시 중단하는 엔진(CockroachDB, 낙관적 저장소)에서 도는 코드는 직렬화 실패 시 제한된 백오프로 트랜잭션 전체를 재시도합니다. |
| DM-35 | medium | 교착을 피하려고 코드 경로 전체에서 행 잠금을 일관된 순서로 잡고, 교착 오류는 한 번 재시도해 처리합니다. |

## 5. 멀티 테넌시

| Model | Use when | Costs |
|---|---|---|
| `tenant_id`를 둔 공유 테이블 | 작은 테넌트가 많고 스키마가 하나 | 모든 쿼리, 유일 제약, 인덱스가 `tenant_id`로 시작합니다. 격리는 필터나 행 수준 보안에 달립니다 |
| 테넌트별 스키마 또는 데이터베이스 | 큰 테넌트가 적고 테넌트별 복구나 거주지 요구가 있음 | 마이그레이션이 모든 테넌트로 퍼집니다. 연결과 카탈로그 오버헤드가 테넌트 수에 비례해 커집니다 |
| 테넌트별 샤딩 | 테넌트가 한 노드를 넘어섬 | 테넌트 간 쿼리가 scatter-gather가 됩니다. 재분배 계획이 필요합니다 |

| ID | Severity | Rule |
|---|---|---|
| DM-40 | critical | 공유 테이블에서 엔진이 허용하면 테넌트 격리를 애플리케이션 아래에서 강제합니다(세션 변수를 쓰는 PostgreSQL 행 수준 보안, 또는 테스트로 검증하는 필수 저장소 필터). 필터가 빠지면 데이터 유출입니다. |
| DM-41 | medium | 복합 키와 인덱스는 `tenant_id`로 시작하고, 유일 제약에 이를 포함합니다(`UNIQUE (tenant_id, email)`). |

## 6. 파생 저장소와 일관성

| ID | Severity | Rule |
|---|---|---|
| DM-50 | high | 모든 캐시, 검색 인덱스, 읽기 복제본, 비정규화 사본은 원본 저장소, 허용되는 지연(staleness) 상한, 처음부터 다시 만드는 방법을 밝힙니다. |
| DM-51 | high | cache-aside 쓰기는 원본을 먼저 갱신하고 캐시 키를 설정이 아니라 삭제합니다. 삭제하면 오래된 쓰기가 새 값 위로 경쟁하는 일을 피합니다. |
| DM-52 | medium | 복제본 읽기는 복제 지연만큼 오래된 값입니다. read-your-writes 경로는 프라이머리로 라우팅하거나 복제본이 따라잡을 때까지 기다립니다. |
| DM-53 | medium | 다른 저장소로 흘려보내는 큐나 스트림은 멱등 소비자와 데드 레터 경로가 필요합니다. 최소 한 번 전달을 기본 가정으로 둡니다. |

## 7. 엔진 선택

| Workload signal | Fits | Poor fit |
|---|---|---|
| 관계형 데이터, 임시 쿼리, 엔티티 간 트랜잭션, 같은 데이터를 다루는 리포팅 | PostgreSQL, MySQL | 키-값 저장소 |
| 임베디드, 쓰는 주체 하나, 로컬 우선, 엣지 읽기 | SQLite(엣지에서 서비스하면 libSQL, D1) | 동시 쓰는 주체가 많음 |
| 파생 데이터의 1밀리초 미만 읽기, 카운터, 속도 제한, 세션, 큐, 리더보드 | Redis, Valkey | 다시 만들 수 없는 데이터의 원본 저장소 |
| 통째로 읽고 쓰는 집계 문서, 유연한 속성, 요청당 엔티티 하나 | MongoDB | 다대다 조인과 문서 간 불변 조건 |
| 접근 패턴이 알려져 있고 규모가 크며 몰리는 트래픽, 매니지드 운영 | DynamoDB | 임시 쿼리, 알 수 없는 패턴 |
| 매우 높은 쓰기 처리량, 시간 순서 파티션, 다중 리전 active-active | Cassandra, ScyllaDB | 조인, 트랜잭션, 잦은 스키마 변경 |
| 엔티티별 최근 구간을 읽는 시계열 수집(센서, 지표, 이벤트) | 중간 수준 속도에는 TimescaleDB나 PostgreSQL 기본 파티셔닝, 매우 높은 쓰기 속도에는 시간 버킷 파티션을 둔 Cassandra/ScyllaDB, 읽기가 집계이고 삽입을 묶을 수 있으면 ClickHouse. 전용 시계열 엔진(InfluxDB, QuestDB)은 번들 가이드 밖입니다 | 오래된 지점을 행 단위로 갱신 |
| 리전 간 강한 일관성을 갖는 수평 SQL | CockroachDB, YugabyteDB, TiDB, Vitess | 작은 단일 리전 앱(운영 비용) |
| 추가가 대부분인 대량 데이터를 분석 | ClickHouse, 웨어하우스 | OLTP 지점 갱신 |

| ID | Severity | Rule |
|---|---|---|
| DM-60 | high | 접근 패턴 표의 하드 요구 사항이 관계형 엔진에서 실패하지 않는 한 관계형 엔진이 기본 원본 저장소입니다. 그 패턴을 위해 옆에 특화 저장소를 더합니다. |
| DM-61 | medium | 엔진을 하나 더 둘 때마다 그것이 맡는 접근 패턴으로 정당화하고, 백업, 모니터링, 온콜 표면의 비용을 치릅니다. 그 비용을 보고서에 씁니다. |
| DM-62 | medium | 후보마다 라이선스와 매니지드 서비스 가용성을 엔진 가이드의 날짜가 붙은 사실로 확인한 뒤 권고합니다. |

## Sources

> Checked 2026-11-07.

| Claim | Source |
|---|---|
| UUIDv7 배치와 시간 순서·정렬 가능 속성, 노출하는 타임스탬프 | <https://www.rfc-editor.org/rfc/rfc9562.html> |
| B-tree 인덱스 지역성, 컬럼 순서, 인덱스가 쓰기에 드는 비용 | <https://use-the-index-luke.com/> |
| 격리 수준과 각 수준이 허용하는 이상 현상 | <https://www.postgresql.org/docs/current/transaction-iso.html> |
| 행 수준 보안 정책 | <https://www.postgresql.org/docs/current/ddl-rowsecurity.html> |
| 트랜잭션 아웃박스 패턴 | <https://microservices.io/patterns/data/transactional-outbox.html> |
| NoSQL 저장소의 접근 패턴 우선 모델링과 파티션 키 분포 | <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-general-nosql-design.html> |
| 방법 순서, ID, 심각도 | 이 패키지가 고른 설계이며 검증된 최적값이 아님 |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall