schema

数据库 Schema（及与 MCP 返回的 Schema 对比）

1. 定义

数据库 schema（模式/结构） 是数据库的”结构蓝图”：有哪些表、每张表有哪些列、各列是什么类型与约束、表与表之间什么关系（主键/外键）、建了哪些索引。它定义的是”数据长什么样”，而不是里面的”数据内容 (data)”。

类比：schema 像建筑的施工图，data 是照图盖好的楼和里面的家具。改 schema（加列、改类型）要”施工迁移”(migration)，是结构性改动；改 data（插一行）只是装修，随时可动。

关联：建表 CREATE TABLE 就是在定义 schema，见 sqlite-turso.md；而 MCP 语境下的”schema”是另一回事，见第 4 节对比，并与 ../ai-agent-guide/mcp.md 的 Tools/Resources、../ai-agent-guide/tool_calling.md 的函数调用 schema 呼应。

2. 核心概念

概念	含义
表 (Table) / 列 (Column)	数据按二维表组织；列是字段，带类型
类型与约束	INT/TEXT/REAL…，NOT NULL/DEFAULT/UNIQUE
主键 (PK)	唯一标识一行
外键 (FK)	指向另一表的主键，表达表间关系（1:1 / 1:N / N:N）
索引 (Index)	加速查询的结构（也是 schema 的一部分）
DDL vs DML	CREATE/ALTER TABLE 改 schema；INSERT/SELECT 改/读 data

3. 怎么看 schema（代码）

-- SQLite：查看某表结构
PRAGMA table_info(user);
-- 结果：cid | name | type | notnull | dflt_value | pk
 
-- PostgreSQL / MySQL：查系统视图
SELECT column_name, data_type FROM information_schema.columns
WHERE table_name = 'user';
 
-- 或 psql 里 \d user；MySQL 里 DESCRIBE user;

-- 定义 schema 本身（DDL）
CREATE TABLE user (
  id   INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  age  INTEGER
);

4. MCP 返回的 schema：同名但可能不是一回事 ⚠️

“schema” 这个词在数据库和 MCP/函数调用里都出现，但描述的对象不同，极易混：

• (A) 数据库 schema（本笔记主题）：描述存储的数据结构（表/列/类型）。当某个 MCP Server（如 postgres）把”库的表结构”作为 Resource（资源） 返回给你时，那返回的内容本身就是一个数据库 schema——本质和本节讲的完全相同，MCP 只是”搬运”了它。
• (B) MCP 工具的参数 schema（JSON Schema）：MCP / 函数调用里说的 schema，通常指工具输入参数的结构（JSON Schema），例如 query 工具的参数定义：

  {
    "type": "object",
    "properties": { "query": { "type": "string" } },
    "required": ["query"]
  }

  它告诉模型”调用这个工具要传什么参数、各是什么类型”，本质是工具接口的契约——不是数据蓝图。

一句话：数据库 schema 描述”数据长啥样”；MCP 工具参数 schema 描述”怎么合法调工具”。一个 MCP Server 会同时拥有 (B)（它的工具定义）和可能返回 (A)（当它把库结构当资源暴露时），别把两者画等号。

5. 对比表

维度	数据库 schema	MCP 工具参数 schema（JSON Schema）
描述对象	存储的数据结构（表/列/类型/关系）	工具/函数的输入参数结构
用途	定义数据怎么存、约束一致性	告诉模型怎么生成合法的工具调用
典型形式	CREATE TABLE / information_schema	{type, properties, required}
谁消费	数据库引擎、开发者	LLM（生成 tool_call）+ 框架（校验参数）
例子	user(id INT, name TEXT)	{query: string, required:["query"]}
经 MCP 出现时	作为 Resource / 数据内容返回	作为 tool 定义在发现阶段暴露

6. 常见误区

• ❌ “MCP 返回的 schema 都是数据库表结构” → 不一定。MCP 里说的 schema 多半指工具的参数 schema（JSON Schema）；只有 Server 显式把库结构当资源返回时，那才是数据库 schema。
• ❌ “schema 就是数据” → schema 是结构/蓝图，data 才是内容；改 schema 要迁移，改 data 不要。
• ❌ “工具参数 schema 和数据库 schema 是一回事” → 一个描述”怎么调工具”，一个描述”数据长啥样”，完全不同的东西，只是都叫 schema。
• ❌ “有了 MCP 就不用管 schema” → 模型靠参数 schema 生成调用；真要查库，还得知道库的真实表结构（常需 Server 把 schema 作为资源暴露，见 ../ai-agent-guide/mcp.md 的 postgres 例子）。

7. 延伸阅读 / 关联概念

• SQLite / Turso — 建表就是在定义 schema；见 sqlite-turso.md
• MCP — Tools 的参数 schema（JSON Schema）与 Resources（可返回库结构）；见 ../ai-agent-guide/mcp.md
• Tool Calling — 函数调用的参数 schema 即这里的 (B)；见 ../ai-agent-guide/tool_calling.md
• Hermes — 擅长按 schema 输出工具调用的模型；见 ../ai-agent-guide/hermes.md