nlqdb — analytical memory for AI agents

nlqdb — 你的自主 DBA。

nlqdb 连接到你已在运行的 Postgres 或 Cloudflare D1 数据库，提出所需的变更，应用你批准的变更，衡量效果，并回滚任何导致性能退化的变更。

存在的意义：使命 — 封装每家公司为打造良好数据库基础设施都会经历的反复试错过程。

发展方向（docs/END_GOAL.md）：粘贴一个连接字符串——通过 nlqdb.com、CLI、SDK，或从 MCP 上的编码 Agent 发起——几分钟内就会收到首批提案，每项提案都包含预期效果、成本和逆向操作。点击一次即可应用；随后，nlqdb 会针对相同查询测量 p95，并保留变更或将其回滚，绝不会在你的应用请求路径上执行。这一闭环仍在构建中 （路线图）；目前已上线的是下方的托管产品。

无需构建后端。 你编写 HTML；每个组件用通俗英语说明自己的需求；nlqdb 推断架构、编写 SQL、运行查询并呈现结果。你无需构建后端。

只需两个操作。这就是整个产品：

1. 创建数据库 — 只需一个词：名称（或目标）。
2. 与它对话，使用通俗英语。

<script src="https://elements.nlqdb.com/v1.js" type="module"></script>

<nlq-data
  goal="the 5 newest orders, with customer and item"
  api-key="pk_live_xxx"
  template="table"
  refresh="10s"
></nlq-data>

这就是实时订单列表的全部后端——无需编写 API，无需定义架构，也无需解析 JSON。引擎选择（Postgres / Mongo / Redis / DuckDB / pgvector / …）、架构推断、索引、备份，以及根据实际工作负载在引擎之间自动迁移，都是你无需操心的幕后工作。

状态 — 早期阶段，开放开发

nlqdb 仍处于早期阶段，并以开放方式开发，但已完全公开——无需门槛，也无需邀请码。营销网站、/v1/ask 管线、<nlq-data> / <nlq-action> 元素、聊天应用、TypeScript SDK、托管 MCP 服务和 nlq CLI 均已以某种形式上线（见下方的功能表）。自然语言 → SQL 的准确率仍在提升，目标是达到我们的公开标准（在免费模型链上，BIRD ≥ 0.65，Spider 2.0 ≥ 0.75），因此回答可能有误——每条响应都会附带置信度信号和实际运行的 SQL。

使用方法

想通过 MCP 连接 Agent？在 Claude Code 中，只需从市场安装一次，即可同时接入托管服务和两个记忆技能：

/plugin marketplace add nlqdb/nlqdb
/plugin install nlqdb-memory@nlqdb

在其他 MCP 宿主上，只需通过浏览器 OAuth 批准一次，即可连接你的 Agent；无头宿主可以使用 npx -y @nlqdb/mcp 和 sk_mcp_* MCP 密钥跳过浏览器 （MCP 设置）。@nlqdb/sdk 和 @nlqdb/mcp 均已发布，可从 npm 导入。

60 秒快速上手指南涵盖纯 HTML、CLI 和十种框架封装，详见 docs.nlqdb.com。从 HTML 教程或 CLI 教程开始。

你无需单独生成 API 密钥：在 nlqdb.com 描述你的数据库，聊天界面就会提供一个已内嵌密钥的 <nlq-data> 代码片段。

示例

examples/ — 提供纯 HTML、Next.js、 Nuxt、SvelteKit、Astro 的最小脚手架，以及仅使用 CLI 的演示。每个示例都是围绕一个 <nlq-data> 元素或一次 CLI 会话构建的最小有效集成。

有何不同

每次发布都必须推动以下四项进步，且任何一项都不能退步 （GLOBAL-025）：

• 引擎质量 — 自然语言 → SQL 的准确率（持续在 BIRD + Spider 2.0 + 内部评测集上测量），以及多引擎层，可根据工作负载将数据发送到合适的引擎。
• 上手体验 — 从访问页面到获得第一个答案，不到一分钟；无需银行卡，也无需配置。
• 用户体验 — 任何写入前都能查看差异，每个答案背后的 SQL 都清晰可见；置信度低时，可一键请求澄清 — 以引导式交互继续，而非陷入死胡同，也绝不默默猜测。
• 性能 — 缓存命中时低于 400 ms，冷启动时低于 1.5 s。

我们的设想是：先在免费开源模型上把这些做好，这些能力在前沿模型上只会更出色 — 无论底层使用什么模型，支撑能力都会不断累积。

模型与套餐

• 永久免费，使用内置的开源模型链 — 查询、嵌入和元素均可使用，无需银行卡。
• 自带 LLM 密钥（Anthropic / OpenAI / Gemini / Grok / OpenRouter），适用于任何套餐，不加价。
• 托管高级模型，适用于付费套餐，让你无需自行管理密钥。
• 自托管源码 — 引擎、CLI、MCP 服务和 SDK 均以源码形式提供，采用 FSL-1.1-ALv2 许可：在任何非竞争性用途下均可免费自托管，自带 LLM 密钥，不收取按次调用费用。每个版本发布两年后，许可证会自动转换为 Apache 2.0。

托管高级模型服务通道于 2026-08-14 上线。完整的模型策略见 GLOBAL-026。

各类接入面一览

接入面	状态	位置
HTTP API（POST /v1/ask、POST /v1/run、POST /v1/insert）	✓ 已发布	apps/api/src/ask/**
<nlq-data> + <nlq-action> 元素	✓ 已发布（v0.1）	packages/elements/**
@nlqdb/sdk（TypeScript）	✓ 已发布（含 runSql + 跨租户授权 + pack-import runner 动词）— 可从 npm 安装；insert() 和 runSql 的 params 将在 0.5.0 发布	packages/sdk/**
框架封装（React / Next / Vue / Nuxt / Svelte / SvelteKit / Astro / Solid + Swift）	~ 已构建并通过 CI 测试；npm / SPM 待发布	packages/{react,next,…}/**
聊天应用 nlqdb.com/app	✓ 已发布	apps/web/**
托管 MCP 服务 mcp.nlqdb.com/mcp	✓ 已发布（主机自动检测待完成）	apps/mcp/**、packages/mcp/**
本地 stdio MCP 服务 @nlqdb/mcp	✓ 已发布 — 使用 sk_mcp_* 密钥运行 npx -y @nlqdb/mcp	packages/mcp/**
可直接使用的 Agent 产物（AGENTS.md · Claude Code 技能 + 插件 · Cursor 规则 · Codex 配置）	✓ 已发布 — 运行 /plugin marketplace add nlqdb/nlqdb，即可一步安装服务和技能	apps/web/public/agent-artifacts/**
nlq CLI（Go）	✓ 已发布（核心动词；设备登录待完成）	cli/**

完整集成矩阵见 docs/progress.md。

npm 上的软件包

已发布到 npm 公共注册表，并附带构建来源证明 （SK-CIPERM-003）。版本徽章 实时取自 npm；表格本身由工作区通过 scripts/sync-readme-packages.mjs 生成，因此 仅列出未设门槛（已移除 "private"）的软件包，不多不少。

软件包	版本	说明	源码
@nlqdb/cli		为宿主平台安装 nlq CLI 二进制文件的垫片。	packages/cli-shim
@nlqdb/mcp		nlqdb 的分析记忆 MCP 服务——一个真正的数据库，你的 AI Agent 可以用自然语言对其执行 GROUP BY、JOIN 和聚合，而不只是回忆信息。	packages/mcp
@nlqdb/sdk		面向 nlqdb /v1 API 的类型化 HTTP 客户端——可在浏览器、Node、Bun、Workers 中使用。	packages/sdk

路线图

以下部分是当前重点；其后的编号阶段是托管产品的路线图，将保留至 GLOBAL-043 删除系列完成。规范计划与退出门槛： docs/phase-plan.md。图例： ✓ 已交付 · ~ 进行中 · ◯ 计划中。

这份路线图由你来塑造。 想添加、调整优先级或删除某项内容？提交一个 PR 编辑本节（如果涉及引擎，也编辑 docs/phase-plan.md），或者先提交一个 issue 提出想法。说明为什么是现在——它将推动四个北极星支柱（引擎质量、入门体验、UX、性能）中的哪一项。刚接触代码库？让你的编码 Agent 查看此仓库，并粘贴：

Read README.md and docs/phase-plan.md, then propose a roadmap change:
add/change "<your idea>" under the right section in one line, with a
"why now" naming which north-star pillar it moves. Open a PR with just
that edit — no code.

环境设置、分支命名和 CLA 见 CONTRIBUTING.md。

现在 — 接入你已在运行的数据库（GLOBAL-043）

在你的 Postgres（Supabase、Neon、RDS）或 Cloudflare D1 上，完成一个循环——观察 → 提议 → 应用 → 验证 → 回滚。计划、KPI 和退出门槛： GLOBAL-043。

• ~ /app/dba 变更日志——按时间倒序记录每项变更及其逆操作 （只读 v0）
• ~ 在合成数据库上接入产品——观察器、create_index 提议、应用 → 验证 → 自动回滚，四个入口（API 入口 POST /v1/attach / client.attach()，以及 client.applyProposal() / rejectProposal()，现已上线），并在 CI 中测试
• ◯ Postgres 验证——在真实流量数据库上提议、应用一个索引并测量效果（对比前后 p95）
• ◯ 在真实的 rateme12 上接入 D1——用于自测
• ◯ 操作手册——未使用索引的删除、膨胀、重类型转换、分区、保留策略、 数据布局

阶段 0 — 基础 ✓

Worker 骨架 · KV + D1 + R2 绑定 · Neon 适配器 + OTel · LLM 路由器 （免费链路）· Better Auth（GitHub + Google + 魔法链接）· /v1/ask 端到端 · 事件队列 + 清空处理 · Stripe webhook · CI/CD + PR 预览 环境。

阶段 1 — 入门

访客来到 nlqdb.com，用简单的英语创建数据库、嵌入数据库， 然后分享链接——全程不到 60 秒，无需银行卡，也无需配置。

• ✓ 营销网站（Astro，已在 nlqdb.com 上线）
• ✓ <nlq-data> + <nlq-action> 元素（v0.1）
• ✓ 登录——魔法链接 + GitHub + Google
• ✓ 聊天界面——流式三段式响应（答案 / 数据 / 跟踪记录）， 匿名模式
• ✓ 匿名模式——72h 令牌，登录后关联到你的账户
• ✓ 托管式 db.create 流程（表卡嵌入功能暂为占位，等待 pgvector 阶段）
• ✓ API 密钥仪表盘（/app/keys）
• ◯ Hello-world 教程润色

阶段 1.5 — 信任 + 遥测

• ✓ 写入前差异预览 + 每次响应都显示 SQL 跟踪记录
• ✓ 每条“尚未支持”路径都进行需求信号遥测
• ◯ 置信度下限（低置信度时请求澄清——引导式交互，而非死胡同）——随质量评估功能上线

阶段 2 — 分发（Agent + 开发者界面）

• ✓ 托管式 MCP 服务（mcp.nlqdb.com/mcp）——主机自动检测待完成； 本地 stdio @nlqdb/mcp 已发布到 npm，因此使用 sk_mcp_* 密钥运行 npx -y @nlqdb/mcp，即可通过无头方式接入，无需浏览器授权步骤 （/agents 现已提供此功能；各主机的安装面板仍仅支持 OAuth）。 在 Claude Code 中，运行 /plugin marketplace add nlqdb/nlqdb，即可一步安装服务 + 两项记忆技能
• ✓ CLI nlq（Go）——核心命令 + 原始 SQL 逃生通道；设备登录 + 聊天 REPL 待完成
• ✓ @nlqdb/sdk——基本方法 + runSql + 跨租户授权 + 包导入执行器命令；已发布并可从注册表导入； insert() 和 runSql params 将在 0.5.0 发布
• ~ 框架封装 + 原生 Swift 包——已构建并通过 CI 测试；npm / SPM 发布待完成
• ✓ 质量评估工具集（BIRD + Spider 2.0）——用于 NL→SQL 接口的 CI 回归警报，不是 KPI
• ~ 使用自有 LLM 的调度——HTTP 通道已上线；其余界面开发中
• ◯ 在聊天中上传 CSV
• ~ 文档站点参考内容完善度——SDK + 框架封装指南、可枚举的错误代码参考，以及供 Agent 使用的构建时 /llms.txt 现已上线；教程润色仍待完成
• ◯ 嵌入内容的自定义域名

阶段 3 — 多引擎引擎（护城河）

• ◯ 工作负载分析器 → 迁移编排器
• ◯ ClickHouse / DuckDB / Redis 作为额外引擎
• ◯ 双重读取验证
• ✓ 托管式高级模型通道（按需求启用）——已于 2026-08-14 上线（PREMIUM_METER_LIVE 已启用）

阶段 4 — 超越 v1

• ~ 使用自有 Postgres / ClickHouse——连接流程已端到端上线 （POST /v1/db/connect + Web UI、CLI、SDK、查询调度）；生产环境需启用 BYO_SECRET_KEK 密钥。Supabase 增加了通过只读 Management-API 一键 OAuth 连接的功能（无需粘贴 DSN）； 生产环境需启用 SUPABASE_OAUTH_CLIENT_ID / _SECRET 密钥；未设置时会优雅回退到 粘贴方式
• ◯ SSO（SAML / OIDC）、审计日志导出、每个组织的配额
• ◯ 欧盟数据驻留、VPC 对等连接、SOC 2

在本地开发

git clone [email protected]:nlqdb/nlqdb.git && cd nlqdb
scripts/bootstrap-dev.sh   # installs everything, pulls Ollama models, seeds .envrc
scripts/login-cloud.sh     # signs you into cloud providers that have a CLI flow

bootstrap-dev.sh 一次性搭建完整工具链——Bun、Node 20+、Go 1.25+、uv；Biome / gofumpt / golangci-lint / ruff；lefthook Git 钩子；云端 CLI（wrangler、flyctl、stripe、gh）；本地 Ollama，确保 LLM 路由器可以离线工作；以及包含自动生成的开发密钥的 .envrc。 详情请见 docs/history/infrastructure-setup.md §8。

日常开发：

bun run fix          # biome format + lint --write (most issues)
bun run check:all    # biome + golangci-lint + ruff (what CI runs)
bun run hooks:run    # run pre-commit hooks against staged files

端到端测试（手动触发）

端到端测试覆盖由用户角色驱动，并且手动触发，以确保成本控制在免费套餐范围内——每个界面对应一个 workflow_dispatch 工作流：

gh workflow run e2e-opencheck.yml             # web — live LLM, Neon branch, Workers preview
gh workflow run e2e-cli.yml                   # Go testscript, hermetic
gh workflow run e2e-sdk.yml                   # vitest + cassettes, hermetic
gh workflow run e2e-mcp.yml                   # InMemoryTransport protocol tests, hermetic
gh workflow run e2e-examples.yml              # Playwright across HTML/Next/Astro/Nuxt/SvelteKit
gh workflow run e2e-examples.yml -f live=true # + staging for the curl + CLI shell smokes

无需使用 GitHub，即可在本地运行隔离环境中的界面：

( cd tests/e2e/cli && go test ./... )
( cd tests/e2e/sdk && bun install && bun run test )
( cd tests/e2e/mcp && bun install && bun run test )
( cd tests/e2e/examples && bun install && bun run install:browsers && bun run test )

只有执行是手动的：tests/e2e/{sdk,mcp,examples} 位于根工作区之外，因此 CI 的 typecheck-e2e 作业会在每个 PR 上对它们运行 tsc——这项免费保障可避免测试套件今天还能通过编译，下一次触发前却已失效。

约定、用户角色映射和录制文件管理规范见 docs/features/e2e-coverage/FEATURE.md。

文档与参考资料

• docs/architecture.md — 系统设计（身份验证、 定价、零成本技术栈、模型选择、托管的 db.create、hello-world）。
• docs/phase-plan.md — 权威阶段计划和 退出门槛。
• docs/decisions.md — 跨领域的 GLOBAL-NNN 决策；各功能的记录位于 docs/features/。
• docs/performance.md — SLO、延迟预算、 Span/指标目录。
• docs/competitors.md — 竞争格局。

社区与法律

• CONTRIBUTING.md — 开发环境设置、分支命名、提交、CLA 流程。
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1。举报请发送至 [email protected]。
• SECURITY.md — 漏洞披露（[email protected]）。目标是在 90 天内修复。
• SUPPORT.md — 提问渠道，以及我们目前尚未提供的服务。
• CLA.md — 贡献者许可协议，首次提交 PR 时通过机器人签署一次即可。
• TRADEMARKS.md — 关于 nlqdb 名称和徽标的使用规范。
• SUBPROCESSORS.md — 可能代表我们处理个人数据的第三方服务。
• IMPRESSUM.md — 瑞士 UWG 要求的运营方披露信息。
• 隐私政策和服务条款：nlqdb.com/privacy · nlqdb.com/terms。

许可证

FSL-1.1-ALv2 — Functional Source License，未来将采用 Apache 2.0 许可证。任何非竞争性用途均可使用源代码；每次发布两年后自动转换为 Apache 2.0。（Sentry、Convex 等项目采用了这一模式。）

nlqdb™ 是项目许可方尚未注册的商标。使用指南请参阅 TRADEMARKS.md。