Luminus-template 数据库迁移指南：用 luminus-migrations 优雅管理 SQL 版本

Luminus-template 数据库迁移指南：用 luminus-migrations 优雅管理 SQL 版本

【免费下载链接】luminus-templatea template project for the Luminus framework项目地址: https://gitcode.com/gh_mirrors/lu/luminus-template

Luminus-template 是 Clojure 社区最流行的 Web 项目脚手架，它通过一条命令即可生成带数据库、认证、前端等完整能力的应用骨架。对于新手开发者来说，最大的困惑往往不是怎么写业务代码，而是数据库结构如何随代码一起演进。本文将以 Luminus-template 内置的 luminus-migrations 为例，手把手教你用 up/down 迁移文件管理 SQL 版本，告别手动改表、到处同步建表语句的混乱日子。

为什么需要数据库迁移工具

团队协作时，如果每个人都在自己的数据库里手动执行ALTER TABLE，很快就会出现"我本地能跑、你本地报错"的尴尬局面。数据库迁移（Migration）把每一次结构变更固化成带时间戳的 SQL 文件，让所有环境（开发、测试、生产）按同一顺序执行同一批脚本，实现数据库版本与代码版本同步演进。

Luminus-template 默认集成了luminus-migrations与conman两个依赖，关系型数据库（PostgreSQL、MySQL、H2、SQLite）开箱即用。相关依赖声明可以在 db.clj 中看到。

迁移文件在项目中的位置

使用模板生成项目后，resources/migrations目录就是你的"数据库版本仓库"，每个迁移都由一对文件组成：

• 时间戳-名称.up.sql：正向迁移，执行结构变更
• 时间戳-名称.down.sql：反向迁移，回滚本次变更

模板自带的用户表示例就是一对标准迁移文件：add-users-table.up.sql 负责建表，配套的down.sql负责DROP TABLE。命名规则参考 db.clj，时间戳精确到秒，保证执行顺序稳定。

最快配置方法：三步跑通首次迁移

拿到新项目后，按下面的顺序操作即可让数据库"活"起来：

1. 在数据库中创建应用所需的空数据库
2. 修改dev-config.edn与test-config.edn里的:database-url，填入库名和账号密码
3. 在项目根目录执行lein run migrate

命令执行后，luminus-migrations 会读取resources/migrations下所有未执行的迁移文件，按时间戳顺序依次应用，并在数据库中记录已执行版本。这套初始化流程在模板自带的说明文档 db_instructions.md 中有完整描述。

如何编写一对优雅的迁移文件

新增一个"文章表"的迁移，只需两条命令：

1. 在resources/migrations下创建20260820120000-add-posts-table.up.sql
2. 创建同名的20260820120000-add-posts-table.down.sql

up 文件负责建表：

CREATE TABLE posts (id SERIAL PRIMARY KEY, title VARCHAR(100) NOT NULL, body TEXT, created_at TIMESTAMP DEFAULT now());

down 文件必须能完全撤销 up 的操作：

DROP TABLE posts;

编写时记住黄金法则：up 与 down 永远成对出现、彼此可逆。这样在任何环境上你都能放心地前进或回退。

回滚与进阶用法

当你需要撤销最近一次迁移时，执行：

lein run rollback

它会执行最近一个 down 文件。数据库连接由mount状态管理，启动入口在 sql.db.clj，回滚前需确保应用能正常连接到数据库。

如果你使用了 Datomic，Luminus-template 还提供了基于 EDN 事务的迁移方式，示例见 schema.edn，它通过命名空间化的规则（如:project-name/norm1）安装 schema 与初始化数据，思路与 SQL 迁移完全一致。

新手最容易踩的 3 个坑

• 忘记成对文件：只写 up 不写 down，回滚时会直接报错找不到脚本
• 修改已执行的迁移：迁移一经执行就不要改动，新增变更请新建迁移文件
• 忽略执行顺序：文件名时间戳必须递增，否则依赖旧表的迁移会失败

掌握 luminus-migrations 之后，你会发现数据库结构的演进也可以像 Git 一样清晰、可追溯。从今天起，为你的每个 Luminus 项目建立规范的迁移习惯，让团队协作不再为"表结构对不对得上"而头疼。

【免费下载链接】luminus-templatea template project for the Luminus framework项目地址: https://gitcode.com/gh_mirrors/lu/luminus-template