# Forge Database

> Inspect schema integrity, migrations, constraints, tenancy, lifecycle, recovery, and production-safe evolution.

- Skill: `is-bo/forge-database-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add is-bo/forge-database-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/is-bo/forge-database-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: is-bo (https://skillmd.com/u/is-bo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/is-bo/forge-database-3

---


# forge-database: Database design

Engine: Hybrid — Forge + Supabase, wshobson, Google

## Purpose

Inspect schema integrity, migrations, constraints, tenancy, lifecycle, recovery, and production-safe evolution.


## Deterministic runtime composition

Before loading any provider procedure, run:

Resolve `../../runtime/cli/src/composition-entry.js` relative to this `SKILL.md`, then run:

`node "<resolved-absolute-runner-path>" database compose --workflow audit --root "<repository-root>" --dry-run --json`

Add one repeatable `--request <provider-or-source>` flag for each explicit user request. Add
`--condition <task-condition>` or `--risk-surface <surface>` only for a task fact you directly
proved; never infer one from generic wording. The command above is the default for this
audit-oriented module; for implementation use `--workflow build`, and for a fix, retest, or
release gate use `--workflow fix`, `verify`, or `ship` respectively. Read the JSON response,
keep the Forge contract at index zero, and resolve paths against the absolute `runtime_root`
reported in that response. Read `eager[].runtimePath` when entering the module. The full
`selected[]` list is availability/provenance; load only `deferred[].runtimePath` when the task
reaches that concern, in tier order. Refuse any path that escapes the root. Respect every reported
suppression and context budget. If `missing` is non-empty, stop and report the installation as
damaged; do not improvise a prose fallback. The runner and specialist content may live in a plugin
cache or global installation; never assume they are inside the audited repository.


Resolve and read `../fullstack-forge/references/shared/module-contract.md` (applicability,
execution, mutation, verification, completion) and
`../fullstack-forge/references/shared/evidence-rules.md` (statuses, standards, tools, findings via
`../fullstack-forge/references/PROTOCOL.md`) relative to this module `SKILL.md` before reporting.

Never hide failed checks or claim that an operation ran when it did not.

## Automatic activation signals

Activate when a request or direct repository evidence involves database design, when
the user explicitly names `forge-database`, or when discovery proves an applicable boundary.

- Applications with a database or durable structured store

## When not to activate

- Stateless applications proven to store no durable data

## Automated support

Relevant discovery inputs are:

- schema and migrations
- ORM metadata
- database configuration and tests

Deterministic support, bounded evidence only:

- `inspect-database-schema`

## Agent inspection procedure

1. Read the schema (migrations, ORM models, or live catalog) and verify primary keys, foreign keys, unique constraints, and nullability against the domain rules.
2. Check types for money (integer minor units or decimal), timestamps (time-zone aware), enums (evolution path), and identifiers.
3. Trace referential integrity and cascade behavior for deletion paths, including soft-deletion consistency.
4. Review the migration history for destructive operations, lock-heavy changes on large tables, and reversibility.
5. Verify tenant-scoping columns and indexes, audit fields, and database-level permissions against least privilege.

Manual inspection requirements:

- Review applied production migration state and large-table risk with operators
- Confirm restore objectives and managed-database settings

Stack-specific guidance:

- Inspect generated SQL and actual constraints, not ORM declarations alone

## Evidence to collect

Standards used as criteria:

- PostgreSQL current documentation
- OWASP Database Security Cheat Sheet

## Common production failures

- Inspect keys, types, nullability, defaults, foreign keys, uniqueness, checks, indexes, and cascade behavior
- Review migration ordering, transactional safety, locks, backfills, expand-contract compatibility, and rollback or forward-fix strategy
- Trace tenant isolation, encryption, retention, audit fields, soft deletion, and backup expectations

## Missing-control checks

Each item needs direct evidence or one reasoned status.

- Primary keys
- Foreign keys
- Unique constraints
- Check constraints
- Nullability
- Normalization
- Intentional denormalization
- Cascade behavior
- Data types
- Money representation
- Date representation
- Time zones
- Enum evolution
- Audit fields
- Soft deletion
- Tenant scoping
- Migration history
- Referential integrity
- Database permissions
- Data retention
- Large-table evolution
- Migration safety
- Rollback implications

## Commands and tools

- Run `forge database audit --json` or `fullstack-forge database audit --json` when
  an explicit audit is requested and the CLI is installed. Normal feature work does not require it.

## Safe fixes

- Add documentation and tests for existing constraints
- Create a new unapplied safe migration when lock and compatibility risk is understood

## Approval-required changes

- Editing applied migrations, dropping data, changing ownership, or rewriting architecture

## Verification

- Apply migrations to an empty and representative upgraded database
- Run integrity and rollback/forward-fix tests

## Completion contract

Follow `fullstack-forge/references/shared/completion.md` and the limitations below.

## Known limitations

- Production row counts, locks, and plans cannot be inferred