AI / agent reference

Let models use PostgreSQL under explicit schema, privilege, cost, and failure contracts

A model does not understand your database merely because it can write SQL. Reliable systems turn database context into a contract, narrow execution into tools, and make correctness repeatably testable.

Context contract

Stable facts to provide to a model—and information that should stay out.

Safe SQL guardrails

Read-only defaults, timeouts, row bounds, transactions, and approval.

Text-to-SQL

Generate, validate, execute, and refuse natural-language database requests safely.

Schema retrieval

Generate compact, versioned, searchable schema summaries from catalogs.

RAG pipeline

Permission filters, hybrid retrieval, pgvector, and traceable citations.

Install pgvector

Install, enable, and verify versions on Docker, Ubuntu, and cloud services.

Vector search in production

Exact baselines, HNSW/IVFFlat, filtered recall, and online monitoring.

Agent evaluation

Regression-test with fixed data, result assertions, and query plans.

Recommended architecture

user intent
  → task class (read / write / DDL / operations)
  → retrieve schema contract and relevant guidance
  → model emits a structured tool call
  → policy layer checks AST, privilege, cost, and parameters
  → restricted database role executes
  → return row count, SQLSTATE, duration, and truncation state
  → write an audit event

Database credentials do not enter model context. The model does not choose connection targets. The tool binds environment, database, schema, and role.

Risk tiers

Tier	Example	Default policy
R0	List/describe schema, bounded read	Auto-run with a short timeout
R1	Sensitive columns, larger aggregate	Permission filter, audit, cost bound
R2	`INSERT` or primary-key single-row `UPDATE`	Dry run plus business API or explicit approval
R3	Bulk writes, DDL, grants, replication, restore	Not exposed to a general agent; expert workflow

Prompts are not a security boundary

“Do not delete data” is behavioral advice. Real boundaries come from roles, network isolation, read-only transactions, SQL parsing, and tool allowlists.

Minimum bar

A deployable database agent should parameterize all values; default to read-only; bound statement time and result rows; reject multiple statements; never return secrets to the model; audit query fingerprints; and handle SQLSTATE values such as 40001, 40P01, and 57014 deterministically.