GitHub Actions 数据库服务配置：MySQL/PostgreSQL/Redis/SQL Server 集成测试指南

GitHub Actions Database 并不是一个需要安装的独立软件包，而是把数据库服务接入 GitHub Actions 工作流的一整套配置方案。很多项目在本地开发时一切正常，一旦提交到 GitHub 跑 CI，就反复出现connection refused、database not found、认证插件不兼容之类的问题。原因通常很简单：数据库容器还没就绪，测试代码已经去连了；或者连接串里的端口、用户名、密码跟服务容器不一致。这篇文章会直接用可复制的 workflow 配置，覆盖 MySQL、PostgreSQL、Redis、SQL Server 的启动方式，再带一个完整的数据库迁移和集成测试示例，最后把 matrix 多版本矩阵、GitHub Actions API 批量触发和常见报错排查一起讲完。

如果你是后端开发、DevOps 或测试工程师，并且正在把自动化测试接入 CI，这篇文章可以直接对照落地。读完你至少能带走三样东西：一套能跑通数据库集成测试的 workflow 模板；一套多数据库版本并行验证的 matrix 配置；一份覆盖高频报错的排查清单。我们直接从核心能力开始。

1. 核心能力速览

这套方案的核心是“服务容器”。GitHub Actions 会在 Runner 上同时启动 job 容器和数据库容器，测试代码通过localhost加映射端口访问数据库，整个生命周期由 Actions 自动管理。job 结束后容器销毁，不需要手动清理测试库，也不会残留数据环境。相比自己搭一台常驻测试数据库，这种方式更干净，也更适合团队协作。镜像版本可以通过标签精确锁定，不同分支可以跑不同版本的数据库，互不干扰。

2. 适用场景与使用边界

GitHub Actions Database 适合解决以下几类问题。第一是集成测试，每次提交都自动跑一遍核心读写、事务、索引和联表查询，确保数据库结构变更没有破坏业务逻辑。第二是数据迁移测试，Alembic、Flyway、Prisma Migrate 或 Django migrate 之类的迁移脚本，在真实的 MySQL、PostgreSQL 容器里执行一遍，能提前发现列不存在、字段类型不兼容、索引冲突这类问题。第三是多版本兼容验证，用matrix同时对多个数据库版本跑测试，比如 MySQL 5.7 和 8.0、PostgreSQL 14 到 16，覆盖不同生产环境。第四是缓存和队列逻辑验证，Redis 服务容器可以测试缓存穿透、限流逻辑、延迟队列等场景。

但这个方案也有明确的使用边界。它不适合当正式数据库环境，因为数据不持久化，job 结束容器就销毁。它也不适合做大规模压测，官方 Runner 的 CPU、内存和磁盘都有限，压测应该在独立环境中做。私有仓库还要注意 Actions 分钟数配额，频繁运行全量矩阵会很快消耗额度，需要控制触发频率。从 fork 的 PR 中执行的工作流默认拿不到 secrets，如果测试需要数据库密码或云服务密钥，要按官方限制配置，避免密钥泄露。数据库容器里不要放真实用户数据，所有测试数据必须脱敏，涉及个人信息的要遵守合规要求。

3. 环境准备与前置条件

准备这套环境不需要额外购买服务器，一个 GitHub 仓库就够了。workflow 文件统一放在仓库的.github/workflows/目录下，Runner 默认选择ubuntu-latest，它自带 Docker、Python、Node.js、Java 等常用运行时。

配置流程上，优先检查两件事。第一是 Runner 网络能否访问镜像仓库，如果使用私有数据库镜像，需要在 workflow 里增加docker/login-action登录步骤。第二是磁盘空间，数据库镜像和测试数据都会占用 Runner 磁盘，官方 Runner 总空间有限，镜像体积较大的 SQL Server 尤其要注意。整体上，只要仓库能正常跑一个简单 workflow，就可以把后面的数据库服务配置直接套进去。

4. 在 GitHub Actions 中启动数据库服务

4.1 MySQL 8 服务容器示例

name: MySQL Integration Test on: push: branches: - main workflow_dispatch: 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-cmd="mysqladmin ping --silent" --health-interval=10s --health-timeout=5s --health-retries=5 env: DB_HOST: 127.0.0.1 DB_PORT: 3306 DB_USER: root DB_PASSWORD: root DB_NAME: app_test steps: - name: Checkout uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.11' - name: Install dependencies run: pip install -r requirements.txt - name: Run migrations run: alembic upgrade head - name: Run integration tests run: pytest tests/integration -v

这段配置的关键点在于options里的健康检查。mysqladmin ping --silent会不断探测 MySQL 是否已经接受连接，health-retries: 5表示最多重试五次，每次间隔 10 秒。GitHub Actions 只会在服务容器健康检查通过后再执行steps，这一步能有效避免测试代码在数据库还没启动完成时就发起连接请求的问题。

4.2 PostgreSQL 16 服务容器示例

name: PostgreSQL Integration Test on: push: branches: [ main ] 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-cmd="pg_isready -U app" --health-interval=10s --health-timeout=5s --health-retries=5 env: DB_HOST: 127.0.0.1 DB_PORT: 5432 DB_USER: app DB_PASSWORD: app DB_NAME: app_test steps: - name: Checkout uses: actions/checkout@v4 - name: Run integration tests run: | echo "DB_HOST=$DB_HOST" echo "DB_PORT=$DB_PORT" # 在这里执行测试脚本

PostgreSQL 镜像的pg_isready -U app可以判断 PG 是否已准备好接受连接。连接串常用格式是postgresql://app:app@127.0.0.1:5432/app_test。注意当你从services中启动 PG 时，POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB必须三者同时设置，缺一个都可能导致初始化不完整，后面连接时会报database "app_test" does not exist。

4.3 Redis 7 服务容器示例

name: Redis Integration Test on: push: branches: [ main ] jobs: test: runs-on: ubuntu-latest services: redis: image: redis:7-alpine ports: - 6379:6379 options: >- --health-cmd="redis-cli ping" --health-interval=10s --health-timeout=5s --health-retries=5 steps: - name: Checkout uses: actions/checkout@v4 - name: Run Redis tests run: | redis-cli -h 127.0.0.1 -p 6379 ping

默认配置下 Redis 没有密码，适合只跑缓存或队列逻辑测试。如果测试逻辑需要密码，可以通过command覆盖容器默认启动命令，例如command: ["redis-server", "--requirepass", "testpass"]，对应的健康检查可以写成redis-cli -a testpass ping。在真实业务中不建议使用无密码 Redis，即使 CI 环境相对隔离，也应该从一开始就按生产习惯配置认证信息。

4.4 SQL Server 2022 服务容器示例

name: SQL Server Integration Test on: push: branches: [ main ] jobs: test: runs-on: ubuntu-latest services: mssql: image: mcr.microsoft.com/mssql/server:2022-latest env: ACCEPT_EULA: "Y" MSSQL_SA_PASSWORD: "YourStrong!Passw0rd" ports: - 1433:1433 options: >- --health-cmd="/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P YourStrong!Passw0rd -C -Q 'SELECT 1'" --health-interval=15s --health-timeout=10s --health-retries=10 steps: - name: Checkout uses: actions/checkout@v4 - name: Run SQL Server tests run: | echo "连接 SQL Server 进行测试"

SQL Server 容器启动比较慢，而且对内存和密码强度有要求。密码必须满足复杂度，包含大小写字母、数字和特殊字符。健康检查里的-C参数是跳过证书校验，这是 SQL Server 2022 镜像中sqlcmd工具的常见写法。如果你的 workflow 频繁出现wait on the database engine recovery handle failed. check the sql server error log，优先检查容器内存是否足够、ACCEPT_EULA是否设置、密码复杂度是否达标。

5. 功能测试：数据库迁移与集成测试

启动服务容器只是第一步，真正有价值的是把它和业务测试打通。下面用一个 Python 示例说明完整流程。

5.1 数据库连接与建表验证

先写一个脚本check_db.py，用来验证数据库连通性和基础建表能力。

import os import pymysql DB_HOST = os.getenv("DB_HOST", "127.0.0.1") DB_PORT = int(os.getenv("DB_PORT", "3306")) DB_USER = os.getenv("DB_USER", "root") DB_PASSWORD = os.getenv("DB_PASSWORD", "root") DB_NAME = os.getenv("DB_NAME", "app_test") conn = pymysql.connect( host=DB_HOST, port=DB_PORT, user=DB_USER, password=DB_PASSWORD, database=DB_NAME, charset="utf8mb4", ) with conn.cursor() as cursor: cursor.execute( "CREATE TABLE IF NOT EXISTS users (" "id INT AUTO_INCREMENT PRIMARY KEY," "name VARCHAR(64) NOT NULL," "email VARCHAR(128) NOT NULL UNIQUE" ")" ) cursor.execute( "INSERT INTO users (name, email) VALUES (%s, %s)", ("test_user", "test@example.com"), ) conn.commit() cursor.execute("SELECT id, name, email FROM users") rows = cursor.fetchall() print("query result:", rows) conn.close() print("database check passed")

在 workflow 中执行：

python check_db.py

看到query result: ((1, 'test_user', 'test@example.com'),)以及database check passed，说明连接、建表、写入、查询四条链路全部打通。这里的判断标准是：脚本退出码为 0，日志中没有异常栈，并且能输出查询到的真实数据。

5.2 集成测试示例

如果项目本身使用 pytest，可以写一个集成测试文件。

import os import pymysql def test_user_table_read_write(): conn = pymysql.connect( host=os.getenv("DB_HOST", "127.0.0.1"), port=int(os.getenv("DB_PORT", "3306")), user=os.getenv("DB_USER", "root"), password=os.getenv("DB_PASSWORD", "root"), database=os.getenv("DB_NAME", "app_test"), charset="utf8mb4", ) with conn.cursor() as cursor: cursor.execute("DELETE FROM users") cursor.execute("INSERT INTO users (name, email) VALUES ('tester', 'tester@example.com')") conn.commit() cursor.execute("SELECT COUNT(*) FROM users") count = cursor.fetchone()[0] assert count == 1 conn.close()

这个测试用例的作用是把数据库写入和查询绑定到 CI 流程里。只要users表结构发生变化或者连接串配置错误，测试就会立刻失败。实际项目中可以继续扩展事务回滚、唯一约束冲突、批量写入和索引命中等测试用例。

5.3 判断成功与失败排查

判断成功的标准非常明确：workflow 中所有步骤都显示绿色对勾，日志中没有任何 ERROR，pytest 输出passed。如果失败，从几个方向查：第一步看数据库服务容器是否健康，进入当前 job 的 services 部分查看健康检查日志；第二步看环境变量DB_HOST、DB_PORT、DB_USER、DB_PASSWORD是否注入成功，直接在 step 里执行echo打印连接串（注意不要打印密码到公开日志）；第三步看客户端驱动版本是否和数据库兼容，比如 MySQL 8 默认认证插件caching_sha2_password在老版本客户端中可能加载失败。

6. 矩阵矩阵与批量任务

很多团队需要验证同一个应用在不同数据库版本上的兼容性，GitHub Actions 的matrix策略正好解决这个问题。一个 job 可以通过矩阵展开成多个并行 job，每个 job 使用不同的镜像和端口。

name: Multi-DB Matrix Test on: push: branches: [ main ] workflow_dispatch: jobs: test: runs-on: ubuntu-latest strategy: fail-fast: false matrix: include: - db: mysql image: mysql:8.0 host_port: 3306 container_port: 3306 health_cmd: "mysqladmin ping --silent" - db: postgres image: postgres:16 host_port: 5432 container_port: 5432 health_cmd: "pg_isready -U app" services: db: image: ${{ matrix.image }} env: MYSQL_ROOT_PASSWORD: root MYSQL_DATABASE: app_test POSTGRES_USER: app POSTGRES_PASSWORD: app POSTGRES_DB: app_test ports: - ${{ matrix.host_port }}:${{ matrix.container_port }} options: >- --health-cmd "${{ matrix.health_cmd }}" env: DB_ENGINE: ${{ matrix.db }} DB_HOST: 127.0.0.1 DB_PORT: ${{ matrix.host_port }} DB_NAME: app_test steps: - name: Checkout uses: actions/checkout@v4 - name: Show matrix info run: | echo "当前测试数据库引擎: $DB_ENGINE" echo "连接端口: $DB_PORT"

这个配置里有两个关键细节。第一，fail-fast: false表示一个数据库的测试失败不会取消其他数据库的测试，这样你能一次看到 MySQL 和 PostgreSQL 各自的结果。第二，不同数据库用不同宿主机端口，避免同时启多个服务容器时端口冲突。矩阵模式适合做版本兼容性回归，比如把 MySQL 5.7、8.0、PostgreSQL 14、15、16 全部加进include列表，一次 push 就能覆盖全部常见生产版本。

7. 通过 GitHub Actions API 触发与查询

GitHub Actions 本身提供 REST API，可以把工作流触发和状态查询接到自己的运维工具里。这个场景特别适合批量任务：早上定时跑一批数据库回归测试，或者提交后自动触发多环境部署。

# 触发 workflow_dispatch 事件 curl -X POST \ -H "Authorization: Bearer $GH_PAT" \ -H "Accept: application/vnd.github+json" \ https://api.github.com/repos/myorg/myapp/actions/workflows/ci.yml/dispatches \ -d '{"ref":"main","inputs":{"env":"staging"}}'

# 查询仓库最近的工作流运行列表 curl -H "Authorization: Bearer $GH_PAT" \ -H "Accept: application/vnd.github+json" \ https://api.github.com/repos/myorg/myapp/actions/runs

# 下载某个运行记录的日志 curl -L -H "Authorization: Bearer $GH_PAT" \ -H "Accept: application/vnd.github+json" \ https://api.github.com/repos/myorg/myapp/actions/runs/{run_id}/logs

使用 GitHub Actions API 时要注意 Token 权限。GITHUB_TOKEN默认不能触发另一个 workflow，这是为了防止工作流无限递归。推荐使用具有workflow权限的 Personal Access Token 或 Fine-grained Token，并存入仓库 Secrets，在 workflow step 中通过${{ secrets.GH_PAT }}引用。任何情况下都不要把 Token 直接写在代码或公开日志里。API 调用也有频率限制，避免在循环里高频请求，否则会收到限流响应。

8. 资源占用与性能观察

服务容器会占据 Runner 的 CPU、内存和磁盘。虽然 GitHub 官方 Runner 有较高的总资源上限，但多个重量级数据库容器同时运行仍然可能互相争抢资源。

观察资源占用主要有两个入口。第一是 workflow run 页面右上角的 Usage，可以看到 job 的总耗时；第二是仓库的 Settings -> Billing 页面，可以查看 Actions 分钟数消耗。如果要细看某个数据库容器占了多少内存，可以在 step 里执行docker stats --no-stream，但注意 Runner 上的容器权限可能受限，最稳妥的方式还是通过容器健康检查状态和 job 总耗时来判断是否存在性能瓶颈。

镜像体积方面，MySQL 8 和 PostgreSQL 16 镜像通常都在几百 MB 级别，Redis 7 Alpine 相对轻量，SQL Server 2022 属于重量级镜像，拉取和启动都会更慢。如果工作流要频繁运行，建议把依赖安装在actions/cache缓存里，减少重复下载。同一个 job 里尽量避免同时启动 MySQL、PostgreSQL、SQL Server 三个重量级容器，这会显著拖慢启动时间，还可能引发 SQL Server 恢复超时。可以把不同数据库拆到不同的 job 中，通过矩阵并行执行，整体效率反而更高。

9. 常见问题与排查方法

补充说明几个高频问题。MySQL 8 的认证插件问题在本地开发时不容易暴露，因为本地客户端往往是最新版本，但 CI 镜像中的旧版客户端可能会报错。最好的处理方式是在 workflow 中显式使用新版驱动，或者为测试环境创建一个使用mysql_native_password的专用账号。SQL Server 的恢复超时问题更容易出现在资源紧张的环境里，如果 sqlcmd 健康检查一直失败，可以尝试把健康检查间隔从 10 秒调到 30 秒，给 SQL Server 更长的冷启动时间。

Redis 连接问题要区分两种情况。如果 Redis 容器没有密码，客户端连接失败通常是因为端口没映射正确，或者连接到了 6379 以外的端口。如果设置了 requirepass，客户端必须显式传密码，Redis Insight 这类图形工具同样需要在连接配置页填入密码，同时确认 database 序号在正确范围内。

10. 最佳实践与使用建议

第一，先跑通最小配置再上全量矩阵。第一次接入时只选一个数据库、一个测试用例，确认服务容器能健康启动、连接串能通、测试能通过，再逐步增加数据库版本和测试文件。第二，优先使用健康检查而不是sleep。sleep 30既浪费时间，又不能保证数据库真的就绪，健康检查才是准确的方式。第三，把数据库凭据统一放进 Secrets，不要在 workflow 中写死密码，更不要打印到日志里。

第四，将迁移和测试分开。先执行数据库迁移脚本，再执行集成测试，这样如果迁移失败，你能很快定位是迁移问题还是业务逻辑问题。第五，为 workflow 设置并发控制，防止连续 push 导致多个相同 job 同时运行：

concurrency: group: ci-${{ github.ref }} cancel-in-progress: true

第六，测试数据必须脱敏。不要把真实用户数据的备份上传到公开仓库或塞进测试容器，涉及人脸、声音、个人信息的数据要确认授权和合规要求。第七，控制成本。可以按main分支、PR、定时任务分别设计触发规则，避免每个 commit 都跑全量矩阵。第八，定期清理不用的镜像和缓存，避免 Runner 磁盘被占满导致拉取镜像失败。

11. 总结与下一步

GitHub Actions Database 最值得先验证的，就是把 MySQL 或 PostgreSQL 的services配置跑通，再接入一个最简单的集成测试。这个流程一旦稳定，后续的数据迁移验证、多版本兼容矩阵、API 自动触发都只是在此基础上叠加。最容易踩的坑有三个：不配置健康检查直接连接数据库，导致connection refused；矩阵中多个数据库使用同一宿主机端口，导致容器启动失败；数据库密码不满足镜像的复杂度要求，导致 SQL Server 这类容器反复重启。

接下来可以继续扩展的方向也很多：把 Redis 加进做缓存和队列测试，把 SQL Server 加进矩阵验证 Windows 部署兼容性，通过 GitHub Actions API 把回归测试集成到发布的自动化流程里，再配合actions/cache缓存依赖，进一步压减 CI 耗时。这套配置本质上是在每次代码提交时自动帮你把数据库这层“地基”重新验证一遍，越早发现问题，修复成本越低。建议把这篇文章的 workflow 模板收藏备用，下次接数据库测试时直接复制改参数就能用。