canonic
About
The context layer that lets AI agents query your data correctly.
Details
- Author
- mischuh
- Categories
- Database, Other, Knowledge Base
Jump to
Setup
Install canonic in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/mischuh/canonic
Follow the installation instructions in the repository README, then restart your MCP client.
The context layer that lets AI agents query your data correctly.
Point canonic at your database and it builds the context an agent needs to answer data questions accurately: definitions, relationships, business meaning, and the guardrails that stop confidently-wrong answers. It keeps that context up to date as your data changes, and it never touches your warehouse beyond reading it.
📖 Full documentation:https://docs.getcanonic.app
Package and image names below show the shape of each install channel; exact names are confirmed per release.
An AI agent connected straight to your warehouse seestables and columns, notmeaning. It doesn't know thatrevenuelives inorders.amountbut excludes refunds, or that "active customer" has a specific definition your finance team agreed on. So it guesses. Schema access makes an agentfluent. It doesn't make itcorrect.
Real output, captured from a live run against theecommerce example:
$ canonic sql "SELECT SUM(amount) FROM fct_orders" ┏━━━━━━━━━┓ ┃ sum ┃ ┡━━━━━━━━━┩ │ 4050.50 │ └─────────┘
This total includes two refunded orders ($260), a confident, well-formatted number that's off by 6.4%.
$ canonic --json query --metrics revenue { "result": { "rows": [["3790.50"]] }, "compiled": { "sql": "SELECT SUM(\"orders\".\"amount\") AS \"total_revenue\" FROM \"fct_orders\" AS \"orders\" WHERE \"orders\".\"status\" 'refunded'" }, "metadata": { "guardrails_fired": [{ "id": "revenue-excludes-refunds", "kind": "mandatory_filter" }] } }
canonic resolves "revenue" to its canonical definition, compiles the guardrail into the SQL whether or not anyone asked for it, and returns the right number with the reasoning attached.
canonic is not a BI tool and not a chat interface: it's the layer that feeds the tools you already have (a BI dashboard, an agent, a notebook) correct, governed answers.
canonic's context lives in three committed surfaces: plain files in your git repo, reviewed like code.
Changes how the SQLruns→ semantics. A human needs it totrustthe answer → knowledge. Governswhichdefinition is authoritative → contracts. SeeConcepts: the three layers.
uvx canonic --version # ephemeral, no install step uv tool install canonic # persistent, global command
pip(fallback for environments withoutuv):
docker pull ghcr.io/mischuh/canonic:latest
Verify withcanonic --version. Air-gapped install and offline wheels: seeInstallation.
The fastest path uses local connectors, no server, no network. Point at a SQLite.dbor DuckDB.duckdb/CSV/Parquet file:
The wizard names your project, connects a source, optionally configures an LLM, drafts your semantics from the live schema, then runs a real query and shows the answer with its freshness and definition. Postgres or an LLM provider need a credential in an environment variablebeforeyou runcanonic setup(canonic never stores secrets incanonic.yamldirectly).
Don't have a database handy?examples/ships 5 ready-to-run sample projects (dbt Jaffle Shop, e-commerce, vehicle rental, SaaS analytics, Dutch railway), see theguides.
You now have a working context layer committed to your repo:
canonic overview # what's askable canonic query --metrics revenue --dimensions order_date # ask it canonic review && canonic status # review what it drafted
canonic exposes its capabilities over a local, on-demand MCP server, verified withClaude Code, Cursor, and Codex:
{ "mcpServers": { "canonic": { "command": "uvx", "args": [ "canonic", "mcp", "start", "--project", "/path/to/canonic/examples/rental", "--suggestions" ] } } }
GUI-launched clients (Claude Desktop, Cursor) don't source your shell profile, so pass connection credentials via the config'senvfield, notexport. Every answer-producing tool of the 11 registered (query,run_sql,search_knowledge, ...) returns a metadata band: resolved definition, guardrails fired, freshness,trust_score. On ambiguity, the agent gets a structured reason, not a guess.
SeeConnecting your agentfor remote/enterprise deployment (--transport http, per-client bearer tokens) and thetools reference.
- Read-only.canonic never mutates your warehouse.
- Propose-only, refuse-and-ask.Every change is a reviewable diff; ambiguous or unsafe answers get a structured reason, not a guess.
- No LLM in the answer path.Queries compile deterministically. An LLM is optional and onlydraftscontext during setup, four providers supported (Anthropic, OpenAI, any OpenAI-compatible endpoint, GitHub Copilot), seeConfiguring an LLM.
- Local-first & air-gapped-capable.Run entirely on your machine; nothing has to leave your network.
- Quickstart: first answer in minutes.
- Concepts: the three layers and the split rule.
- CLI reference: every command, flag by flag.
- MCP / agent integration: wiring canonic into Claude Code, Cursor, Codex, or any MCP client.
- Guides: 5 ready-to-run example projects.
- Reference: error codes and the fullcanonic.yamlconfig schema.
An AI-powered gateway for managing over 40 data sources like Alibaba Cloud and mainstream databases, featuring NL2SQL, code generation, and data migration.
Query Apple Health data using natural language and SQL.
Interact with AskTable SaaS or local deployments to query data sources using natural language.
Interact with CrateDB using natural language for Text-to-SQL queries and documentation retrieval.
MCP servers that give AI clients safe, structured access to SQL databases. One installable package per database engine. Every package exposes the same minimal two-tool surface, execute_sql and search_objects, with guardrails on by default: read-only mode, row caps, and statement timeouts.
Enables AI assistants to query data from DataFocus using natural language.
Provides read-only access to Apache Iceberg tables via Apache Impala, allowing LLMs to inspect schemas and execute queries.
Data intelligence platform - query your database in natural language, build dashboards, and set up automated alerts that monitor your metrics 24/7.
Interact with MongoDB databases using natural language to query collections, inspect schemas, and manage data.
Interact with MongoDB databases using natural language. Query collections, inspect schemas, and manage data.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
