Forest项目中MySQL数据库迁移指南
在现代Java EE或Jakarta EE应用的开发与维护过程中，使用嵌入式数据库（如Derby）进行初期验证虽便捷，但一旦进入生产环境或需要团队协作、性能调优时，往往暴露出可扩展性差、管理不便等问题。Forest项目作为一个典型的示例应用，默认采用Derby作为持久化存储，但在实际部署中，切换到MySQL这类成熟的关系型数据库几乎是必然选择。
本文将带你完整走一遍从Derby迁移到MySQL的全过程——这不是简单的配置替换，而是一次涉及数据源定义、驱动加载、SQL语法适配、字符集统一以及JPA方言调整的系统性改造。整个过程无需修改业务代码，重点在于基础设施层的精准对齐。
我们首先从最核心的数据源配置入手。web.xml中的<data-source>定义了应用服务器如何获取数据库连接池。原生配置指向的是 Derby 的嵌入式数据源类，现在要改为 MySQL 对应的实现类：
<data-source> <name>java:global/ForestDataSource</name> <class-name>com.mysql.cj.jdbc.MysqlDataSource</class-name> <server-name>localhost</server-name> <port-number>3306</port-number> <user>root</user> <password>admin</password> <property> <name>databaseName</name> <value>forest</value> </property> <property> <name>useSSL</name> <value>false</value> </property> <property> <name>allowPublicKeyRetrieval</name> <value>true</value> </property> </data-source>这里的关键变更点有三个：一是class-name必须使用com.mysql.cj.jdbc.MysqlDataSource，这是 MySQL Connector/J 8.x 版本的标准数据源工厂类；二是通过<property>显式指定databaseName，避免依赖默认库导致连接失败；三是关闭 SSL 并启用公钥检索，这两个设置在本地调试阶段非常关键——特别是新版 MySQL 默认启用了 caching_sha2_password 认证机制，若不开启allowPublicKeyRetrieval=true，会直接抛出“Public Key Retrieval is not allowed”的异常。
⚠️ 提醒：如果你还在使用旧版驱动（如5.1.x），类名应为
com.mysql.jdbc.jdbc2.optional.MysqlDataSource，但强烈建议升级至8.x以上版本以获得更好的兼容性和安全性支持。
仅仅改写配置是不够的，运行时还必须确保 JDBC 驱动能被正确加载。你需要将mysql-connector-java-8.0.33.jar或更高版本放入应用服务器的共享库路径中，例如 GlassFish 的典型路径为：
domains/domain/lib/mysql-connector-java-8.0.33.jar这个目录位于类路径（classpath）之上，所有部署的应用都可以访问其中的 JAR 包。你也可以通过 Maven 或 Gradle 管理依赖，但在传统 Java EE 容器中，手动放置仍是更稳妥的方式，尤其当多个应用共用同一数据库驱动时。
📦 小技巧：不要把驱动放在应用的
WEB-INF/lib下，这可能导致类加载器冲突或资源泄漏。优先使用容器级库管理。
接下来是数据库实例本身的准备。虽然某些配置可以自动创建数据库，但我们推荐显式初始化，这样能更好地控制字符集和排序规则：
CREATE DATABASE IF NOT EXISTS forest CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;使用utf8mb4而非utf8是一个工程最佳实践。MySQL 的utf8实际只支持最多三个字节的 UTF-8 编码，无法存储 Emoji 或部分生僻汉字；而utf8mb4才是真正完整的 UTF-8 支持。同时，utf8mb4_unicode_ci排序规则提供了更准确的多语言比较能力，适合国际化场景。
创建完成后，后续脚本执行前记得切换上下文：
USE forest;真正的挑战出现在 SQL 脚本迁移环节。Derby 和 MySQL 在语法细节上存在诸多差异，直接运行原始脚本几乎必定报错。我们需要逐一重写drop.sql、create.sql和data.sql。
首先是drop.sql，用于清理旧结构。由于外键约束的存在，删除顺序不当会导致失败，因此我们先禁用外键检查：
SET FOREIGN_KEY_CHECKS = 0; DROP TABLE IF EXISTS PERSON_GROUPS; DROP TABLE IF EXISTS PERSON; DROP TABLE IF EXISTS GROUPS; DROP TABLE IF EXISTS ORDER_DETAIL; DROP TABLE IF EXISTS CUSTOMER_ORDER; DROP TABLE IF EXISTS ORDER_STATUS; DROP TABLE IF EXISTS PRODUCT; DROP TABLE IF EXISTS CATEGORY; SET FOREIGN_KEY_CHECKS = 1;IF EXISTS可防止表不存在时报错，提升脚本健壮性。这种“防御性编程”思维在自动化部署中尤为重要。
然后是create.sql，它定义了整套表结构。除了基本字段映射外，有几个关键点需要注意：
SET SQL_MODE = "NO_AUTO_VALUE_ON_ZERO"; SET time_zone = "+00:00"; USE forest; SET character_set_client = utf8mb4; SET character_set_results = utf8mb4; SET collation_connection = 'utf8mb4_unicode_ci';这些会话级设置确保建表时使用的字符集一致，避免乱码。接着是各表定义，其中几个典型转换如下：
- Derby 的
GENERATED BY DEFAULT AS IDENTITY自增逻辑，在 MySQL 中替换为INT AUTO_INCREMENT PRIMARY KEY - BLOB 类型字段如
IMG_SRC原为BLOB(1073741823)，应改为无长度限制的LONGBLOB - 所有主键和外键约束通过
ALTER TABLE ... ADD CONSTRAINT分离声明，提高可读性 - 唯一索引和普通索引明确创建，便于后续优化查询性能
例如PERSON表：
CREATE TABLE PERSON ( ID INT NOT NULL AUTO_INCREMENT PRIMARY KEY, FIRSTNAME VARCHAR(50) NOT NULL, LASTNAME VARCHAR(100) NOT NULL, EMAIL VARCHAR(45) NOT NULL UNIQUE, ADDRESS VARCHAR(45) NOT NULL, CITY VARCHAR(45) NOT NULL, PASSWORD VARCHAR(100), DTYPE VARCHAR(31) ); CREATE UNIQUE INDEX SQL_PERSON_EMAIL_INDEX ON PERSON(EMAIL);注意到我们将EMAIL设为唯一字段，并额外建立唯一索引——这不仅满足业务需求，也为 JPA 关联查询提供支撑。
对于多对多关系表如PERSON_GROUPS，主键由(GROUPS_ID, EMAIL)联合构成，并分别添加外键引用：
CREATE TABLE PERSON_GROUPS ( GROUPS_ID INT NOT NULL, EMAIL VARCHAR(45) NOT NULL, PRIMARY KEY (GROUPS_ID, EMAIL) ); ALTER TABLE PERSON_GROUPS ADD CONSTRAINT FK_PERSON_GROUPS_PERSON FOREIGN KEY (EMAIL) REFERENCES PERSON(EMAIL); ALTER TABLE PERSON_GROUPS ADD CONSTRAINT FK_PERSON_GROUPS_GROUPS FOREIGN KEY (GROUPS_ID) REFERENCES GROUPS(ID);这种设计模式在权限系统中极为常见，务必保证约束完整。
最后是data.sql，负责插入初始数据。这部分改动相对较小，但仍需注意函数兼容性问题：
INSERT INTO PERSON (FIRSTNAME, LASTNAME, EMAIL, ADDRESS, CITY, PASSWORD, DTYPE) VALUES ('Robert', 'Exampler', 'robert@example.com', 'Example street', 'San Francisco', MD5('1234'), 'Customer');此处使用了 MySQL 内置的MD5()函数加密密码。虽然方便演示，但切勿在生产环境中使用 MD5。它已被证明极易碰撞破解。正确的做法是采用强哈希算法如 bcrypt、PBKDF2 或 Argon2，并配合随机盐值存储。
其他数据插入保持原样即可，包括商品、订单状态、用户角色等基础配置项。
完成上述更改后，别忘了检查 JPA 持久化单元是否适配。打开persistence.xml，确认以下内容：
<persistence-unit name="forestPU" transaction-type="JTA"> <jta-data-source>java:global/ForestDataSource</jta-data-source> <properties> <property name="javax.persistence.schema-generation.database.action" value="none"/> <property name="hibernate.dialect" value="org.hibernate.dialect.MySQL8Dialect"/> <property name="hibernate.show_sql" value="true"/> </properties> </persistence-unit>最关键的是hibernate.dialect设置。Hibernate 需要知道目标数据库的具体方言才能生成合适的 SQL。对于 MySQL 8.x，必须使用MySQL8Dialect；如果是 5.7，则降级为MySQL57Dialect。错误的方言可能导致分页语句失效、JSON 类型处理异常等问题。
此外，schema-generation.database.action=none表明我们自行管理 DDL，不会由 JPA 自动生成表结构，这也符合本次迁移“完全掌控”的原则。
整个迁移流程可归纳为六个标准步骤：
| 步骤 | 操作 |
|---|---|
| 1 | 修改web.xml数据源为 MySQL 实现类 |
| 2 | 将 MySQL JDBC 驱动放入容器 lib 目录 |
| 3 | 创建forest数据库并设置字符集为utf8mb4 |
| 4 | 重写drop.sql、create.sql、data.sql以适配 MySQL 语法 |
| 5 | 核查persistence.xml使用正确的方言和数据源引用 |
| 6 | 清理工作目录、重启服务器并验证功能 |
每一步都不可或缺。尤其是第6步中的“清理缓存”，很多开发者忽略这一点，导致旧类文件或编译残留引发奇怪问题。GlassFish 用户应删除generated/和tmp/目录；TomEE 用户则需清空work/文件夹。
遇到问题怎么办？以下是高频故障及应对策略：
“No suitable driver found”
最常见原因：驱动未加载。检查 JAR 是否在正确路径，类名是否拼错（cj不是jdbc）。查看服务器日志是否有ClassNotFoundException。“Access denied for user”
用户权限不足。执行授权命令：sql GRANT ALL PRIVILEGES ON forest.* TO 'root'@'%' IDENTIFIED BY 'admin'; FLUSH PRIVILEGES;
注意'%'允许远程连接，仅限测试环境使用。生产环境应限定 IP。“Unknown database ‘forest’”
数据库未创建或名称不匹配。检查web.xml中databaseName属性值是否与实际库名一致。图片插入失败或显示乱码
多数源于字符集不统一。确认数据库、连接、表字段均使用utf8mb4；IMG_SRC字段必须是LONGBLOB类型，不能误设为TEXT或VARCHAR。
最终你会发现，这次迁移带来的不只是数据库更换，更是一次架构认知的升级。你掌握了如何在不同 RDBMS 之间平滑过渡的技术要点，理解了 JDBC、JPA、SQL 方言之间的协同关系。这种能力远超 Forest 示例本身的价值——它可以复用于任何基于 JPA 的传统 Web 应用迁移项目。
更重要的是，你为系统打开了通往高可用的大门：MySQL 支持主从复制、读写分离、慢查询分析、备份恢复等一系列企业级特性，而这些正是嵌入式数据库无法提供的。
🚀 技术演进的本质，就是不断将简单原型推向稳健生产的迭代过程。每一次成功的迁移，都是向工程成熟度迈出的坚实一步。
作者：AI系统工程师
最后更新：2025年4月5日
