DuckDB Read-Only Connections for Local Agent Analytics

Local analytics agents do not need the power to mutate every file they can inspect.

Local access is still access

DuckDB is excellent for local analytical work because it can query local files, attached databases, and in-process data with very little ceremony. That same strength becomes a governance problem when an agent uses DuckDB to inspect data on behalf of a human workflow.

A read-only connection is a simple boundary with a large effect. DuckDB documents read-only database access in its client APIs and concurrency guidance. If the agent only needs to inspect Parquet files, CSV extracts, or a local database snapshot, write capability should not be present by default.

The connection mode is part of the contract

The DuckDB concurrency documentation explains that multiple processes can read from a database while write access has tighter constraints. The DuckDB Python DB API documentation includes connection parameters for database access from Python applications.

For ODI, the governance question is not whether DuckDB is local or embedded. The question is whether the access mode, input paths, extensions, secrets, and output paths are part of the review evidence. Read-only access gives the agent a narrower default before policy has to catch every downstream mistake.

Patterns that work

• Use read-only database connections for inspection, profiling, and evidence collection.
• Give agents approved input paths instead of broad filesystem discovery.
• Separate query results from durable writes, exports, and side effects.
• Log the files, tables, extensions, and connection mode used during each run.
• Promote a workflow to write access only after the owner approves the write contract.

For adjacent ODI context, read DuckDB replacement scans for governed dataframes, DuckDB prepared statements for agent safety, and DuckDB local vector search governance.

What breaks first

• An exploratory agent writes side files into the same directory it was asked to inspect.
• A local database snapshot becomes the accidental system of record.
• A notebook helper silently creates or modifies tables while collecting evidence.
• The team cannot replay which files the agent inspected because access mode was not logged.

Questions to ask

• Which local analytics workflows truly require write access?
• Can the agent prove which connection mode it used?
• Which file paths are approved for inspection, and which are blocked?
• Where do query outputs go after the read-only step finishes?

Sources to start with

These primary sources anchor the technical claims in this guide.

• DuckDB concurrency documentation
• DuckDB Python DB API documentation
• DuckDB configuration documentation

The safest local analytics agent is the one that can see enough and change nothing by accident.