Docker Compose如何初始化数据库?怎样避免重复执行导致数据被覆盖

发布人:A5数据发布时间:2026-10-23 11:02阅读量:117

Docker Compose 初始化数据库时,并不是每次执行 docker compose up 都会重新运行 SQL。以官方 PostgreSQL 镜像为例,/docker-entrypoint-initdb.d/ 下的脚本只会在数据库数据目录为空、首次创建数据库集群时执行一次。只要使用持久化卷保存数据,容器重启、重新创建甚至普通的 docker compose down 都不会重复初始化,也不会覆盖已有数据。

先确定初始化和迁移的边界配图

下面以 Docker Compose V2、Docker Engine 和 PostgreSQL 16 为例,演示首次部署、初始化表结构、写入种子数据、验证重复启动,以及出现初始化错误后的处理方式。示例默认在 Linux、macOS 或 WSL 环境中执行,数据库服务名为 db。

A5数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,覆盖建站、业务后台、数据库与容器应用场景。香港、美国、日本等地的部分方案配备SSD或NVMe存储,并提供不同CPU、内存及网络线路组合,可为Docker Compose部署的数据库、持久化数据卷和相关服务提供相应的硬件与网络资源基础。

先确定初始化和迁移的边界

Docker Compose 负责创建容器、网络和卷,但不会自行判断 SQL 是否应该执行。是否执行初始化脚本,通常由数据库官方镜像的入口脚本决定。

需要区分以下三种情况:

场景是否会执行初始化目录中的脚本数据风险
第一次使用空数据卷启动会执行会创建表并写入初始数据
容器重启或重新创建,但数据卷仍存在不会执行原有数据保留
删除数据卷后再次启动会重新执行原数据会丢失,必须先确认备份

因此,较安全的组合是:

  • 使用命名卷保存数据库目录;
  • 把建表和初始数据脚本挂载到 /docker-entrypoint-initdb.d/;
  • 种子数据使用唯一约束和幂等写入;
  • 后续表结构变更交给迁移工具或版本化迁移脚本;
  • 不使用 docker compose down -v 作为普通重启命令。

需要注意,修改 01-schema.sql 或 02-seed.sql 后,已有数据卷不会自动重新执行这些文件。初始化脚本用于“首次建库”,不应代替日常数据库迁移。

准备目录和运行环境

先检查 Docker 和 Compose 是否可用:

docker --version
docker compose version
docker info

命令能够正常返回版本和 Docker 服务信息即可。如果系统只有旧版 docker-compose 命令,也可以使用,但本文示例统一采用新版的 docker compose 子命令。

创建项目目录和初始化脚本目录:

mkdir -p compose-db/initdb
cd compose-db

touch compose.yaml
touch .env
touch initdb/01-schema.sql
touch initdb/02-seed.sql

建议将密码文件和数据库备份加入忽略列表:

cat > .gitignore <<'EOF'
.env
backup*.sql
EOF

在 .env 中写入示例配置:

POSTGRES_DB=appdb
POSTGRES_USER=appuser
POSTGRES_PASSWORD=Change-This-To-A-Long-Random-Password

正式环境应替换为长度更长、随机性更高的密码,并避免把 .env 提交到公开代码仓库。这个示例密码只用于说明配置格式,不应直接用于生产环境。

编写 Compose 配置

将以下内容写入 compose.yaml:

编写 Compose 配置配图

services:
  db:
    image: postgres:16
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - pg/var/lib/postgresql/data
      - ./initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"
        ]
      interval: 5s
      timeout: 5s
      retries: 12
      start_period: 10s

volumes:
  pg

这里有几个关键配置:

  • pg/var/lib/postgresql/data 是数据库持久化卷;
  • ./initdb:/docker-entrypoint-initdb.d:ro 将初始化目录以只读方式挂载到容器;
  • healthcheck 用于判断 PostgreSQL 是否已经可以接受连接;
  • 没有配置 ports,表示数据库只在 Compose 内部网络中提供服务;
  • 如果同一个 Compose 项目中有应用容器,应用连接地址应使用 db:5432,而不是 localhost:5432。

如果确实需要从宿主机连接数据库,可以增加端口映射,但建议只监听本机:

    ports:
      - "127.0.0.1:5432:5432"

不要在没有访问控制和防火墙策略的情况下直接使用 "5432:5432",否则可能将数据库端口暴露到所有网络接口。

验证 Compose 配置

在首次启动前执行:

docker compose config --quiet

该命令没有输出且返回成功,表示 Compose 文件结构和变量引用基本正确。

还可以确认 Compose 识别到了服务和卷:

docker compose config --services
docker compose config --volumes

预期分别包含:

db

和:

pgdata

如果 .env 文件缺少变量,或者 YAML 缩进错误,应先修复配置,再进入启动步骤。

编写首次初始化脚本

将以下内容写入 initdb/01-schema.sql:

CREATE TABLE IF NOT EXISTS app_user (
    id BIGSERIAL PRIMARY KEY,
    username TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

该脚本创建一个用户表示例,并通过 UNIQUE 约束保证用户名不会重复。

将以下内容写入 initdb/02-seed.sql:

INSERT INTO app_user (username)
VALUES ('demo')
ON CONFLICT (username) DO NOTHING;

两个文件名使用数字前缀,是为了明确执行顺序。官方 PostgreSQL 镜像通常会按文件名顺序处理初始化文件。

这里使用 ON CONFLICT (username) DO NOTHING,即使脚本被手工再次执行,也不会因为相同用户名而插入重复数据。对于种子数据,不建议使用下面这类写法:

TRUNCATE TABLE app_user;
INSERT INTO app_user (username) VALUES ('demo');

TRUNCATE 会清空已有数据,不能作为防止重复执行的方案。也不要在初始化脚本中使用无条件的 DROP TABLE、DELETE FROM 或重新创建表的逻辑,除非明确知道当前数据可以销毁。

验证初始化文件是否存在

ls -l initdb

预期能够看到:

01-schema.sql
02-seed.sql

PostgreSQL 官方镜像通常处理 .sql、压缩 SQL 文件以及可执行的 .sh 文件。普通 SQL 文件不需要额外增加执行权限;如果使用 Shell 脚本,则应确认脚本格式和权限符合要求。

首次启动数据库

先拉取指定版本的镜像:

docker compose pull db

然后创建容器并后台启动:

docker compose up -d db

检查容器状态:

docker compose ps

启动完成后,状态通常会显示为 Up 或 Up (healthy)。首次启动需要创建数据库集群,耗时可能比普通重启更长。

查看启动日志:

docker compose logs --tail=200 db

重点关注以下结果:

  • 数据库目录初始化完成;
  • 01-schema.sql 和 02-seed.sql 被处理;
  • PostgreSQL 已经开始监听;
  • 日志出现类似“ready to accept connections”的就绪信息。

日志只能辅助判断,最终还要通过数据库查询验证。

验证数据库是否接受连接

docker compose exec db sh -c \
  'pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

预期结果类似:

/app-postgres:5432 - accepting connections

主机名和路径可能因镜像版本不同而变化,关键是结果包含 accepting connections。

验证表结构和初始化数据

查看当前数据库中的表:

docker compose exec db sh -c \
  'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "\dt"'

预期能够看到 app_user 表。

查询种子数据数量:

docker compose exec db sh -c \
  'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -tAc "SELECT count(*) FROM app_user;"'

首次启动时,预期结果为:

1

进一步查看数据:

docker compose exec db sh -c \
  'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT id, username, created_at FROM app_user;"'

如果表不存在、连接失败或查询结果为空,应先查看数据库日志,不要立即删除卷。

验证重启和重建不会重复写入

完成首次验证后,可以用同一条查询记录当前数据量:

验证重启和重建不会重复写入配图

docker compose exec db sh -c \
  'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -tAc "SELECT count(*) FROM app_user;"'

然后重启容器:

docker compose restart db

等待服务恢复后再次查询:

docker compose exec db sh -c \
  'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -tAc "SELECT count(*) FROM app_user;"'

结果仍应为:

1

再测试容器重建:

docker compose up -d --force-recreate db

--force-recreate 会重新创建容器,但不会主动删除 pgdata 卷。服务恢复后再次执行查询,结果仍应为 1。

还可以测试普通停止和启动:

docker compose down
docker compose up -d db

这里特意没有使用 -v。重新启动后,查询结果仍应为:

1

这说明数据保存于卷中,而不是依赖某个临时容器。

防止应用启动时重复写入

数据库官方初始化脚本只在空数据目录执行一次,但应用程序本身可能在每次启动时执行初始化 SQL。例如,应用启动逻辑中如果包含以下语句,就可能重复写入:

INSERT INTO app_user (username) VALUES ('demo');

应改为带唯一约束的幂等写法:

INSERT INTO app_user (username)
VALUES ('demo')
ON CONFLICT (username) DO NOTHING;

如果是更新固定配置,可以明确指定更新范围:

INSERT INTO app_setting (setting_key, setting_value)
VALUES ('site_name', 'A5IDC')
ON CONFLICT (setting_key)
DO UPDATE SET setting_value = EXCLUDED.setting_value;

但要注意,DO UPDATE 会覆盖已有值。对于可能被管理员修改的业务数据,不能简单套用该写法,应根据数据所有权决定是跳过、更新还是报错。

表结构变更则不应继续修改已经执行过的 01-schema.sql。例如,需要新增字段时,应创建版本化迁移:

ALTER TABLE app_user
ADD COLUMN IF NOT EXISTS email TEXT;

生产环境通常还应配合迁移版本表、迁移工具或应用部署流程,确保同一个迁移版本只执行一次。初始化脚本解决的是“空数据库第一次创建”,迁移脚本解决的是“已有数据库的结构演进”。

常见异常和处理方法

修改 SQL 后没有重新执行

最常见原因是 pgdata 已经存在。即使容器被删除,数据目录仍然不是空目录,官方入口脚本就会跳过 /docker-entrypoint-initdb.d/。

先确认脚本确实挂载到了容器:

docker compose exec db sh -c \
  'ls -l /docker-entrypoint-initdb.d'

如果能看到文件,但修改没有生效,说明问题通常不是挂载,而是数据库已经完成过初始化。

在没有业务数据的测试环境中,可以备份或确认数据可丢弃后重新创建卷:

docker compose down
docker compose config --volumes
docker volume ls

确认实际卷名称后再删除:

docker volume rm <实际的_pgdata卷名>

然后重新启动:

docker compose up -d db

删除卷会永久删除该卷中的数据库文件。生产环境或包含业务数据的环境,不应直接执行此操作。

数据库连接被拒绝

按由低风险到高风险的顺序检查:

docker compose ps
docker compose logs --tail=200 db
docker compose exec db sh -c \
  'pg_isready -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

不同结果的含义如下:

  • 容器处于 Restarting:优先查看日志中的密码、权限或配置错误;
  • 容器仍在启动:等待健康检查通过,不要立即重建;
  • pg_isready 成功但应用连接失败:检查应用是否使用了 db 作为主机名,以及数据库名、用户名是否一致;
  • 从宿主机连接失败:确认是否配置了 ports,且连接地址与监听范围匹配;
  • 应用使用 localhost 连接:在应用容器中,localhost 指向应用自身,不是数据库容器。

初始化脚本执行到一半失败

如果 SQL 脚本执行失败,数据库目录可能已经被创建,但后续脚本没有完成。此时直接修改 SQL 后执行 docker compose restart db,通常不会再次自动运行初始化目录。

初始化脚本执行到一半失败配图

如果是空环境,可以:

  1. 查看日志定位具体 SQL 错误;
  2. 修正脚本;
  3. 确认没有需要保留的数据;
  4. 删除对应数据卷;
  5. 重新启动数据库并重新验证。

如果卷中已有业务数据,不要删除卷。应保留现场,先备份数据库,再将修复内容作为手工 SQL 或正式迁移执行。

重启后看起来像换了一个数据库

如果数据突然为空,常见原因是 Compose 项目名称变化,导致创建了另一个同名卷前缀不同的数据卷。例如,从不同目录执行 Compose,或者修改了 COMPOSE_PROJECT_NAME,都可能使默认卷名称发生变化。

检查当前项目声明的卷:

docker compose config --volumes
docker volume ls

再对照卷的创建时间和标签:

docker volume inspect <卷名>

部署脚本应固定工作目录和 Compose 项目名,避免开发、测试、生产环境误用同一个卷,也避免同一环境因为目录变化而创建新卷。

使用 MySQL 时需要调整的内容

如果实际使用 MySQL,原理基本相同:官方 MySQL 镜像在 /var/lib/mysql 为空时执行 /docker-entrypoint-initdb.d/ 中的初始化文件,已有数据目录不会因为容器重启而重新执行。

主要差异如下:

项目PostgreSQLMySQL
数据目录/var/lib/postgresql/data/var/lib/mysql
初始化数据库变量POSTGRES_DBMYSQL_DATABASE
初始化用户变量POSTGRES_USERMYSQL_USER
密码变量POSTGRES_PASSWORDMYSQL_PASSWORD
初始化目录/docker-entrypoint-initdb.d//docker-entrypoint-initdb.d/
常用就绪检查pg_isreadymysqladmin ping

MySQL 的种子数据也应增加唯一索引,并使用 INSERT IGNORE 或带条件的 INSERT ... ON DUPLICATE KEY UPDATE。不要因为更换了数据库镜像,就把删除数据卷作为常规初始化手段。

备份、回滚和重新初始化

在删除数据卷、修复失败的初始化或更换数据库配置前,先生成逻辑备份:

docker compose exec -T db sh -c \
  'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB"' > backup.sql

检查备份文件是否存在且非空:

ls -lh backup.sql
test -s backup.sql && echo "backup file is not empty"

备份命令成功不等于备份一定可恢复。更稳妥的做法是在独立数据库中测试导入:

docker compose exec db sh -c \
  'createdb -U "$POSTGRES_USER" restore_check'

然后导入备份:

cat backup.sql | docker compose exec -T db sh -c \
  'psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d restore_check'

导入完成后检查表和数据:

docker compose exec db sh -c \
  'psql -U "$POSTGRES_USER" -d restore_check -c "\dt"'

如果只是配置文件写错、但数据仍然完整,回滚配置后执行:

docker compose down
docker compose up -d db

这不会删除 pgdata。

如果是全新的测试环境,需要回到“空数据库重新初始化”的状态,应先确认数据无需保留,再执行:

docker compose down
docker volume rm <实际的_pgdata卷名>
docker compose up -d db

docker compose down -v 会删除当前 Compose 项目声明的卷,可能同时删除多个数据库或其他持久化数据。除非已经确认影响范围并完成备份,否则不要使用该命令。

验收与回滚检查项

首次部署完成后,至少核对以下内容:

  • docker compose config --quiet 通过;
  • db 容器状态为运行中,并通过健康检查;
  • pg_isready 返回 accepting connections;
  • app_user 表已经创建;
  • 初始化种子数据数量符合预期;
  • docker compose restart db 后数据数量不变;
  • docker compose up -d --force-recreate db 后数据数量不变;
  • 普通 docker compose down 和再次 up 后数据仍然存在;
  • 应用连接数据库时使用 db:5432,而不是容器内的 localhost;
  • .env、备份文件和数据库密码没有提交到公开仓库。

执行回滚或重新初始化前,还应确认:

  • 已生成可读取的 pg_dump 备份;
  • 已明确当前数据卷的实际名称;
  • 已区分“删除容器”和“删除数据卷”的影响;
  • 只在确认数据可丢弃的环境中删除卷;
  • 备份已经在独立数据库中完成过恢复测试;
  • 重新初始化后重新执行表结构、种子数据和连接验证。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5295.html

相关推荐