PG16 Upgrade Preflight: online-karte-service
本書は
online-karte-serviceの Aurora PostgreSQL 13.23 → 16.13 メジャーバージョンアップに関する 事前調査・実測結果・方式判断材料・未解決事項 をまとめる。本番で実際に実行する停止、Datastream 操作、replication slot 操作、major upgrade、復旧、rollback 等の 操作手順は本書に含めない。実行手順は別の production runbook で管理する。
対象サービス: online-karte-service
DB: Amazon Aurora PostgreSQL 13.23 → 16.13
外部 CDC: GCP Datastream → BigQuery
最終更新: 2026-09-18
0. 結論サマリ
0-1. 現時点の方式判断
現時点では in-place major upgrade を第一候補とする。
これは「Blue/Green が 90 分のメンテナンス枠に収まらない」ためではない。Blue/Green も本番相当 clone で実測上は 60〜80 分程度の枠で実施可能であり、Switchover の write downtime は約 3 秒だった。
in-place を第一候補とする理由は以下。
- 本番相当 clone で dedicated in-place upgrade を 2 回実施し、全断が 606 秒 / 639 秒(約 10〜11 分) と再現している。
- reader を含む完全復帰も約 12 分台であり、90 分のメンテナンス枠に対して十分な余裕がある。
- in-place ではサービスの write を止めた状態で logical replication slot を削除・再作成できるため、slot 不在期間の業務 DML を 0 件に維持する設計を取れる。
- 上記が成立すれば、Datastream の旧 log position から新 slot の first LSN までに補完すべき業務 change event を発生させず、通常時の全件 backfill / 自前差分補完を回避できる。
- Blue/Green は write downtime を約 3 秒に短縮できる一方、外部 Datastream slot を外した状態で Blue を稼働させる時間が長くなり、CDC gap の補完設計が複雑になる。
したがって判断軸は、「90 分に収まるか」ではなく、「約 10〜11 分の計画停止を許容することで CDC 整合性と移行手順を単純化する価値があるか」 とする。
0-2. 現時点の Go/No-Go 判定
条件付きで in-place 採用可能。重大な技術ブロッカーは現時点では確認されていない。
本番実施前に残っている主要事項は次の 3 点。
- PG16 Cluster Parameter Group の本番用 Terraform 化
- staging での Datastream 復旧リハーサル
- slot 不在時の state 遷移
- 同名 slot 再作成後の自動再接続 / Recover 要否
- Recover 時に既存 Completed object の backfill が自動起動しないことの確認
- rollback 方針と RTO の合意
- snapshot restore 所要は未実測
- PG16 で write 再開後は PG13 snapshot への単純 rollback ができず、原則 fix-forward
1. 対象環境
| 項目 | staging | production |
|---|---|---|
| リージョン | ap-northeast-1 | ap-northeast-1 |
| DB | online_karte | online_karte |
| 現行 engine | Aurora PostgreSQL 13.23 | Aurora PostgreSQL 13.23 |
| target | Aurora PostgreSQL 16.13 | Aurora PostgreSQL 16.13 |
| instance topology | Writer 1 台 | Writer 1 + Reader 2 |
| instance class | db.t3.medium | db.r6g.2xlarge ×3 |
| backup retention | 7 days | 7 days |
| Global Database | なし | なし |
| RDS Proxy | なし | なし |
| current volume | — | 約 89.1 GiB(2026-09-18 実測) |
容量値について
過去資料では約 159 GB としていたが、2026-09-18 の VolumeBytesUsed / snapshot AllocatedStorage は約 89 GiB だった。159 GB の出所は未確定。
2026-07 の dedicated in-place clone 計測時の実容量も確定していないため、606/639 秒は 本番相当 clone による代表値として扱い、完全一致保証とはしない。
2. アーキテクチャと Aurora 接続元
最新調査では、online-karte-service Aurora への直接接続元を pg_stat_activity / pg_stat_replication / pg_roles / Performance Insights(7日)/ ECS task IP の突合で確認した。
2-1. production の Writer / Reader
| instance | role | 主な用途 |
|---|---|---|
online-karte-service-2 | Writer | application write / read、Datastream CDC |
online-karte-service-0 | Reader | application read、Trocco read |
online-karte-service-1 | Reader | application read、Trocco read |
過去調査では
online-karte-service-0を Writer と誤認していた。最新実測では Writer=-2、Reader=-0/-1が正しい。Writer/Reader 固有メトリクスを参照する際は対象 instance を取り違えないこと。
2-2. Aurora への直接接続アーキテクチャ
Aurora に TCP で直接つなぐ実体は 4 種類だけ。太線が書き込みを伴う経路。
読み方のポイント。
| 見るべき点 | 内容 |
|---|---|
| 書き込むのは 2 経路だけ | ECS(application DML)と Datastream(論理レプリケーションの読み取り接続。DB は変更しないが slot を保持する) |
Writer は -2 | 書き込みも CDC の slot も Writer にしかない。Reader で slot 系メトリクスを見ても常に 0 になる |
| Datastream は単一ホストではない | 接続プロファイルの 10.128.0.5 は internal LB の VIP。Aurora が観測する接続元は HAProxy VM 2 台(10.128.0.22 / 10.128.0.23) |
| Trocco は Reader 専用 | 踏み台経由で Reader だけに接続(app_name=trocco.io)。書き込み経路ではない |
| 踏み台は書ける | 運用者 psql は Writer にも接続できる。メンテナンス中の不用意な 1 行が write freeze を壊す |
DB role はログイン可能なものが 3 つだけ(n3dnr9bs / datastream / rdsadmin)。application はすべて n3dnr9bs に集約されているため、接続元の識別は client_addr で行う(application_name は Trocco と psql 以外は空)。
rdsadmin は AWS の管理プロセスで、全 instance に local 接続する。制御も停止もできないが、pgAudit の WRITE には現れないため write freeze の判定には影響しない。
2-3. 直接接続元の実測一覧
| 接続元 | user | 接続先 | read/write | 用途 |
|---|---|---|---|---|
online-karte-service-service ECS ×5 | n3dnr9bs | Writer + Reader | read/write | 本体 API。DATABASE_URL=Writer / DATABASE_REPLICA_URL=Reader |
| GCP Datastream(HAProxy 2台経由) | datastream | Writer only | CDC read | logical replication / WAL sender |
| Trocco(Tokyo bastion 経由) | n3dnr9bs | Reader only | read only | ETL |
| 運用者 psql(Tokyo bastion 経由) | n3dnr9bs | 任意 | 原則調査 | 手動運用・調査 |
| RDS internal | rdsadmin | 全 instance | AWS internal | RDS 管理プロセス |
ログイン可能な DB role は実測上 n3dnr9bs / datastream / rdsadmin の3つ。application 用 DB user は n3dnr9bs の1つに集約されている。
2-4. Datastream の実接続経路
Datastream connection profile が指している 10.128.0.5:5432 は Aurora へ直接接続するホストではなく、GCP internal LB の VIP。実際には2台の HAProxy VM に分散される。
GCP Datastream online-karte
-> connection profile: 10.128.0.5:5432
-> GCP Internal LB
-> HAProxy 10.128.0.22
-> HAProxy 10.128.0.23
-> Aurora Writer endpoint (DNS dynamic resolution)
-> online-karte-service-2Aurora 側で観測される client_addr は 10.128.0.22 / 10.128.0.23。HAProxy は resolvers awsdns / hold valid 5s で Aurora endpoint を動的解決している。
現在の logical replication は以下。
- publication:
datastream/FOR ALL TABLES - slot:
datastream_replication_slots/pgoutput - slot state:
active=t pubinsert/pubupdate/pubdelete/pubtruncate = t
2-5. Aurora へ直接接続していない主要コンポーネント
以下は調査時点で online-karte-service Aurora への直接 DB 接続は確認されていない。
| component | DB direct connection | 実際の経路 / 補足 |
|---|---|---|
chronic-api | なし | backend-online-karte HTTP API 経由。DB credential なし |
online-ops-service / worker | なし | 自サービス DB または API 経由 |
online-karte-websocket-service | なし | 7日間の接続元に未出現 |
online-karte-front-service | なし | 7日間の接続元に未出現 |
| Retool | なし | Aurora 直結ではなく BigQuery 等を参照 |
| Airflow / MWAA | なし | online-karte DB への DB 接続を確認せず |
| Lambda 各種 | なし | SQS / API 経由で application に到達 |
online-karte-docs | なし | 別 Aurora cluster |
chronic-api は Security Group 上 Aurora:5432 を許可されているが、現在の task definition に DB credential はなく、7日間の実接続も確認されていない。SG の許可だけを「実接続あり」と解釈しない。
2-6. Direct DB connection と write 発生経路は分けて考える
以前の調査では EventBridge / Lambda ESM / SQS / Twilio / Retool 等を含めて18系統を「write source」として列挙していたが、最新の DB 接続調査では、Aurora に直接 application write を行う実体は online-karte-service-service ECS の5タスクに集約されている。
EventBridge、SQS、Lambda、外部 webhook 等は Aurora に直接接続する DB client ではなく、API / application layer を経由して最終的な DB write を誘発する上流トリガである。
したがって preflight 上は次のように整理する。
- 直接 application writer:
online-karte-service-serviceECS ×5 - CDC consumer: Datastream(Writer only)
- read-only consumer: Trocco(Reader only)
- manual connection: operator psql(任意 instance。メンテ時に不用意な write を行わない)
- AWS internal:
rdsadmin - indirect write trigger: API / queue / webhook 等を介して application writer に到達する上流系統
この区別により、「18系統すべてがAuroraへ直接接続している」という解釈はしない。
3. Preflight 実測結果
docs/sre/scripts/pg16-preflight-check.sh を staging / production で read-only 実行済み。
| 区分 | staging | production | 判定 |
|---|---|---|---|
| SUMMARY | PASS=25 / WARN=1 / FAIL=2 | PASS=25 / WARN=3 / FAIL=2 | FAIL/WARN は既知項目 |
| PK なし table | 2 | 2 | mastra_evals, mastra_workflow_snapshot |
| REPLICA IDENTITY 不適 | 0 | 0 | 対応済み |
| logical replication slot | 1 | 1 | Datastream 用 |
| prepared transaction | 0 | 0 | PASS |
| unlogged table | 0 | 0 | PASS |
| large object | 0 | 0 | PASS |
| long transaction | 0 | 0 | PASS |
| PG16 非互換 SQL / object | 0 | 0 | PASS |
rds.logical_replication | on | on | PASS |
wal_level | logical | logical | PASS |
wal_sender_timeout | 0 | 0 | PASS |
publication datastream | 1 | 1 | FOR ALL TABLES |
| sequence | 58 | 58 | 参考 |
3-1. Logical replication slot は in-place の明確なブロッカー
Aurora PostgreSQL の major version upgrade は logical replication slot が存在すると進められない。実際の clone 計測でも Datastream slot が原因で precheck failure を確認済み。
公式根拠
- AWS: Performing a major version upgrade
https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.PostgreSQL.MajorVersion.htmlDrop logical replication slotsが major upgrade の事前要件として明記されている。
- AWS: Reestablishing logical replication after a major upgrade
https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Appendix.PostgreSQL.CommonDBATasks.pglogical.recover-replication-after-upgrade.html- publisher への transaction を一時的に迂回し、slot を削除して upgrade 後に replication を再確立することを推奨している。
4. PG16 Parameter Group 調査
4-1. PG13 production の user 設定
| parameter | PG13 current | PG16 方針 | reboot |
|---|---|---|---|
rds.logical_replication | 1 | 1 | static |
max_wal_senders | 20 | 20 | static |
shared_preload_libraries | pgaudit,pg_stat_statements | 同値 | static |
wal_sender_timeout | 0 | 0 | dynamic |
max_slot_wal_keep_size | 1000 | 1000 | dynamic |
pgaudit.log | all | all | dynamic |
log_min_duration_statement | 1000 | 1000 | dynamic |
rds.log_retention_period | 1440 | 1440 | dynamic |
max_replication_slots | default 20 | default 20 | static |
instance parameter group には user 設定が 0 件であることを確認済み。
4-2. PG16 での互換性
同一アカウント / 同一リージョンの別 cluster online-karte-docs が Aurora PostgreSQL 16.6 / available で稼働しており、その CPG は --source user で 上記 8 parameter を production PG13 と完全に同一の値で明示設定している(2026-09-18 実測)。したがって「この 8 設定の組み合わせが PG16 family で成立すること」は稼働実績で裏付けられている。本番用 CPG は実質この CPG の複製でよい。
PG13 → PG16 で廃止された cluster parameter は 3 件(rds.extensions / rds.run_logical_replication_as_subscription_owner / vacuum_defer_cleanup_age)で、いずれも production では未設定のため移行影響はない。
ただし target は 16.13 であり、online-karte-docs は 16.6 であるため、本番用 CPG 作成後に staging で主要値を実測確認する。
PG16 で追加された logical replication 関連 parameter は基本的に default のままとする。特に aurora.enhanced_logical_replication は移行時に新規有効化しない。
なお wal_level は Aurora では直接設定可能な parameter として存在せず、rds.logical_replication から導出される。PG13 / PG16 とも同じ挙動。
本番で CPG 未整備のまま upgrade した場合の最大リスクは、
rds.logical_replication=1/max_wal_senders=20(いずれも static)が既定値に戻り、PG16 起動後に logical replication slot を作成できず CDC が復旧しないこと。clone 実測では AWS 側が不整合を自動補正するイベント(adjusted from 10 to 20/adjusted from 0 to 1)も観測されているが、Reader 側では逆方向の補正(1 to 0)も出るため、自動補正に依存せず CPG で明示設定する。
4-3. 本番の未完了事項
本番用 online-karte-service-pg16 Cluster Parameter Group は未作成。Terraform 管理で作成が必要。
in-place では instance PG に non-default 設定がないため、Blue/Green 時に想定していた「cluster / instance PG の両方を必須作成」という前提は見直す。
5. In-place 所要時間の実測
5-1. dedicated in-place clone 計測
| 日付 | 構成 | Total time offline | 備考 |
|---|---|---|---|
| 2026-07-22 | production clone / db.r6g.2xlarge ×3 | 606 秒 | slot drop 後に成功 |
| 2026-07-23 | production clone / db.r6g.2xlarge ×3 | 639 秒 | 再現確認 |
| 2026-09-15 | Blue/Green の Green cluster(production clone 由来) | 691 秒 | RDS event の Total time offline 実測。13.23.5 → 16.13.3 |
reader の安定復帰まで含めた実測では、全断開始から全 instance 安定まで約 741 秒(12 分 21 秒)。
2026-09-15 の RDS event log からは in-place upgrade の内訳も取得できている(89 GiB 相当)。
| 経過 | イベント |
|---|---|
| 08:08:53 | upgrade 開始(cluster はまだ online) |
| 08:09:12〜08:09:14 | online upgrade prechecks(約 2 秒) |
| 08:09:15 | cluster を offline 化(全断開始) |
| 08:09:37 | pre-upgrade snapshot の自動作成 |
| 08:12:00 | volume clone |
| 08:14:16 | writer の upgrade |
| 08:20:46 | primary 接続可(全断終了・約 6 分 30 秒) |
| 08:22:43 | upgrade 完了 |
Total time offline として報告される 691 秒には、offline 化の前後に発生する cluster 側の処理が含まれる。アプリから見た接続不能時間はこれより短い(約 6 分 30 秒) が、runbook では安全側の 606〜691 秒を採用する。
DB 全体 ANALYZE VERBOSE は約 28〜30 秒であり、non-blocking。
5-2. Blue/Green clone 計測は比較材料として保持
| 項目 | 実測 |
|---|---|
| BG 作成 | 約 39〜40 分 |
| Switchover write downtime | 約 3 秒 |
| Switchover 全体 | 約 1 分 8 秒 |
| Green ANALYZE | 約 29〜30 秒 |
90 分枠で Blue/Green が不可能というわけではない。方式判断は停止時間だけではなく CDC 整合性・復旧手順の複雑性も含める。
6. Datastream / logical replication の事前調査
6-1. 現在の Datastream 設定
| 項目 | production |
|---|---|
| stream | online-karte / RUNNING |
| publication | datastream |
| replication slot | datastream_replication_slots |
| include | schema public |
| write mode | merge(PK なし table は append-only fallback) |
backfillAll | 有効 |
maxConcurrentBackfillTasks | 1 |
dataFreshness | 300s |
| object count | 151 |
| historical backfill completed | 102 objects |
| connection | GCP internal LB 10.128.0.5 → HAProxy VM 2 台(10.128.0.22 / 10.128.0.23)→ Aurora endpoint |
stream/freshness | 0 秒(2026-09-18・6 時間 360 点すべて 0) |
stream/total_latencies | mean 3.0〜3.6 秒 |
lastRecoveryTime | 未設定(Recover 実行実績なし) |
staging も slot 名、publication 名、backfillAll、maxConcurrentBackfillTasks=1、freshness 300s、engine 13.23 が production と一致している。
ただし instance topology / class は異なるため、Datastream の control-plane 挙動を検証する環境として適しているが、復旧所要時間や負荷の production 代表値とはしない。
6-2. BigQuery destination の構成(2026-09-18 実測)
| 項目 | 実測 |
|---|---|
| dataset | fd-datastream-prd.online_karte_public |
| table 数 | 131(Datastream object 151 のうち 20 は source が 0 行で BQ 未作成) |
| 総容量 / 行数 | 約 139.7 GiB / 約 7,007 万行 |
max_staleness | 全 table で 5 分(INTERVAL '0-0 0 0:5:0') |
| partition | なし(cluster by のみ) |
| PK | 主要 table は定義あり。mastra_workflow_snapshot のみ PK なし → append-only |
主要 table の baseline(migration 前後の突合に使用)。
| table | BQ 行数 | BQ PK |
|---|---|---|
| EventLog | 34,107,985 | id |
| KarteVersion | 5,229,441 | id |
| KarteSubmission | 800,203 | id |
| Accept | 781,810 | id |
| Karte | 781,795 | id |
| KarteContentYjs | 738,749 | karteId |
| Patient | 469,500 | id |
| WorkflowStatus | 461,346 | workflowRunId |
| mastra_workflow_snapshot | 12,478,170 | なし |
🔴
max_staleness=5 分は post-migration 検証の解釈を誤らせる最大の要因。BigQuery CDC はmax_staleness以内のクエリに対して upsert log を読まずに結果を返すため、Datastream が BQ へ書き込んでも最大 5 分間はクエリ結果に現れない。この事実を知らずに「BQ が追いついていない」と判断すると、不要な backfill を自ら起動してしまう(
maxConcurrentBackfillTasks=1のため数時間の負荷になる)。検証時は必ず 5 分以上待ってから再クエリする。出典: https://cloud.google.com/bigquery/docs/change-data-capture#manage_table_staleness
7. Publication / Replication slot / Backfill の整理
この 3 つを混同しないことが重要。
7-1. Publication
PostgreSQL publication は、publisher が どの table のどの DML change を publish するかを定義する database object。
datastream は FOR ALL TABLES で、INSERT / UPDATE / DELETE / TRUNCATE を publish している。
PostgreSQL 公式では publication の publish 設定は DML の publish 内容を制御するものであり、initial data synchronization copy そのものを制御するものではないと説明されている。
- PostgreSQL 16: Publication
https://www.postgresql.org/docs/16/logical-replication-publication.html
in-place における扱い
AWS / Google の PostgreSQL major upgrade 手順で明示的に削除対象とされているのは logical replication slot であり、publication を事前に drop するようには記載されていない。
したがって preflight 上の前提は以下とする。
- in-place では publication は事前削除しない。
- upgrade 後に
datastream/FOR ALL TABLESが維持されていることを検証する。 - 万一存在しなければ復旧対象とする。
これは「publication が必ず維持される」という独立した保証ではなく、公式 major-upgrade 手順で publication drop が要求されていないことと PostgreSQL の object 性質を踏まえた運用前提。本番 runbook では必ず post-upgrade verification を行う。
Blue/Green では別クラスタへ切り替わるため扱いが異なり、本番相当 clone 実測では Switchover 後に publication が存在しないことを確認済み。
7-2. Replication slot
Replication slot は consumer の WAL 読み取り位置を保持する stateful object。
Aurora PostgreSQL major version upgrade では logical replication slot が存在すると upgrade できないため、in-place でも削除・upgrade 後再作成が必要。
- AWS: Performing a major version upgrade
https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.PostgreSQL.MajorVersion.html - Google Datastream: Stream data from PostgreSQL databases
https://cloud.google.com/datastream/docs/sources-postgresql
Google は PostgreSQL major upgrade について、slot を drop → database upgrade → slot recreate とし、stream が fail した場合は Recover、data consistency が必要なら backfillを行うよう案内している。
重要なのは、slot recreate と backfill は同じ操作ではないこと。
再作成そのものは一瞬で終わる(実測)
2026-09-15 の本番 clone(PG16 16.13)での実測値。
| 操作 | 所要 |
|---|---|
CREATE PUBLICATION datastream FOR ALL TABLES(135 table) | 19.6 ms |
pg_create_logical_replication_slot('datastream_replication_slots','pgoutput') | 47.3 ms |
| 合計 | 約 0.07 秒 |
つまり slot / publication の再作成はメンテナンス枠の律速要因にならない。律速になりうるのは backfill が走った場合のみ。
7-3. Slot 再作成後の CDC gap
新しく作成した replication slot は、旧 slot の過去位置をそのまま復元するものではない。
Google Datastream Recover の仕様では、新しい slot の first LSN から stream を再開し、旧 log position を失った時点から新 slot の first LSN までに発生した change events は失われ得る、とされている。
- Google Datastream: Recover a stream
https://cloud.google.com/datastream/docs/recover-a-stream
したがって、次の 2 ケースを分ける。
A. slot 不在期間に業務 DML がある
- Datastream から取得できない change event が存在する。
- data consistency が必要なら backfill または差分補完が必要。
B. slot 不在期間の業務 DML が 0
- old position と new slot first LSN の間に、補完対象となる業務 change event が存在しない。
- この場合、通常の全件 backfill を実施する理由はない。
「B なら backfill 不要」は Google がその文章のまま保証しているものではなく、Google が定義する loss 範囲と今回の write-freeze 設計から導く運用判断。
7-4. backfillAll の意味
backfillAll を設定していることは、slot を再作成するたびに既存 Completed object を全件再 backfill することを意味しない。
Datastream は object ごとに backfill state を持ち、既存 object の backfill を再実行する場合は backfill を開始する操作が別途存在する。
- Google Datastream: Manage backfill for stream objects
https://cloud.google.com/datastream/docs/manage-backfill-for-the-objects-of-a-stream
したがって現時点の理解は以下。
slot recreate
!= automatic full backfill
publication recreate
!= automatic full backfill
Recover
!= necessarily automatic full backfillただし Recover 時に今回の backfillAll stream で Completed object の state がどう変化するかは実測未了のため、staging リハーサルで確認する。
7-5. backfill を回避する価値(実測)
2025-09-17 の全件 backfill 実績(102 objects / 合計 204.5 分)と現在の行数から算出した所要見積り。maxConcurrentBackfillTasks=1 のため 逐次実行であり、合算される。
| table | 当時の実測 | 現在の規模 | 現在の所要見積り |
|---|---|---|---|
| KarteVersion | 6,843 秒(114 分) | 5,229,441 行 / BQ 53.2 GiB | 約 5.7 時間 |
| EventLog | 2,684 秒(44.7 分) | 34,107,985 行 / BQ 16.0 GiB | 約 2.4 時間 |
| KarteContentYjs | 779 秒(13 分) | 738,749 行 / BQ 22.3 GiB | 約 1.0 時間 |
| Karte / Accept | 42 秒 / 41 秒 | 各 約 78 万行 | 各 約 3 分 |
| KarteSubmission | 31 秒 | 800,203 行 | 約 2 分 |
| WorkflowStatus | 22 秒 | 461,346 行 | 約 2〜3 分 |
全件 backfill は現実的な選択肢ではない。これが「slot 不在期間の business DML を 0 にして backfill 自体を不要にする」設計を採る根拠であり、in-place を第一候補とする理由の中核。
8. Write freeze の成立性
in-place を採用する場合の CDC 整合性は、slot 不在期間の business DML を 0 件にできることに依存する。
最新の接続元調査では、Aurora に直接 application write を行う経路は online-karte-service-service ECS 5タスクに集約されている。一方で、外部イベントやqueue等がこの application layer を起動するため、write freeze では 入口の遮断と DML が実際に 0 になったことの観測を分けて扱う。
入口の遮断手段は ECS desired-count 0 のみである。ECS を動かしたまま ALB で塞ぐ方式は理屈の上では成立するが、その仕組みが実装されていない(8-1 の訂正を参照)。いずれの方式でも ALB を迂回して DB に直結する経路(master ETL / 運用者 psql)は別途止める必要がある。
Trocco は Reader-only、Datastream は CDC consumer、rdsadmin は AWS internal であり、通常の business DML writer ではない。operator psql は任意 instance に接続可能なため、メンテナンス中の不用意な手動 write は別途防止する。
8-1. 観測手段
本番では pgaudit.log=all が有効で、CloudWatch PostgreSQL logs に READ / WRITE / DDL / MISC が出力されている。
直近 30 分の調査では以下を観測。
| class | command | 件数 / 30 分 |
|---|---|---|
| READ | SELECT | 145,116 |
| MISC | BEGIN / COMMIT | 各 21,959 |
| WRITE | INSERT | 4,161 |
| WRITE | UPDATE | 125 |
| WRITE | DELETE | 0 |
| MISC | SET | 87 |
pgAudit は READ / WRITE / DDL / MISC を class として明示的に分類するため、autovacuum 等の内部処理と application DML を分離できる。判定に使うクエリは以下。
fields @timestamp, @message
| filter @message like /AUDIT: SESSION/
| parse @message "AUDIT: SESSION,*,*,*,*,*," as a, b, cls, cmd, objtype
| filter cls = "WRITE" or cls = "DDL"
| stats count() as n by cls, cmd出力先は log group /aws/rds/cluster/online-karte-service/postgresql(2026-09-18 時点で約 232 GB 蓄積・retention 無期限)。
pgAudit は application DML / DDL を確認する強い観測手段だが、単独で数学的な完全証明とはしない。
補助的な観測手段(Writer online-karte-service-2 で実測)
pgAudit 以外にも、独立した signal が複数使える。いずれも Writer で測ること。
02:00〜03:00 JST・過去7日の平常値(write freeze 時はこれが 0 近傍へ落ちる)
| 手段 | 平常値(02:00-03:00 JST) | write freeze 判定での使い方 |
|---|---|---|
PI db.SQL.tup_inserted | 0.21〜0.68 /s | 0 になること。application DML の直接指標 |
PI db.SQL.tup_updated | 1.62〜1.98 /s | 同上 |
PI db.SQL.tup_deleted | 0.06〜0.30 /s | 同上 |
CloudWatch WriteIOPS | 19.6〜61.8(avg 21.3) | 大幅に低下すること。ただし autovacuum 等でも発生するため 0 にはならない |
CloudWatch OldestReplicationSlotLag | 45,398〜559,672 B(avg 60,203) | 0 になること=slot が WAL を読み切った証拠 |
CloudWatch CommitThroughput | 取得可(直近 69.73) | 参考値 |
使えないもの
| 手段 | 結果 |
|---|---|
CloudWatch DMLThroughput | データポイント 0。Aurora PostgreSQL では未提供 |
PI db.Transactions.xact_commit | 02:00-03:00 JST でも 12.21〜15.60 /s。read-only transaction も計上されるため 0 にならず、write=0 の証明には使えない |
⛔ Reader で測ると全ての値が意味を失う。Reader(
-0/-1)ではWriteIOPS=0.00、tup_*=0.0、OldestReplicationSlotLag=0 が常に返り、「write が無い」ように見えてしまう。slot は Writer にしか存在しない。⛔ タイムゾーンの罠:AWS CLI は CloudWatch / Performance Insights のタイムスタンプを JST(
+09:00)で返す一方、RDSdescribe-*は UTC(+00:00)で返す。UTC と思い込んで時刻を換算すると、02:00 JST のつもりでまったく別の時間帯を測ることになる。必ず raw のオフセットを確認すること。
write freeze 判定には以下を組み合わせる。
- pgAudit で WRITE / DDL が一定期間 0
- SQS in-flight が 0
- Datastream event_count が 0
- replication slot lag / confirmed position が追従済み
- すべての write source が停止状態であること
深夜帯でも DML は 0 にならない(実測)
「深夜 02:00 なら write がない」という前提は成立しない。Datastream stream/event_count の 02:00–03:00 JST 実測(7 日)は以下。
| 日付(JST) | change events |
|---|---|
| 09-11 | 898 |
| 09-12 | 1,096 |
| 09-13 | 1,231 |
| 09-14 | 696 |
| 09-15 | 1,186 |
| 09-16 | 1,268 |
| 09-17 | 1,479 |
一度も 0 になっていない(参考: 全時間帯 min 493 / avg 7,801 / max 17,512 events/h)。つまり write freeze は「時間帯に頼る」のではなく「能動的に全経路を止める」ことでしか達成できない。
停止対象(2026-09-18 実測値)
application write は2系統ある。API 経由(大多数)と、API を迂回して Aurora に直結する経路。後者は ECS を desired=0 にしても止まらない。
① API 経由
外部トリガ(Twilio / mental-appointment / EventBridge / SQS / Retool)
→ Lambda・chronic-api(いずれも DB credential を持たず HTTP のみ)
→ online-karte-service ECS ×5 ← ここだけが DB に接続する
→ Aurora Writer
② API を迂回(★ECS desired=0 では止まらない)
master ETL(`nest start --entryFile main.command` = 別エントリポイント)→ Aurora Writer 直結(DDL を含む)
運用者 psql(踏み台 10.10.15.214) → Aurora Writer 直結⛔【訂正 2026-09-24】「ECS 停止は必須ではない — ALB 遮断で代替できる」は誤りだった
旧版の記述: 「①の経路は ALB で入口を塞げば一括で止まるため、ECS を
desired=0にしなくても write freeze は成立する」 訂正: online-karte には ALB で入口を塞ぐ仕組みが実装されていない。
確認項目(2026-09-24 実測) 結果 ALB リスナールール 2 本とも forward。fixed-responseは未設定WAF の関連付け なし application の maintenance mode app/src/bff/srcを全文検索して該当実装なし。maintenance 系 FF(11365-enable-patient-products-maintenance-mode/15336-*)はすべて患者プロダクト専用(PMP・メンタル予約v2)で online-karte は対象外🔴
ECS desired-count 0が online-karte を止める唯一の手段である。 「ALB で塞げば止まる」というアーキテクチャ上の性質は正しい(入口が 1 つなので塞げば止まる)が、 それはメンテナンス枠の中で本番 ALB のリスナールールを新規に変更する作業であり、既存の仕組みではない。 2026-09-24 に方式 C(ECS 停止のみ+深夜の受付停止ウィンドウに重ねる)を採用したため、この方式は採らない。 詳細と時間予算への影響:staging-inplace-upgrade.md§13-1 / §15-1。
ECS タスクの挙動(2026-09-18 実測・この表自体は有効)
以下は「DB 断中に ECS タスクが自律的に write / DDL を発行しないか」の実測であり、遮断方式の選択とは独立に有効である。
| 確認項目 | 実測 | 意味 |
|---|---|---|
| アプリ内の自律処理 | @Cron / pg-boss / Bull / SQS handler すべて 0 件 | 入力が無ければ自分からは書かない |
| 起動時 migration | Dockerfile CMD ["npm","run","start:prod"] → node dist/src/main のみ。prisma migrate deploy なし | タスクが再起動しても DDL を流さない |
/healthz の実装 | return { status: 'ok' }(app.service.ts)。DB を触らない | DB 断中も 200 を返す |
| ALB health check | path /healthz / interval 40s / unhealthy 閾値 10 / timeout 30s / matcher 200,201 | DB が落ちてもタスクは unhealthy にならず置き換わらない |
| ECS service | healthCheckGracePeriod=0 / min 100% / max 200% | 同上 |
💡 これらより、
desired=0の間にタスクが勝手に DDL を流したり、DB 断を理由に置き換わったりしないことが確認できている。⛔ 旧版はここに「利点:
desired=0→5のスケールアウト待ち(数分)が不要になり、メンテナンス枠が短くなる」と書いていたが、遮断機構が存在しない以上この利点は得られない。ECS 再開の 5 分は時間予算に計上する(staging-inplace-upgrade.md§15-1 #14)。
⛔ CloudFront での遮断では不十分。API の入口は CloudFront ではなく公開 ALB であり、
chronic-apiも各 Lambda もこの ALB を直接叩く。textonline-karte.fstdr.jp -> CloudFront (d3jc3yj0knvwlx.cloudfront.net) ← ユーザー向け画面 backend-online-karte.fstdr.jp -> 公開 ALB online-karte-service-2073905677... ← ★API はこちら 54.178.184.240 / 43.206.53.238CloudFront だけを止めても、SQS に溜まった仕事が Lambda → chronic-api → ALB 経由で流れて write が発生する。 ⛔ 旧版はここで「遮断は ALB のリスナールール(固定 503 等)または WAF で行うこと」と指示していたが、そのルールは実装されていない(上の訂正)。入口を止める手段は ECS
desired-count 0のみである。 なお「入口が公開 ALB に 1 本化されており、CloudFront では不十分」という事実自体は有効で、これは ECS を止めれば①の経路が一括で止まることの根拠でもある。
⛔ ECS を起動するのは slot 再作成が完了した後(旧版は「ALB を開けるのは」と書いていた)。
textslot DROP → PG16 upgrade(DB 断 約10分)→ DB 復帰 → wal_level / publication 確認 → slot CREATE ← ここまで ECS は desired=0 → Datastream RESUME → 復旧確認 → backfill 異常なし確認 → 最終 Go → ECS 起動(=医師トラフィック再開)DB 復帰から slot 再作成までの間に ECS を起動すると、その間の write は CDC から永久に失われる。 🔴 さらに ECS 起動=医師トラフィック再開(遮断手段が無い)ため、backfill 異常なしの確認を ECS 起動より前に完了させる必要がある。順序の詳細は
staging-inplace-upgrade.md§13-1。
停止対象の一覧
| 対象 | 区分 | 現在値 | 備考 |
|---|---|---|---|
ECS desired-count 0 | 必須 | ECS desired 5 | 🔴 online-karte を止める唯一の手段(2026-09-24 訂正)。ALB リスナールールは 2 本とも forward で fixed-response 未設定・WAF 未関連付け・app 側 maintenance mode も未実装。CloudFront では不可 |
update-orca / update-dataindex 系 ETL | 必須 | アプリ内 cron なし(@Cron 0 件)=手動 / 外部起動 | 別プロセスで DB 直結。desired=0 を迂回するうえ DDL を発行。自動起動しないため周知でしか防げない |
| 運用者 psql(踏み台経由) | 必須 | 接続実績あり(10.10.15.214) | desired=0 を迂回する。調査のつもりの1行が write=0 を壊す。作業者への周知 |
| release(migration / dbt tag push) | 必須 | — | migration が DDL/DML を流す。凍結周知 |
Lambda ESM retry-receipt-workflow-worker | 衛生 | Enabled(UUID 20307d29-bc20-4e8c-939a-4efe18ec8c20) | ECS が 0 なら DB write は起きないが、in-flight を残さないため無効化。復旧時の enable 戻し忘れに注意(戻し忘れても無音で滞留する) |
EventBridge retry-receipt-workflow-schedule | 対応不要 | cron(30 15 * * ? *) = 00:30 JST | メンテ枠 02:00 と重ならない。実測では orchestrator が 00:30 JST に1回、worker が 00:30〜00:50 JST に 17〜48 回(1日 2026-09-17 のみ 180 回)で、01:00 JST までに完了している |
| SQS 5 キュー | 観測対象 | 現在すべて 0 / 0 / 0 | 止める対象ではない。ApproximateNumberOfMessagesNotVisible = 0(処理中なし)を Go 条件にする。滞留分は明けに処理され、slot 再作成後なので CDC に正しく乗る |
8-2. WAL LSN だけを判定条件にしない
pg_current_wal_lsn() は autovacuum など application DML 以外でも進む可能性があるため、「LSN が完全停止したこと」を write freeze の唯一条件にはしない。
必要なのは Datastream 対象 table への business DML / DDL がないこと。
9. Datastream objects 151 件の差異
Datastream object count と Aurora の瞬間的な table count を単純比較して migration failure と判定しない。
調査結果:
Datastream objects 151
├─ _temp object 35
└─ non-_temp 116
├─ Prisma model 103
├─ _prisma_migrations 1
└─ Prisma 外 12_temp object は update-orca / update-dataindex 系 ETL の table swap により一時的に作られた object を Datastream metadata が保持しているもの。
migration 後の baseline は単純な 151 件一致ではなく、non-_temp の主要 116 object が継続 CDC されていることを中心に確認する。
なお Prisma schema に存在する model で Datastream object にないものは 0 件だった。
10. 移行前から存在する CDC 不整合
PG16 migration 起因の障害と既存障害を混同しないため、以下を baseline として保持する。
10-1. mastra_workflow_snapshot
2026-08-05 以降、BigQuery への CDC が停止。
Cloud Logging で以下を確認済み。
BIGQUERY_UNSUPPORTED_PRIMARY_KEY_CHANGEmastra_workflow_snapshotのみで発生- REPLICA IDENTITY を
FULL→USING INDEXに変更したことを契機に、Datastream が BigQuery destination への primary-key change と解釈
これは PG16 migration とは独立した既存障害。
重要な認識: このテーブルは「CDC が止まっている」のではなく、Datastream は現在も source から読み取り続け、BigQuery 側が受け付けずに破棄し続けている。したがって slot の追従(lag)には影響しない。
migration 前後の baseline として以下を記録する(2026-09-18 実測)。
| 指標 | 値 |
|---|---|
BQ mastra_workflow_snapshot 行数 | 12,478,170 |
BQ MAX(datastream_metadata.source_timestamp) | 2026-08-05 |
unsupported_event_count | 約 38,037 件 / 24h |
| Datastream console 表示(7 日) | 250,854 件(上記レートと整合) |
error_code | BIGQUERY_UNSUPPORTED_PRIMARY_KEY_CHANGE |
object_name | public_mastra_workflow_snapshot のみ |
migration 後の判定は「この値が同じペースで継続していること」。
object_nameに他 table が現れた場合のみ PG16 起因の新規障害として扱う。なお Datastream console が「実行中(エラーあり)」と表示するのはこの unsupported event の警告であり、stream API のerrorsフィールドは空(stream 自体は健全)。
10-2. _temp swap 系 master tables
update-orca / update-dataindex 系は _temp table にデータを投入した後 rename で本体と交換する。
そのため CDC 上は _temp object へ新データが流れ、本体 BQ table が古いままのケースが存在する。
これも PG16 migration とは独立した既存問題。
10-3. BI / dbt
最新調査(2026-09-18)での dbt project の実測は以下。
| 項目 | 実測 |
|---|---|
| model 数 | 119(staging 96 / intermediate 21 / marts 2。うち staging 12 本は +enabled: false) |
| materialization | staging / intermediate / marts すべて view |
| incremental model | 0 本 |
| snapshot | 0 本(snapshots/ は .gitkeep のみ) |
| production trigger | cron なし。online-karte-dbt-v** の tag push のみ |
dbt test | production workflow ではコメントアウトされている |
| schema test | 4 件のみ(int 層の event_id / karte_id に unique + not_null) |
source freshness / loaded_at_field | 未設定 |
全 model が view のため dbt 側に状態が持続せず、古い source で実行しても次の参照時に自動的に最新を読む。したがって「収束しない model」は 0 本。
⚠️ 一方で marts が
viewであることは別のリスクを生む。dbt を実行していなくても、Retool / Redash / 人が Explore した瞬間に BQ raw をライブで読むため、メンテ中の stale data がそのまま BI に出る。「dbt を止めれば分析が凍る」という前提は本構成では成立せず、BI 側の利用停止周知でしか防げない。
主要な downstream consumer は BQ job 実績(14 日)から以下。旧資料の「Looker を主要 downstream とする」表現は採らない(LookML repository・Looker instance・Looker の BQ job はいずれも未確認)。
| consumer | 参照先 | 参照回数 |
|---|---|---|
| Retool | fd-datastream-prd.online_karte_public(raw) | 6,902 |
| Redash | 同上(raw) | 422 |
| Trocco | online-karte-prd.postgres | 28 |
Airflow (online-ops-prd) | online-karte-prd.ai_scribe 系 | 118(05:00 JST 帯) |
| dbt (GitHub Actions) | — | 106 |
dbt marts (main_v2) | — | 実データ参照 0 件 |
検証対象は marts ではなく、Retool / Redash が直接読む
fd-datastream-prd.online_karte_publicの raw table。marts が 2026-08-05 以降更新されていないことに 43 日間気付かれなかったのは、実データ参照が 0 件だったため。
mastra_workflow_snapshot に依存する既存 KPI は 2026-08-05 以降更新されていないため、これを PG16 migration の合否判定には使用しない。
11. アプリケーション PG16 互換性
mental-online-karte repository を確認済み。
| dependency | version | 調査結果 |
|---|---|---|
Prisma / @prisma/client | 5.18.0 | PG16 対応範囲 |
pg | 8.11.5 | protocol 上 major version 固有リスク低 |
| Mastra PG | 0.10.0 | pg 経由。RI が主要論点 |
$queryRaw,$executeRaw, unsafe raw SQL 等は 0 件。- DB access は Prisma / Mastra が中心。
- PK なし 2 table の REPLICA IDENTITY は設定済み。
- PG16 非互換 SQL の顕著なリスクは preflight で未検出。
mastra_workflow_snapshot の downstream CDC 問題はアプリ PG16 互換性とは分離して扱う。
12. Rollback 調査
12-1. upgrade 前 rollback point
Aurora major version upgrade 時には pre-upgrade snapshot が自動作成されることを clone 実測で確認済み。AWS 公式も upgrade 中に DB cluster snapshot を作成すると説明している。
- AWS: Performing a major version upgrade
https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.PostgreSQL.MajorVersion.html
12-2. RTO
snapshot restore の production 相当実時間は未計測。
現時点では以下を含めると、rollback RTO は 安全側で 90 分超を想定する。
- snapshot restore
- writer / reader 復旧
- endpoint 切替(下記の理由で RTO の主要因)
- Datastream 再接続
- downstream consistency 確認
RTO の主要因は snapshot restore ではなく endpoint 切替
snapshot restore で作られる cluster は既存と同じ識別子を名乗れないため、cluster endpoint の DNS 名が変わる。その結果、以下すべての更新が必要になる。
- ECS が参照する Secrets Manager の
DATABASE_URL/DATABASE_REPLICA_URL - HAProxy VM 2 台の backend 設定(
DB_ENDPOINT_PLACEHOLDER) - 場合によっては Datastream connection profile
あるいは「旧 cluster を rename してから元の名前で restore する」方式を採るが、この場合さらに時間が伸びる。どちらの方式を採るかが未設計であり、これが RTO を確定できない最大の理由。
参考として、2026-09-15 の clone 作成は cluster 作成 06:47:09 → 1 台目 instance available 07:04:13(約 17 分)、3 台目まで約 22 分だった。ただし clone は copy-on-write であり snapshot restore の代用値にはならない。
90 分という値は実測確定値ではなく planning estimate。snapshot restore の実測により更新する。
12-3. PG16 write 再開後
PG16 で新規 write を受けた後に PG13 pre-upgrade snapshot へ戻すと、その write は snapshot に存在しない。
現状、PG16 → PG13 へ新規 write を逆同期する経路は構築していない。
したがって サービス write 再開は rollback の実質的な不可逆点として扱い、それ以降は原則 fix-forward とする。
13. 本番実施前に残っている確認事項
P0
| 項目 | 状態 | 完了条件 |
|---|---|---|
| PG16 Cluster Parameter Group | 未作成 | Terraform 管理で作成、staging で主要 parameter を実測 |
| Datastream recovery rehearsal | 未実施 | staging で slot 不在 → recreate → Recover 要否 → backfill state を実測 |
| rollback 方針 | 未確定 | endpoint 切替設計と RTO を関係者合意 |
P1
| 項目 | 状態 | 備考 |
|---|---|---|
| snapshot restore 所要 | 未実測 | production-like clone で実測推奨 |
| HAProxy PG16 追従 | 高確度だが未リハ | endpoint は in-place では不変想定。staging で確認 |
| write freeze | 観測方式確立 | production 当日に複数 signal で判定 |
| safe CDC canary | 候補決定 | EventLog の自然発生 write を使用。id Int @id @default(autoincrement()) / createdAt / payload Json の append-only 監査ログで、合成データを本番医療 table に入れずに end-to-end を確認できる。検証時は max_staleness=5 分 の経過待ちが必須 |
| existing mastra CDC incident | 未解決 | migration とは独立に管理 |
14. 本番 Go/No-Go に必要な事前条件
以下が満たされるまでは本番実施を Go としない。
- PG16 CPG が Terraform 管理で準備済み。
- staging で PG16 CPG 適用後に
wal_level=logical/rds.logical_replication=onを確認済み。 - staging で Datastream の slot recreation / Recover rehearsal が成功している。
- Recover 時に意図しない full backfill が自動起動しないこと、または起動時の扱いが設計済み。
- Aurora への直接接続元と indirect write trigger の棚卸しが完了し、application writer / read-only consumer / CDC / manual connection の役割が確定している。
- write freeze を pgAudit / queue / Datastream / slot lag 等の複数 signal で判定できる。
- rollback の endpoint 切替方式と RTO を関係者が受容している。
- PG16 write 再開後は原則 fix-forward となることが合意されている。
- migration 前から存在する
mastra_workflow_snapshot/_temp系 CDC 不整合を baseline として記録している。 - migration window 中に migration / ETL / release を流さない運用が合意されている。
15. 公式ドキュメント
AWS / Aurora PostgreSQL
Performing a major version upgrade
https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.PostgreSQL.MajorVersion.html- logical replication slot が存在すると major upgrade できない。
- upgrade 中に pre-upgrade DB cluster snapshot を作成する。
Reestablishing logical replication after a major upgrade
https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Appendix.PostgreSQL.CommonDBATasks.pglogical.recover-replication-after-upgrade.html- publisher への transaction を一時的に迂回し、slot を drop、upgrade 後に replication を再確立することを推奨。
Google Cloud Datastream
Stream data from PostgreSQL databases
https://cloud.google.com/datastream/docs/sources-postgresql- PostgreSQL major upgrade 前に slot を drop、upgrade 後に recreate。
- stream が fail した場合 Recover。
- data consistency が必要な場合 backfill。
Recover a stream
https://cloud.google.com/datastream/docs/recover-a-stream- PostgreSQL Recover は new replication slot の first LSN から再開。
- lost log position と new first LSN の間の change events は loss 対象となり得る。
Manage backfill for stream objects
https://cloud.google.com/datastream/docs/manage-backfill-for-the-objects-of-a-stream- object ごとに backfill state を管理し、backfill は独立した操作として扱われる。
PostgreSQL
- Logical Replication: Publication
https://www.postgresql.org/docs/16/logical-replication-publication.html- publication は publish 対象 DML を定義する。
- publication の publish parameter は initial data synchronization copy 自体を制御しない。
16. 調査記録
| 日付 | 対象 | 調査結果 |
|---|---|---|
| 2026-07-22 | production clone | in-place 13.20→16.13、offline 606 秒 |
| 2026-07-23 | production clone | in-place 再現、offline 639 秒、ANALYZE 28 秒 |
| 2026-09-14 | staging / production | PG16 preflight read-only 実施 |
| 2026-09-15 | production clone | Blue/Green 実測。BG 約 40 分、Switchover write downtime 約 3 秒 |
| 2026-09-17 | production | Datastream / backfill / CDC gap 調査 |
| 2026-09-18 | production / staging | PG16 parameter diff(online-karte-docs が 16.6 で同値稼働)、write source、pgAudit による WRITE/DDL 分類、rollback、Datastream object 151 件の内訳、downstream(Retool/Redash/Trocco/Airflow)を追加調査 |
| 2026-09-18 | production | Aurora 直接接続元を pg_stat_activity / pg_stat_replication / pg_roles / PI(7日)/ ECS task IP 突合で確定。Writer は -2(従来 -0 と誤認)。login role は n3dnr9bs / datastream / rdsadmin の 3 つ。Datastream の実接続元は 10.128.0.22 / 10.128.0.23 |
17. 関連 Issue / 資料
- 親:
#12736 - 手法選定:
#15755 - in-place clone 計測:
#15837 - 本番実施:
#16249 - PG16 app compatibility:
#16216 - Datastream / RI:
#15448,#15995 - Blue/Green 本番 clone 計測:
#19117
本書は preflight の事実整理を正とし、実際の本番操作順序・コマンド・タイムライン・中断条件・rollback 操作は production runbook 側で定義する。