Flyway MCP 服务器
一个模型上下文协议（MCP）服务器，为像Claude Code这样的AI助手提供Flyway数据库迁移管理功能。
此问题所解决的（问题）
如果没有这个MCP服务器，AI助手将直接通过SQL命令修改数据库模式，绕过您的迁移工作流程。这会导致：
- ❌ 未版本控制、未跟踪的数据库更改
- ❌ 环境间存在不一致性
- ❌ 难以重现更改
- ❌ 没有模式修改的审计追踪
解决方案
这个Flyway MCP服务器通过为AI助手提供工具来创建和管理带版本的迁移文件，而不是直接运行SQL命令，从而强制实施正确的迁移实践。
之前（直接SQL）：
You: "Add a users table to the database"
Claude: [Runs CREATE TABLE directly via PostgreSQL MCP]
Result: Untracked schema change ❌之后（使用 Flyway MCP 时）：
You: "Add a users table to the database"
Claude: [Creates V20241022143000__create_users_table.sql]
You: "Apply the migration"
Claude: [Runs flyway_migrate]
Result: Versioned, tracked, repeatable migration ✅特点/功能
- 移民管理创建、应用和跟踪数据库迁移
- 模式验证验证迁移并检查冲突
- 迁移历史查看已应用迁移的详细信息
- 强制工作流鼓励使用迁移文件而非直接修改模式
- 已准备好进行版本控制所有迁移都是可以提交到Git的文件
可用工具
- 初始化项目 - 为项目初始化Flyway（设置迁移文件夹和配置）
- 创建迁移（或“生成迁移脚本”） - 创建遵循适当命名规范的新迁移文件
- Flyway 迁移 - 将待处理的迁移应用于数据库
- Flyway信息 - 获取当前迁移状态和历史记录
- Flyway_Validate（或可译为“Flyway验证”） - 验证已应用的迁移与可用文件是否一致
- flyway_基准线（或flyway_初始状态） - 对现有数据库进行基线分析
- Flyway 修复 - 修复故障后的迁移历史
- flyway_clean 可以翻译为“Flyway 清理”或“Flyway 数据清理”，具体取决于上下文和使用场景。在这里，我选择了较为通用的“Flyway 清理”作为翻译 - 删除所有数据库对象（⚠️ 仅限开发环境使用！)
安装
先决条件
- Node.js v16 或更高版本
- 一个PostgreSQL数据库（或其他Flyway支持的数据库）
设置
- 克隆或下载此仓库
git clone https://github.com/dmattox-sparkcodelabs/Flyway-MCP-Server.git
cd Flyway-MCP-Server- 安装依赖项
npm install- 使脚本可执行
chmod +x index.js- 配置Claude代码
编辑您的Claude桌面配置文件：
Linux：
nano ~/.config/Claude/claude_desktop_config.jsonmacOS：
nano ~/Library/Application\ Support/Claude/claude_desktop_config.jsonWindows：
notepad %APPDATA%\Claude\claude_desktop_config.json添加此配置：
{
"mcpServers": {
"flyway": {
"command": "node",
"args": ["/absolute/path/to/Flyway-MCP-Server/index.js"],
"env": {
"FLYWAY_URL": "postgresql://user:password@host:5432/database",
"FLYWAY_LOCATIONS": "filesystem:/absolute/path/to/your/project/migrations"
}
}
}
}重要提示： 替换为绝对路径：
- 路径至
index.js在这个仓库中 - 指向您的项目迁移目录的路径
- 在Windows系统中，使用正斜杠
/或者转义的反斜杠\\在路径中
- 在你的项目中创建迁移目录
cd /path/to/your/project
mkdir -p migrations- 重启Claude代码
完全退出并重新启动 Claude Code 以使更改生效。
- 验证安装
claude mcp list应显示：
flyway: node /path/to/index.js - ✓ Connected配置
服务器通过Claude代码配置中的环境变量进行配置：
必需的
- FLYWAY_URL 翻译成中文是：“Flyway 数据库连接 URL”。 或者 POSTGRES_CONNECTION_STRING 翻译为中文是：“PostgreSQL 连接字符串” - 数据库连接URL
- 格式： postgresql://user:password@host:port/database - 示例： postgresql://admin:pass123@localhost:5432/mydb
可选
- FLYWAY_LOCATIONS 翻译为中文是“FLYWAY（飞航路径）位置” - 迁移目录（默认：
filesystem:./migrations)
- 示例： filesystem:/home/user/project/migrations - 多个地点： filesystem:./migrations,filesystem:./seeds
- FLYWAY_USER（可译为“Flyway 用户”） - 数据库用户（如果不在URL中）
- FLYWAY_PASSWORD 翻译为中文是“Flyway 密码” - 数据库密码（如果不在URL中）
- FLYWAY_BASELINE_ON_MIGRATE 翻译为中文是：“迁移时启用FLYWAY基线” - 第一次运行时自动设置基线（默认：
false）
WSL/Windows 注释
在使用Windows托管的PostgreSQL与WSL（Windows Subsystem for Linux）时：
{
"FLYWAY_URL": "postgresql://user:pass@host.docker.internal:5432/database"
}多项目支持
Flyway MCP Server 支持通过每个项目的单独配置来处理多个项目。
项目初始化
当你开始一个新的项目时，首先要进行初始化：
问克劳德：
"Initialize Flyway for the project at /home/user/my-project"这将：
- ✅ 创建
migrations/目录（如果不存在） - ✅ 创建
.flyway-mcp.json配置文件 - ✅ 将此项目设置为所有迁移操作的活动项目
项目配置文件 (.flyway-mcp.json):
{
"migrations_path": "./migrations",
"created_at": "2025-01-22T10:30:00.000Z"
}项目切换
只需初始化一个不同的项目即可进行切换：
You: "Initialize Flyway for the ecommerce project at /home/user/ecommerce"
Claude: [Switches to ecommerce project]
You: "Create a migration to add products table"
Claude: [Creates migration in /home/user/ecommerce/migrations/]所有后续操作都将使用当前激活项目的配置。
使用方法
检查迁移状态
问克劳德：
"Show me the Flyway migration status"
"What migrations are pending?"
"Have all migrations been applied?"创建迁移
问克劳德：
"Create a Flyway migration to add a users table with id, username, email, and created_at"
"Create a migration to add an index on the email column"
"Create a migration to add a foreign key from orders to users"克劳德将创建一个类似这样的文件：
migrations/V20241022143000__create_users_table.sql应用迁移
问克劳德：
"Apply the pending Flyway migrations"
"Run the Flyway migrations"
"Migrate the database"验证迁移
问克劳德：
"Validate the Flyway migrations"
"Check for migration conflicts"
"Verify the migration checksums"基线现有数据库
如果您已有一个包含已创建表的数据库：
问克劳德：
"Baseline the Flyway schema history for the existing database"
"Set up Flyway baseline at version 1"《移民档案公约》
迁移文件遵循Flyway的标准命名：
V{YYYYMMDDHHmmss}__{description}.sql示例：
V20241022143000__create_users_table.sql这个 create_migration 工具自动地：
- 生成时间戳
- 净化描述
- 在正确的位置创建文件
工作流程
- 计划 - 确定需要哪种模式更改
- 创建 - 请Claude创建一个Flyway迁移
- 评论 - 检查生成的SQL文件
- 申请 - 请克劳德执行迁移操作
- 验证 - 确认其已成功应用
- 提交（或“提交更改”） - 将迁移文件添加到Git中
最佳实践
✅ 做：
- 始终使用
create_migration对于模式更改 - 在应用迁移文件之前进行审查
- 保持迁移规模小且目标明确
- 使用描述性的迁移名称
- 将迁移文件提交到版本控制系统
- 在生产环境之前，先在本地进行迁移测试
- 跑
flyway_validate在部署之前
❌ 不要：
- 切勿直接运行CREATE/ALTER/DROP命令
- 不要编辑已应用的迁移文件
- 不要删除迁移文件
- 不要使用
flyway_clean正在生产中 - 不要跳过迁移验证
常用命令
| 任务 | 应向Claude询问什么 |
|---|---|
| ------ | ------------------- |
| 检查状态 | “显示Flyway迁移状态” |
| 创建迁移 | “为\[变更\]创建Flyway迁移” |
| 应用迁移 | “应用待处理的 Flyway 迁移” |
| 验证 | “验证Flyway迁移” |
| 基线 | “为Flyway模式历史设置基线” |
| 维修历史 | “修复Flyway模式历史” |
故障排除
服务器无法连接问题
Claude Code 显示 Flyway MCP 为断开连接状态解决方案
- :
args检查路径中的 - 是正确且绝对的
FLYWAY_URL验证 - 已设置且有效
node --version - 确保已安装 Node.js v16 或更高版本：
claude mcp list检查
用于错误消息
迁移目录未找到问题
关于迁移目录的错误解决方案
# Create the directory
mkdir -p /path/to/your/migrations
# Verify FLYWAY_LOCATIONS in config uses absolute path:
数据库连接失败问题
无法连接到数据库解决方案
- ：
- 验证数据库是否正在运行
- 检查连接字符串格式
psql -h host -U user -d database - 测试连接：
host.docker.internal对于WSL（Windows Subsystem for Linux）：使用localhost
而不是
迁移未应用问题 flyway_migrate :
不应用迁移解决方案
- :
- 检查迁移文件是否存在于正确的目录中
V{timestamp}__{description}.sql - 验证文件是否遵循命名规范
- 检查数据库用户是否具有CREATE/ALTER权限
flyway_info跑 - 查看迁移状态
检查迁移SQL中的错误
现有数据库包含表问题
数据库中有表，但没有Flyway历史记录解决方案
Ask Claude: "Baseline the Flyway schema history":
这将您当前的数据库状态标记为起点。
测试 见 TESTING.md 翻译为中文是：“测试说明文件.md” 或者更简洁地 “测试文档.md”（其中 “.md” 表示这是一个Markdown格式的文件）
- 对于；为了
- 运行自动化测试
- 使用MCP Inspector进行交互式测试
- 使用真实数据库进行测试
集成测试设置
好处 ✅ 版本控制 \- 所有模式变更均在Git中追踪 ✅ 重复性 \- 相同的迁移方案适用于所有环境 ✅ 安全 \- 防止意外的直接模式更改 ✅ 可审计性 \- 所有模式修改的完整历史记录 ✅ 准备就绪，可进行持续集成/持续交付（CI/CD） \- 在数据流中可以实现迁移的自动化 ✅（对号，表示正确、确认或完成） 团队协作
- 每个人都使用相同的迁移文件
与其他MCP的集成
- 这个MCP与您现有的MCP服务器协同工作： Azure DevOps MCP（Microsoft Certified Professional，微软认证专业人员，此处特指Azure DevOps方向）
- - 对于工作项、拉取请求（PRs）、构建（Builds） PostgreSQL MCP（PostgreSQL管理认证计划/PostgreSQL管理认证）
- - 用于查询数据（读取操作） Flyway MCP（注：MCP在此处可能代表特定的缩写或术语，根据上下文可能翻译为“Flyway的MCP（某特定概念/项目/版本等）”，但具体含义需结合上下文确定，若MCP无特定含义则可保持原样或根据实际情况调整）
\- 对于模式变更（通过迁移进行的写入操作）
每个都有其特定的用途，互不重叠。
- 安全注意事项
- 凭据通过环境变量传递（绝不在代码中硬编码）
flyway_clean这个（或“该”） - 该命令存在风险 - 仅在开发环境中使用
- 无身份验证/授权 - 依赖于MCP客户端的安全性
- 数据库权限应根据环境进行限制
迁移文件以进程用户权限写入
- 建筑学 单文件MCP服务器
index.js-server.js（与……一起）带着 - 模块协议
- 通过stdio传输的模型上下文协议运行时
- Node.js（v16+）迁移工具
node-flywayFlyway 通过 - 包装器；外壳；封装验证
用于类型安全参数的Zod模式
许可证
麻省理工学院许可证 - 版权所有 (c) 2025 David Mattox @ SparkCodeLabs.com 见 许可证
文件中有详细信息。
做出贡献 欢迎提出问题和提交拉取请求，请访问：