dbconnect
When to use
- Need to test SQL Server or Oracle connectivity.
- Need to list named connections from a
.connectionsfile. - Need to inspect schema or run ad hoc SQL.
- Need to execute SQL files such as migrations.
- Need query output written to CSV.
Inputs to gather
- Target DB type:
mssqlororacle - Either
--connstring or named connection for--use - SQL text or path to
.sqlfile - Optional CSV output path
- Whether the SQL writes data (INSERT/UPDATE/DELETE/MERGE/DDL/EXEC) — if so, confirm intent with the user before adding
--allow-write
Procedure
- Read
references/dbconnect-usage.mdandreferences/dbconnect-examples.md. - Confirm
dbconnect\bin\dbconnect.exeexists. - If the user wants saved connections, run
scripts\dbconnect-list.bat. - For a connectivity check, run a trivial query like
SELECT 1using the right wrapper. - For schema inspection, use the schema query pattern in
references/dbconnect-examples.md. - For migrations or other file-based SQL, execute the
.sqlfile path through the wrapper. SQL Server files may containGObatch separators; dbconnect splits and runs them as separate batches automatically. - If results must be preserved, pass an output CSV path — this also bypasses the console
--max-rowscap. For large ad hoc queries without--output, either add--max-rows <n>or expect console output truncated at 200 rows by default. - Return the exact command run, summarize results, and call out any prerequisite failures.
Rules
- Prefer wrapper scripts in
scripts/; do not invoke the exe manually unless troubleshooting. - Do not invent connection strings, named connections, or schema names.
- dbconnect blocks INSERT/UPDATE/DELETE/MERGE/DROP/ALTER/CREATE/TRUNCATE/GRANT/REVOKE/EXEC/EXECUTE statements by default (exit code 7). Confirm explicit user intent before re-running with
--allow-write— this is a text-based guard, not a parser, so do not treat its absence of a block as proof the SQL is safe. - If authentication or network access fails, report the exact stderr and stop.
- Keep secrets out of logs and responses when echoing commands.
References
references/dbconnect-usage.mdreferences/dbconnect-examples.mdscripts/dbconnect-run.ps1scripts/dbconnect-run.batscripts/dbconnect-list.bat