{
  "markdown": "# nlqdb — your autonomous DBA.\n\n> Build a real app from day one with no data modeling. nlqdb infers your schema from how you use it, evolves it, and keeps it optimized — and shows you every change before it lands.\n\nYour app talks to its database in plain English — over HTTP, the SDK, the\n`nlq` CLI, or MCP from Claude, Cursor and Codex. The first insert creates the\nshape; later inserts and reads evolve it; the DBA builds the indexes and\nplaces data on the right engine, and every change is previewed, versioned and\none click to undo. The LLM never emits SQL: it returns a typed plan, our\ncompiler emits the parameterised statement, and you see the exact SQL every time.\n\n**No backend to build.** You write HTML; each\ncomponent asks for what it wants in plain English; nlqdb infers the schema,\nwrites the SQL, runs it, and renders the result. There is no backend for you\nto build.\n\nTwo actions. That's the whole product:\n\n1. **Create a database** — one word: a name (or a goal).\n2. **Talk to it** in plain English.\n\n```html\n<script src=\"https://elements.nlqdb.com/v1.js\" type=\"module\"></script>\n\n<nlq-data\n  goal=\"the 5 newest orders, with customer and item\"\n  api-key=\"pk_live_xxx\"\n  template=\"table\"\n  refresh=\"10s\"\n></nlq-data>\n```\n\nThat's the entire backend for a live order list — no API to write, no\nschema to define, no JSON to parse. Engine choice (Postgres / Mongo /\nRedis / DuckDB / pgvector / …), schema inference, indexing, backups, and\nauto-migration between engines based on your real workload are background\nconcerns you never have to see.\n\n## Status — early, open\n\nnlqdb is **early** and built in the open, but fully public — no gate, no\ninvite code. The marketing site, the `/v1/ask` pipeline, the `<nlq-data>` /\n`<nlq-action>` elements, the chat app, the TypeScript SDK, the hosted MCP\nserver, and the `nlq` CLI are all live in some form (see the surface table\nbelow). Natural-language → SQL accuracy is still climbing toward our public\nbar (BIRD ≥ 0.65, Spider 2.0 ≥ 0.75 on the free model chain), so answers can\nbe wrong — every response carries a confidence signal and the SQL it ran.\n\n## Use it\n\nConnecting an agent over MCP? On **Claude Code**, one marketplace add wires the\nhosted server *and* both memory skills in a single step:\n\n```\n/plugin marketplace add nlqdb/nlqdb\n/plugin install nlqdb-memory@nlqdb\n```\n\nOn any other MCP host, [**connect your agent**](https://docs.nlqdb.com/agent-memory/)\nwith one browser-OAuth approval; headless hosts skip the browser with\n`npx -y @nlqdb/mcp` (`0.1.1`) and an `sk_mcp_*` MCP key\n([MCP setup](https://docs.nlqdb.com/mcp/)). `@nlqdb/sdk` (`0.4.0`) and\n`@nlqdb/mcp` (`0.1.1`) are both published and importable from npm.\n\nThe 60-second walkthrough — plain HTML, CLI, and ten framework wrappers —\nlives at [`docs.nlqdb.com`](https://docs.nlqdb.com). Start with the\n[HTML tutorial](https://docs.nlqdb.com/tutorials/html/) or the\n[CLI tutorial](https://docs.nlqdb.com/tutorials/cli/).\n\nYou don't generate an API key separately: describe your database at\n[nlqdb.com](https://nlqdb.com/?utm_source=github), and the chat hands you a\n`<nlq-data>` snippet with the key already inlined.\n\n## Examples\n\n[`examples/`](./examples) — minimal scaffolds in plain HTML, Next.js,\nNuxt, SvelteKit, Astro, plus a CLI-only walkthrough. Each is the smallest\nvalid integration around one `<nlq-data>` element or one CLI session.\n\n## What makes it different\n\nFour things every release has to move, none allowed to regress\n([`GLOBAL-025`](./docs/decisions/GLOBAL-025-north-star.md)):\n\n- **Engine quality** — natural-language → SQL accuracy (measured\n  continuously on BIRD + Spider 2.0 + an internal eval), plus the\n  multi-engine layer that moves your data to the right engine for your\n  workload.\n- **Onboarding** — landing to first answer in under a minute, no card,\n  no config.\n- **UX** — see the diff before any write, see the SQL behind every\n  answer, and on low confidence get a one-click clarify — a guided turn,\n  never a dead-end, and never a silent guess.\n- **Performance** — sub-400 ms cached, sub-1.5 s cold.\n\nThe bet: get this right on free, open models and it only gets better on\nfrontier ones — the scaffolding compounds with whatever model is\nunderneath.\n\n## Models & plans\n\n- **Free forever** on the built-in open-model chain — queries, embeds,\n  and the elements, no card required.\n- **Bring your own LLM key** (Anthropic / OpenAI / Gemini / Grok / OpenRouter)\n  on any tier, at no markup.\n- **Hosted premium models** on paid plans, when you'd rather not manage a\n  key of your own.\n- **Self-host the source** — the engine, CLI, MCP server, and SDKs are\n  source-available under [FSL-1.1-ALv2](./LICENSE): free to self-host for\n  any non-competing use, bring your own LLM key, no per-call fees. The\n  license auto-converts to Apache 2.0 two years after each release.\n\nThe hosted-premium model lane went live 2026-08-14. The full model strategy is in\n[`GLOBAL-026`](./docs/decisions/GLOBAL-026-llm-strategy-byollm-hosted-premium.md).\n\n## Surfaces at a glance\n\n| Surface | Status | Where |\n|---|---|---|\n| HTTP API (`POST /v1/ask`, `POST /v1/run`) | ✓ shipped | `apps/api/src/ask/**` |\n| `<nlq-data>` + `<nlq-action>` elements | ✓ shipped (v0.1) | `packages/elements/**` |\n| `@nlqdb/sdk` (TypeScript) | ✓ shipped (incl. `runSql` + cross-tenant grant + pack-import runner verbs) — installable from npm (`0.4.0`) | `packages/sdk/**` |\n| Framework wrappers (React / Next / Vue / Nuxt / Svelte / SvelteKit / Astro / Solid + Swift) | ~ built + CI-tested; npm / SPM publish pending | `packages/{react,next,…}/**` |\n| Chat app `nlqdb.com/app` | ✓ shipped | `apps/web/**` |\n| Hosted MCP server `mcp.nlqdb.com/mcp` | ✓ shipped (host auto-detect pending) | `apps/mcp/**`, `packages/mcp/**` |\n| Local stdio MCP server `@nlqdb/mcp` | ✓ shipped (`0.1.1`) — `npx -y @nlqdb/mcp` with an `sk_mcp_*` key | `packages/mcp/**` |\n| Droppable agent artifacts (AGENTS.md · Claude Code skill **+ plugin** · Cursor rules · Codex config) | ✓ shipped — `/plugin marketplace add nlqdb/nlqdb` installs the server + skills in one step | `apps/web/public/agent-artifacts/**` |\n| `nlq` CLI (Go) | ✓ shipped (core verbs; device-login pending) | `cli/**` |\n\nFull integration matrix in [`docs/progress.md`](./docs/progress.md).\n\n## Packages on npm\n\nPublished to the public npm registry with build provenance\n([`SK-CIPERM-003`](./docs/features/ci-permissions/FEATURE.md)). Version badges\nare live from npm; the table itself is generated from the workspace by\n[`scripts/sync-readme-packages.mjs`](./scripts/sync-readme-packages.mjs), so it\nlists exactly the packages that are un-gated (`\"private\"` removed) and nothing\nthat isn't.\n\n<!-- BEGIN:packages -->\n| Package | Version | What it is | Source |\n|---|---|---|---|\n| [`@nlqdb/cli`](https://www.npmjs.com/package/@nlqdb/cli) | [![@nlqdb/cli](https://img.shields.io/npm/v/@nlqdb/cli?label=npm&color=cb3837)](https://www.npmjs.com/package/@nlqdb/cli) | Shim that installs the nlq CLI binary for the host platform. | [`packages/cli-shim`](./packages/cli-shim) |\n| [`@nlqdb/mcp`](https://www.npmjs.com/package/@nlqdb/mcp) | [![@nlqdb/mcp](https://img.shields.io/npm/v/@nlqdb/mcp?label=npm&color=cb3837)](https://www.npmjs.com/package/@nlqdb/mcp) | Analytical-memory MCP server for nlqdb — a real database your AI agent can GROUP BY / JOIN / aggregate over in natural language, not just recall. | [`packages/mcp`](./packages/mcp) |\n| [`@nlqdb/sdk`](https://www.npmjs.com/package/@nlqdb/sdk) | [![@nlqdb/sdk](https://img.shields.io/npm/v/@nlqdb/sdk?label=npm&color=cb3837)](https://www.npmjs.com/package/@nlqdb/sdk) | Typed HTTP client for the nlqdb /v1 API — works in browsers, Node, Bun, Workers. | [`packages/sdk`](./packages/sdk) |\n<!-- END:packages -->\n\n## Roadmap\n\nThe two sections below are the **live focus**; the numbered phases after\nthem are the engine roadmap. Canonical plan + exit gates:\n[`docs/phase-plan.md`](./docs/phase-plan.md). Legend:\n**✓ shipped · ~ in progress · ◯ planned**.\n\n> **This roadmap is yours to shape.** Want something added, reprioritised, or\n> dropped? Open a PR editing this section (and\n> [`docs/phase-plan.md`](./docs/phase-plan.md) if it's engine-facing), or open\n> an issue to float it first. Say **why now** — which of the four north-star\n> pillars (engine quality, onboarding, UX, performance) it moves. New to the\n> codebase? Point your coding agent at this repo and paste:\n>\n> ```\n> Read README.md and docs/phase-plan.md, then propose a roadmap change:\n> add/change \"<your idea>\" under the right section in one line, with a\n> \"why now\" naming which north-star pillar it moves. Open a PR with just\n> that edit — no code.\n> ```\n>\n> Setup, branch naming, and the CLA are in [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n### Now — Phase A: the schema infers itself (`GLOBAL-041`)\n\nThe first insert creates the shape; later inserts and reads evolve it. KPI:\nfirst-insert inference rate ≥ 95 % at Phase A exit on the dogfood workload.\nBuild order in [`GLOBAL-041`](./docs/decisions/GLOBAL-041-autonomous-dba.md).\n\n- ◯ `kind=extend` typed plan — a write naming an unseen table or field widens\n  the schema in the same transaction as the insert, never a `schema_mismatch`\n- ◯ Extend diff + trace on every surface (SDK · CLI · MCP · `<nlq-data>`)\n- ✓ KPI counters `asks_extend_ok` / `asks_extend_failed` on the `/v1/ask` write path\n  (`SK-SCHEMA-010`; the rate reads on `/app/admin`)\n- ◯ Phase B — `pg_stat_*` + `EXPLAIN` collection → typed proposals (index /\n  retype / drop / rename / move-to-engine) → `/app/dba` dashboard with\n  1-click apply + undo\n- ✓ Rails kept from the prior bet for the expert-knowledge app:\n  `agent_memory_v1` preset, `nlqdb_remember` / `nlqdb_read` MCP tools,\n  per-agent RLS isolation, the Claude Code plugin, `/agents`\n\n### Next — the expert-knowledge marketplace (\"Become AI\")\n\nNon-technical professionals turn their expertise into structured,\nqueryable knowledge that AI agents pay to use. Decisions locked; build\ngated on Phase A (`SK-EKP-005`)\n([`docs/features/expert-knowledge-platform/`](./docs/features/expert-knowledge-platform/FEATURE.md)).\n\n- ◯ Interview authoring — answer questions about your craft, get queryable\n  rows (pilot: language tutor)\n- ✓ Cross-tenant read grants — mint/list/revoke control plane + live\n  fail-closed granted read on `/v1/ask` (schema-only plan, rows-only\n  egress, exactly-once per-query metering proven at the route boundary);\n  revoke-in-flight bound measured against live Postgres\n- ◯ One catalog — free packs + paid expert knowledge DBs\n- ~ Trust hardening — buyer queries schema-only end-to-end: knowledge-DB\n  asks skip narration by default and the granted cross-tenant read is\n  un-narrated (returned rows never reach an LLM); no-training\n  interview-provider pin pending\n\n### Phase 0 — Foundations ✓\n\nWorker skeleton · KV + D1 + R2 bindings · Neon adapter + OTel · LLM router\n(free chain) · Better Auth (GitHub + Google + magic link) · `/v1/ask`\nend-to-end · events queue + drain · Stripe webhook · CI/CD + PR preview\nenvironments.\n\n### Phase 1 — On-ramp\n\nA stranger lands on `nlqdb.com`, creates a DB in plain English, embeds it,\nand shares the link — in under 60 seconds, no card, no config.\n\n- ✓ Marketing site (Astro, live at `nlqdb.com`)\n- ✓ `<nlq-data>` + `<nlq-action>` elements (v0.1)\n- ✓ Sign-in — magic link + GitHub + Google\n- ✓ Chat surface — streaming three-part response (answer / data / trace),\n  anonymous mode\n- ✓ Anonymous mode — 72h token, adopted onto your account on sign-in\n- ✓ Hosted db.create pipeline (table-card embeddings stubbed pending the\n  pgvector slice)\n- ✓ API keys dashboard (`/app/keys`)\n- ◯ Hello-world tutorial polish\n\n### Phase 1.5 — Trust + telemetry\n\n- ✓ Diff preview on writes + visible SQL trace on every response\n- ✓ Demand-signal telemetry on every \"not yet\" path\n- ◯ Confidence floor (clarify-on-low-confidence — a guided turn, not a dead-end) — lands with quality-eval\n\n### Phase 2 — Distribution (agent + developer surfaces)\n\n- ✓ Hosted MCP server (`mcp.nlqdb.com/mcp`) — host auto-detect pending;\n  local stdio `@nlqdb/mcp@0.1.1` is on npm, so `npx -y @nlqdb/mcp` with an\n  `sk_mcp_*` key is a headless route in with no browser consent step\n  (`/agents` now carries it; the per-host install panel is still OAuth-only).\n  On Claude Code, `/plugin marketplace add nlqdb/nlqdb` installs the server +\n  both memory skills in one step\n- ✓ CLI `nlq` (Go) — core verbs + raw-SQL escape hatch; device-login +\n  chat REPL pending\n- ✓ `@nlqdb/sdk` — basic methods + `runSql` + cross-tenant grant +\n  pack-import runner verbs; published and importable from the registry\n  (`0.4.0`)\n- ~ Framework wrappers + native Swift package — built + CI-tested; npm /\n  SPM publish pending\n- ✓ Quality-eval harness (BIRD + Spider 2.0) — a CI regression alarm for\n  the NL→SQL interface, not a KPI\n- ~ Bring-your-own-LLM dispatch — HTTP lane live; remaining surfaces in\n  progress\n- ◯ CSV upload in chat\n- ~ Docs-site reference completeness — SDK + framework-wrapper guides,\n  an enumerable error-code reference, and a build-time `/llms.txt` for\n  agents now live; tutorial polish remains\n- ◯ Custom domains for embeds\n\n### Phase 3 — Multi-engine engine (the moat)\n\n- ◯ Workload analyzer → migration orchestrator\n- ◯ ClickHouse / DuckDB / Redis as additional engines\n- ◯ Dual-read verification\n- ✓ Hosted-premium model lane (demand-gated) — live 2026-08-14 (`PREMIUM_METER_LIVE` flipped)\n\n### Phase 4 — Beyond v1\n\n- ~ Bring-your-own Postgres / ClickHouse — connect path live end-to-end\n  (`POST /v1/db/connect` + web UI, CLI, SDK, query dispatch); prod-gated on\n  the `BYO_SECRET_KEK` secret. **Supabase** adds one-click OAuth connect over\n  the read-only Management-API (no DSN to paste); prod-gated on the\n  `SUPABASE_OAUTH_CLIENT_ID` / `_SECRET` secrets, with a graceful fall-back to\n  paste when unset\n- ◯ SSO (SAML / OIDC), audit-log export, per-org quotas\n- ◯ EU data residency, VPC peering, SOC 2\n\n## Develop locally\n\n```bash\ngit clone git@github.com:nlqdb/nlqdb.git && cd nlqdb\nscripts/bootstrap-dev.sh   # installs everything, pulls Ollama models, seeds .envrc\nscripts/login-cloud.sh     # signs you into cloud providers that have a CLI flow\n```\n\n`bootstrap-dev.sh` stands up the whole toolchain in one shot — Bun, Node\n20+, Go 1.25+, uv; Biome / gofumpt / golangci-lint / ruff; lefthook git\nhooks; the cloud CLIs (wrangler, flyctl, stripe, gh); a local Ollama so the\nLLM router works offline; and a `.envrc` with self-generated dev secrets.\nDetails in\n[`docs/history/infrastructure-setup.md §8`](./docs/history/infrastructure-setup.md#8-dev-toolchain).\n\nDay-to-day:\n\n```bash\nbun run fix          # biome format + lint --write (most issues)\nbun run check:all    # biome + golangci-lint + ruff (what CI runs)\nbun run hooks:run    # run pre-commit hooks against staged files\n```\n\n### End-to-end tests (manual trigger)\n\nE2E coverage is **persona-driven** and **manually triggered** so cost stays\ninside the free-tier envelope — one `workflow_dispatch` workflow per\nsurface:\n\n```bash\ngh workflow run e2e-opencheck.yml             # web — live LLM, Neon branch, Workers preview\ngh workflow run e2e-cli.yml                   # Go testscript, hermetic\ngh workflow run e2e-sdk.yml                   # vitest + cassettes, hermetic\ngh workflow run e2e-mcp.yml                   # InMemoryTransport protocol tests, hermetic\ngh workflow run e2e-examples.yml              # Playwright across HTML/Next/Astro/Nuxt/SvelteKit\ngh workflow run e2e-examples.yml -f live=true # + staging for the curl + CLI shell smokes\n```\n\nRun the hermetic surfaces locally without GitHub:\n\n```bash\n( cd tests/e2e/cli && go test ./... )\n( cd tests/e2e/sdk && bun install && bun run test )\n( cd tests/e2e/mcp && bun install && bun run test )\n( cd tests/e2e/examples && bun install && bun run install:browsers && bun run test )\n```\n\nOnly *execution* is manual: `tests/e2e/{sdk,mcp,examples}` live outside the root\nworkspace, so CI's `typecheck-e2e` job `tsc`s them on every PR — the free\nbackstop against a suite that compiles today and rots before the next dispatch.\n\nConventions, persona mapping, and cassette governance are in\n[`docs/features/e2e-coverage/FEATURE.md`](./docs/features/e2e-coverage/FEATURE.md).\n\n## Docs & reference\n\n- [`docs/architecture.md`](./docs/architecture.md) — system design (auth,\n  pricing, the $0 stack, model selection, hosted db.create, hello-world).\n- [`docs/phase-plan.md`](./docs/phase-plan.md) — canonical phase plan and\n  exit gates.\n- [`docs/decisions.md`](./docs/decisions.md) — cross-cutting `GLOBAL-NNN`\n  decisions; per-feature records live under\n  [`docs/features/`](./docs/features).\n- [`docs/performance.md`](./docs/performance.md) — SLOs, latency budgets,\n  span/metric catalog.\n- [`docs/competitors.md`](./docs/competitors.md) — competitive landscape.\n\n## Community & legal\n\n- [CONTRIBUTING.md](./CONTRIBUTING.md) — dev setup, branch naming, commits, CLA flow.\n- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) — Contributor Covenant 2.1. Reports to `conduct@nlqdb.com`.\n- [SECURITY.md](./SECURITY.md) — vulnerability disclosure (`security@nlqdb.com`). 90-day fix target.\n- [SUPPORT.md](./SUPPORT.md) — where to ask questions and what we don't (yet) offer.\n- [CLA.md](./CLA.md) — Contributor License Agreement, signed once via the bot on your first PR.\n- [TRADEMARKS.md](./TRADEMARKS.md) — what you can and can't do with the nlqdb name and logo.\n- [SUBPROCESSORS.md](./SUBPROCESSORS.md) — third-party services that may process personal data on our behalf.\n- [IMPRESSUM.md](./IMPRESSUM.md) — Swiss UWG-mandated operator disclosures.\n- Privacy policy and terms of service: [nlqdb.com/privacy](https://nlqdb.com/privacy) · [nlqdb.com/terms](https://nlqdb.com/terms).\n\n## License\n\n[FSL-1.1-ALv2](./LICENSE) — Functional Source License, Apache 2.0 future\nlicense. Source-available for any non-competing use; auto-converts to\nApache 2.0 two years after each release. (Pattern used by Sentry, Convex,\nand others.)\n\n`nlqdb`™ is an unregistered trademark of the project's licensor. See\n[TRADEMARKS.md](./TRADEMARKS.md) for usage guidelines.\n",
  "bytes": 18049,
  "sha": "717ede779fb53c6acc5d45617398981785267154fb3d27d057c95eb401e63af5",
  "repo_slug": "nlqdb/nlqdb",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_nlqdb_nlqdb_0bc93b11/readme"
}