db-integration
/db-integration
Execute user-defined database queries during test runs, from the project's integration/ catalog (SQL Server via sqlcmd). Use whenever a test step needs a DB check: verify a row was created/updated by a UI action, check column values, or seed test data. Triggers on spec steps starting with "db:", or requests like "check the database", "verify the row", "query the table". The agent executes ONLY queries the user has defined in integration/*_db.json — it never composes its own SQL.
- Author
- mhmdelgazzar ↗
- Repository
- agentex ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/run_db.js, scripts/run_db.test.js
What it does and when to use it
Execute user-defined database queries during test runs, from the project's integration/ catalog (SQL Server via sqlcmd). Use whenever a test step needs a DB check: verify a row was created/updated by a UI action, check column values, or seed test data. Triggers on spec steps starting with "db:", or requests like "check the database", "verify the row", "query the table". The agent executes ONLY queries the user has defined in integration/*_db.json — it never composes its own SQL.
Triggers from the description
Original author description
Execute user-defined database queries during test runs, from the project's integration/ catalog (SQL Server via sqlcmd). Use whenever a test step needs a DB check: verify a row was created/updated by a UI action, check column values, or seed test data. Triggers on spec steps starting with "db:", or requests like "check the database", "verify the row", "query the table". The agent executes ONLY queries the user has defined in integration/*_db.json — it never composes its own SQL.
How it works
- Role
- The catalog — the ONLY SQL you may execute
- Step syntax in test specs
- Where the connection comes from
- Safety rules (also enforced by the runner)
- Evidence
- Preflight
SKILL.md preview
---
name: db-integration
description: >
Execute user-defined database queries during test runs, from the project's integration/
catalog (SQL Server via sqlcmd). Use whenever a test step needs a DB check: verify a row was
created/updated by a UI action, check column values, or seed test data. Triggers on spec
steps starting with "db:", or requests like "check the database", "verify the row",
"query the table". The agent executes ONLY queries the user has defined in
integration/*_db.json — it never composes its own SQL.
---
# DB Integration — cataloged database steps
## Role
You execute the database query a test step asks for, strictly from the project's
`integration/*_db.json` catalog. You never compose your own SQL or run a query outside the
catalog.
Lets test scenarios query the database **by name**, from definitions the user wrote. Execution
is done by the bundled runner script (deterministic, enforces the safety rules in code):
```
node ${CLAUDE_PLUGIN_ROOT}/skills/db-integration/scripts/run_db.js \
--entry <file-name>.<query-name> --param key=value [--param ...] \
[--env <environment-name>] [--expect-rows N] [--expect-min-rows N] \
--log <SESSION_DIR>/logs/<scenario>-<entry>.log
```
It loads the catalog, validates & escapes params, refuses DDL, resolves the connection (active
environment's db block, else legacy catalog env vars), runs sqlcmd, writes the evidence log, checks expectations, and prints one JSON line:
`{"result":"PASS|FAIL|BLOCKED", ...}` (exit 0/1/2). Read
**`${CLAUDE_PLUGIN_ROOT}/skills/db-integration/references/sqlcmd.md`** for the catalog format,
connection env vars, sqlcmd install/preflight, and the manual fallback.
## The catalog — the ONLY SQL you may execute
Definitions live in the **consumer project** at **`./integration/`** (`<database>_db.json`).
- If the folder/file is missing when a step needs it, scaffold from
`${CLAUDE_PLUGIN_ROOT}/skills/db-integration/templates/sample_db.json` (never overwrite),
then ask the user to define their entries.
- **Hard rule:** a step naming a query not defined in the catalog is **BLOCKED** — report
which definition is missing. Never improvise SQL.
## Step syntax in test specs
```
db: <file-name>.<query-name>(param=value, ...) → <expectation>
```
Example: `db: sample-db.todo-by-title(title=qa-test-item) → expect 1 row`
## Where the connection comes from
1. **`environments/<env>.json` `db` block** of the active environment (pass the
orchestrator's environment name via `--env`; omitted = the project's
`defaultEnvironment`): `{ "server", "port", "name", "user", "password": { "envSecret": "SQLCMDPASSWORD" } }`.
2. **Legacy fallback** — the catalog's `connection` block naming `.env` vars
(`serverEnv` …) exactly as before. Old projects keep working untouched.
The password is never in a JSON file: `db.password` is a `{ "envSecret": "NAME" }`
reference resolved from `.env` and handed to sqlcmd only through its environment.
## Safety rules (also enforced by the runner)
- Writes (INSERT/UPDATE/DELETE) run if cataloged — the catalog is the authorization.
- **DDL is banned unconditionally** — `DROP` / `TRUNCATE` / `ALTER` are refused even if
cataloged (runner rejects them; report as a catalog error).
- Password only via the `SQLCMDPASSWORD` env var — never on a command line, never printed.
- Suspicious param values (quotes, `;`, `--`, comment markers, newlines) are rejected by the
runner — surface the value to the user instead of executing.
## Evidence
Runner writes the result set to the `--log` path (under the session's `logs/`). Expectation
mismatch = **FAIL** defect with that log as evidence, reported in the standard defect format.
## Preflight
Requires `sqlcmd` — preflight and install per the reference (offer before installing in
sequential mode).
Files in this package (5)
- SKILL.md 4 KB
- references/sqlcmd.md 4 KB
- scripts/run_db.js 5 KB
- scripts/run_db.test.js 3 KB
- templates/sample_db.json 1 KB
Versions
The database has no other skills named db-integration.
Database snapshot: 13.11.2026 · package version 6580bb395450 (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
- 100api-integration
Execute user-defined API calls during test runs, from the project's integration/ catalog. Use whenever a test step needs an HTTP call: verify via API that a UI action persisted, check an endpoint's response, or seed test data through a service. Triggers on spec steps starting… - 100go-database
Use when writing or reviewing Go SQL queries, transactions, repositories, pools, migrations, or row mapping with database/sql, pgx, or an ORM; also for slow queries and queries in loops. - 100sql-database-assistant
This skill should be used when the user asks to "optimize SQL queries", "explore database schemas", "generate migration SQL", "analyze query performance", or "document database structure". - 100sql-style-and-tuning
Write SQL that is easy to read and review, and make slow queries fast by reading the plan first. Use it whenever you write or review a query, view or model, when a query or page is slow, when the same query runs many times in a row (N+1), or before adding an index. - 100database-optimization
Optimize SQL queries, indexes, and identify N+1 problems. Use for database performance and migration review. - 100sql-pro
Optimizes SQL queries, designs database schemas, and troubleshoots performance issues. Use when a user asks why their query is slow, needs help writing complex joins or aggregations, mentions database performance issues, or wants to design or migrate a schema. Invoke for complex…