chore(#124): DB 運用 Runbook を追加し Cloud SQL 関連の設定を整理

[bobtaroh]

概要

Issue #124 の STG 計測で「Cloud Run (asia-northeast1) ⇄ Neon DB (us-east-1) のクロスリージョン RTT が p50 1.5sec の主因」と判明したので、まず DB に対する破壊的・大規模な変更全般に使える 運用 Runbook を整え、合わせて Cloud SQL を使わないことを前提とした設定整理をする。

Runbook の妥当性は Issue #124 の検証作業 (us-east-1 → Singapore Neon → us-east-1 への往復) で確認済み。今回の Singapore 移行はそのまま Runbook の Case Study として残してある。

実際の DB 移行 (production を含む正式切替) はこの Runbook に沿って別途実施する。

詳細

追加: docs/db-operations.md

DB に対する破壊的・大規模な変更全般の Runbook。Alembic で完結する無停止スキーマ変更は対象外。

想定ユースケース:

• リージョン移行 (Neon us-east-1 → ap-southeast-1 等)
• プロバイダ移行 (Neon → Cloud SQL on asia-northeast1 等)
• メジャーバージョン更新 (Postgres 16 → 17 等で in-place アップグレードが不可能なとき)
• 大規模データ再構築 (pg_dump → 変換 → リストアが必要なとき)

共通フロー 12 ステップ:

1. 計画 (スコープ・所要時間・ロールバック条件)
2. 切替先 DB の準備
3. ローカル準備 (psql/pg_dump、環境変数)
4. メンテナンスモード ON (production のみ)
5. 旧 DB から pg_dump
6. 新 DB へリストア
7. 件数 / スキーマの整合性確認
8. Secret Manager の DATABASE_URL_* を新 URL に差し替え
9. Cloud Run を新リビジョンで再デプロイ
10. 疎通確認 + レイテンシー計測
11. メンテナンスモード OFF
12. 旧 DB の保持と削除

Case Study として Issue #124 の Singapore 移行検証 (前後の p50/p95 数値、Runbook へのフィードバック) を末尾に収録。

修正

• docs/requirements.md: 仕様書の DB 記述を「MySQL」「Railway」から「PostgreSQL (Neon)」「GCP Cloud Run」に修正し、Runbook への参照を追加
• .github/workflows/deploy-backend.yml: Cloud Run デプロイステップに --clear-cloudsql-instances を追加。古いリビジョンに残る run.googleapis.com/cloudsql-instances アノテーションがデプロイのたびに引き継がれてしまうため、毎回明示的にクリアする
• scripts/setup-gcp.sh: Cloud SQL インスタンス / DB / ユーザー作成と DATABASE_URL 生成のロジックを削除し、外部 DB (Neon) 前提に整理。Secret 自体の登録は手動とし、本スクリプトでは存在チェックと IAM 権限付与のみを行う。sqladmin.googleapis.com の有効化や roles/cloudsql.client の付与も Cloud SQL を使う場合の参考としてコメントだけ残す

動作確認

• bash -n scripts/setup-gcp.sh で構文 OK
• 未参照変数 (INSTANCE_NAME/DB_USER 等) が残っていないことを grep で確認
• Runbook 本体は破壊的操作を含まないドキュメントなので、構文・整合性のみ検証
• Runbook の手順 2 〜 11 は Issue 【バックエンド】APIレイテンシー追加改善：ボトルネック特定と最適化（#118 の続き） #124 検証 (2026-05-23) で実際に staging に対して実施済みで、すべて再現可能であることを確認。学びは Case Study の「Runbook へのフィードバック」セクションに収録

Issue #124 の検証で取れた数値 (n=30、参考)

route	tot_p50 us-east1	tot_p50 sg	tot_p95 us-east1	tot_p95 sg
/trips/url/{url_id}	1477ms	727ms	1607ms	821ms
/trips/{trip_id}	1481ms	728ms	1651ms	808ms
/trips/{trip_id}/pages	1313ms	647ms	1473ms	725ms
/pages/{page_id}/blocks	1310ms	646ms	1630ms	725ms
/blocks/{block_id}	1147ms	644ms	1478ms	723ms

すべて約 -50% (≒ 太平洋越え RTT 半減ぶん)。詳細は PR #139 (計測スクリプト) の本文を参照。

確認項目

• 動作確認を実施している (上記、本 PR では破壊的操作を含まないため構文 / 整合性のみ)
• issueはPRページ右下のDevelopmentからissueが紐づいている (【バックエンド】APIレイテンシー追加改善：ボトルネック特定と最適化（#118 の続き） #124)

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

本 PR は、Issue #124 で判明したクロスリージョンレイテンシーの改善を目的として、DB を Neon の ap-southeast-1 リージョンへ移行するための準備作業です。実作業のための SOP を整備し、既存のインフラセットアップスクリプトから Cloud SQL 関連のロジックを整理・削除することで、外部 DB 利用への移行をスムーズにするための変更を行っています。

Highlights

• DB リージョン移行 SOP の策定: Neon DB を us-east-1 から ap-southeast-1 へ移行するための詳細な運用手順書 (SOP) を docs/db-migration.md として追加しました。
• インフラ構成の整理: Cloud SQL への依存を排除し、外部マネージド DB (Neon) を前提とした構成へ移行しました。これに伴い scripts/setup-gcp.sh から Cloud SQL 作成ロジックを削除し、Secret の管理と IAM 権限付与に特化させました。
• デプロイ設定の最適化: Cloud Run デプロイ時に古い Cloud SQL インスタンスのアノテーションが引き継がれないよう、--clear-cloudsql-instances を追加しました。

New Features

🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/deploy-backend.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[github-actions]

Visit the preview URL for this PR (updated for commit 87bbc9d):

https://tabi-share-8ef6b--pr140-chore-issue-124-db-m-fw25vsxd.web.app

_{(expires Sat, 30 May 2026 15:13:14 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 9f2a87ede127df7673322845e34cf22c1372d720}

[bobtaroh]

このPRは不要になったので、closeする、