Claude-skill-registry database-use

Any time database-related activity is required.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/database-use" ~/.claude/skills/majiayu000-claude-skill-registry-database-use && rm -rf "$T"

manifest: skills/data/database-use/SKILL.md

Database use instructions

Configuration & Standards

Engine: PostgreSQL only (Port: 5433).

Connection string: sourced from

.env

via

DATABASE_URL

(see

SQLALCHEMY_DATABASE_URI

DATABASE_URL

config.py

Testing DB:
- By default tests also use the live DB (see
```
pytest
```
  note below).
- Optional override:
```
TEST_DATABASE_URL
```
  (used by
```
TestingConfig
```
  in
```
config.py
```
  ).
SQLAlchemy instance: Import
```
db
```
from
```
utils_db/database.py
```
. Do NOT create a new instance in
```
app.py
```
.
Scripts location:
- Canonical database scripts/utilities live in
```
utils_db/
```
  .
- No ad-hoc “root scripts” in the repo root.
Execution safety:
- Do NOT paste multi-line SQL or Python into the terminal.
- Draft ad-hoc scripts in
```
temp/
```
  first, then promote reusable ones into
```
utils_db/
```
  .
Testing CSRF:
```
TestingConfig
```
disables CSRF (
```
WTF_CSRF_ENABLED = False
```
) specifically for tests.

Credentials

Connection credentials:
```
.env
```
.
Users' credentials:
```
.env
```
User passwords in DB are hashed. Hash is stored in the pw_hashed column.

Structure

Schema documentation:
```
.roo/docs/database_schema.md
```
SQLAlchemy model files:
```
models/models_*.py
```
(eg,
```
models/models_user.py
```
)
SQLAlchemy database instance:
```
utils_db/database.py
```

Schema tools:

Primary:
```
utils_db/schema_inspector.py
```
Supplemental:
```
utils_db/schema_compare.py
```
(writes reports to
```
temp/
```
)

Preferred Utilities

Reuse existing tools in

utils_db/

before writing new ones:

```
utils_db/user_password_utils.py
```
```
utils_db/user_management_utils.py
```
```
utils_db/media_utils.py
```

Source of Truth Hierarchy

The formal Source of Truth (SoT) hierarchy for database schema information:

PGDB (live PostgreSQL)
models_*.py (SQLAlchemy) (eg,
```
models/models_user.py
```
)
```
.roo/docs/database_schema.md
```
(generated)

When there is any doubt about a column, see PGDB. If a column is needed or a column name needs to change, always ask user for permission to make the add/change.

Schema Update Workflow

When making schema or data changes, follow this workflow in order:

Modify PGDB
- Make changes to the live database (see "Credentials" above).
- When creating a script to check or change the database:
  - Do NOT paste the script into the terminal.
  - Check
```
utils_db/
```
    for a suitable or near-suitable script first; reuse/extend if possible.
  - If it’s a true one-off, draft it in
```
temp/
```
    first.
  - If it’s reusable, create/update a
```
.py
```
    utility in
```
utils_db/
```
    .
Update models
- Update the appropriate SQLAlchemy model file(s) under
```
models/models_*.py
```
  .

Regenerate documentation

Run:

python utils_db/schema_inspector.py generate-docs

to update

.roo/docs/database_schema.md

Log changes
- Record the date and change in
```
.roo/docs/pgdb_changes.md
```
  .

Schema Inspector Utility

The

utils_db/schema_inspector.py

tool provides commands for schema management:

```
introspect
```
- Inspect live database schema and display structure
```
compare-db-models
```
- Compare live database against SQLAlchemy models to identify discrepancies

compare-models-doc

- Compare SQLAlchemy models against

.roo/docs/database_schema.md

```
generate-docs
```
- Generate/update
```
.roo/docs/database_schema.md
```
from current database state
```
report
```
- Generate discrepancy reports under
```
.roo/reports/
```
(JSON and Markdown)
```
validate
```
- Verify schema documentation is up-to-date with the database

Usage notes:

This utility uses the configured database URL (from
```
.env
```
) and initializes
```
db
```
from
```
utils_db/database.py
```
.
Some schema comparison utilities may emit reports under
```
.roo/reports/
```
when run.

Usage examples:

Introspect schema:

python utils_db/schema_inspector.py introspect

Compare:

python utils_db/schema_inspector.py compare-db-models

Compare models vs docs:

python utils_db/schema_inspector.py compare-models-doc

Generate docs:

python utils_db/schema_inspector.py generate-docs

Validate docs:

python utils_db/schema_inspector.py validate

Testing

Run tests with
```
pytest
```
against the live PostgreSQL database.

TestingConfig

(

config.py

), CSRF is disabled (

WTF_CSRF_ENABLED = False