Open Data Infrastructure
DuckDB Prepared Statements for Agent Query Safety
How DuckDB prepared statements can make agent query templates safer, more reviewable, and easier to test before execution.
An agent that builds SQL by pasting strings together is not clever. It is a future incident report with syntax highlighting.
Agent SQL needs narrow contracts
DuckDB is a common choice for local analytics, embedded tools, and test harnesses. That makes it attractive for agent workflows that need to inspect files, run small analytical queries, or test retrieval data close to the developer.
The safety problem appears when the agent is allowed to assemble arbitrary SQL from user text. Prepared statements do not solve authorization, but they do separate the query shape from the values the agent provides. That separation makes review easier.
Prepared statements narrow the query path
DuckDB documents prepared statement syntaxes using placeholders such as question marks, positional parameters, and named parameters. Its client APIs also support binding values before execution. For agent tools, that means the approved template can be reviewed once while values are supplied at runtime.
Core idea: prepared statements turn agent SQL from open-ended generation into a parameterized contract.
A safer local harness
Keep a small registry of approved query templates. Bind parameters with documented APIs. Log the template name, bound values, table files, snapshot or source version, and policy decision. If the agent needs a new query shape, require a new template review.
For related ODI patterns, read DuckDB ATTACH patterns, DuckDB local vector search, and AI-ready policy test fixtures.
What breaks first
- The tool uses prepared statements for values but lets the agent choose table names freely.
- The template is safe, but the file path gives access to unmanaged local data.
- Logs store the final result but not the template and bound parameters.
- The local harness passes tests that ignore denial paths and restricted fields.
Query safety questions
Ask which parts of the query are fixed, which values are bound, which tables are allowed, and which errors are safe to return to the model. The answer should be code and evidence, not trust.
Sources to start with
These primary sources anchor the technical claims in this guide.
- DuckDB prepared statements documentation
- DuckDB C prepared statements documentation
- DuckDB Python DB API documentation
- OpenLineage object model documentation
The safest agent query is the one whose shape was reviewed before the agent touched it.