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/schema-changes.ko.md

View on GitHub
# 스키마 변경

데이터를 담은 테이블, 컬렉션, 키 공간에 DDL, 마이그레이션, 백필, 인덱스 빌드를 작성하거나 승인하기 전에 이 규칙을 사용합니다. 엔진 중립이며, 각 문장이 잡는 잠금이나 알고리즘은 엔진 가이드가 밝힙니다. 발견 사항은 아래 `SC-*` ID를 인용합니다.

## 1. 원칙

| ID | Severity | Rule |
|---|---|---|
| SC-01 | critical | 지금 도는 애플리케이션 버전을 깨는 변경을 배포하지 않습니다. 배포 구간 동안 옛 코드와 새 코드가 모두 동작해야 합니다. 먼저 확장하고, 데이터를 마이그레이션하고, 코드를 전환하고, 마지막에 축소합니다(병행 변경). |
| SC-02 | high | 마이그레이션 하나는 한 종류의 일만 합니다. 스키마 변경, 데이터 백필, 인덱스 빌드를 한 트랜잭션이나 한 파일에 섞지 않습니다. |
| SC-03 | high | 바쁜 테이블의 모든 DDL은 짧은 잠금 대기 시간 제한(`lock_timeout`, `lock_wait_timeout`, 엔진의 동등 설정)과 문장 시간 제한을 설정해, 긴 트랜잭션 뒤에 줄 서서 그 뒤의 모든 쿼리를 막는 대신 빨리 실패하고 재시도하게 합니다. |
| SC-04 | high | 백필은 기본 키 범위로 제한된 배치로 실행하고, 배치마다 커밋하며, 배치 사이에 쉬거나 스로틀하고, 멱등이며 재개 가능하게 합니다. 테이블 전체에 `UPDATE` 하나를 쓰지 않습니다. |
| SC-05 | high | 모든 단계에 작성한 롤백이 있거나, 잃는 데이터와 함께 일방향으로 표시합니다. 컬럼, 테이블, 키 계열 삭제는 일방향입니다. 백업을 뜨거나, 다음 릴리스에서 아무도 읽지 않음을 확인할 때까지 사본을 유지합니다. |
| SC-06 | medium | ORM이 생성한 마이그레이션은 실행 전에 SQL로 검토합니다. 도구의 출력은 초안이지 결정이 아닙니다. |
| SC-07 | medium | 큰 테이블을 재작성하거나 스캔하는 변경은 운영과 비슷한 규모의 사본에서 예행하고 소요 시간을 기록합니다. |

## 2. 변경 분류

| Class | Examples | Default procedure |
|---|---|---|
| 추가, 메타데이터만 | 널 허용 컬럼 추가, 엔진이 메타데이터로 저장하는 상수 기본값 컬럼 추가, 테이블 추가, 뷰 생성 | 한 단계. 그래도 잠금 대기 시간 제한을 설정합니다(SC-03) |
| 추가, 스캔 동반 | 기존 데이터에 `NOT NULL`, `CHECK`, 외래 키 추가, 유일 제약 추가 | 검증 없이(`NOT VALID`) 추가하거나 무중단으로 만든 별도 유일 인덱스로 추가한 뒤 두 번째 단계에서 검증합니다 |
| 새 필수 컬럼 | `NOT NULL`이어야 하지만 상수 기본값이 없는 컬럼 추가 | 널 허용으로 추가하고(엔진이 메타데이터로 저장하면 상수 기본값과 함께), 값을 채우는 쓰기 코드를 배포하고, 기존 행을 배치로 백필(SC-04)한 뒤, 제약을 검증 없이 추가하고 검증합니다. 단계마다 마이그레이션 파일 하나, 단계마다 별도 배포입니다 |
| 인덱스 빌드 | 인덱스 생성 또는 삭제 | 엔진의 무중단 빌드(`CONCURRENTLY`, `ALGORITHM=INPLACE, LOCK=NONE`, 백그라운드 인덱스 빌드). 엔진이 금지하는 트랜잭션 안에서는 하지 않습니다 |
| 재작성 | 컬럼 타입 변경, 자주 바뀌는 기본값을 갖는 컬럼 추가, 재정렬 또는 재클러스터링 | 새 컬럼이나 테이블로 expand/contract(확장/축소): 이중 쓰기, 백필, 전환, 축소. 또는 무중단 스키마 변경 도구 |
| 이름 변경 | 컬럼 또는 테이블 이름 변경 | expand/contract(확장/축소): 새 이름 추가, 이중 쓰기 또는 뷰, 백필, 읽는 쪽 전환, 이후 릴리스에서 옛 이름 삭제 |
| 파괴적 | 컬럼, 테이블, 쿼리가 쓰는 인덱스, 키 계열 삭제 | 먼저 코드에서 읽기와 쓰기를 멈추고 배포한 뒤 한 릴리스 기다렸다가 삭제합니다. 삭제한 인덱스를 쓰는 실행 계획이 없는지 확인합니다 |
| 데이터만 | 대량 갱신, 삭제, 이동 | 드라이 런 개수 확인을 먼저 한 배치 백필(SC-04) |

## 3. Expand/Contract 템플릿

1. **확장**: 새 컬럼, 테이블, 인덱스, 키 형태를 추가합니다. 아직 아무것도 읽지 않습니다.
2. **이중 쓰기**: 애플리케이션이 옛 형태와 새 형태에 모두 씁니다(또는 트리거가 하며, 임시임을 문서화합니다).
3. **백필**: 기존 데이터를 배치로 복사하고(SC-04), 개수와 체크섬 또는 표본 비교로 검증합니다.
4. **읽기 전환**: 플래그 뒤에서 새 형태로 읽습니다. 오류와 지연 시간을 지켜봅니다.
5. **옛 쓰기 중단**: 옛 형태로의 쓰기를 제거합니다.
6. **축소**: 읽기가 없는 릴리스 주기 하나를 지난 뒤 옛 형태를 삭제하고, 데이터를 재현할 수 없으면 백업을 둡니다.

각 단계는 별도 배포입니다. 1, 2, 4단계는 코드로 되돌릴 수 있고, 5, 6단계는 돌아올 수 없는 지점이며 보고서에 명시합니다.

## 4. NoSQL과 키-값 변경

| ID | Severity | Rule |
|---|---|---|
| SC-20 | high | 스키마가 없는 저장소도 코드에는 스키마가 있습니다. 문서나 항목에 버전을 붙이고(`schemaVersion`), 백필이 끝날 때까지 읽는 쪽이 두 버전을 모두 받아들이게 합니다. |
| SC-21 | high | 파티션, 샤드, 해시 키를 바꾸면 새 테이블이나 컬렉션과 모든 항목의 마이그레이션이 필요합니다. 이중 쓰기를 동반한 expand/contract(확장/축소)로 계획합니다. |
| SC-22 | medium | Redis나 Valkey 키 형식을 바꾸면 새 키에 쓰고, TTL 구간 동안 새 키를 먼저 읽고 옛 키를 나중에 읽으며, 옛 키는 만료되게 합니다. 운영 시간에 스캔으로 키 이름을 제자리에서 바꾸지 않습니다. |
| SC-23 | medium | 큰 컬렉션에 DynamoDB GSI나 MongoDB 인덱스를 추가하면 백그라운드로 백필하며 용량을 소모합니다. 일정을 잡고 스로틀링이나 복제 지연을 지켜봅니다. |

## 5. 리뷰 체크리스트

[rules/validation.md](validation.md) §3을 사용합니다. 그곳의 모든 줄에 답하기 전에는 변경이 안전하지 않습니다.

## Sources

> Checked 2026-11-07.

| Claim | Source |
|---|---|
| 병행 변경(확장, 마이그레이션, 축소) | <https://martinfowler.com/bliki/ParallelChange.html> |
| 진화적 데이터베이스 설계와 코드로서의 마이그레이션 | <https://martinfowler.com/articles/evodb.html> |
| `lock_timeout`은 제한보다 오래 잠금을 기다리는 문장을 중단함 | <https://www.postgresql.org/docs/current/runtime-config-client.html> |
| `CREATE INDEX CONCURRENTLY`는 쓰기를 막지 않고 빌드하며 트랜잭션 블록 안에서는 실행할 수 없음 | <https://www.postgresql.org/docs/current/sql-createindex.html> |
| MySQL 무중단 DDL 알고리즘과 잠금 절 | <https://dev.mysql.com/doc/refman/8.4/en/innodb-online-ddl-operations.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: 193kUpdated Claude CodeCodexVerifiedInstall