Skip to content

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 を第一候補とする理由は以下。

  1. 本番相当 clone で dedicated in-place upgrade を 2 回実施し、全断が 606 秒 / 639 秒(約 10〜11 分) と再現している。
  2. reader を含む完全復帰も約 12 分台であり、90 分のメンテナンス枠に対して十分な余裕がある。
  3. in-place ではサービスの write を止めた状態で logical replication slot を削除・再作成できるため、slot 不在期間の業務 DML を 0 件に維持する設計を取れる。
  4. 上記が成立すれば、Datastream の旧 log position から新 slot の first LSN までに補完すべき業務 change event を発生させず、通常時の全件 backfill / 自前差分補完を回避できる。
  5. Blue/Green は write downtime を約 3 秒に短縮できる一方、外部 Datastream slot を外した状態で Blue を稼働させる時間が長くなり、CDC gap の補完設計が複雑になる。

したがって判断軸は、「90 分に収まるか」ではなく、「約 10〜11 分の計画停止を許容することで CDC 整合性と移行手順を単純化する価値があるか」 とする。

0-2. 現時点の Go/No-Go 判定 ​

条件付きで in-place 採用可能。重大な技術ブロッカーは現時点では確認されていない。

本番実施前に残っている主要事項は次の 3 点。

  1. PG16 Cluster Parameter Group の本番用 Terraform 化
  2. staging での Datastream 復旧リハーサル
    • slot 不在時の state 遷移
    • 同名 slot 再作成後の自動再接続 / Recover 要否
    • Recover 時に既存 Completed object の backfill が自動起動しないことの確認
  3. rollback 方針と RTO の合意
    • snapshot restore 所要は未実測
    • PG16 で write 再開後は PG13 snapshot への単純 rollback ができず、原則 fix-forward

1. 対象環境 ​

項目stagingproduction
リージョンap-northeast-1ap-northeast-1
DBonline_karteonline_karte
現行 engineAurora PostgreSQL 13.23Aurora PostgreSQL 13.23
targetAurora PostgreSQL 16.13Aurora PostgreSQL 16.13
instance topologyWriter 1 台Writer 1 + Reader 2
instance classdb.t3.mediumdb.r6g.2xlarge ×3
backup retention7 days7 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 ​

instancerole主な用途
online-karte-service-2Writerapplication write / read、Datastream CDC
online-karte-service-0Readerapplication read、Trocco read
online-karte-service-1Readerapplication 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 ×5n3dnr9bsWriter + Readerread/write本体 API。DATABASE_URL=Writer / DATABASE_REPLICA_URL=Reader
GCP Datastream(HAProxy 2台経由)datastreamWriter onlyCDC readlogical replication / WAL sender
Trocco(Tokyo bastion 経由)n3dnr9bsReader onlyread onlyETL
運用者 psql(Tokyo bastion 経由)n3dnr9bs任意原則調査手動運用・調査
RDS internalrdsadmin全 instanceAWS internalRDS 管理プロセス

ログイン可能な 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 に分散される。

text
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-2

Aurora 側で観測される 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 接続は確認されていない。

componentDB 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-service ECS ×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 実行済み。

区分stagingproduction判定
SUMMARYPASS=25 / WARN=1 / FAIL=2PASS=25 / WARN=3 / FAIL=2FAIL/WARN は既知項目
PK なし table22mastra_evals, mastra_workflow_snapshot
REPLICA IDENTITY 不適00対応済み
logical replication slot11Datastream 用
prepared transaction00PASS
unlogged table00PASS
large object00PASS
long transaction00PASS
PG16 非互換 SQL / object00PASS
rds.logical_replicationononPASS
wal_levellogicallogicalPASS
wal_sender_timeout00PASS
publication datastream11FOR ALL TABLES
sequence5858参考

3-1. Logical replication slot は in-place の明確なブロッカー ​

Aurora PostgreSQL の major version upgrade は logical replication slot が存在すると進められない。実際の clone 計測でも Datastream slot が原因で precheck failure を確認済み。

公式根拠


4. PG16 Parameter Group 調査 ​

4-1. PG13 production の user 設定 ​

parameterPG13 currentPG16 方針reboot
rds.logical_replication11static
max_wal_senders2020static
shared_preload_librariespgaudit,pg_stat_statements同値static
wal_sender_timeout00dynamic
max_slot_wal_keep_size10001000dynamic
pgaudit.logallalldynamic
log_min_duration_statement10001000dynamic
rds.log_retention_period14401440dynamic
max_replication_slotsdefault 20default 20static

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-22production clone / db.r6g.2xlarge ×3606 秒slot drop 後に成功
2026-07-23production clone / db.r6g.2xlarge ×3639 秒再現確認
2026-09-15Blue/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:53upgrade 開始(cluster はまだ online)
08:09:12〜08:09:14online upgrade prechecks(約 2 秒)
08:09:15cluster を offline 化(全断開始)
08:09:37pre-upgrade snapshot の自動作成
08:12:00volume clone
08:14:16writer の upgrade
08:20:46primary 接続可(全断終了・約 6 分 30 秒)
08:22:43upgrade 完了

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
streamonline-karte / RUNNING
publicationdatastream
replication slotdatastream_replication_slots
includeschema public
write modemerge(PK なし table は append-only fallback)
backfillAll有効
maxConcurrentBackfillTasks1
dataFreshness300s
object count151
historical backfill completed102 objects
connectionGCP internal LB 10.128.0.5 → HAProxy VM 2 台(10.128.0.22 / 10.128.0.23)→ Aurora endpoint
stream/freshness0 秒(2026-09-18・6 時間 360 点すべて 0)
stream/total_latenciesmean 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 実測) ​

項目実測
datasetfd-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 前後の突合に使用)。

tableBQ 行数BQ PK
EventLog34,107,985id
KarteVersion5,229,441id
KarteSubmission800,203id
Accept781,810id
Karte781,795id
KarteContentYjs738,749karteId
Patient469,500id
WorkflowStatus461,346workflowRunId
mastra_workflow_snapshot12,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 そのものを制御するものではないと説明されている。

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 後再作成が必要。

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 は失われ得る、とされている。

したがって、次の 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 を開始する操作が別途存在する。

したがって現時点の理解は以下。

text
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当時の実測現在の規模現在の所要見積り
KarteVersion6,843 秒(114 分)5,229,441 行 / BQ 53.2 GiB約 5.7 時間
EventLog2,684 秒(44.7 分)34,107,985 行 / BQ 16.0 GiB約 2.4 時間
KarteContentYjs779 秒(13 分)738,749 行 / BQ 22.3 GiB約 1.0 時間
Karte / Accept42 秒 / 41 秒各 約 78 万行各 約 3 分
KarteSubmission31 秒800,203 行約 2 分
WorkflowStatus22 秒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 分の調査では以下を観測。

classcommand件数 / 30 分
READSELECT145,116
MISCBEGIN / COMMIT各 21,959
WRITEINSERT4,161
WRITEUPDATE125
WRITEDELETE0
MISCSET87

pgAudit は READ / WRITE / DDL / MISC を class として明示的に分類するため、autovacuum 等の内部処理と application DML を分離できる。判定に使うクエリは以下。

text
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_inserted0.21〜0.68 /s0 になること。application DML の直接指標
PI db.SQL.tup_updated1.62〜1.98 /s同上
PI db.SQL.tup_deleted0.06〜0.30 /s同上
CloudWatch WriteIOPS19.6〜61.8(avg 21.3)大幅に低下すること。ただし autovacuum 等でも発生するため 0 にはならない
CloudWatch OldestReplicationSlotLag45,398〜559,672 B(avg 60,203)0 になること=slot が WAL を読み切った証拠
CloudWatch CommitThroughput取得可(直近 69.73)参考値

使えないもの

手段結果
CloudWatch DMLThroughputデータポイント 0。Aurora PostgreSQL では未提供
PI db.Transactions.xact_commit02: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)で返す一方、RDS describe-* は UTC(+00:00)で返す。UTC と思い込んで時刻を換算すると、02:00 JST のつもりでまったく別の時間帯を測ることになる。必ず raw のオフセットを確認すること。

write freeze 判定には以下を組み合わせる。

  1. pgAudit で WRITE / DDL が一定期間 0
  2. SQS in-flight が 0
  3. Datastream event_count が 0
  4. replication slot lag / confirmed position が追従済み
  5. すべての write source が停止状態であること

深夜帯でも DML は 0 にならない(実測) ​

「深夜 02:00 なら write がない」という前提は成立しない。Datastream stream/event_count の 02:00–03:00 JST 実測(7 日)は以下。

日付(JST)change events
09-11898
09-121,096
09-131,231
09-14696
09-151,186
09-161,268
09-171,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 にしても止まらない。

text
① 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 modeapp/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 件入力が無ければ自分からは書かない
起動時 migrationDockerfile 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 checkpath /healthz / interval 40s / unhealthy 閾値 10 / timeout 30s / matcher 200,201DB が落ちてもタスクは unhealthy にならず置き換わらない
ECS servicehealthCheckGracePeriod=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 を直接叩く。

text
online-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.238

CloudFront だけを止めても、SQS に溜まった仕事が Lambda → chronic-api → ALB 経由で流れて write が発生する。 ⛔ 旧版はここで「遮断は ALB のリスナールール(固定 503 等)または WAF で行うこと」と指示していたが、そのルールは実装されていない(上の訂正)。入口を止める手段は ECS desired-count 0 のみである。 なお「入口が公開 ALB に 1 本化されており、CloudFront では不十分」という事実自体は有効で、これは ECS を止めれば①の経路が一括で止まることの根拠でもある。

⛔ ECS を起動するのは slot 再作成が完了した後(旧版は「ALB を開けるのは」と書いていた)。

text
slot 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 と判定しない。

調査結果:

text
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_CHANGE
  • mastra_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_codeBIGQUERY_UNSUPPORTED_PRIMARY_KEY_CHANGE
object_namepublic_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)
materializationstaging / intermediate / marts すべて view
incremental model0 本
snapshot0 本(snapshots/ は .gitkeep のみ)
production triggercron なし。online-karte-dbt-v** の tag push のみ
dbt testproduction workflow ではコメントアウトされている
schema test4 件のみ(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参照先参照回数
Retoolfd-datastream-prd.online_karte_public(raw)6,902
Redash同上(raw)422
Troccoonline-karte-prd.postgres28
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 を確認済み。

dependencyversion調査結果
Prisma / @prisma/client5.18.0PG16 対応範囲
pg8.11.5protocol 上 major version 固有リスク低
Mastra PG0.10.0pg 経由。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 を作成すると説明している。

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 としない。

  1. PG16 CPG が Terraform 管理で準備済み。
  2. staging で PG16 CPG 適用後に wal_level=logical / rds.logical_replication=on を確認済み。
  3. staging で Datastream の slot recreation / Recover rehearsal が成功している。
  4. Recover 時に意図しない full backfill が自動起動しないこと、または起動時の扱いが設計済み。
  5. Aurora への直接接続元と indirect write trigger の棚卸しが完了し、application writer / read-only consumer / CDC / manual connection の役割が確定している。
  6. write freeze を pgAudit / queue / Datastream / slot lag 等の複数 signal で判定できる。
  7. rollback の endpoint 切替方式と RTO を関係者が受容している。
  8. PG16 write 再開後は原則 fix-forward となることが合意されている。
  9. migration 前から存在する mastra_workflow_snapshot / _temp 系 CDC 不整合を baseline として記録している。
  10. migration window 中に migration / ETL / release を流さない運用が合意されている。

15. 公式ドキュメント ​

AWS / Aurora PostgreSQL ​

Google Cloud Datastream ​

PostgreSQL ​


16. 調査記録 ​

日付対象調査結果
2026-07-22production clonein-place 13.20→16.13、offline 606 秒
2026-07-23production clonein-place 再現、offline 639 秒、ANALYZE 28 秒
2026-09-14staging / productionPG16 preflight read-only 実施
2026-09-15production cloneBlue/Green 実測。BG 約 40 分、Switchover write downtime 約 3 秒
2026-09-17productionDatastream / backfill / CDC gap 調査
2026-09-18production / stagingPG16 parameter diff(online-karte-docs が 16.6 で同値稼働)、write source、pgAudit による WRITE/DDL 分類、rollback、Datastream object 151 件の内訳、downstream(Retool/Redash/Trocco/Airflow)を追加調査
2026-09-18productionAurora 直接接続元を 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 側で定義する。