HaltSQL documentation

HaltSQL is a policy firewall for LLM-generated PostgreSQL. It checks whether an exact SQL string is allowed for a caller under a declarative policy, and returns a verdict with machine-readable reasons. It never rewrites SQL and never connects to the database.

These docs describe version 0.0.1 (pre-1.0). The verdict format and reason codes are stable; other interfaces may still change. See Versioning and upgrades.

Start here

If you want to	Read
See a denied query in five minutes	Quickstart
Give Claude Desktop, Cursor or another MCP client safe Postgres access	Replace server-postgres, then Secure an MCP agent
Protect an agent you are building in Python, TypeScript, Go or Java	Integrations
Understand the design before you evaluate it	Architecture and Threat model
Get answers to common evaluation questions	FAQ

Guides by role

Application and agent developers

• Quickstart: install the CLI, write a policy, check queries.
• Multi-tenant analytics agent: a Python agent behind the haltsql-server sidecar, end to end.
• Agent frameworks: LangChain, LangGraph, OpenAI Agents SDK, Google ADK, LlamaIndex, CrewAI, Semantic Kernel and Vanna.
• SDKs: Python, TypeScript, Go and Java.
• Reason codes: what each denial means and how an agent should fix its query.

Platform and SRE teams

• Deployment overview, then the cloud guides for AWS, Google Cloud and Azure.
• Kubernetes operator and Terraform.
• Production checklist: everything to confirm before go-live.
• High availability and scaling, Versioning and upgrades, Troubleshooting and Runbooks.
• Observability, Audit sinks and Performance.

Security and compliance reviewers

• Security overview: data flows, what each component sees and stores, and the fail-closed design.
• Hardening guide: the recommended secure baseline.
• Compliance mapping: how HaltSQL features support SOC 2, ISO/IEC 27001, GDPR and HIPAA controls.
• Supply chain and releases and the Security questionnaire.
• Threat model and Defense in depth.

Data governance teams

• Data catalogs: turn PII labels from dbt, DataHub, Unity Catalog, Atlan, Collibra and OpenMetadata into policy.
• Roll out a policy safely: tests, CI, shadow mode, signed bundles and rollback.
• Policy reference and Tenancy semantics.

Integrations

Area	Covered
MCP clients	Claude Desktop, Claude Code, Cursor, VS Code and any MCP client
Agent frameworks	LangChain, LangGraph, OpenAI Agents SDK, Google ADK, LlamaIndex, CrewAI, Semantic Kernel, Vanna
SDKs	Python, TypeScript, Go, Java, plus the HTTP API for any language
Data catalogs	dbt, DataHub, Unity Catalog, Atlan, Collibra, OpenMetadata
Identity providers	Keycloak, Microsoft Entra ID, Okta, Auth0 and any OIDC provider
Secrets managers	HashiCorp Vault, AWS Secrets Manager, Google Secret Manager
Audit and observability	S3, GCS, Kafka, Elasticsearch, OpenSearch, OpenTelemetry, Prometheus
Wire proxy	Any PostgreSQL driver: psql, JDBC, pgx, psycopg and others

Features

• CLI: every haltsql command, flag and exit code.
• HTTP API: the haltsql-server sidecar (OpenAPI 3.1).
• Wire proxy: haltsql-proxy, the PostgreSQL wire-protocol firewall.
• Signed policy bundles and Policy CI.
• Shadow mode reports: what would have been denied, and conservative policy suggestions.
• Open Policy Agent: an optional deny-only decision after HaltSQL allows a query.
• RLS generation and Schema and PII import.

How it works

Explainers with diagrams, from the big picture down to the code:

• Architecture: components and where HaltSQL sits in your stack.
• The verification pipeline: one verify call, end to end.
• The parser and the analyzer: from SQL text to typed AST to reasons.
• The tenancy proof: what must be proven before a tenant table is read.
• Policies and config and the policy lifecycle.
• Deployment modes, inside the proxy and inside the server.
• How HaltSQL is tested: the test suites, attack corpus and enterprise lab.

Reference

• Policy reference: every key in a kind: Policy document.
• Config reference: the kind: Config document for the CLI and server.
• Verdict format: the JSON returned for every check.
• Reason codes: what each code means.
• Tenancy semantics: exactly what HaltSQL must prove for a tenant-scoped table.
• Glossary: HaltSQL terms in one place.

Document kinds at a glance

Everything HaltSQL reads is YAML or JSON with apiVersion: haltsql.dev/v1 and a kind:

Kind	Purpose	Reference
Policy	What SQL is allowed	policy-reference.md
Config	How the CLI and server run	config-reference.md
TestSuite	Allow/deny test cases for a policy	testing.md
Catalog	Schema snapshot (tables and column types)	policy-reference.md
Scenario	Enterprise lab scenario	testing.md
ProxyConfig	How haltsql-proxy runs	proxy.md
PolicyBundle	Signed set of policies (canonical JSON + .sig)	policy-bundles.md

haltsql validate FILE... checks Policy, Config, TestSuite, Catalog and Scenario documents; haltsql-proxy validate --config FILE checks a ProxyConfig, and haltsql bundle verify checks a PolicyBundle. haltsql schema export writes JSON Schemas for editor autocomplete.

Project

• Architecture Decision Records
  • 0001: Parse with libpg_query
  • 0002: Typed AST, fail closed
  • 0003: Tenancy semantics
  • 0004: Verdict schema and reason codes
  • 0005: Apache-2.0 license (superseded by 0006)
  • 0006: MIT license
  • 0007: Deny-only external policy and admin API
• Contributing, Security policy, Governance and Changelog.