打开项目连上数据库手工跑一遍SQL文件——这可能是很多Java后端同事每天都在重复做的事情。时间一长问题就来了测试环境换了一批机器脚本要重跑同事加了个新表你本地数据对不上CI流水线部署了好几次数据库结构早就和代码脱节了。Spring Boot其实自带了一套完整的SQL导入机制但很多人用起来总是踩坑要么是文件压根不执行要么是重复执行导致数据错乱要么是导入过程中断后不知道怎么恢复。这篇就聊聊我在Spring Boot导入SQL文件这件事上折腾出来的几个靠谱姿势从原生机制到代码导入方案再到迁移工具选型把这个问题彻底讲透。1. 项目启动时的SQL初始化到底怎么工作1.1 原生机制的执行条件Spring Boot从2.5版本开始把SQL初始化逻辑统一到了spring.sql.init.*这组配置项下更早版本用的是spring.datasource.initialization-mode。你不需要写任何代码只要把文件放到指定位置项目启动时就会自动执行。具体来说放在classpath根目录下的schema.sql会在数据源初始化之后自动执行紧接着data.sql会执行。默认情况下schema.sql负责建表、改表结构data.sql负责灌数据两者都可以通过配置控制是否重复执行。这里有一个非常关键的混淆点很多人以为schema.sql在应用启动时一定会执行但它有一个重要的前置条件——如果你用了JPA且没有配置ddl-autoSpring Boot会优先让Hibernate根据Entity映射生成表然后才轮到schema.sql执行。结果就是你的schema.sql里写了CREATE TABLE启动日志却显示表已存在因为Hibernate已经帮你把表建好了。1.2 关键配置项说明spring.sql.init.mode这个配置决定SQL文件在什么数据源上执行有embedded和always两个值。默认是embedded意味着只有内嵌数据库比如H2、HSQLDB才会执行MySQL、PostgreSQL这些外部数据库默认不执行。很多开发同学在本地连MySQL时发现schema.sql静悄悄没反应八成就是mode没改成always。实际开发中需要区分环境常见的配置写法是这样的spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver sql: init: mode: always schema-locations: classpath:sql/schema.sql >Bean public DataSourceScriptDatabaseInitializer dataSourceScriptDatabaseInitializer( DataSource dataSource, Value(classpath:sql/custom.sql) Resource resource) { var settings new ScriptDatabaseInitializerSettings(); settings.setEncoding(UTF-8); settings.setContinueOnError(false); settings.setSeparator(;); return new DataSourceScriptDatabaseInitializer(dataSource, List.of(resource), settings); }这个类的执行时机和默认配置的初始化器一样都是在DataSource初始化完成后立刻执行。如果你想让它晚一点执行可以加DependsOn依赖或者用事件监听器包一层后文第4章会给出一个在应用完全启动后执行SQL的完整方案。说实话日常开发中绝大多数情况用配置文件就搞定了自定义初始化器更多是为了解决按固定顺序执行多份脚本、执行完要记录日志这类特殊诉求。如果只是想把几个SQL文件导入数据库先不要急着写Java代码。2. 运行时按需导入SQL文件从文件读取到逐条执行2.1 为什么需要运行时导入项目启动时自动初始化适合的场景是数据库是全新的、没有手工改过的数据、每次部署只执行一次。但实际开发中还有大量场景需要运行中导入运维人员上传了一个新的SQL脚本要求立刻在运行中的实例上执行又不能重启服务系统里做一个数据恢复功能用户选择备份文件应用读取文件内容后导入数据库多租户场景下每个租户注册时要动态建库建表schema.sql那套固定脚本根本没法覆盖。这种时候你需要在代码里手写一套SQL文件导入逻辑。看起来简单其实坑非常多。先给一套完整实现再讲最容易翻车的脚本切分问题。2.2 基于JdbcTemplate的导入工具类import org.springframework.core.io.ClassPathResource; import org.springframework.jdbc.core.JdbcTemplate; import org.springframework.stereotype.Component; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.util.List; Component public class SqlImportService { private final JdbcTemplate jdbcTemplate; public SqlImportService(JdbcTemplate jdbcTemplate) { this.jdbcTemplate jdbcTemplate; } public void importFromClasspath(String classpathFile) throws Exception { ClassPathResource resource new ClassPathResource(classpathFile); String sql new String(resource.getInputStream().readAllBytes(), StandardCharsets.UTF_8); executeSplitSql(sql); } public void importFromFile(String filePath) throws Exception { String sql Files.readString(java.nio.file.Path.of(filePath), StandardCharsets.UTF_8); executeSplitSql(sql); } private void executeSplitSql(String sql) { ListString statements splitSqlStatements(sql); for (String statement : statements) { jdbcTemplate.execute(statement); } } }看到这里你可能会觉得这也太简单了吧读文件、按分号切分、循环执行三行搞定真正用起来你就知道splitSqlStatements这个方法能不能写好直接决定你的导入功能是稳定上线还是上线了马上被人骂。2.3 SQL脚本切分的三大难题第一注释问题。SQL文件里常见两种注释--开头的行注释和/* */包裹的块注释。如果切分时没处理掉注释一个--注释里恰好包含分号就会把一个完整语句拦腰截断。更麻烦的是块注释内部可能有多行多个分号直接按分号切会产生一堆空语句。第二字符串字面量里的分号。INSERT INTO t VALUES (a;b;c);这一条里字符串a;b;c内部的分号绝对不能当作语句结束符。要正确处理你必须写出一个能区分引号内分号和语句结束分号的切分器。第三存储过程、函数、触发器的DELIMITER问题。这是最痛的点。MySQL的存储过程定义通常要写DELIMITER $$ ... END$$体内部全是分号你完全不能按照普通语法规则去切分。Spring Boot自带的ScriptUtils虽然解决了前两个问题但对DELIMITER的处理也不能算完美——它确实有相关逻辑但遇到复杂的定义经常出错。我在项目里用的切分策略是逐字符扫描private ListString splitSqlStatements(String sql) { ListString statements new ArrayList(); StringBuilder currentStatement new StringBuilder(); boolean inSingleQuote false; boolean inDoubleQuote false; boolean inLineComment false; boolean inBlockComment false; for (int i 0; i sql.length(); i) { char c sql.charAt(i); char next i 1 sql.length() ? sql.charAt(i 1) : 0; if (inLineComment) { if (c \n) { inLineComment false; currentStatement.append(c); } continue; } if (inBlockComment) { if (c * next /) { inBlockComment false; i; } continue; } if (inSingleQuote) { currentStatement.append(c); if (c \ next \) { currentStatement.append(next); i; } else if (c \\) { currentStatement.append(next); i; } else if (c \) { inSingleQuote false; } continue; } if (inDoubleQuote) { currentStatement.append(c); if (c ) { inDoubleQuote false; } continue; } if (c - next -) { inLineComment true; i; continue; } if (c / next *) { inBlockComment true; i; continue; } if (c \) { inSingleQuote true; currentStatement.append(c); continue; } if (c ) { inDoubleQuote true; currentStatement.append(c); continue; } if (c ;) { String statement currentStatement.toString().trim(); if (!statement.isEmpty()) { statements.add(statement); } currentStatement.setLength(0); continue; } currentStatement.append(c); } String statement currentStatement.toString().trim(); if (!statement.isEmpty()) { statements.add(statement); } return statements; }这段代码处理了行注释、块注释、单引号、双引号和转义基本覆盖日常90%以上的SQL文件。但要注意MySQL的DELIMITER关键字还是需要单独预处理。我的做法是执行前检查脚本里有没有DELIMITER如果存在就先用正则把整个存储过程块提取出来再单独交给JDBC执行而不是塞进普通的逐条执行流水线。如果你不想自己造轮子Spring Boot自带的org.springframework.jdbc.datasource.init.ScriptUtils也可以帮你切分它提供了splitSqlScript方法可以传不同的分隔符参数。但实测下来它对MySQL的DELIMITER支持确实有限遇到复杂的存储过程还是自己处理更踏实。2.4 大文件导入的性能与事务策略如果是几百KB的小SQL文件上面那套循环执行就够了。但如果要导入的备份文件有几百MB逐条execute会慢到让你怀疑人生而且一旦中途出错之前执行的SQL全部无法回滚。我的建议是控制事务边界批量提交。做法很简单在执行前把自动提交关掉手动控制每N条语句提交一次public void importLargeSql(String filePath) throws Exception { Connection connection DataSourceUtils.getConnection(jdbcTemplate.getDataSource()); try { connection.setAutoCommit(false); ListString statements splitSqlStatements(Files.readString(Path.of(filePath))); int batchSize 100; int count 0; for (String statement : statements) { jdbcTemplate.execute(statement); count; if (count % batchSize 0) { connection.commit(); } } connection.commit(); } catch (Exception e) { connection.rollback(); throw e; } finally { DataSourceUtils.releaseConnection(connection, jdbcTemplate.getDataSource()); } }注意MySQL的DDL语句自带隐式提交你没法把CREATE TABLE放进一个事务里回滚所以整个文件要么全部成功要么全部失败在MySQL上做不到。实际工程里更通用的策略是先记录执行日志表每执行完一条记录一条失败了从出错的语句继续而不是把所有SQL强行包在一个事务里。我踩过的坑曾经有一次线上数据恢复把30万行INSERT塞进一个事务里执行结果跑了很久还没跑完最后连接超时中间状态的脏数据反而要把人逼疯。后来改成每500条commit一次性能和可控性都好了很多。3. 更正式的做法把SQL文件交给Flyway管理3.1 为什么原生机制不够用schema.sql和data.sql这套原生机制在项目早期和原型开发阶段非常爽文件往resources里一放项目一启动表也有了测试数据也齐全了。但项目发展到多环境、多人协作之后这套机制就逐渐暴露一个问题没有版本管理。你跟同事各改了一份schema.sql合代码的时候到底以谁为准生产环境已经执行过V1版本的建表语句新版本的schema.sql里如果包含整库重建的脚本你直接往生产库里跑数据库里的表全被清空重来这显然不行。所以正规一点的团队都会引入专门的数据库版本迁移工具最主流的就是Flyway和Liquibase。3.2 Flyway的基础用法Flyway的思路很简单用版本号管理每一份SQL脚本。脚本文件命名遵循V{n}__{描述}.sql比如V1__init_schema.sql、V2__add_user_table.sql、V3__insert_config_data.sql。Flyway会在数据库中创建一个flyway_schema_history表每次执行完一个脚本就插入一条记录。下次启动时它只执行那些还没在历史表里出现过的脚本。接入Flyway非常轻松Spring Boot的spring-boot-starter依赖已经内置了Flyway只要classpath里有flyway-core的依赖Spring Boot就会自动把Flyway挂到数据源初始化流程上dependency groupIdorg.flywaydb/groupId artifactIdflyway-core/artifactId version9.16.3/version /dependency脚本放在src/main/resources/db/migration目录下命名规则V1__xxx.sql、V2__xxx.sql启动时自动按顺序执行。我目前的个人习惯是V1开头建基础表结构V2开头加业务表V3开头补索引和修改字段V4开头初始化固定数据数据字典、配置参数。命名上建议保持纯英文避免中文文件名在不同平台和文件系统下产生识别问题。3.3 Flyway实操时的几个注意事项第一一旦执行过的脚本文件绝对不能改动。Flyway校验的是文件的checksum如果你改了某个历史脚本的内容并再次启动应用启动直接报错提示校验和不匹配。这不是Flyway在找茬恰恰是它在保护你——防止有人偷偷改了已经上生产的脚本。第二要区分结构迁移和数据迁移。结构迁移脚本里尽量只写DDL不要混入大批量DML数据迁移脚本里写明幂等操作比如INSERT可以用INSERT IGNORE、ON DUPLICATE KEY UPDATE或者先用DELETE再INSERT避免重复插入导致主键冲突。在Flyway机制下每个脚本只会执行一次但数据脚本在执行时仍然要考虑重复插入情况——脚本虽然一次性执行但数据本身可能在多个环境反复导入。第三生产环境的新增字段最好写成一条完整的ALTER TABLE语句。有些数据库对一条ALTER TABLE只支持修改一个字段但MySQL支持在同一条ALTER TABLE里写多个ADD COLUMN。尽量把ADD COLUMN和MODIFY COLUMN写在一起减少执行多次失败的概率。3.4 什么时候选择LiquibaseLiquibase和Flyway的核心思路不同。Liquibase使用统一的changeLog文件来管理变更changelog里每一个changeSet记录一次数据库变更这些变更可以用SQL写也可以用Liquibase自有的XML/YAML格式写。它最大的优势是可以跨数据库类型写一份changeSetMySQL、PostgreSQL、Oracle都能跑Liquibase会自动把通用操作翻译成目标数据库的方言。如果你的产品要同时支持多个数据库Liquibase比Flyway合适。如果你只用一种数据库更看重简单直接的SQL脚本Flyway会更加顺手。我个人日常用的还是Flyway理由有两条一是SQL脚本一眼能看懂二是命名和版本管理很直观。但请你理解这是技术选型问题不是绝对好坏问题。4. 后台系统内置SQL导入功能怎么做4.1 需求形态除了项目启动时初始化和数据库版本迁移还有一类场景是给系统做一个在线SQL导入功能——管理员在后台选择SQL文件上传应用解析并执行常用于运营后台的数据修复、测试平台的数据准备、SaaS租户的数据初始化。这种功能要作为独立模块来设计不能跟schema.sql、Flyway混在一起。这类功能的实现要点有三个上传文件的存储位置、SQL解析与执行、执行结果反馈。前面给的SqlImportService可以复用这里补充几个管理后台特有的注意点。4.2 防止误操作与权限控制能在后台导入SQL的人等于拿着数据库的写权限在线上操作。所以这个功能必须做权限控制通常要配到管理员级别并且所有操作留审计日志。我做过的一个后台模块里每次执行前会把SQL文件内容、执行人、执行时间、执行结果存入operation_log表万一出了问题可以追溯。还要考虑一个很多新手容易忽略的点导入功能要支持预览确认流程。管理员上传文件后系统解析出前20条SQL展示出来让管理员确认没问题才真正执行。步骤很简单但能非常有效地防止误操作。实际项目中我有一次就是因为预览时发现脚本里混了一条DROP TABLE语句才避免了一次事故。4.3 有状态执行支持断点续跑文件大到一定程度或者中途网络断开、数据库连接异常导入就会中断。真要做得可靠你需要引入执行状态机每个导入任务有一个taskId执行前在任务表记录待执行状态每执行N条SQL更新一次已执行条数失败时记录失败语句和异常堆栈任务状态变成失败重试时优先从失败位置继续。有了这些运维人员就能在一个任务中断后不慌不忙地点击继续不用从头再来。我见过不少项目没有这个设计一个几百万行数据的导入一旦失败就要从头再来特别痛苦。在实现上你可以给SqlImportService增加一个执行进度回调接口public interface ImportProgressListener { void onProgress(String taskId, int completed, int total); void onError(String taskId, String sql, Exception e); }循环执行的时候每执行完一条就调用listener上报进度页面端用WebSocket或者轮询接口展示进度条。这个方案实现成本不高但体验提升非常明显。4.4 在应用启动完成后执行SQL有些场景要求应用整个启动完成后再执行SQL不能用默认初始化器也不能用Flyway的自动迁移。可以监听ApplicationReadyEventComponent public class SqlImportOnReadyRunner { EventListener(ApplicationReadyEvent.class) public void onReady() { if (shouldImport()) { sqlImportService.importFromClasspath(sql/post-startup.sql); } } }这种方式的典型用途包括从某个外部工单系统拉取脚本之后执行、启动时动态生成租户库、或者执行一些依赖完整Spring容器状态的初始化逻辑。需要注意ApplicationReadyEvent在测试环境可能触发多次所以shouldImport()里最好加个标志位或者用数据库记录防止重复执行。5. 常见问题与排查技巧实录5.1 schema.sql不执行排查路径非常固定确认spring.sql.init.mode是不是always。外部数据库默认是embedded不动配置的话文件不会被加载。确认文件路径是否匹配schema-locations。如果配置了classpath:sql/schema.sql就确认resources/sql/schema.sql真的存在注意编译输出目录target/classes下有没有。确认数据源是否正常初始化。如果项目里手动定义了一个DataSource的Bean并且没有交给Spring Boot管理初始化器可能拿不到你的数据源。看启动日志。Spring Boot会打一条ScriptUtils相关的日志如果SQL文件被成功执行你能看到每条语句的执行输出。我在本地遇到过最隐蔽的一次schema.sql能被加载但因为里面的CREATE TABLE语句没有加IF NOT EXISTS而Hibernate又提前根据Entity建了表导致启动直接报错。排查了半天才发现是Hibernate建表和schema.sql的冲突问题。建议关闭Hibernate的ddl-auto设置成none让建表统一交给schema.sql或者把建表任务交给Flyway不要两套机制并存。5.2 data.sql重复执行导致数据重复原生机制下data.sql每次启动都会执行。如果你的data.sql里是纯INSERT语句第二次启动就会因为主键冲突报错。解决方案有三个用INSERT IGNORE / ON DUPLICATE KEY UPDATE启动时先执行DELETE FROM xxx再INSERT保证初始化数据的整体替换把数据初始化任务交给Flyway的版本化脚本保证只执行一次。5.3 中文乱码SQL文件里的中文注释或者中文数据在入库后变问号通常是编码链路上出了问题。确保文件本身是UTF-8编码、spring.sql.init.encodingutf-8、数据库连接URL上带上characterEncodingutf8、数据库表字段的collation是utf8mb4_general_ci或者utf8mb4_unicode_ci。实操中我建议在pom.xml里配置resource的编码过滤properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /properties这样Maven在复制resource文件的时候不会重新编码能降低一类莫名其妙的乱码问题。5.4 Flyway校验失败启动日志里常见的信息是Validation failed for migration V2__xxx.sql。解决办法看情况如果你确实没有改过历史脚本对比当前文件内容再用版本管理工具看一下git diff搞清楚脚本最后一次改动的内容。如果必须改脚本且这个脚本只在开发环境执行过可以删除本地flyway_schema_history里对应的记录再让Flyway重新执行。生产环境千万别这么干。最稳妥的办法不要去改历史脚本而是写一个新脚本比如V2_1__fix_something.sql把需要的变更写在里面。这是Flyway社区推荐的规范操作。5.5 大SQL文件导入时出现PacketTooLargeExceptionMySQL默认的max_allowed_packet通常是4MB如果你的SQL文件里某一条INSERT的SQL非常长、或者包含很大的BLOB文本超过了这个限制就会报PacketTooLargeException。解决办法修改MySQL的全局参数SET GLOBAL max_allowed_packet 64 * 1024 * 1024;需要超级权限在数据库连接URL上配置maxAllowedPacket属性比如jdbc:mysql://localhost:3306/demo?maxAllowedPacket67108864代码层面尽量把大字段拆成小块插入或者在SQL脚本里避免写超长单条语句。5.6 执行顺序不可控默认情况下schema.sql会先于data.sql但如果你配了多个data-locations它们之间的顺序是按照配置列表中的顺序执行的。如果要控制多个文件之间的严格顺序建议自定义初始化器或者用Flyway的版本号排序而不是依赖配置列表的偶然顺序。把常见的排查要点整理成一个速查表症状可能原因建议处理schema.sql未执行modeembedded外部数据库不执行改为always启动报表已存在Hibernate先建表schema.sql再建表关闭ddl-auto统一建表方式data.sql重复数据纯INSERT无幂等处理改为INSERT IGNORE或结合Flyway中文乱码编码链路不一致文件、连接、数据库字符集统一UTF-8Flyway校验失败历史脚本被修改禁止改历史脚本写新迁移脚本PacketTooLarge单条SQL超过max_allowed_packet调整数据库参数或拆分SQLSQL执行顺序错乱多位置路由不对用Flyway版本号或自定义初始化器6. 我最终推荐的技术组合6.1 不同阶段的技术选择这个话题说到底没有一套方案能覆盖所有场景。我个人的选择标准是这样的项目还在玩具阶段、个人项目、或者演示Demo直接用Spring Boot原生schema.sql data.sql配置一个always模式就完事简单快速零学习成本。项目开始有多个环境、多人协作、需要管理数据库结构变更时马上引入Flyway。把建表和改表脚本全交给版本化迁移原生schema.sql就可以退场了。数据初始化脚本放在Flyway里但要注意书写幂等。运维后台需要在线导数据、做数据恢复、一键初始化租户数据时用前面那套SqlImportService加上进度监听和审计日志不要在Flyway里混入临时数据操作。一句话总结就是能自动就自动能版本化就版本化涉及用户交互和临时数据的管理后台操作再走代码导入。6.2 给入门同学的一个最小可运行示例如果是刚开始接触Spring Boot的新人还没到看长篇大论的时候直接照着下面这个最小示例上手最快先建一个Spring Boot项目引入spring-boot-starter-jdbc和MySQL驱动。在application.yml里配置好数据源。在src/main/resources下新建schema.sqlCREATE TABLE IF NOT EXISTS user ( id BIGINT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE IF NOT EXISTS config ( config_key VARCHAR(50) PRIMARY KEY, config_value VARCHAR(500), updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP );再建data.sqlINSERT INTO config (config_key, config_value) VALUES (system.name, Demo System); INSERT INTO config (config_key, config_value) VALUES (system.version, 1.0.0);application.yml里加spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: root sql: init: mode: always continue-on-error: false启动项目后打开数据库客户端就能看到两张表和两条初始化数据。整个过程不需要写一行Java代码。这个示例里用了IF NOT EXISTS所以即使项目多次重启schema.sql也不会因为重复建表报错。config表是核心配置表data.sql里如果每次重启都重复INSERT第二次启动就会主键冲突。要解决这个问题可以把INSERT改成INSERT INTO config (config_key, config_value) VALUES (system.name, Demo System) ON DUPLICATE KEY UPDATE config_value VALUES(config_value);这样就可以反复启动了。6.3 最后一个建议在Spring Boot里导入SQL文件方案看着五花八门本质其实就三个选择启动自动执行、代码手动导入、迁移工具版本管理。把这三种方式的适用场景分清楚你就不会再为SQL文件到底该放哪这种问题纠结了。我能给的最大建议是不要把所有SQL都堆在schema.sql里也不要什么情况都想着写一段Java执行代码找到最适合当前项目阶段的方式才是重点。踩过几次坑之后我现在的习惯是先问自己三个问题这个数据库是全新的还是已有数据的这批SQL是固定结构还是临时数据执行失败后能不能从头再来三个问题回答完用哪套方案基本就清楚了。希望这篇文章能帮你少走几步弯路。
打开项目连上数据库手工跑一遍SQL文件——这可能是很多Java后端同事每天都在重复做的事情。时间一长问题就来了测试环境换了一批机器脚本要重跑同事加了个新表你本地数据对不上CI流水线部署了好几次数据库结构早就和代码脱节了。Spring Boot其实自带了一套完整的SQL导入机制但很多人用起来总是踩坑要么是文件压根不执行要么是重复执行导致数据错乱要么是导入过程中断后不知道怎么恢复。这篇就聊聊我在Spring Boot导入SQL文件这件事上折腾出来的几个靠谱姿势从原生机制到代码导入方案再到迁移工具选型把这个问题彻底讲透。1. 项目启动时的SQL初始化到底怎么工作1.1 原生机制的执行条件Spring Boot从2.5版本开始把SQL初始化逻辑统一到了spring.sql.init.*这组配置项下更早版本用的是spring.datasource.initialization-mode。你不需要写任何代码只要把文件放到指定位置项目启动时就会自动执行。具体来说放在classpath根目录下的schema.sql会在数据源初始化之后自动执行紧接着data.sql会执行。默认情况下schema.sql负责建表、改表结构data.sql负责灌数据两者都可以通过配置控制是否重复执行。这里有一个非常关键的混淆点很多人以为schema.sql在应用启动时一定会执行但它有一个重要的前置条件——如果你用了JPA且没有配置ddl-autoSpring Boot会优先让Hibernate根据Entity映射生成表然后才轮到schema.sql执行。结果就是你的schema.sql里写了CREATE TABLE启动日志却显示表已存在因为Hibernate已经帮你把表建好了。1.2 关键配置项说明spring.sql.init.mode这个配置决定SQL文件在什么数据源上执行有embedded和always两个值。默认是embedded意味着只有内嵌数据库比如H2、HSQLDB才会执行MySQL、PostgreSQL这些外部数据库默认不执行。很多开发同学在本地连MySQL时发现schema.sql静悄悄没反应八成就是mode没改成always。实际开发中需要区分环境常见的配置写法是这样的spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver sql: init: mode: always schema-locations: classpath:sql/schema.sql >Bean public DataSourceScriptDatabaseInitializer dataSourceScriptDatabaseInitializer( DataSource dataSource, Value(classpath:sql/custom.sql) Resource resource) { var settings new ScriptDatabaseInitializerSettings(); settings.setEncoding(UTF-8); settings.setContinueOnError(false); settings.setSeparator(;); return new DataSourceScriptDatabaseInitializer(dataSource, List.of(resource), settings); }这个类的执行时机和默认配置的初始化器一样都是在DataSource初始化完成后立刻执行。如果你想让它晚一点执行可以加DependsOn依赖或者用事件监听器包一层后文第4章会给出一个在应用完全启动后执行SQL的完整方案。说实话日常开发中绝大多数情况用配置文件就搞定了自定义初始化器更多是为了解决按固定顺序执行多份脚本、执行完要记录日志这类特殊诉求。如果只是想把几个SQL文件导入数据库先不要急着写Java代码。2. 运行时按需导入SQL文件从文件读取到逐条执行2.1 为什么需要运行时导入项目启动时自动初始化适合的场景是数据库是全新的、没有手工改过的数据、每次部署只执行一次。但实际开发中还有大量场景需要运行中导入运维人员上传了一个新的SQL脚本要求立刻在运行中的实例上执行又不能重启服务系统里做一个数据恢复功能用户选择备份文件应用读取文件内容后导入数据库多租户场景下每个租户注册时要动态建库建表schema.sql那套固定脚本根本没法覆盖。这种时候你需要在代码里手写一套SQL文件导入逻辑。看起来简单其实坑非常多。先给一套完整实现再讲最容易翻车的脚本切分问题。2.2 基于JdbcTemplate的导入工具类import org.springframework.core.io.ClassPathResource; import org.springframework.jdbc.core.JdbcTemplate; import org.springframework.stereotype.Component; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.util.List; Component public class SqlImportService { private final JdbcTemplate jdbcTemplate; public SqlImportService(JdbcTemplate jdbcTemplate) { this.jdbcTemplate jdbcTemplate; } public void importFromClasspath(String classpathFile) throws Exception { ClassPathResource resource new ClassPathResource(classpathFile); String sql new String(resource.getInputStream().readAllBytes(), StandardCharsets.UTF_8); executeSplitSql(sql); } public void importFromFile(String filePath) throws Exception { String sql Files.readString(java.nio.file.Path.of(filePath), StandardCharsets.UTF_8); executeSplitSql(sql); } private void executeSplitSql(String sql) { ListString statements splitSqlStatements(sql); for (String statement : statements) { jdbcTemplate.execute(statement); } } }看到这里你可能会觉得这也太简单了吧读文件、按分号切分、循环执行三行搞定真正用起来你就知道splitSqlStatements这个方法能不能写好直接决定你的导入功能是稳定上线还是上线了马上被人骂。2.3 SQL脚本切分的三大难题第一注释问题。SQL文件里常见两种注释--开头的行注释和/* */包裹的块注释。如果切分时没处理掉注释一个--注释里恰好包含分号就会把一个完整语句拦腰截断。更麻烦的是块注释内部可能有多行多个分号直接按分号切会产生一堆空语句。第二字符串字面量里的分号。INSERT INTO t VALUES (a;b;c);这一条里字符串a;b;c内部的分号绝对不能当作语句结束符。要正确处理你必须写出一个能区分引号内分号和语句结束分号的切分器。第三存储过程、函数、触发器的DELIMITER问题。这是最痛的点。MySQL的存储过程定义通常要写DELIMITER $$ ... END$$体内部全是分号你完全不能按照普通语法规则去切分。Spring Boot自带的ScriptUtils虽然解决了前两个问题但对DELIMITER的处理也不能算完美——它确实有相关逻辑但遇到复杂的定义经常出错。我在项目里用的切分策略是逐字符扫描private ListString splitSqlStatements(String sql) { ListString statements new ArrayList(); StringBuilder currentStatement new StringBuilder(); boolean inSingleQuote false; boolean inDoubleQuote false; boolean inLineComment false; boolean inBlockComment false; for (int i 0; i sql.length(); i) { char c sql.charAt(i); char next i 1 sql.length() ? sql.charAt(i 1) : 0; if (inLineComment) { if (c \n) { inLineComment false; currentStatement.append(c); } continue; } if (inBlockComment) { if (c * next /) { inBlockComment false; i; } continue; } if (inSingleQuote) { currentStatement.append(c); if (c \ next \) { currentStatement.append(next); i; } else if (c \\) { currentStatement.append(next); i; } else if (c \) { inSingleQuote false; } continue; } if (inDoubleQuote) { currentStatement.append(c); if (c ) { inDoubleQuote false; } continue; } if (c - next -) { inLineComment true; i; continue; } if (c / next *) { inBlockComment true; i; continue; } if (c \) { inSingleQuote true; currentStatement.append(c); continue; } if (c ) { inDoubleQuote true; currentStatement.append(c); continue; } if (c ;) { String statement currentStatement.toString().trim(); if (!statement.isEmpty()) { statements.add(statement); } currentStatement.setLength(0); continue; } currentStatement.append(c); } String statement currentStatement.toString().trim(); if (!statement.isEmpty()) { statements.add(statement); } return statements; }这段代码处理了行注释、块注释、单引号、双引号和转义基本覆盖日常90%以上的SQL文件。但要注意MySQL的DELIMITER关键字还是需要单独预处理。我的做法是执行前检查脚本里有没有DELIMITER如果存在就先用正则把整个存储过程块提取出来再单独交给JDBC执行而不是塞进普通的逐条执行流水线。如果你不想自己造轮子Spring Boot自带的org.springframework.jdbc.datasource.init.ScriptUtils也可以帮你切分它提供了splitSqlScript方法可以传不同的分隔符参数。但实测下来它对MySQL的DELIMITER支持确实有限遇到复杂的存储过程还是自己处理更踏实。2.4 大文件导入的性能与事务策略如果是几百KB的小SQL文件上面那套循环执行就够了。但如果要导入的备份文件有几百MB逐条execute会慢到让你怀疑人生而且一旦中途出错之前执行的SQL全部无法回滚。我的建议是控制事务边界批量提交。做法很简单在执行前把自动提交关掉手动控制每N条语句提交一次public void importLargeSql(String filePath) throws Exception { Connection connection DataSourceUtils.getConnection(jdbcTemplate.getDataSource()); try { connection.setAutoCommit(false); ListString statements splitSqlStatements(Files.readString(Path.of(filePath))); int batchSize 100; int count 0; for (String statement : statements) { jdbcTemplate.execute(statement); count; if (count % batchSize 0) { connection.commit(); } } connection.commit(); } catch (Exception e) { connection.rollback(); throw e; } finally { DataSourceUtils.releaseConnection(connection, jdbcTemplate.getDataSource()); } }注意MySQL的DDL语句自带隐式提交你没法把CREATE TABLE放进一个事务里回滚所以整个文件要么全部成功要么全部失败在MySQL上做不到。实际工程里更通用的策略是先记录执行日志表每执行完一条记录一条失败了从出错的语句继续而不是把所有SQL强行包在一个事务里。我踩过的坑曾经有一次线上数据恢复把30万行INSERT塞进一个事务里执行结果跑了很久还没跑完最后连接超时中间状态的脏数据反而要把人逼疯。后来改成每500条commit一次性能和可控性都好了很多。3. 更正式的做法把SQL文件交给Flyway管理3.1 为什么原生机制不够用schema.sql和data.sql这套原生机制在项目早期和原型开发阶段非常爽文件往resources里一放项目一启动表也有了测试数据也齐全了。但项目发展到多环境、多人协作之后这套机制就逐渐暴露一个问题没有版本管理。你跟同事各改了一份schema.sql合代码的时候到底以谁为准生产环境已经执行过V1版本的建表语句新版本的schema.sql里如果包含整库重建的脚本你直接往生产库里跑数据库里的表全被清空重来这显然不行。所以正规一点的团队都会引入专门的数据库版本迁移工具最主流的就是Flyway和Liquibase。3.2 Flyway的基础用法Flyway的思路很简单用版本号管理每一份SQL脚本。脚本文件命名遵循V{n}__{描述}.sql比如V1__init_schema.sql、V2__add_user_table.sql、V3__insert_config_data.sql。Flyway会在数据库中创建一个flyway_schema_history表每次执行完一个脚本就插入一条记录。下次启动时它只执行那些还没在历史表里出现过的脚本。接入Flyway非常轻松Spring Boot的spring-boot-starter依赖已经内置了Flyway只要classpath里有flyway-core的依赖Spring Boot就会自动把Flyway挂到数据源初始化流程上dependency groupIdorg.flywaydb/groupId artifactIdflyway-core/artifactId version9.16.3/version /dependency脚本放在src/main/resources/db/migration目录下命名规则V1__xxx.sql、V2__xxx.sql启动时自动按顺序执行。我目前的个人习惯是V1开头建基础表结构V2开头加业务表V3开头补索引和修改字段V4开头初始化固定数据数据字典、配置参数。命名上建议保持纯英文避免中文文件名在不同平台和文件系统下产生识别问题。3.3 Flyway实操时的几个注意事项第一一旦执行过的脚本文件绝对不能改动。Flyway校验的是文件的checksum如果你改了某个历史脚本的内容并再次启动应用启动直接报错提示校验和不匹配。这不是Flyway在找茬恰恰是它在保护你——防止有人偷偷改了已经上生产的脚本。第二要区分结构迁移和数据迁移。结构迁移脚本里尽量只写DDL不要混入大批量DML数据迁移脚本里写明幂等操作比如INSERT可以用INSERT IGNORE、ON DUPLICATE KEY UPDATE或者先用DELETE再INSERT避免重复插入导致主键冲突。在Flyway机制下每个脚本只会执行一次但数据脚本在执行时仍然要考虑重复插入情况——脚本虽然一次性执行但数据本身可能在多个环境反复导入。第三生产环境的新增字段最好写成一条完整的ALTER TABLE语句。有些数据库对一条ALTER TABLE只支持修改一个字段但MySQL支持在同一条ALTER TABLE里写多个ADD COLUMN。尽量把ADD COLUMN和MODIFY COLUMN写在一起减少执行多次失败的概率。3.4 什么时候选择LiquibaseLiquibase和Flyway的核心思路不同。Liquibase使用统一的changeLog文件来管理变更changelog里每一个changeSet记录一次数据库变更这些变更可以用SQL写也可以用Liquibase自有的XML/YAML格式写。它最大的优势是可以跨数据库类型写一份changeSetMySQL、PostgreSQL、Oracle都能跑Liquibase会自动把通用操作翻译成目标数据库的方言。如果你的产品要同时支持多个数据库Liquibase比Flyway合适。如果你只用一种数据库更看重简单直接的SQL脚本Flyway会更加顺手。我个人日常用的还是Flyway理由有两条一是SQL脚本一眼能看懂二是命名和版本管理很直观。但请你理解这是技术选型问题不是绝对好坏问题。4. 后台系统内置SQL导入功能怎么做4.1 需求形态除了项目启动时初始化和数据库版本迁移还有一类场景是给系统做一个在线SQL导入功能——管理员在后台选择SQL文件上传应用解析并执行常用于运营后台的数据修复、测试平台的数据准备、SaaS租户的数据初始化。这种功能要作为独立模块来设计不能跟schema.sql、Flyway混在一起。这类功能的实现要点有三个上传文件的存储位置、SQL解析与执行、执行结果反馈。前面给的SqlImportService可以复用这里补充几个管理后台特有的注意点。4.2 防止误操作与权限控制能在后台导入SQL的人等于拿着数据库的写权限在线上操作。所以这个功能必须做权限控制通常要配到管理员级别并且所有操作留审计日志。我做过的一个后台模块里每次执行前会把SQL文件内容、执行人、执行时间、执行结果存入operation_log表万一出了问题可以追溯。还要考虑一个很多新手容易忽略的点导入功能要支持预览确认流程。管理员上传文件后系统解析出前20条SQL展示出来让管理员确认没问题才真正执行。步骤很简单但能非常有效地防止误操作。实际项目中我有一次就是因为预览时发现脚本里混了一条DROP TABLE语句才避免了一次事故。4.3 有状态执行支持断点续跑文件大到一定程度或者中途网络断开、数据库连接异常导入就会中断。真要做得可靠你需要引入执行状态机每个导入任务有一个taskId执行前在任务表记录待执行状态每执行N条SQL更新一次已执行条数失败时记录失败语句和异常堆栈任务状态变成失败重试时优先从失败位置继续。有了这些运维人员就能在一个任务中断后不慌不忙地点击继续不用从头再来。我见过不少项目没有这个设计一个几百万行数据的导入一旦失败就要从头再来特别痛苦。在实现上你可以给SqlImportService增加一个执行进度回调接口public interface ImportProgressListener { void onProgress(String taskId, int completed, int total); void onError(String taskId, String sql, Exception e); }循环执行的时候每执行完一条就调用listener上报进度页面端用WebSocket或者轮询接口展示进度条。这个方案实现成本不高但体验提升非常明显。4.4 在应用启动完成后执行SQL有些场景要求应用整个启动完成后再执行SQL不能用默认初始化器也不能用Flyway的自动迁移。可以监听ApplicationReadyEventComponent public class SqlImportOnReadyRunner { EventListener(ApplicationReadyEvent.class) public void onReady() { if (shouldImport()) { sqlImportService.importFromClasspath(sql/post-startup.sql); } } }这种方式的典型用途包括从某个外部工单系统拉取脚本之后执行、启动时动态生成租户库、或者执行一些依赖完整Spring容器状态的初始化逻辑。需要注意ApplicationReadyEvent在测试环境可能触发多次所以shouldImport()里最好加个标志位或者用数据库记录防止重复执行。5. 常见问题与排查技巧实录5.1 schema.sql不执行排查路径非常固定确认spring.sql.init.mode是不是always。外部数据库默认是embedded不动配置的话文件不会被加载。确认文件路径是否匹配schema-locations。如果配置了classpath:sql/schema.sql就确认resources/sql/schema.sql真的存在注意编译输出目录target/classes下有没有。确认数据源是否正常初始化。如果项目里手动定义了一个DataSource的Bean并且没有交给Spring Boot管理初始化器可能拿不到你的数据源。看启动日志。Spring Boot会打一条ScriptUtils相关的日志如果SQL文件被成功执行你能看到每条语句的执行输出。我在本地遇到过最隐蔽的一次schema.sql能被加载但因为里面的CREATE TABLE语句没有加IF NOT EXISTS而Hibernate又提前根据Entity建了表导致启动直接报错。排查了半天才发现是Hibernate建表和schema.sql的冲突问题。建议关闭Hibernate的ddl-auto设置成none让建表统一交给schema.sql或者把建表任务交给Flyway不要两套机制并存。5.2 data.sql重复执行导致数据重复原生机制下data.sql每次启动都会执行。如果你的data.sql里是纯INSERT语句第二次启动就会因为主键冲突报错。解决方案有三个用INSERT IGNORE / ON DUPLICATE KEY UPDATE启动时先执行DELETE FROM xxx再INSERT保证初始化数据的整体替换把数据初始化任务交给Flyway的版本化脚本保证只执行一次。5.3 中文乱码SQL文件里的中文注释或者中文数据在入库后变问号通常是编码链路上出了问题。确保文件本身是UTF-8编码、spring.sql.init.encodingutf-8、数据库连接URL上带上characterEncodingutf8、数据库表字段的collation是utf8mb4_general_ci或者utf8mb4_unicode_ci。实操中我建议在pom.xml里配置resource的编码过滤properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /properties这样Maven在复制resource文件的时候不会重新编码能降低一类莫名其妙的乱码问题。5.4 Flyway校验失败启动日志里常见的信息是Validation failed for migration V2__xxx.sql。解决办法看情况如果你确实没有改过历史脚本对比当前文件内容再用版本管理工具看一下git diff搞清楚脚本最后一次改动的内容。如果必须改脚本且这个脚本只在开发环境执行过可以删除本地flyway_schema_history里对应的记录再让Flyway重新执行。生产环境千万别这么干。最稳妥的办法不要去改历史脚本而是写一个新脚本比如V2_1__fix_something.sql把需要的变更写在里面。这是Flyway社区推荐的规范操作。5.5 大SQL文件导入时出现PacketTooLargeExceptionMySQL默认的max_allowed_packet通常是4MB如果你的SQL文件里某一条INSERT的SQL非常长、或者包含很大的BLOB文本超过了这个限制就会报PacketTooLargeException。解决办法修改MySQL的全局参数SET GLOBAL max_allowed_packet 64 * 1024 * 1024;需要超级权限在数据库连接URL上配置maxAllowedPacket属性比如jdbc:mysql://localhost:3306/demo?maxAllowedPacket67108864代码层面尽量把大字段拆成小块插入或者在SQL脚本里避免写超长单条语句。5.6 执行顺序不可控默认情况下schema.sql会先于data.sql但如果你配了多个data-locations它们之间的顺序是按照配置列表中的顺序执行的。如果要控制多个文件之间的严格顺序建议自定义初始化器或者用Flyway的版本号排序而不是依赖配置列表的偶然顺序。把常见的排查要点整理成一个速查表症状可能原因建议处理schema.sql未执行modeembedded外部数据库不执行改为always启动报表已存在Hibernate先建表schema.sql再建表关闭ddl-auto统一建表方式data.sql重复数据纯INSERT无幂等处理改为INSERT IGNORE或结合Flyway中文乱码编码链路不一致文件、连接、数据库字符集统一UTF-8Flyway校验失败历史脚本被修改禁止改历史脚本写新迁移脚本PacketTooLarge单条SQL超过max_allowed_packet调整数据库参数或拆分SQLSQL执行顺序错乱多位置路由不对用Flyway版本号或自定义初始化器6. 我最终推荐的技术组合6.1 不同阶段的技术选择这个话题说到底没有一套方案能覆盖所有场景。我个人的选择标准是这样的项目还在玩具阶段、个人项目、或者演示Demo直接用Spring Boot原生schema.sql data.sql配置一个always模式就完事简单快速零学习成本。项目开始有多个环境、多人协作、需要管理数据库结构变更时马上引入Flyway。把建表和改表脚本全交给版本化迁移原生schema.sql就可以退场了。数据初始化脚本放在Flyway里但要注意书写幂等。运维后台需要在线导数据、做数据恢复、一键初始化租户数据时用前面那套SqlImportService加上进度监听和审计日志不要在Flyway里混入临时数据操作。一句话总结就是能自动就自动能版本化就版本化涉及用户交互和临时数据的管理后台操作再走代码导入。6.2 给入门同学的一个最小可运行示例如果是刚开始接触Spring Boot的新人还没到看长篇大论的时候直接照着下面这个最小示例上手最快先建一个Spring Boot项目引入spring-boot-starter-jdbc和MySQL驱动。在application.yml里配置好数据源。在src/main/resources下新建schema.sqlCREATE TABLE IF NOT EXISTS user ( id BIGINT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50) NOT NULL, email VARCHAR(100) UNIQUE, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE IF NOT EXISTS config ( config_key VARCHAR(50) PRIMARY KEY, config_value VARCHAR(500), updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP );再建data.sqlINSERT INTO config (config_key, config_value) VALUES (system.name, Demo System); INSERT INTO config (config_key, config_value) VALUES (system.version, 1.0.0);application.yml里加spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: root sql: init: mode: always continue-on-error: false启动项目后打开数据库客户端就能看到两张表和两条初始化数据。整个过程不需要写一行Java代码。这个示例里用了IF NOT EXISTS所以即使项目多次重启schema.sql也不会因为重复建表报错。config表是核心配置表data.sql里如果每次重启都重复INSERT第二次启动就会主键冲突。要解决这个问题可以把INSERT改成INSERT INTO config (config_key, config_value) VALUES (system.name, Demo System) ON DUPLICATE KEY UPDATE config_value VALUES(config_value);这样就可以反复启动了。6.3 最后一个建议在Spring Boot里导入SQL文件方案看着五花八门本质其实就三个选择启动自动执行、代码手动导入、迁移工具版本管理。把这三种方式的适用场景分清楚你就不会再为SQL文件到底该放哪这种问题纠结了。我能给的最大建议是不要把所有SQL都堆在schema.sql里也不要什么情况都想着写一段Java执行代码找到最适合当前项目阶段的方式才是重点。踩过几次坑之后我现在的习惯是先问自己三个问题这个数据库是全新的还是已有数据的这批SQL是固定结构还是临时数据执行失败后能不能从头再来三个问题回答完用哪套方案基本就清楚了。希望这篇文章能帮你少走几步弯路。
