容器与云原生 / 系统课时

接入数据库容器

接入数据库容器

把数据库放进容器并不只是“启动一个 PostgreSQL 镜像”。要想让数据可保留、首次启动可自动建表、应用能判断数据库是否就绪,至少要同时处理环境变量、命名卷、初始化脚本和健康检查。本节以 PostgreSQL 为例完成一套可验证的本地开发配置。

学习目标

  • 配置 PostgreSQL 初始化所需的账号、密码和数据库名
  • 使用命名卷保存数据库数据,并理解初始化脚本的触发条件
  • 通过健康检查和 psql 验证数据库真正可用

准备数据库配置与初始化脚本

建立 compose.yaml,再创建 db/init/001_schema.sql。数据库密码通过 ${POSTGRES_PASSWORD} 注入,不写死在 Compose 文件中;POSTGRES_USER 和 POSTGRES_DB 则定义首次初始化时要创建的角色和数据库。

compose.yaml 内容如下:

yaml
services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: appdb
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./db/init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 5s

volumes:
  postgres-data:

db/init/001_schema.sql 使用一条简单建表语句验证初始化链路:

sql
CREATE TABLE IF NOT EXISTS app_note (
    id BIGSERIAL PRIMARY KEY,
    body TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

挂载到 /docker-entrypoint-initdb.d 的脚本只会在 PostgreSQL 初始化空数据目录时执行。后续即使修改 SQL 文件并重启容器,只要 postgres-data 仍然已有数据,入口脚本就不会再次自动执行。

PostgreSQL 容器首次初始化与后续重启

启动数据库并观察健康状态

在包含 compose.yaml 的目录执行下面的命令。这里的密码只用于本地演示,实际项目应由安全的环境变量或密钥管理机制提供。

bash
POSTGRES_PASSWORD=dev-only docker compose up -d db
docker compose ps db

预期输出

text
NAME            IMAGE                 COMMAND                  SERVICE   CREATED          STATUS                    PORTS
<NAME>          postgres:17-alpine    "docker-entrypoint..."   db        <TIME> ago       Up <TIME> (healthy)       5432/tcp

容器名和时间会因项目目录与启动时间不同而变化,因此用 <NAME>、<TIME> 表示动态值。关键是 STATUS 最终出现 healthy;如果长期停留在 starting 或变为 unhealthy,应先查看数据库日志和健康检查命令。

验证初始化结果

数据库健康后,直接在容器中调用 psql 查询表清单。这样能同时验证容器运行、账号配置、数据库名称和初始化脚本四个环节。

bash
docker compose exec db psql -U app -d appdb -c '\dt'

预期输出

text
           List of relations
 Schema |   Name   | Type  | Owner
--------+----------+-------+-------
 public | app_note | table | app
(<N> row)

<N> 表示实际返回行数。只要能看到 app_note,就说明首次初始化脚本已经执行。若提示数据库或角色不存在,优先检查环境变量;若连接成功但没有表,则检查脚本挂载路径以及该命名卷是否早已完成过初始化。

理解数据卷与“重新初始化”

停止并删除容器不会自动删除命名卷,因此下面的操作可以安全地重建数据库容器而保留数据:

bash
docker compose down
POSTGRES_PASSWORD=dev-only docker compose up -d db

预期结果

text
数据库容器会被重新创建,但 postgres-data 命名卷继续复用;已有 app_note 表仍然存在,初始化脚本不会再次执行。

如果你明确要清空本地实验数据并重新执行初始化脚本,可以删除 Compose 项目的卷后再启动。但该操作会永久删除卷中的数据库内容,只适用于确认可丢弃的数据。

bash
docker compose down -v
POSTGRES_PASSWORD=dev-only docker compose up -d db

预期结果

text
旧的 postgres-data 卷被删除;下一次启动会创建空数据目录,并重新执行 /docker-entrypoint-initdb.d 中的初始化脚本。

健康检查解决的不是数据迁移

pg_isready 只能证明 PostgreSQL 已经接受连接,不能证明所有业务表、迁移版本或种子数据都符合应用要求。接入真实应用时,数据库迁移应由专门的迁移工具或一次性任务管理,应用启动逻辑也应能处理短暂连接失败。

完成接入后,应把验收标准保持在三个层面:容器状态为 healthy,命名卷在重建容器后仍保留数据,业务需要的表结构可通过数据库查询确认。这样数据库容器才从“能启动”变成“可重复使用、可验证、可恢复”的基础服务。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接入数据库容器

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通