メインコンテンツまでスキップ

第26章：データのバックアップ＆リストアを最短で覚える📦🧯

この章、やることはシンプルです😄 「DBの中身を“ファイルとして持ち出す” → “戻す” を、最短ルートで身につけます💪✨

1) まず結論：バックアップは “2種類” だけ覚えればOK🧠✨​

✅ A. ロジカルバックアップ（推奨）＝ pg_dump で中身をダンプする🐘💾​

  • 安全・移植性が高い（別環境でも戻しやすい）
  • 普段の開発はこれで十分
  • pg_dump → pg_restore（or psql）で戻す流れ （カスタム形式は pg_restore が必要、は公式にも明記されています）(PostgreSQL)

⚠️ B. 物理バックアップ（上級）＝ volume を丸ごとコピーする🧱📦​

  • 速いけど、取り方を間違えると壊れやすい
  • 特にPostgresは、雑に tar でコピーすると事故ることがある （ファイルシステムレベルのバックアップは“基本、DB停止が必要”と公式が明確に言っています）(PostgreSQL)

なのでこの章は、まず A（pg_dump）を必修にします😺✨ B は「知ってると便利」枠で後半に置きます。

2) 今日のゴール🎯✨​

  • ✅ バックアップファイルが1個作れる
  • ✅ そのバックアップから DBを元通りに戻せる
  • ✅ 「事故りにくい手順（型）」が手元に残る

3) 事前に“迷子防止”チェック👀🧭​

3-1. DBサービス名だけ確認しよう🔎​

まず composeのサービス一覧を見ます。

docker compose ps

例：DBサービス名が db ならこの章のコマンドはそのまま使えます👌 もし postgres みたいな名前なら、コマンド中の db を置換してね🙂

4) 推奨ルート：pg_dump（カスタム形式）でバックアップする🐘💾✨​

4-1. バックアップ置き場を作る📁✨（Windows / PowerShell想定）​

プロジェクト直下に backups フォルダを作ります。

mkdir backups

4-2. いちばん事故らない方法：コンテナ内にダンプ→docker compose cpで取り出す📤✨​

この方式、Windowsでめちゃ安定します👍 リダイレクトやクォート地獄を避けられるからです😇

(1) コンテナ内にバックアップを作る（例：/tmp/db.dump）​

docker compose exec db sh -lc 'pg_dump -Fc -U "$POSTGRES_USER" -d "$POSTGRES_DB" -f /tmp/db.dump'
  • -Fc = カスタム形式（圧縮される＆復元の自由度が高い）(PostgreSQL)
  • sh -lc = コンテナの環境変数（$POSTGRES_USER など）をそのまま使う作戦😺

(2) ローカルにコピーする（docker compose cp）​

docker compose cp db:/tmp/db.dump backups/db.dump

docker compose cp は「サービスコンテナ ↔ ローカル」コピー用の公式コマンドです(Docker Documentation)

(3) サイズを見て“0バイトじゃない”確認✅​

dir backups

4-3. もう1つのやり方（ストリームで直に保存）も知っておく🎛️​

慣れてきたらこれも便利です👇 -T を付けるのがコツ（TTYを切る）🧩 docker compose exec は既定でTTYを割り当てるので、リダイレクトやパイプと相性が悪い時があります。-T はそれを無効化します(Docker Documentation)

docker compose exec -T db sh -lc 'pg_dump -Fc -U "$POSTGRES_USER" -d "$POSTGRES_DB"' > backups/db.dump

5) リストア（復元）する🔁🐘✨​

ここからが本番！ 「戻せる」ようになったら、バックアップは“武器”になります🗡️😎

5-1. 復元の前に：書き込みを止める（安全第一）🛑✋​

API/WorkerがDBに書き込んでる最中に戻すとややこしいので、いったん止めます。

例（サービス名は適宜置換してね）：

docker compose stop api worker

DBだけは動かしてOK👌（復元に必要）

5-2. バックアップファイルをコンテナに戻す📥​

docker compose cp backups/db.dump db:/tmp/db.dump

5-3. まず“掃除しながら復元”するのがラク🧹✨​

開発環境ならだいたいこれが気持ちいいです🙂

docker compose exec db sh -lc 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists /tmp/db.dump'
  • --clean = 既存オブジェクトを削除して作り直す
  • --if-exists = “無いものを消そうとしてエラー”を減らす
  • カスタム形式は pg_restore で戻すのが正しいルートです(PostgreSQL)

5-4. 戻ったか確認する✅（テーブル一覧を見る）​

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

テーブルがズラッと出たら勝ち🎉🎉🎉

5-5. アプリを戻す▶️​

docker compose start api worker

6) “壊して戻す”ミニ演習（これやると一気に身につく）🧪🔥​

演習A：わざとテーブルを1個消す😈​

docker compose exec db sh -lc 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "DROP TABLE IF EXISTS demo_table;"'

演習B：さっきの手順で復元して、戻ったことを確認✅​

  • pg_restore --clean --if-exists を実行
  • \dt でテーブルが戻ってるか見る👀

この演習が通ったら、あなたはもう「戻せる人」です😺✨

7) 上級：volumeを tar で丸ごとバックアップ（便利だけど注意！）🧱📦⚠️​

まず大前提： **Postgresのデータディレクトリをファイルコピーする系は、基本“DB停止が必要”**です。 tar などはファイルシステムの原子的スナップショットを取らないので、停止なしだと壊れる可能性がある、と公式がはっきり説明しています(PostgreSQL)

それでも「開発用に、完全停止してからサクッと取る」なら使えます🙂

7-1. ボリューム名を探す🔎​

docker volume ls

Composeのボリュームは プロジェクト名_ボリューム名 みたいな名前になりがちです（例：myapp_pgdata）。

7-2. DBを止める（超重要）🛑​

docker compose stop db

7-3. volume → ローカルへtar保存📦​

（例：ボリューム名が myapp_pgdata の場合）

docker run --rm -v myapp_pgdata:/data -v "${PWD}\backups:/backup" alpine sh -lc "cd /data && tar -czf /backup/pgdata.tgz ."

Docker公式ドキュメントにも、tar を使ったボリュームのバックアップ／リストア例が載っています(Docker Documentation) ただし、Postgresに関しては停止前提にするのが安全です😺

8) つまずきがちなポイント集（先回り）🧯✨​

😵 「psql: FATAL: password authentication failed」​

  • ユーザー名/DB名が違う可能性
  • .env 側の POSTGRES_USER / POSTGRES_DB / POSTGRES_PASSWORD を見直す （この章のコマンドはコンテナ内の環境変数を参照するので、基本は合ってるはず👌）

😵 「バックアップはできたけど復元でエラーが山盛り」​

  • まず --clean --if-exists を付けてみる（開発ならこれが最強🧹）
  • それでもダメなら「dumpを取った時のスキーマと、今のコードがズレてる」こともある（マイグレーションの整合性問題）

😵 「PowerShellのリダイレクトが怖い」​

  • だから cp方式（コンテナ内に作ってから取り出す） が安定なんです😺✨

9) AIに手伝わせるコツ🤖✨（安全運用）​

おすすめの聞き方（コピペOK）👇

Docker Composeのdbサービス(Postgres)で、pg_dump -Fcでバックアップし、pg_restoreで復元する手順を、
Windows PowerShellで動く形で出して。docker compose cp方式も含めて。
注意点（停止が必要なケース、--clean/--if-exists）も箇条書きで。

出てきた手順は、最後にあなたが 「消していいもの/ダメなもの」 を確認するのが大事👍 （特に本番系の話になると、消し方の判断が命です😇）

✅ この章の“持ち帰りテンプレ”（最短3本）🎁✨​

バックアップ（安定版）

docker compose exec db sh -lc 'pg_dump -Fc -U "$POSTGRES_USER" -d "$POSTGRES_DB" -f /tmp/db.dump'
docker compose cp db:/tmp/db.dump backups/db.dump

復元（掃除しながら）

docker compose cp backups/db.dump db:/tmp/db.dump
docker compose exec db sh -lc 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists /tmp/db.dump'

確認

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

次の章（第27章）では、このバックアップ資産を“事故らない形で守る”ために、秘密情報・権限・マウント範囲を最小セットで固めていきます🔐🚧✨