给 AI 开发者 / Vibe Coder

这一节是这个站点和官方文档最大的差异化所在。MariaDB 几十年的文档是写给 DBA 的，但今天的开发者越来越多通过 LLM 间接操作数据库。这些范式过去没人系统整理过。

1. LLM 友好的 Schema 设计

LLM 在没有 schema 注释的情况下经常猜错列含义。给表和列写结构化注释，是让 Agent 写对 SQL 的最便宜投资。

CREATE TABLE orders (
  id          BIGINT AUTO_INCREMENT PRIMARY KEY
              COMMENT '订单号，全局唯一',
  user_id     BIGINT NOT NULL
              COMMENT 'FK -> users.id，下单用户',
  amount_cents INT NOT NULL
              COMMENT '金额，以分为单位（人民币）',
  status      ENUM('pending','paid','shipped','cancelled') NOT NULL
              COMMENT '订单状态机：pending->paid->shipped；任何状态都可 cancelled',
  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
              COMMENT '下单时间（服务器本地时区）',
  INDEX idx_user_created (user_id, created_at)
) COMMENT='电商订单主表';

把这些注释通过 INFORMATION_SCHEMA.COLUMNS.COLUMN_COMMENT 拉出来塞进 Agent 的上下文，准确率会显著提升。

命名也要 LLM 友好

✅ 推荐	❌ 避免	原因
`order_amount_cents`	`oac` / `amt2`	缩写让 LLM 猜错
`is_active`	`flag1`	布尔列加 `is_` 前缀
`created_at` / `updated_at`	`ctime` / `mtime`	行业标准
`status` 用 ENUM 而非字符串	`status_code = 'A'`	ENUM 在 schema 里可枚举值，LLM 一看就懂

2. MCP 接入 MariaDB

Model Context Protocol 是 Anthropic 提出的开放标准，让 AI 助手以受控方式访问外部系统。MariaDB 可以通过通用 MySQL MCP server 接入，因为协议层完全兼容。

在 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "mariadb-playground": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "readonly",
        "MYSQL_PASSWORD": "xxx",
        "MYSQL_DATABASE": "playground"
      }
    }
  }
}

Cursor 在 ~/.cursor/mcp.json 用一样的配置：

{
  "mcpServers": {
    "mariadb": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-mysql"],
      "env": { "MYSQL_HOST": "...", "MYSQL_USER": "readonly" }
    }
  }
}

任何支持 MCP 的 SDK 都行：

import { McpServer } from '@modelcontextprotocol/sdk/server';
import { connect } from 'mysql2/promise';

const db = await connect({ host: '127.0.0.1', user: 'readonly', database: 'playground' });
// 在 server 里注册 tools: list_tables, describe_table, run_query…

永远给 MCP 用只读账号，并限制到特定 database。Agent 出错的代价比人类大得多。

3. Agent 安全写库的几个范式

让 Agent 直接 UPDATE / DELETE 是最危险的姿势。推荐三种安全包装：

范式 A：影子表 + 人工 review

Agent 只写到 staging_* 表，CI 跑 diff，人工合并到主表。

范式 B：事务 + 行数上限

START TRANSACTION;
-- agent 生成的语句
UPDATE orders SET status='cancelled' WHERE user_id = 42;
-- 检查影响行数
SELECT ROW_COUNT();  -- 如果远超预期，回滚
-- ROLLBACK 或 COMMIT

范式 C：通过应用层 API，而不是直连 SQL

Agent 调用你提供的 cancel_order(order_id) 工具，工具内部用 prepared statement，参数被强类型校验。这是生产环境的默认推荐。

4. 向量检索：MariaDB 也能干

MariaDB 11.7 起原生支持 VECTOR 数据类型和近似最近邻索引（HNSW），你不需要单独装 pgvector / Pinecone / Qdrant 就能做 RAG。

CREATE TABLE doc_chunks (
  id       BIGINT AUTO_INCREMENT PRIMARY KEY,
  content  TEXT,
  embed    VECTOR(1536) NOT NULL,
  VECTOR INDEX (embed)
);

-- 查询：找出与查询向量最相似的 5 段
SELECT id, content,
       VEC_DISTANCE_EUCLIDEAN(embed, VEC_FromText('[0.1,0.2,...]')) AS dist
FROM doc_chunks
ORDER BY dist
LIMIT 5;

详见 MariaDB Vector 官方文档。

5. Vibe Coding Recipes

一些日常 prompt 模板，可以直接抄进 Cursor / Claude Code 的 rules 文件：

## MariaDB rules

- 用 `utf8mb4_unicode_ci`，永远不用 `utf8`
- 主键统一 `BIGINT AUTO_INCREMENT PRIMARY KEY`，业务字段不做主键
- 所有金额用 `*_cents INT/BIGINT`，避免浮点
- 时间列固定 `created_at` / `updated_at DATETIME DEFAULT CURRENT_TIMESTAMP`
- 写 `UPDATE`/`DELETE` 前必须带 `WHERE`；如果不带，必须显式标注 `-- intentional: full table`
- 不要用 MyISAM；新表默认 InnoDB
- 不要写 `SELECT *`，明确列出列名