Skip to content
Skills Library
Programming · Testing

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.

Repository
agentex ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

db:check the databaseverify the rowquery the table
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

  1. Role
  2. The catalog — the ONLY SQL you may execute
  3. Step syntax in test specs
  4. Where the connection comes from
  5. Safety rules (also enforced by the runner)
  6. Evidence
  7. Preflight
Original SKILL.md headings · 70 lines, 446 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.