GitHub Actions数据库集成实践：服务容器、迁移脚本与问题排查

开篇先聊一个很常见的场景本地开发时MySQL 跑得好好的Spring Boot 项目也一切正常可一旦提交代码触发 CI数据库服务要么连不上要么初始化 SQL 没执行要么服务容器迟迟不 Ready。尤其是在多人协作的仓库里数据库结构变更往往只有一个人知道其他人一拉代码就是个“半坏状态”。后来我把 GitHub Actions 里的数据库场景完整梳理了一遍从服务容器、迁移脚本、等待策略到常见报错排查整理出了一套可以照着抄的流程。本文会先讲清楚 GitHub Actions 与数据库配合的核心概念再给出 MySQL、PostgreSQL、Redis 三类常见数据库的配置示例最后用一个完整的自动迁移验证案例收尾并附上高频问题排查清单。如果你正准备把数据库变更接入 CI或者想用 GitHub Actions 自动执行迁移、备份、验证脚本这篇文章会比较对路。1. 为什么要在 GitHub Actions 中管理数据库1.1 没有数据库的 CI 是不完整的很多团队的 CI 流程只跑单元测试遇到需要数据库的集成测试就直接跳过。这会让一批问题只有在代码合并后、部署到某个测试环境时才会暴露。比如建表字段写错了、索引重复、初始化数据不完整、SQL 在 MySQL 和 PostgreSQL 之间的方言差异等全部等到人工联调才发现。把数据库纳入 GitHub Actions 的日常流程后至少可以获得几个好处每次 push 都会在一个全新的环境里执行建库、建表、初始化数据。数据库结构与代码同步验证避免“代码更新了SQL 没跑”的问题。集成测试可以真实连接数据库而不是用 Mock 完全替代。迁移脚本的幂等性变得可验证部署时更放心。这里的核心不是说要让 CI 代替 DBA而是让数据库相关的变更在代码提交阶段就能被自动检查。1.2 GitHub Actions 里数据库能做什么GitHub Actions 本身不提供“数据库管理”功能它提供的是工作流编排能力。你可以通过以下方式操作数据库使用services在 job 中启动临时数据库容器。在 step 中执行 SQL 脚本。使用官方或第三方 Action 连接外部数据库。在自托管 Runner 上运行数据库备份、恢复、迁移脚本。把数据库连接信息放在配置文件和 Secrets 中按环境动态注入。其中services是最常用的一种方式它允许你在一个 job 运行时启动 MySQL、PostgreSQL、Redis、MongoDB 等依赖服务。这些服务和主 job 共享一个网络可以通过 localhost 或映射端口访问。1.3 适用场景与不适用场景适用场景包括集成测试前准备数据库。自动化执行 DDL/DML 脚本。验证迁移工具Flyway、Liquibase、Alembic是否正常。生成模拟数据用于接口测试。对备份脚本做冒烟验证。不适用场景生产数据库的托管和持久化存储。需要数据长期保留的任务。对性能要求极高的压力测试。因为 GitHub Actions 的 job 每次运行都是临时环境容器销毁后数据不会保留。你可以把它理解成一个“一次性数据库环境”只适合验证流程不适合保存业务数据。2. 环境准备与基础概念2.1 准备工作在开始之前你需要确认以下内容一个 GitHub 仓库。仓库中已经开启 GitHub Actions 功能。一个可用的 workflow 文件通常放在.github/workflows/目录下。如果使用仓库外数据库需要准备连接串和访问密钥。如果你希望在本地先调试 workflow 语法可以使用act工具模拟 GitHub Actions 环境。不过需要注意act对 service container 的支持和 GitHub 在线环境存在差异遇到问题时以真实 GitHub Actions 运行结果为准。2.2 理解 job、step、service 三者的关系GitHub Actions 中一次工作流可以包含多个 job一个 job 内部有多个 step。services是挂在某个 job 底下的辅助服务和该 job 一起启动、一起销毁。简单理解job 是执行单元。step 是 job 中的命令。service 是 job 额外启动的容器。job ├── runner 主环境 ├── service: mysql ├── service: redis └── step 1: checkout step 2: 连接数据库执行 SQL step 3: 运行测试这种结构非常适合数据库集成测试。runner 上运行你的应用代码service 容器提供外部依赖代码通过 localhost 访问数据库。2.3 版本选择建议GitHub Actions 提供的是通用 Linux 环境你运行的数据库镜像版本需要自己指定。我的建议是MySQL 使用mysql:8.0或mysql:5.7不要使用latest避免版本漂移。PostgreSQL 使用postgres:15或postgres:16。Redis 使用redis:7。SQL Server 使用mcr.microsoft.com/mssql/server镜像并注意官方容器对内存和初始化参数有要求。Oracle 镜像体积较大在公共 Runner 上需要结合资源情况评估生产场景更推荐使用外部数据库实例或自托管 Runner。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。3. 在 GitHub Actions 中启动数据库服务容器3.1 MySQL 服务容器MySQL 是最常见的业务数据库。下面是一个最小可用的 MySQL service 配置name: mysql-example on: push: jobs: test: runs-on: ubuntu-latest services: mysql: image: mysql:8.0 env: MYSQL_ROOT_PASSWORD: root MYSQL_DATABASE: app_test ports: - 3306:3306 options: - --health-cmdmysqladmin ping -h localhost -proot --health-interval10s --health-timeout5s --health-retries5 steps: - name: Checkout uses: actions/checkoutv4 - name: Wait for MySQL run: | for i in $(seq 1 30); do if (echo /dev/tcp/127.0.0.1/3306) /dev/null 21; then echo MySQL is ready exit 0 fi sleep 2 done echo MySQL is not ready after 60 seconds exit 1 - name: Show databases run: | docker exec ${{ job.services.mysql.id }} mysql -uroot -proot -e SHOW DATABASES;这段配置有几个关键点MYSQL_ROOT_PASSWORD是 MySQL 容器初始化 root 账号的密码。MYSQL_DATABASE会在首次启动时自动创建。ports将容器内部 3306 端口映射到 runner 的 127.0.0.1 上。options中的 health-cmd 会让容器定期检查 MySQL 是否 Ready。即使配置了 health-cmd我仍然建议在 step 中主动等待端口避免后续步骤拿到未就绪的数据库连接。关于${{ job.services.mysql.id }}这是 GitHub Actions 自动生成的 service 容器 ID。你可以在同一个 job 的后续 step 中使用它来进入容器执行命令。3.2 PostgreSQL 服务容器PostgreSQL 的配置方式和 MySQL 类似只是环境变量名和健康检查命令不同。name: postgres-example on: push: jobs: test: runs-on: ubuntu-latest services: postgres: image: postgres:16 env: POSTGRES_USER: app POSTGRES_PASSWORD: app POSTGRES_DB: app_test ports: - 5432:5432 options: - --health-cmdpg_isready -U app -d app_test --health-interval10s --health-timeout5s --health-retries5 steps: - name: Checkout uses: actions/checkoutv4 - name: Wait for PostgreSQL run: | for i in $(seq 1 30); do if (echo /dev/tcp/127.0.0.1/5432) /dev/null 21; then echo PostgreSQL is ready exit 0 fi sleep 2 done echo PostgreSQL is not ready after 60 seconds exit 1 - name: Check connection run: | docker exec ${{ job.services.postgres.id }} \ psql -U app -d app_test -c SELECT version();PostgreSQL 容器初始化时会根据POSTGRES_USER创建用户根据POSTGRES_PASSWORD设置密码根据POSTGRES_DB创建数据库。如果你没有指定用户默认会使用postgres用户。这里的等待脚本使用了 bash 的/dev/tcp特性不依赖外部客户端适合在公共 Runner 上使用。3.3 Redis 服务容器Redis 经常被用来做缓存、队列或测试环境中的临时存储。name: redis-example on: push: jobs: test: runs-on: ubuntu-latest services: redis: image: redis:7 ports: - 6379:6379 options: - --health-cmdredis-cli ping --health-interval10s --health-timeout5s --health-retries5 steps: - name: Checkout uses: actions/checkoutv4 - name: Wait for Redis run: | for i in $(seq 1 30); do if (echo /dev/tcp/127.0.0.1/6379) /dev/null 21; then echo Redis is ready exit 0 fi sleep 2 done echo Redis is not ready after 60 seconds exit 1 - name: Redis Ping run: | docker exec ${{ job.services.redis.id }} redis-cli pingRedis 默认没有密码如果你的项目需要密码可以使用如下方式启动services: redis: image: redis:7 ports: - 6379:6379 options: - --health-cmdredis-cli -a redispass ping --health-interval10s --health-timeout5s --health-retries5 --requirepass redispass连接时对应的密码就是redispass。3.4 外部数据库连接方式有些场景下你不想在 CI 中启动数据库容器而是连接团队已有的测试库或临时实例。jobs: test: runs-on: ubuntu-latest env: DB_HOST: your-db-host DB_PORT: 3306 DB_NAME: app_test DB_USER: ci_user DB_PASSWORD: ${{ secrets.DB_PASSWORD }} steps: - name: Checkout uses: actions/checkoutv4 - name: Run SQL run: | python - EOF import pymysql import os conn pymysql.connect( hostos.environ[DB_HOST], portint(os.environ[DB_PORT]), useros.environ[DB_USER], passwordos.environ[DB_PASSWORD], databaseos.environ[DB_NAME], ) with conn.cursor() as cur: cur.execute(SELECT 1) print(cur.fetchone()) conn.close() EOF使用外部数据库时必须使用 GitHub Actions Secrets 保存密码等敏感信息不能直接写在 workflow 中。4. 核心配置与执行流程拆解4.1 连接信息注入方式在 GitHub Actions 中数据库连接信息通常有两种注入方式第一种是写在env中适合数据库容器在同一 job 内启动的情况。env: SPRING_DATASOURCE_URL: jdbc:mysql://127.0.0.1:3306/app_test SPRING_DATASOURCE_USERNAME: root SPRING_DATASOURCE_PASSWORD: root第二种是通过 Secrets 注入适合连接外部数据库。env: DB_PASSWORD: ${{ secrets.DB_PASSWORD }}之所以不建议把数据库密码直接写在 workflow 或 SQL 脚本中是因为 workflow 文件会被保存到仓库历史中一旦被误提交到公开仓库密码就完全暴露了。4.2 等待数据库就绪很多 CI 失败都是因为执行 SQL 的步骤启动太快而数据库容器还在初始化。常见解决方案有两种一是使用健康检查脚本。在上一节的示例中options里已经配置了 health-cmd但这并不保证 GitHub Actions 会等待容器变 healthy所以还需要在 step 中做主动等待。二是使用通用端口探测脚本for i in $(seq 1 30); do if (echo /dev/tcp/127.0.0.1/3306) /dev/null 21; then echo database is ready exit 0 fi sleep 2 done echo database is not ready after 60 seconds exit 1这种方式的好处是只依赖 bash不依赖任何数据库客户端。4.3 执行 SQL 脚本执行 SQL 脚本时需要根据 runner 环境选择合适的方式。最稳妥的方式是使用容器自带的客户端。docker exec ${{ job.services.mysql.id }} mysql -uroot -proot app_test scripts/init.sql也可以使用 Python 连接数据库执行。下面是一个基于 PyMySQL 的迁移脚本示例。5. 完整实战数据库迁移自动验证5.1 需求拆解我们设计一个仓库包含两个 SQL 脚本分别创建users表和orders表。每次 push 时GitHub Actions 会启动 MySQL依次执行这两个脚本然后检查两张表是否存在。功能点使用 MySQL 8.0 服务容器。自动等待数据库就绪。使用 Python 执行迁移脚本。使用 Python 验证表结构。所有步骤在一个 workflow 中完成。5.2 项目结构database-ci-demo/ ├── .github/ │ └── workflows/ │ └── database-ci.yml ├── scripts/ │ ├── 001_create_users.sql │ ├── 002_create_orders.sql │ ├── migrate.py │ └── verify.py └── README.md5.3 编写 SQL 脚本scripts/001_create_users.sqlCREATE TABLE IF NOT EXISTS users ( id INT AUTO_INCREMENT PRIMARY KEY, email VARCHAR(255) NOT NULL UNIQUE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );scripts/002_create_orders.sqlCREATE TABLE IF NOT EXISTS orders ( id INT AUTO_INCREMENT PRIMARY KEY, user_id INT NOT NULL, order_no VARCHAR(64) NOT NULL, amount DECIMAL(10, 2) NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, CONSTRAINT fk_orders_user_id FOREIGN KEY (user_id) REFERENCES users(id) );这两个脚本使用了 MySQL 语法所以后面的验证逻辑也以 MySQL 为准。如果你使用的是 PostgreSQL需要把AUTO_INCREMENT换成SERIAL或GENERATED ALWAYS AS IDENTITY。5.4 编写迁移脚本scripts/migrate.pyimport pymysql import sys connection pymysql.connect( host127.0.0.1, port3306, userroot, passwordroot, databaseapp_test, autocommitTrue, charsetutf8mb4, ) cursor connection.cursor() sql_files [ scripts/001_create_users.sql, scripts/002_create_orders.sql, ] try: for path in sql_files: with open(path, r, encodingutf-8) as f: sql f.read() for statement in sql.split(;): statement statement.strip() if statement: cursor.execute(statement) print(fexecuted: {statement[:60]}...) print(migration done) finally: cursor.close() connection.close()这个脚本只使用;做简单拆分适合普通 DDL 脚本。如果你的 SQL 中包含存储过程、触发器或复杂的函数体建议使用专业的迁移工具比如 Flyway 或 Liquibase而不是自己写脚本解析。5.5 编写验证脚本scripts/verify.pyimport pymysql connection pymysql.connect( host127.0.0.1, port3306, userroot, passwordroot, databaseapp_test, charsetutf8mb4, ) cursor connection.cursor() try: cursor.execute(SHOW TABLES LIKE users) assert cursor.fetchone(), users table is missing cursor.execute(SHOW TABLES LIKE orders) assert cursor.fetchone(), orders table is missing cursor.execute(SHOW CREATE TABLE orders) create_sql cursor.fetchone() assert create_sql, orders table create sql is missing print(verify passed: users and orders tables exist) finally: cursor.close() connection.close()5.6 编写 workflow 文件.github/workflows/database-ci.ymlname: database-ci on: push: branches: [ main ] pull_request: jobs: mysql-test: runs-on: ubuntu-latest services: mysql: image: mysql:8.0 env: MYSQL_ROOT_PASSWORD: root MYSQL_DATABASE: app_test ports: - 3306:3306 options: - --health-cmdmysqladmin ping -h localhost -proot --health-interval10s --health-timeout5s --health-retries5 steps: - name: Checkout uses: actions/checkoutv4 - name: Wait for MySQL run: | for i in $(seq 1 30); do if (echo /dev/tcp/127.0.0.1/3306) /dev/null 21; then echo MySQL is ready exit 0 fi sleep 2 done echo MySQL is not ready after 60 seconds exit 1 - name: Install PyMySQL run: pip install pymysql - name: Run migrations run: python scripts/migrate.py - name: Verify tables run: python scripts/verify.py5.7 运行与预期结果提交这个仓库后GitHub Actions 会在每次 push 时自动运行。如果一切正常你会看到三个关键 step 全部通过Install PyMySQL成功。Run migrations输出两条 executed 信息和 migration done。Verify tables输出 verify passed。如果迁移脚本中出现了语法错误workflow 会在Run migrations步骤失败并通过日志把错误 SQL 片段展示出来。6. 常见问题与排查思路6.1 服务容器连接不上现象连接 127.0.0.1:3306 失败。step 中报 Connection refused。服务容器一直处于 starting 状态。原因数据库容器仍在初始化。端口映射没写。使用localhost而不是127.0.0.1导致解析到 IPv6。解决思路在 workflow 中主动等待数据库端口。连接地址统一使用127.0.0.1。检查服务容器的健康状态日志。6.2 SQL Server 报错wait on the database engine recovery handle failed如果你的 workflow 中使用的是mcr.microsoft.com/mssql/server镜像有时会遇到类似这样的错误wait on the database engine recovery handle failed. check the sql server error log这个报错一般和 SQL Server 服务启动过程中的恢复机制有关。常见原因包括容器启动时资源不足导致 SQL Server 进程被系统杀掉。数据库文件损坏或重启后一致性检查失败。初始化配置不对比如ACCEPT_EULA未设置。排查步骤先查看容器日志找到具体失败阶段。确保镜像版本和宿主环境匹配。如果是在公共 Runner 上运行注意资源限制尽量简化初始化逻辑。如果只是验证 SQL 语法也可以考虑使用更适合 CI 的数据库类型。在 CI 中运行 SQL Server 时一定要把ACCEPT_EULA和MSSQL_SA_PASSWORD设置正确并预留足够的启动时间。6.3 Oracle recover database 怎么处理有些团队需要在 CI 中验证 Oracle 数据库的恢复流程比如执行 restore 和 recover 操作。这类操作对环境和权限要求很高在公共 Runner 上并不方便。如果确实需要验证建议使用自托管 Runner并提前准备好 Oracle 环境。不要把真实生产库的连接信息放在 workflow 中。恢复操作只是 CI 的一个环节不要替代正规备份恢复演练。常见的恢复命令类似-- 在 RMAN 或 SQL*Plus 中恢复数据库 STARTUP MOUNT; ALTER DATABASE RECOVER DATABASE; ALTER DATABASE OPEN;这些命令必须在获得授权的前提下执行并且要明确当前是测试库还是生产库。生产环境的恢复操作一定要走变更审批流程不能直接拿到 CI 里跑。6.4 Activiti 报错couldnt deduct database type from datasource如果你在 GitHub Actions 中跑 Spring Boot 项目并且集成了 Activiti可能会遇到类似org.activiti.engine.ActivitiException: Couldnt deduct database type from database type null这个报错的核心原因是 Activiti 无法从数据源 URL 推断出数据库类型。可能情况JDBC URL 写成了jdbc:log4jdbc:mysql://...。数据库类型不在 Activiti 的支持列表中。数据源初始化还没完成Activiti 就去读取了元数据。解决思路检查数据源 URL 是不是标准格式例如jdbc:mysql://127.0.0.1:3306/app_test。在配置文件中显式声明数据库类型spring.datasource.urljdbc:mysql://127.0.0.1:3306/app_test spring.datasource.usernameroot spring.datasource.passwordroot spring.datasource.driver-class-namecom.mysql.cj.jdbc.Driver如果使用的是 PostgreSQL对应 URL 是spring.datasource.urljdbc:postgresql://127.0.0.1:5432/app_test出现这类问题时不要只看 workflow 中的报错要结合应用的启动日志一起排查重点确认数据源是否在 Activiti 初始化前完成注入。6.5 Redis Insight 客户端连接问题Redis Insight 是 Redis 官方提供的桌面客户端。如果你在本地用 Redis Insight 连接一个通过 GitHub Actions 或 Docker 启动的 Redis需要确认几个信息Host通常填127.0.0.1或localhost。Port填写实际映射端口比如6379。Username如果 Redis 未启用 ACL可以不填。Password如果容器启动时指定了--requirepass这里要填一致。如果连接不上先在命令行用客户端测试docker exec ${{ job.services.redis.id }} redis-cli -h 127.0.0.1 -p 6379 ping如果 ping 返回 PONG说明 Redis 本身正常问题多半出在 Redis Insight 的连接参数上。6.6 问题汇总表问题现象常见原因解决思路MySQL 连接被拒绝端口映射错误或容器未就绪检查 ports 配置并等待数据库 ReadySQL Server recovery handle 失败初始化参数不对、资源不足查看容器日志检查启动参数和资源限制Activiti 无法推断数据库类型JDBC URL 不规范使用标准 JDBC URL 并显式声明驱动Redis Insight 连接不上密码或端口填错用 redis-cli ping 排查服务端状态外部数据库连不上Secrets 未配置检查环境变量和网络连通性7. 最佳实践与工程建议7.1 连接信息使用环境变量和 Secrets不要把数据库密码写死在 SQL 脚本或 workflow 中。对于外部数据库使用 GitHub Actions Secrets。env: DB_HOST: ${{ secrets.DB_HOST }} DB_PORT: ${{ secrets.DB_PORT }} DB_USER: ${{ secrets.DB_USER }} DB_PASSWORD: ${{ secrets.DB_PASSWORD }}对于 service container虽然密码是写在 workflow 里的但也要注意不要把它提交到公开仓库的明显位置。至少把数据库名、用户名、密码作为一组变量集中管理。7.2 迁移脚本保持幂等同一条 SQL 脚本最好能重复执行而不报错。能用IF NOT EXISTS就用IF NOT EXISTS。CREATE TABLE IF NOT EXISTS users ( id INT AUTO_INCREMENT PRIMARY KEY, email VARCHAR(255) NOT NULL UNIQUE );如果使用迁移工具比如 Flyway脚本文件名要遵循版本号规则。不要随意修改已经执行过的脚本而是新增一个版本号更高的脚本。7.3 避免依赖一键安装数据库有些开发者会在 step 中直接执行sudo apt-get install mysql-server这会让每次 CI 的时间变得很长而且不同版本环境下的安装过程不稳定。更推荐使用 services 容器既快又干净。7.4 日志和调试排查 workflow 失败时最重要的就是看 Actions 的运行日志。你可以在关键 step 中增加输出- name: Debug environment run: | env | sort docker ps -a但要注意不要把密码等敏感信息输出到日志中。可以在本地先观察再决定是否打印完整环境变量。7.5 自托管 Runner 注意事项如果你在自托管 Runner 上运行数据库相关 workflow需要注意Runner 是否安装了 Docker。磁盘空间是否足够。服务容器之间是否有端口冲突。是否需要清理历史容器和镜像。公共 Runner 每次都是新环境所以不需要担心这些但自托管 Runner 必须主动维护。7.6 测试环境和生产环境分离CI 中使用的数据库是临时的生产环境是持久化的。不要把 CI 的数据库配置直接搬到生产环境。至少应该区分CI 数据库临时、无敏感数据、每次重建。测试环境数据库可以保留历史数据但不一定是完整业务数据。生产数据库必须有备份、监控、变更审批流程。8. 总结与后续拓展通过这篇文章你应该已经掌握了 GitHub Actions 中数据库服务容器的基本用法包括 MySQL、PostgreSQL、Redis 的启动方式等待数据库就绪的方法以及如何用 Python 执行迁移和验证脚本。这套流程在真实项目里非常有用。你可以在上面继续扩展接入 Flyway 或 Liquibase 做正式迁移。在集成测试阶段用测试库数据初始化。添加备份脚本的冒烟验证确保备份任务能够执行。把数据库结构变更通知到团队群让每个人知道表结构发生了变化。结合 Docker Compose 和自托管 Runner 跑更复杂的数据库集群。建议你先从一个最小的 MySQL workflow 开始跑通然后再逐步加入 Redis、PostgreSQL、外部数据库等场景。数据库相关的问题最难排查的往往是环境不稳定而不是 SQL 语法本身。把 GitHub Actions 的数据库流程规范化之后很多隐藏问题都会在 CI 阶段提前暴露出来后面的联调和部署会轻松很多。