feat(storage): add native PostgreSQL runtime and verified offline application import
Build and publish container images / images (push) Failing after 12m29s
Build and publish container images / images (push) Failing after 12m29s
This commit is contained in:
1 parent
96065d1e89
commit
0ba1dcfef0
243 files changed
+21441
-3090
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# 保存基盤の多様化と運用機能の統合
|
||||
|
||||
状態:詳細設計・段階導入。2026-09-27。
|
||||
状態:詳細設計・段階導入。2026-11-15 更新。
|
||||
本書は [基本設計](arch.md) と [拡張契約](platform-extension-architecture.md) を補完する。
|
||||
各 TODO は実装済みを意味しない。本番 DB・保存先の移行は別途承認する。
|
||||
|
||||
@@ -384,6 +384,35 @@ setup 完了後は token 再利用不可。機密欄の再表示・ログ出力
|
||||
|
||||
### S2:外部 backend
|
||||
|
||||
- [x] PostgreSQL 接続層と独立した migration runner(アプリの backend 切替は未接続)。
|
||||
- [x] Object/Path/Revision/Asset の共通 metadata Repository と空 DB 用スキーマ、SQLite/PostgreSQL 共通契約テスト。
|
||||
- [x] 既存 Store の Campus/Domain 取得・ホスト解決・ドメイン別設定・Campus 作成/更新の native SQL 移植と共通契約テスト。
|
||||
- [x] 管理者グループの初期化・メンバー更新・継承切替・projection・派生所属とセッションの失効を共通 SQL と transaction に移植。
|
||||
- [x] 一般グループの作成・一覧・メンバー一覧・Path 権限設定、直接 Role binding と Group 権限の付与判定、Principal 状態更新と失効を共通 SQL に移植。
|
||||
- [x] 初回 owner・パスワードアカウント・プロフィール・セッション管理、TOTP、外部認証の設定と Identity 紐付け、CLI 認証引き継ぎの DB 処理を移植し、SQLite/PostgreSQL 共通契約テストを追加。
|
||||
- [x] 認可と読み取りナビゲーションの Locality 制限、City 所有者・公開範囲の上限制約、ユーザー/グループ ACL 更新、保護 Path/City 構造の DB ガードを移植。
|
||||
- [x] 公開 manifest・自動公開・匿名 navigation、承認要求、ユーザー領域とプロフィール連絡先の公開制御を native SQL に移植し、共通 DB テストを追加。
|
||||
- [x] Domain 作成/更新/削除と Campus 削除、管理者継承、連携トークン・instance 登録・署名 manifest の DB 処理を移植。
|
||||
- [x] 通常 Revision 保存・履歴取得・履歴復元の Store 境界と HTTP 呼び出しを native metadata Repository に接続し、合成データで保存・競合・故障時の rollback を検証。
|
||||
- [x] Path の再帰移動・コピー・snapshot 付き一括削除、alias/primary link と navigator の DB 処理を移植。
|
||||
- [x] City map・所属 Page・Path context・health・監査履歴の取得、タイトル・境界変更、Spot 整理(移動・統合)を移植。
|
||||
- [x] Asset の一覧・参照・履歴、作成/更新・復元・削除を移植し、楽観ロックと履歴保存失敗時の rollback を検証。
|
||||
- [x] City の個別作成・配置・relation・再帰削除、一括変更計画の preview/apply、自動生成候補と名前競合の問い合わせを移植。
|
||||
- [x] Browser・children・Path 補完・権限付き Object metadata 一覧を移植し、native canonical HTML の H1 と複数 Store 間の children cache 失効を検証。
|
||||
- [x] アーカイブ import のセッション・計画・journal・Path rollback を移植。全 DB の SQLite→PostgreSQL インポートとは別機能。
|
||||
- [x] タスク・プロジェクトの保存/取得/履歴/階層付き一覧/削除、DAV resource・collection・資格情報・既定リスト名の Store 操作を移植し、両 DB で契約を検証。
|
||||
- [x] タスク個人設定、作業時間の開始・終了・訂正・取消と監査履歴、Pomodoro と日次集計、ダッシュボード配置・達成率、予定枠の DB 予約を移植。
|
||||
- [x] 通知 Inbox の保存・重複排除・取得・既読、期限/着手日の通知配信、タイマー完了、活動 journal の outbox 補完処理を移植。scheduler と Push 配信は別途接続する。
|
||||
- [x] タスク capture と Wiki 同時作成、削除後の明示的再作成、プロジェクト配下のメモ作成を移植。受付記録・本文参照・Path・outbox の原子性を検証。
|
||||
- [x] 日次メールの送信予約、本人の同意・権限確認、送信履歴、明示的再試行、保持期限処理を移植。SMTP worker と scheduler は別途統合する。
|
||||
- [x] カレンダーの再構築可能な月別索引、予定の取得・更新・削除、DAV resource 操作、タスク予定枠と日次予定の cache 参照を移植。正本 ICS と manifest の形式は維持する。
|
||||
- [x] 連絡先の保存・検索・削除・履歴復元・export、CardDAV の resource 名・差分同期・metadata inventory と資格情報失効を移植。
|
||||
- [x] ブログ・日記の設定、記事作成・登録・解除・一覧、投稿受付の重複排除、公開タイトルと別 Domain への射影設定を移植。本文と埋め込み Asset 参照の固定、監査失敗時の rollback を検証。
|
||||
- [x] RSS/FreshRSS の購読元・既読/スター・記事 cache・分類・購読 import・Wiki 取り込みと受付記録、外部操作の claim・確認・履歴を移植。scheduler 登録は別途接続する。
|
||||
- [ ] 通常 HTTP/scheduler/CLI 起動を経由した認証・公開・federation の PostgreSQL 統合試験。
|
||||
- [x] 読み取り専用の移植診断 CLI と、対応済み core の catalog / 履歴検査。
|
||||
- [x] 停止状態の core SQLite→PostgreSQL→SQLite 往復リハーサル、内容指紋・採番・参照・Document の検証。
|
||||
- [ ] Object/Path/Revision/Asset の全 Store 操作と関連正本更新の接続、既存 DB 移行、共通統合テスト。
|
||||
- [ ] PostgreSQL の全 repository 移植と SQLite との共通機能テスト。
|
||||
- [ ] MySQL の DDL/索引/照合順序/同時書き込み試験。
|
||||
- [ ] S3 adapter と互換サービスで range/条件付き作成/破損/切断/容量制限を検証。
|
||||
@@ -391,6 +420,790 @@ setup 完了後は token 再利用不可。機密欄の再表示・ログ出力
|
||||
- [ ] Redis cache adapter と停止時の制限付き縮退、policy epoch による失効。
|
||||
- [ ] mutable canonical CAS と metadata 参照の回復プロトコル、HA の fencing。
|
||||
|
||||
#### PostgreSQL 対応の実装順序
|
||||
|
||||
2026-11-14 時点では `internal/db.OpenPostgreSQL` と
|
||||
`ApplyPostgreSQLMigrations` を追加した。既存の `Open`、`Migrate`、通常の Store 初期化、
|
||||
通常起動、DR、CLI は引き続き SQLite 用であり、PostgreSQL を本番選択可能にはしない。
|
||||
利用者の DB を自動変換せず、既存 migration の checksum も変更しない。
|
||||
|
||||
接続には pgx の database/sql 実装を使用し、DSN はインスタンスの秘密設定として扱う。
|
||||
既定で検証付き TLS と平文 fallback の禁止を要求する。開発専用の
|
||||
`AllowInsecure` を明示した場合だけ非検証接続を許す。接続確認の timeout、
|
||||
pool の上限、connection の寿命を設け、失敗時は pool を閉じる。
|
||||
エラーは SQLSTATE と操作名だけを公開し、DSN、SQL、サーバの詳細メッセージや
|
||||
constraint 内の個人情報をエラー文字列へ含めない。
|
||||
|
||||
PostgreSQL 用 migration は SQLite の SQL 自動翻訳ではなく、独立した append-only 定義とする。
|
||||
BIGINT の epoch ms、ネイティブの `$1` 引数、明示した conflict target を使う。
|
||||
runner は READ COMMITTED transaction と共通の transaction-level advisory lock で
|
||||
ledger の初回作成を含めて直列化する。異なる component にも同じロックを使う。
|
||||
DDL、checksum 履歴、最新 assertion の検証を同じ transaction に含め、
|
||||
失敗時は rollback、正常終了時は commit と同時にロックを解放する。
|
||||
未知の新しい履歴、欠けた version、変更された定義は適用を停止する。
|
||||
|
||||
| 順序 | 範囲 | 完了条件 |
|
||||
| --- | --- | --- |
|
||||
| 1 | 接続と migration | 実 PostgreSQL で並行適用、rollback、履歴不一致、lock 待ちキャンセルを検証 |
|
||||
| 2 | Object/Path/Revision/Asset | Domain 分離、UUID 不変性、revision 保存、再帰 rename、hash 参照の SQLite 共通契約を通過 |
|
||||
| 3 | 認証と ACL | ユーザー、グループ、セッション、公開範囲の共通契約を通過 |
|
||||
| 4 | タスクと CalDAV | プロジェクト所属、VTODO、ETag と競合更新、通知を検証 |
|
||||
| 5 | ジョブと通知 | claim token、lease、row lock、outbox と重複処理耐性を検証 |
|
||||
| 6 | City と検索と管理 | rowid/PRAGMA/FTS5 依存を分離し、安定した順序・検索・schema 診断を検証 |
|
||||
| 7 | 既存データ移行と運用 | 停止状態の export/import、件数・参照・hash 検査、restore rehearsal、起動設定と readiness を接続 |
|
||||
|
||||
#### 既存 Store の Campus と Domain と設定の移植
|
||||
|
||||
`internal/store` に backend を保持し、既存 API から native PostgreSQL の SQL を使える
|
||||
経路を追加した。既定値は SQLite とし、従来の Store constructor と最小 fixture の
|
||||
振る舞いを維持する。SQL の `?` を一括変換せず、query 構築時に placeholder を生成する。
|
||||
ホスト名の判定は SQLite の `instr` と PostgreSQL の `strpos` を明示的に分ける。
|
||||
|
||||
移植済みの範囲は次のとおり。
|
||||
|
||||
- Campus の既定値取得、UUID 取得、一覧、作成と更新。
|
||||
- Domain の既定値取得、UUID 取得、一覧、件数、Host 解決、実効 FQDN の取得。
|
||||
- Domain ごとの設定の取得と UPSERT。欠けた設定は従来どおり空文字とし、更新時刻は既存の秒単位を維持。
|
||||
- 既存 Store の Path 解決で backend を選択し、Domain が local であることを確認して共通 Repository を呼ぶ。
|
||||
|
||||
Campus の FQDN と Domain の相対ホスト名・FQDN 指定を同じ規則で解決する。
|
||||
未知の Host を既定 Domain へ fallback せず、無効な Campus/Domain と remote Domain の
|
||||
ローカル名前空間へのアクセスを既存の取得規則に従って拒否する。
|
||||
Campus 作成・更新では、移植済み writer が同じ namespace lock を使う範囲で、
|
||||
ホスト名競合の検査と書き込みを一つの transaction に入れる。
|
||||
PostgreSQL では同一 DB の advisory lock、SQLite では書き込みロックを検査前に取得する。
|
||||
transaction の期限とキャンセルは内部の SQL 呼び出しまで伝搬する。
|
||||
|
||||
Domain/Campus の context 付き取得 API を追加し、HTTP のリクエスト単位の Host 解決でも
|
||||
request context を利用する。PostgreSQL の SQL/driver/Scan エラーから個人情報や設定値を
|
||||
出力しないようにし、入力フォームへ返せる固定の validation message は区別して保持する。
|
||||
|
||||
PostgreSQL の初期スキーマは `store-namespaces` migration として独立させる。
|
||||
対象は `campuses`、`domains`、`config`、`personal_appearance` のテーブル定義と索引であり、
|
||||
後者の個人外観 API の移植まで完了したという意味ではない。
|
||||
既知の列不足や適用済み定義の不一致は停止し、既存 SQLite の ALTER/adopt 処理は流用しない。
|
||||
既定 Campus/Domain の初期化は transaction で直列化し、並行実行時の重複と関連付けの欠落を防ぐ。
|
||||
これは旧インスタンスの全データを取り込む import 処理ではない。
|
||||
|
||||
Domain 作成・更新は Campus/実効 Host/配置先の検査、Domain 本体、既定 locale、
|
||||
管理者グループ作成と所属 projection を同じ管理用 writer lock と transaction に含める。
|
||||
同じ実効 Host の同時作成は一つだけ成功し、別 Campus への移動は旧 Campus 由来の管理者権限を取り消す。
|
||||
依存テーブルや projection の障害時は Domain と設定も rollback する。
|
||||
Domain/Campus 削除の参照・最終要素検査も transaction 内で実施する。
|
||||
Campus 削除では連携 token、instance と capability、署名 manifest の checkpoint も削除する。
|
||||
|
||||
`store-federation` は token hash、instance identity、manifest 採番と受信 checkpoint を保持する。
|
||||
登録と token 失効は同じ lock を使用し、登録後に失効済み token を再利用できない。
|
||||
署名の検証後、初回 controller fingerprint の固定、旧 revision と同一 revision の異なる内容の拒否、
|
||||
受信 Campus/Domain/管理者継承と checkpoint の保存を一つの transaction で扱う。
|
||||
`store-domain-entry` は manifest v2 の許可済み entry 設定と日記/ブログの有効化・prefix を保持する。
|
||||
これは日記/ブログ本文の新規作成・検索・projection repository 全体の移植完了ではない。
|
||||
|
||||
現時点の PostgreSQL Store は component 統合テスト内でのみ構築する。
|
||||
本番用 constructor と起動フラグはまだ解放せず、通常のサーバーは SQLite のままとする。
|
||||
core 限定インポートの対象も拡張しておらず、namespace を含む DB は引き続き対象外として拒否する。
|
||||
|
||||
#### 認証と管理者グループの移植
|
||||
|
||||
`store-auth-foundation` の native migration は Principal、Identity、Domain membership、
|
||||
Role、直接 Role binding、Capability grant、Group、Group member と Campus 管理者継承の
|
||||
provenance を定義する。アバターは BYTEA、時刻は BIGINT の Unix milliseconds、
|
||||
識別子と一意制約の比較は C collation とする。既存テーブルの暗黙の取り込みや修復は行わない。
|
||||
適用済み migration の列検査が失敗した場合も既存 Principal を保持したまま停止する。
|
||||
|
||||
既存 Store の `IsBuiltinGroupAdmin` と `IsCampusAdmin` は SQLite と PostgreSQL の
|
||||
両方で動作する。context 付き API は SQL エラーと拒否を区別し、従来の bool API は
|
||||
DB 障害時も権限を与えない。Domain と membership の対応、Principal・membership・Group
|
||||
の有効状態、Domain の enabled、owner/manager role を同じ SQL で検査する。
|
||||
SQLite と実 PostgreSQL の共通テストで状態変更、越境所属、キャンセル、DB 障害を検証する。
|
||||
|
||||
`EnsureBuiltinAdminGroups`、メンバーの追加・更新・削除、`SetCampusAdminInheritance`、
|
||||
`ProjectCampusAdminMemberships` は両 DB 共通の実装を使う。
|
||||
グループの名前・UUID による取得と member role の参照も backend に対応する。
|
||||
PostgreSQL では namespace 更新と同じ advisory lock、SQLite では読み取り前の
|
||||
DB writer lock を使い、元の grant 更新と継承先の再計算を同一 transaction に含める。
|
||||
context 付き API の期限は内部の SQL まで伝搬する。
|
||||
|
||||
継承の入力は独立した grant に限り、派生 grant を新たな継承元にしない。
|
||||
複数の継承元のうち最も強い role を実効値とし、継承解除時には弱いローカル role が再び現れる。
|
||||
派生した membership のみを追跡し、独立した group/role binding で採用済みの所属と session は保持する。
|
||||
派生権限しかない所属は削除し、その Domain の session を同じ transaction で失効する。
|
||||
再有効化しても失効済み session は復活させない。
|
||||
最後の独立 owner の並行削除、継承先での inherited-only grant 削除、owner の通常更新による降格は拒否する。
|
||||
Role からの初期 grant は記録済みの migration marker で再投入を防ぎ、明示的に取り消した権限を
|
||||
再起動で復活させない。Domain の異なる Role binding と別 Domain を指定する manage grant は初期 owner にしない。
|
||||
|
||||
native migration の v2 には失効処理に必要な `auth_sessions` と索引を追加する。
|
||||
管理者継承の共通テストは合成 session 行で取り消しと保持を検査し、
|
||||
projection 後半の故障注入でメンバー追加・削除・継承切替のすべてが rollback することを確認する。
|
||||
|
||||
一般グループの作成は owner の有効な Domain membership と active な Principal を確認し、
|
||||
Group、owner member、派生 membership の独立所属への採用を同一 transaction に含める。
|
||||
一覧の `domain` visibility は単に Principal UUID があるだけでなく、その Domain で有効な所属を要求する。
|
||||
`members` visibility とメンバー一覧、role 参照、Path 権限評価でも membership の Domain 一致を検査する。
|
||||
別 Domain の不正な owner 行を最後の独立 owner の代わりに数えない。
|
||||
一覧は EXISTS で重複を避け、表示名・名前・UUID による安定順を持たせる。
|
||||
|
||||
native migration の v3 は `group_permissions` とメンバーの Identity 参照用索引を追加する。
|
||||
権限設定は既存 Group を要求し、同じ Group/Path の設定を upsert する。
|
||||
`read`、`read_write_once`、`read_write`、`upload_only` の既存 capability と literal Path 境界を保持する。
|
||||
SQL の `%` と `_` を wildcard として扱わず、readonly Principal は read だけを許す。
|
||||
|
||||
直接 Role binding の付与判定も backend に対応し、Domain の異なる Role を拒否する。
|
||||
exact Object モードでは Domain 全体や wildcard の grant を採用しない。
|
||||
この低水準判定は Locality 制限を代替しない。`AuthorizeContext` と
|
||||
`AuthorizeExactObjectContext` は Role/Group grant と Locality cap、Object の別名・別 Domain 制限を
|
||||
同じ read-only transaction で評価する。PostgreSQL は REPEATABLE READ を用い、
|
||||
ナビゲーション用 `LoadReadPathPolicyContext` も同じ snapshot 契約を持つ。
|
||||
公開コンテンツの匿名読み取りとユーザー領域の公開制約も、下記の同一 snapshot 契約を使う。
|
||||
アカウント作成時の Role/binding 書き込みは下記の transaction に含める。
|
||||
それ以外の federation・管理操作からの Role/binding 書き込みは別途移植する。
|
||||
|
||||
`SetPrincipalState` は管理者継承と同じ writer lock を利用する。
|
||||
グローバルな Principal の状態更新、active 以外への変更による全 Domain の session 失効、
|
||||
派生管理者権限の再計算を同じ transaction に含め、失敗時は全体を rollback する。
|
||||
既に失効した session の失効時刻を上書きせず、active へ戻しても session は復活させない。
|
||||
|
||||
アカウント作成は Principal、Identity、Credential、Domain membership、Role/binding を
|
||||
同じ transaction に含める。初回 owner は管理者グループへの projection まで含め、
|
||||
途中の失敗時にはアカウントも残さない。並行 bootstrap は一つだけ成功する。
|
||||
password hash の計算は writer lock を取得する前に行う。
|
||||
native migration v4〜v7 は Credential、Challenge、Provider 設定、CLI 認証引き継ぎを追加する。
|
||||
v8 は既存の Group/Role mapping と認証監査ログ用テーブルを追加する。監査イベントの新しい発行機能を追加する変更ではない。
|
||||
適用済み migration の SQL/checksum は変更しない。
|
||||
|
||||
ブラウザ/API session の発行は停止・継承失効と同じ writer lock を利用する。
|
||||
token の用途 prefix を hash 対象に含め、Domain 境界と有効な所属を検査する。
|
||||
プロフィールと avatar の読み書き、Domain のアカウント一覧、session 一覧・失効も両 DB に対応する。
|
||||
|
||||
TOTP の登録確定と counter 消費は同じ transaction 内で検証・更新する。
|
||||
SQLite の JSON 関数を PostgreSQL 上で代用せず、Go 側で counter を読み、writer lock で
|
||||
再利用を防ぐ。外部認証の設定保存では、空の secret を指定した更新は UPSERT 内で
|
||||
現在の暗号化 secret を保持する。外部 Identity の競合で別 Principal に紐付け直さず、
|
||||
重複するメールアドレスや表示名は曖昧なマッチとして拒否する。
|
||||
|
||||
CLI の認証要求は同時受付でも件数上限を超えないよう transaction で直列化する。
|
||||
承認消費と API session 発行は一括 commit し、発行失敗時には承認も rollback する。
|
||||
同時 exchange の成功は一つに限り、poll 間隔・origin・Domain・trusted choice を保持する。
|
||||
共通テストは合成データだけを用い、実際の LDAP/OIDC/SMTP サーバーには接続しない。
|
||||
|
||||
`store-city-foundation` は階層・所有者・公開設定・監査記録・公開 manifest の保存用 schema を持つ。
|
||||
`CityGovernance`、所有者候補検索、`ChangeCityGovernance`、`LocalityAccess` は native SQL を使う。
|
||||
変更前に管理者継承と同じ advisory lock を取得し、epoch/topology の比較、上位の公開範囲、
|
||||
所有者の委任権限を検査する。preview は rollback し、実変更は policy・epoch・監査を一括 commit する。
|
||||
上位管理者の ACL を下位所有者が広げることは拒否し、対象者の削除などの縮小だけを許可する。
|
||||
|
||||
`store-locality-foundation` は Path と設定のガードに加え、Zone/Spot/Street所属の変更を
|
||||
保護する PostgreSQL trigger を持つ。ACL のある Domain で enforcing を解除できず、
|
||||
保護 Path の移動・削除・別名による脱出を拒否する。新規 Object を保護範囲内に作成することは許可する。
|
||||
Path の比較には C collation の文字列範囲を使い、`%`、`_`、大小文字、日本語を LIKE の wildcard としない。
|
||||
trigger を無効化・削除した状態は migration の assertion と ACL 変更時の検査で拒否する。
|
||||
将来の City/namespace writer も、行ロックより先に同じ管理用 lock を取得する順序に統一する。
|
||||
|
||||
共通テストでは上位公開範囲の制約、所有者委任、ACL 縮小、同時変更の単一成功、
|
||||
preview の非永続化、監査失敗時の rollback、保護 namespace、失効後の次リクエストを確認する。
|
||||
schema の追加は City 全体の対応完了を意味しない。通常 HTTP ハンドラとの PostgreSQL 統合試験、
|
||||
City 全変更系と他の管理経路からの Role/binding 操作の監査は残る。
|
||||
既存 SQLite の他の mutation から呼ばれる旧 transaction wrapper は
|
||||
SQLite 用のままであり、それらの PostgreSQL 化は呼び出し側の lock 契約も含めて行う。
|
||||
`EnsureAuthSchema` は PostgreSQL の認証・Locality schema 初期化へ接続済み。
|
||||
管理対象 migration の未移植 component は `ErrPostgreSQLComponentNotReady` で拒否し、
|
||||
SQLite migration runner を PostgreSQL 接続へ流さない。本番用 PostgreSQL Store は未公開のままとする。
|
||||
|
||||
#### 公開とユーザー領域の移植
|
||||
|
||||
`store-publication` は公開 manifest の失効と navigation generation 用 trigger を持つ。
|
||||
匿名 Revision 読み取りと navigation は、明示承認と自動公開候補を同一 read-only snapshot で確認する。
|
||||
有効な Campus/Domain、HEAD、hash、別名、公開範囲、公開者の状態を検査し、
|
||||
本文更新・別名追加・権限変更後の次リクエストに失効を反映する。
|
||||
上位の手動承認必須設定は下位の自動公開を止める。
|
||||
PostgreSQL の navigation trigger は statement 単位で更新し、generation を行数ではなく失効 token として扱う。
|
||||
|
||||
`store-publication-approval` の要求作成は domain/idempotency key の競合を UPSERT で処理する。
|
||||
承認は状態・generation・期限を検査し、decision 記録と状態更新を一括 commit する。
|
||||
同時承認の成功は一つだけで、期限切れ整理ジョブの実行前でも期限切れ要求は承認できない。
|
||||
|
||||
`store-user-space` は profile/avatar/root/descendant の公開設定、Path ごとの縮小例外、監査記録を持つ。
|
||||
公開読み取りは有効な本人所属と Domain の上限、本文 HEAD を同じ snapshot で評価し、
|
||||
別名付き Object は匿名公開しない。例外 Path の改名は同じ所有者の namespace に制限し、
|
||||
改名・削除に policy を追従させる。policy 更新と監査記録は一括 commit する。
|
||||
`store-profile-contacts` は電話番号を Principal の一般情報と分離し、
|
||||
本人の同意・profile 公開設定・Domain の上限を満たす場合だけ匿名へ公開する。
|
||||
競合した version は拒否し、非公開時は値だけでなく version/visibility も返さない。
|
||||
|
||||
既存 SQLite の同一時刻 Revision は `rowid` で HEAD を決定する一方、native PostgreSQL は UUID を用いる。
|
||||
新規 native 保存は時刻を単調増加させるが、旧 DB の同時刻データにはその保証がない。
|
||||
全件 import は言語別 HEAD とその参照先を移行前後で照合し、順序の保存方法を確定するまで
|
||||
本番切替を許可しない。core の往復試験だけでこの条件を満たしたと判断しない。
|
||||
|
||||
#### 共通 metadata Repository の実装範囲
|
||||
|
||||
`internal/metadata` は Object 作成、Domain ごとの Path 解決と alias、再帰移動、
|
||||
言語別 Revision HEAD の比較更新、履歴 UUID の参照と非破壊復元、Asset HEAD と
|
||||
履歴の原子的更新を提供する。SQL の placeholder を組み立て時に生成し、
|
||||
SQL 文字列の一括置換は行わない。DB には Document 本文を保持せず、
|
||||
低水準の `AppendRevision` は呼び出し側が Geduldh へ先に検証・永続化した SHA-256 を公開する。
|
||||
`SaveDocument` は参照固定と payload 永続化も含めた保存パイプラインを提供する。
|
||||
Revision の `body` 列は既存形式との橋渡し用の空キャッシュであり、正本ではない。
|
||||
|
||||
PostgreSQL の書き込みは Domain 単位の transaction-level advisory lock を取得し、
|
||||
Revision ではその後に Object 単位の lock も取得する。lock の取得順を統一し、
|
||||
異なる Object の保存でも Domain 内の outbox sequence を直列化する。
|
||||
アプリ用の `NewApplication` は、その前に namespace 管理と共通の advisory lock を取り、
|
||||
有効な Campus と Domain、local 配置を transaction 内で再確認する。
|
||||
順序は namespace 管理 → Domain → Object とする。本文の検証・永続化 I/O 中には取得しない。
|
||||
SQLite は読み取り前に書き込みロックを取得する。
|
||||
全 writer が同じ契約を使う前提で、プロセス内の mutex に依存せずに HEAD を比較する。
|
||||
Revision の時刻は同一言語の前の値より必ず後にし、順序付けに隠れた rowid を使わない。
|
||||
復元は新しい Revision UUID で追加し、過去の Revision を変更しない。
|
||||
埋め込み Document の参照も履歴から引き継ぎ、現在の Asset HEAD へ置き換えない。
|
||||
|
||||
再帰移動は移動先が空であることを検査し、一つの UPDATE で配下を移動する。
|
||||
全 Path のメモリ展開や一件ずつの SQL 発行はしない。Path は SQLite の binary、
|
||||
PostgreSQL の C collation とし、配下の検査は索引を使える文字列範囲で行う。
|
||||
日本語、大小文字、`%`、`_`、仮想フォルダ、同名の別 Domain を区別する。
|
||||
同一 Domain 内の alias 追加は既存 Path を上書きしない。Domain を越えるリンクの
|
||||
取り扱いは認可・共有の移植時に別途実装する。
|
||||
|
||||
`InitializeFresh` は専用 migration 履歴で管理する空 DB/schema 用の初期化である。
|
||||
既存の未管理テーブルがある場合は採用や変換をせず失敗し、既存データを保持する。
|
||||
再実行時には必要なテーブルと列の存在を SELECT assertion で検査し、不足時は停止する。
|
||||
列型、照合順序、索引、一意制約の完全な catalog 検査はまだ対象外である。
|
||||
既存 Store の初期化からは呼ばない。Store の PostgreSQL 分岐には Path 解決、
|
||||
Object/Page 作成、通常 Revision 保存と履歴復元を接続した。アプリ用の Page 作成は
|
||||
Object・origin・Path と `page.created` を一括 commit し、イベント保存失敗時は全て rollback する。
|
||||
`NewApplication` 自体は通常起動の constructor や認可処理ではない。
|
||||
|
||||
保存パイプラインの実装と、変更系のアプリ接続前の残件は次のとおり。
|
||||
|
||||
- [x] DB 非依存の Asset freeze を切り出し、既存 SQLite Store からも利用。
|
||||
- [x] 共通 Repository の `SaveDocument` で Document 永続化、埋め込み Asset 検証、参照記録を接続。
|
||||
- [x] 共通 Repository の Revision 保存と activity outbox の追加を同じ transaction に統合。
|
||||
- [x] 通常保存・復元 HTTP API を Domain 明示の Store 境界へ接続し、PostgreSQL 分岐から新パイプラインを呼び出す。
|
||||
- [x] 言語別 HEAD・履歴 cursor・Document 参照一覧の native SQL と欠損 payload の失敗処理を接続。
|
||||
- [x] 通常の Path 再帰変更、native filename Revision とコピー時の埋め込み参照保持、navigator の追従を接続。
|
||||
- [x] Asset Store API の native SQL と履歴復元を接続。
|
||||
- [ ] Web/API/CLI の変更系を新保存パイプラインへ切り替え。
|
||||
- [ ] Path/City の残る入口・reconciler と関連 metadata を監査し、通常 HTTP と cache invalidation を統合試験。
|
||||
- [ ] 既存 Store の残りの取得・一覧・専用リンク操作・import writer を移植。
|
||||
- [ ] 既存 schema の移行計画、schema drift の assertions、整合性検査を整備。
|
||||
- [ ] 同時 GC との pin 契約、巨大 Asset の検証 I/O の予算と再検証 cache を整備。
|
||||
|
||||
`internal/documentrefs.Freeze` は可変 `asset:` を HTML の参照属性から解決し、
|
||||
SHA-256 URL と出自属性へ固定する。同一 address の解決と同一 hash の参照記録は重複させない。
|
||||
通常テキスト、コード例、非 HTML payload は解決せず、変更不要の HTML token は元の byte 列を維持する。
|
||||
既存 Store は従来の resolver を adapter として使い、PostgreSQL 用の保存では Domain を明示した resolver を使う。
|
||||
外部 URL へアクセスする機能ではない。
|
||||
|
||||
`SaveDocument` は対象 Object の Domain 内の Path と言語別 HEAD を先に確認し、
|
||||
解決した埋め込み payload を検証してから、凍結済み Document を Geduldh へ永続化する。
|
||||
この間に DB transaction や lock は保持しない。その後に HEAD を再比較し、
|
||||
Revision、`revision_document_refs`、`revision.created` の pending outbox、型別 watermark を
|
||||
一つの transaction で確定する。outbox の sequence は型別 watermark から割り当て、
|
||||
増え続けるイベント履歴全体を走査しない。イベント配信と worker lease の移植は別工程である。
|
||||
|
||||
アプリ用 Repository は未紐付け Object に限り作成元 Domain の origin を認め、
|
||||
create/save/bind の順序を維持する。別 Domain に Path が存在する Object へ origin だけで書き込めない。
|
||||
Object のみを渡す旧呼び出しは所属 Domain が一意の場合に限り解決し、複数なら明示指定を要求する。
|
||||
これは認可の代替ではなく、HTTP 側の read/write 権限検査は維持する。
|
||||
|
||||
`SaveRevisionContentInDomain` は期待 HEAD の有無を区別する。空文字の期待値は未作成を要求し、
|
||||
期待値なしは無条件 append とする。CAS 失敗を無条件 append で自動再試行しない。
|
||||
PostgreSQL の `RestoreRevisionInDomain` は過去の本文と埋め込み参照の payload を検証し、
|
||||
現在の Asset HEAD を再解決せず新しい Revision に引き継ぐ。
|
||||
DocumentRoot を必須とし、正本の欠損を空の DB body cache で補修しない。
|
||||
SQLite の既存 writer と復元の参照固定動作は維持しており、その統一は別の変更単位とする。
|
||||
|
||||
Path の native 変更処理は namespace 管理 lock を取得してから snapshot を再検証する。
|
||||
移動・コピー・一括 unlink は最大 10,000 Path、30 秒の transaction 予算で実行し、
|
||||
`%`・`_` をワイルドカードにしない索引範囲を使う。予算超過時に部分適用はしない。
|
||||
再帰移動では City 境界、ユーザー領域の公開例外、保存した navigator の Path を同じ transaction で更新する。
|
||||
既存の locality ACL によって保護された namespace の移動・削除は引き続き拒否する。
|
||||
ACL を自動的に別の Path へ拡張する機能や DB guard の迂回は追加しない。
|
||||
公開 manifest と navigation generation は既存の native trigger で失効する。
|
||||
|
||||
native のファイル名変更は、言語別 HEAD の参照 hash を保つ新 Revision を追加する。
|
||||
コピーでは新 Object/Revision UUID を割り当て、全 Revision と埋め込み参照の対応を同じ transaction で複製する。
|
||||
本文 blob は再利用する。unlink は履歴と blob を消さず、City の定義も自動削除しない。
|
||||
コピー履歴で同時刻の旧 HEAD を維持する条件は、全件 import の順序問題と合わせて確認する。
|
||||
|
||||
City の読み取りは PostgreSQL の repeatable-read snapshot を利用する。
|
||||
整理操作は topology version を管理 lock 内で照合し、Page placement、Spot relation、監査記録を一括更新する。
|
||||
Page の URL は Spot 整理では変更しない。境界検査は最大 4,096 node に制限し、
|
||||
Spot 整理の既存の選択数・展開 Page 数・relation 数上限も維持する。
|
||||
Asset 復元は payload の hash を検証してから期待 HEAD を比較更新する。
|
||||
削除は mutable Asset を取り除くが、履歴と既存 Revision からの参照は保持する。
|
||||
|
||||
payload 永続化後に競合や DB エラーが起きた場合、参照のない不変 blob が残ることは許容する。
|
||||
同じ hash を別 writer が利用する可能性があるため、保存失敗時に blob を削除しない。
|
||||
参照のない blob の回収は pin と保持期間を持つ GC の役割とし、同時削除を行う構成では
|
||||
pin 契約の接続が済むまで新パイプラインを有効にしない。
|
||||
|
||||
portable core の v1 定義は変更せず、参照と outbox のスキーマを v2 として追加した。
|
||||
試験用 v1 の既存行を維持した移行、DDL 途中失敗時の rollback、再試行を共通テストで確認する。
|
||||
これは本番 SQLite からのデータ移行機能ではない。
|
||||
|
||||
既存 SQLite Store では、Revision の outbox 用 Domain 取得時に未知の SQL エラーを
|
||||
無視しないよう是正した。outbox 自体がない最小 fixture は従来どおり扱うが、
|
||||
outbox がある状態での取得・書き込みエラーは Revision と一緒に rollback する。
|
||||
|
||||
共通テストでは Domain 分離、言語の分離、同時 CAS、重複作成時の orphan 防止、
|
||||
Revision の不変性、復元時の競合、Asset 履歴の故障注入 rollback を検証する。
|
||||
保存パイプラインでは payload 書き込み失敗、埋め込み検証失敗、保存 I/O 中の別編集、
|
||||
参照・outbox の故障注入、異なる Object の並行 sequence 採番も検証する。
|
||||
これらは変更系 Web/API の PostgreSQL 対応完了を意味しない。
|
||||
|
||||
`PAGESWIKI_TEST_POSTGRES_DSN` に使い捨て PostgreSQL の URL を指定すると、
|
||||
`go test -race -count=1 ./internal/db ./internal/metadata ./internal/documentrefs` が実 DB と参照固定のテストを実行する。
|
||||
各テストはランダムな schema を作成し、終了時にその schema だけを削除する。
|
||||
試験用ユーザーには CREATE SCHEMA 権限が必要で、本番 DSN は使用しない。
|
||||
DSN を指定しない通常テストでは実 DB 部分だけが skip されるため、
|
||||
PostgreSQL 対応のリリースゲートでは DSN 指定を必須とする。
|
||||
初期検証対象は PostgreSQL 17。最低対応版の確約は CI matrix の整備後とする。
|
||||
|
||||
展示環境では metadata の PostgreSQL 化だけで NFS 対応完了とはしない。
|
||||
Document の no-replace publish と directory fsync、カレンダー正本の lock と atomic rename、
|
||||
秘密鍵とバックアップの配置を別々に検証する。PostgreSQL 自体の PGDATA を
|
||||
未検証の共有 NFS へ移すことで SQLite の問題を置き換える運用は採用しない。
|
||||
DB 用の適切な永続領域または外部 PostgreSQL を確保する。
|
||||
|
||||
#### 移植診断と停止状態の往復リハーサル
|
||||
|
||||
`pageswiki schema portability --db FILE --json` は既存 SQLite を読み取り専用で開き、
|
||||
テーブルの担当領域、未対応テーブル・view・trigger・index、portable migration 履歴、
|
||||
既知 core の catalog の差を報告する。行の値、DDL 本文、DSN、秘密鍵は出力しない。
|
||||
DB がなければ作成せず終了し、初期化や migration は行わない。
|
||||
アプリ全体が未対応の間は `application_ready=false` と終了コード 1 を返す。
|
||||
`core_compatible=true` は下記の限定リハーサルに必要な契約であり、本番移行の許可ではない。
|
||||
未対応テーブルを削除してこの診断を通すことはしない。
|
||||
|
||||
`InspectPortability` は SQLite では既知 core の生成 DDL と索引を厳密に照合し、
|
||||
PostgreSQL では列型、NOT NULL、default、collation、identity、主キー・一意制約・外部キー・CHECK、
|
||||
通常索引の定義と有効状態、sequence の設定を検査する。未知の unique index も無視しない。
|
||||
PostgreSQL の RLS、独自 policy・trigger・routine・rule・sequence、継承・partition 等の未移植の状態は拒否する。
|
||||
trigger は情報スキーマの権限による非表示に依存せず catalog から確認する。
|
||||
PostgreSQL で検査する範囲は現在の schema であり、別 schema のアプリを含む全 DB の認証評価ではない。
|
||||
backend 固有の migration ledger は checksum を検査するが、相手側へコピーしない。
|
||||
|
||||
`CloneCoreForRehearsal` は内部テスト用の core コピーであり、本番用 CLI には公開しない。
|
||||
対象は Object、origin、Path、Revision、Asset、Asset 履歴、Revision の Document 参照、
|
||||
activity outbox と型別 watermark の 9 テーブルに限る。認証、設定、タスク等の
|
||||
追加テーブルがある実稼働 DB は拒否する。全 writer と GC の停止を呼び出し側の前提とし、
|
||||
オンライン移行や二重書き込みを行う機能ではない。
|
||||
|
||||
コピーでは一つの source snapshot から主キー順に行を読み、型付きの値を保って
|
||||
空の staging DB/schema に挿入する。一度に保持するのは一行分であり、最大の一行自体の
|
||||
メモリ使用量は別の制約になる。移行元の DB を変更せず、移行先が空でない場合、
|
||||
同じ DB を別 connection pool から指定した場合、未知の schema がある場合は拒否する。
|
||||
移行先の全 core テーブルを保護し、途中でエラーが起きた場合はコピーした全行を rollback する。
|
||||
文字コード不正、NUL、TEXT 列の BLOB、整数型の不整合、参照欠損を黙って変換しない。
|
||||
|
||||
照合は件数だけではなく、テーブル名・列順・主キー順の各行を長さ付きで SHA-256 に入力する。
|
||||
64bit 整数を浮動小数へ変換せず、日本語、大小文字、異なる Unicode 表現、`%`・`_` を保つ。
|
||||
履歴の採番は現存する最大 ID と generator の保持状態の両方から次の値を決め、
|
||||
過去の ID が再利用されないようにする。PostgreSQL では非 transactional な `setval` ではなく、
|
||||
コピー transaction 内で identity を `RESTART` する。
|
||||
|
||||
参照先の不変 Document は、別途保持する同一の Geduldh Store で SHA-256 を検証する。
|
||||
この関数は blob、カレンダー正本、鍵、インスタンス設定をコピーしない。
|
||||
SQL だけの指紋一致をインスタンス全体のバックアップや復元の成功とは扱わない。
|
||||
実 DB テストでは PostgreSQL 側の追加更新を含めて別の SQLite へ戻し、内容指紋の一致と
|
||||
その後の採番を確認する。未知の制約・RLS・索引の拒否、コピー途中失敗の rollback、
|
||||
source の不変性、Document 欠損、同一 DB への自己コピーも検証する。
|
||||
|
||||
#### 本番 PostgreSQL 移行の受入ゲート
|
||||
|
||||
今回の対象は、全 writer を停止した状態での SQLite→PostgreSQL の片方向インポートと、
|
||||
移行後の通常運用である。PostgreSQL→SQLite の逆移行、自動切り戻し、二重書き込み、
|
||||
オンライン差分同期は今回の実装・受入条件から除外する。
|
||||
既存の core 往復テストは回帰テストとして残すが、本番全件の逆移行へ拡張する作業は行わない。
|
||||
移行前バックアップと片方向インポートの整合性検証は引き続き必須とする。
|
||||
|
||||
2026-11-14 の棚卸しでは Store の SQL 呼び出し点は約 100 ファイル・967 か所ある。
|
||||
これはすべてが SQLite 固有であるという意味ではないが、接続層と core だけでは
|
||||
通常起動・認可・全アプリ機能を満たさない。次の未完了ゲートを残す。
|
||||
|
||||
2026-11-15 時点の受入条件は以下の 8 工程に整理する。1 と 2 の主要 DB 処理は共通テストを通過したが、
|
||||
通常 HTTP/scheduler/CLI 経由の PostgreSQL 統合は工程 7 と合わせて検証する。
|
||||
工程数は受入ゲートの区分であり、8 回の変更や応答で完了するという工数見積もりではない。
|
||||
|
||||
| 順序 | 残工程 | 本番切替前の受入条件 |
|
||||
| --- | --- | --- |
|
||||
| 1 | 認証と権限の統合 | 認証・公開・承認・ユーザー領域の DB 処理は移植済み。残る管理経路の直接 SQL、通常 HTTP 認証と navigation cache の PostgreSQL 統合を確認 |
|
||||
| 2 | Domain と Campus と federation の統合 | namespace CRUD・管理者継承・token・instance・署名 manifest は移植済み。controller/managed プロセスの再起動、鍵・instance identity の保持と HTTP 配信を確認 |
|
||||
| 3 | core と Document と City の接続 | 全 Store 変更系、GC pin、検証 I/O の予算、Document root identity、Asset 復元、Path 移動・削除時の City 境界・ACL・関連リンク・filename Revision・snapshot 検査・cache 失効を接続 |
|
||||
| 4 | タスクと CalDAV と各拡張 | プロジェクト所属、VTODO、ETag/ctag/sync-token、通知、連絡先・RSS・ブログ等の repository と対応テーブルを移植 |
|
||||
| 5 | ジョブと通知 | claim/lease/fencing、キャンセル、outbox 消費、重複排除、再起動時の処理、ログ保持を検証 |
|
||||
| 6 | 検索と管理 | FTS5/rowid/PRAGMA/JSON 関数・照合順序への依存を分離し、権限付き検索・一覧と管理設定を検証 |
|
||||
| 7 | 通常起動と設定 | backend 別 bootstrap、全 Ensure、secret 参照、schema 診断、readiness、CLI/standby の接続を統一し、PostgreSQL で全体試験を通過 |
|
||||
| 8 | 全件インポートと切替 | 全正本テーブルの片方向インポート、再生成可能 cache の分類と再構築、canonical files・鍵の保持、件数・参照・内容指紋・採番の整合性、移行前 backup と PostgreSQL backup/restore を検証し、停止状態で本番切替 |
|
||||
|
||||
MySQL、S3、Redis、HA、逆移行はこの 8 工程の完了条件に追加しない。
|
||||
|
||||
#### 初回切替を短縮する場合の残件
|
||||
|
||||
初回は単一インスタンス・ローカル Document root・停止状態での片方向 import を対象とする。
|
||||
利用者は必須残件を先行し、任意機能をリリース後へ回す方針を了承した。
|
||||
Push 配信・zombie GC・ログの保持期限処理・hosted editor session には native 停止ゲートを実装した。
|
||||
その他の機能を停止する場合も利用者へ制限を示したうえで、
|
||||
起動時・HTTP・CLI・worker の全入口を同じ機能ゲートで拒否する。
|
||||
`NewPostgreSQLWithDocumentRoot` で native の通常 Store を初期化し、
|
||||
合成データによる Server 起動・HTTP 操作・停止後の再初期化まで接続した。
|
||||
`cmd/pageswiki/main.go` は `PAGESWIKI_DB_BACKEND=postgresql` による選択と、
|
||||
全件 import の完了記録・鍵・Document root の一致検査を接続した。未指定時は SQLite のままである。
|
||||
全件転送は `pageswiki migrate-postgres` を使用する。
|
||||
`internal/metadata/portability.go` の core 限定リハーサルとは別の実装である。
|
||||
|
||||
切替に直結する実装順序は次のとおりとする。
|
||||
|
||||
1. ジョブ基盤と outbox の統合。DB 層の claim・完了 token・再起動時の中断扱い・重複排除、
|
||||
Task/Calendar/RSS のイベント登録は移植済み。Server の起動で worker owner を取得し、
|
||||
停止と join 後に解放する。native 通常 Store による HTTP・再初期化・worker 二重起動拒否を検証済み。
|
||||
2. 通常起動・検索・管理経路の接続。backend 明示の Store 初期化、主要画面、
|
||||
内蔵エディタ保存、認証失効、DAV discovery まで接続済み。
|
||||
本番用 backend 選択も接続済み。認証、ACL、公開範囲は省略しない。
|
||||
3. 全件 import。全正本テーブル・鍵・設定・受付/操作履歴・同期番号を列挙し、
|
||||
cache と区別して保全する。identity 採番、本文参照、件数・内容指紋と再実行を検証する。
|
||||
4. 隔離した通常 HTTP 起動と再起動試験、backup/restore 検証後に停止移行する。
|
||||
実行する機能の CRUD、DAV 条件付き更新、権限失効、失敗時の rollback を通してからリリースする。
|
||||
|
||||
| 後回しにできる候補 | 初回切替で必要な条件と制限 |
|
||||
| --- | --- |
|
||||
| HA/LB/DR、無停止・オンライン移行 | 単一インスタンス、旧系の writer を停止した import に限定。PostgreSQL の backup/restore は省略しない |
|
||||
| PostgreSQL から SQLite への逆移行 | 既定どおり対象外。旧 backup からの復旧は、切替後の更新を引き継ぐ逆移行とは別物 |
|
||||
| 自動 GC の同時実行と pin 機構 | native zombie GC は定期実行・手動 API・Store の全入口を拒否する。本文ファイルの GC を新設せず、容量を監視する。本文参照・hash の整合性検証は残す |
|
||||
| 高度な全文検索・ランキング最適化 | native は権限付き Path/ファイル名検索と City メタデータ検索を実装。Page 本文・H1 の検索とサジェストへの H1 付与は未対応。FTS5 や全本文走査で代用しない |
|
||||
| hosted editor | native は起動・ticket 交換・session 取得・保存を拒否し、選択肢から除外する。設定と既存 session は保全し、内蔵エディタを使用する。session の base revision 更新と本文保存をまたぐ整合性は後続対応 |
|
||||
| サムネイル再生成・リソース履歴のグラフ | 対象イベントと API を明示的に無効化。正本と派生 cache/履歴の分類を先に確定し、未分類テーブルを捨てない |
|
||||
| Push/SMTP/外部サービスへの送信 | 配信だけを停止する制限運用は可能だが、Inbox と受付履歴は保持する。不明な送信結果を成功や再送待ちへ変換しない |
|
||||
| ログの自動保持期限処理 | native では定期 cleanup を実行せず、手動呼び出しも拒否する。ログと集計を保全する代わりに容量監視が必要。policy 別の件数・実行時間を制限した cleanup は後続対応 |
|
||||
| MySQL、S3、Redis 等の追加 backend | 今回の PostgreSQL 切替とは別プロジェクトとして扱う |
|
||||
|
||||
全件 import、通常起動、認証/公開権限、正本ファイルと鍵の保全、必要機能の統合試験、
|
||||
移行前 backup は短縮対象にしない。機能縮小で省けるのは各機能の稼働対応であり、
|
||||
その機能が持つユーザーデータの保全ではない。
|
||||
|
||||
#### ジョブと HTTP 接続の移植状況
|
||||
|
||||
`store-event-jobs` は PostgreSQL 用の独立 migration とし、定義、キュー、ログ、集計と設定を作成する。
|
||||
native worker は専用接続の advisory lock により同一 DB/schema に一つだけ起動できる。
|
||||
これは単一インスタンス用の排他であり、HA の lease/failover を提供するものではない。
|
||||
接続が利用不能なら新規 claim を拒否する。
|
||||
`Server.NewChecked` は worker owner 取得・イベント登録の失敗を起動エラーとして返す。
|
||||
`Runner.Stop` は受付を止めて実行中処理を cancel し、完了状態保存を待つ。
|
||||
`Server.Close` は scheduler loop・保守処理・worker の終了後に排他を解放する。
|
||||
停止待ちの timeout は終了完了を意味せず、実行中処理が残る間は排他を保持する。
|
||||
main の SIGTERM/Ctrl+C は Campus 同期の新規開始を止め、進行中同期の終了を待ち、
|
||||
HTTP と worker の停止へ接続した。各外部同期要求は従来の network timeout を使う。
|
||||
|
||||
ジョブの claim、同時実行数とキュー深さの検査、再試行は writer transaction 内で行う。
|
||||
完了には claim ごとの token を要求し、再試行・再起動前の worker の完了を拒否する。
|
||||
完了状態の保存後にログ保存が失敗しても、副作用のあるジョブを自動で再実行しない。
|
||||
再起動時に残る running は結果不明として failed にし、明示的な再試行を待つ。
|
||||
schema 初期化だけで稼働中のジョブを奪わない。
|
||||
|
||||
定期イベントの enqueue と次回日時の更新は同一 transaction で行い、キュー満杯なら両方を rollback する。
|
||||
組み込みイベントの登録は管理者による無効化や周期変更を上書きしない。
|
||||
Task の活動通知、期限通知、Focus、日次メール、RSS、Calendar sweep の登録を接続した。
|
||||
外部配信の実行可否は別の制限であり、登録の移植完了をもって配信を有効化しない。
|
||||
|
||||
outbox の正本 journal と型別 watermark は core 所有のままとし、
|
||||
`store-activity-consumers` が通知先ごとの checkpoint と検索 index を追加する。
|
||||
型別に件数を制限して読み込み、別 consumer の処理済み状態に影響されず、
|
||||
checkpoint の更新は単調増加とする。投影処理と同一 transaction で rollback できる API を維持する。
|
||||
|
||||
HTTP に残っていた Object alias、Calendar の active member、City zone kind、ブログ射影先、
|
||||
設定変更対象の Campus 解決、個人表示設定の直接 SQL は Store API に移した。
|
||||
参照は件数/時間を制限し、alias と射影先の権限判定は引き続き HTTP 側で行う。
|
||||
管理対象を解決できない場合は現在の Campus へ fallback せず拒否する。
|
||||
個人表示設定は現在の membership を再検査し、CAS と read-only 拒否を適用する。
|
||||
`EnsureTasksSchema` は native foundation と productivity migration へ接続した。
|
||||
|
||||
アナウンス、プレビュー解析 cache、リソース履歴も native migration と Store API に接続した。
|
||||
アナウンスは Domain を跨いだ同一 UUID の上書きを拒否し、削除時は Inbox との transaction を維持する。
|
||||
プレビュー解析 cache は PostgreSQL の byte 長で容量を制限し、resource sample は job UUID で重複排除する。
|
||||
これらの変更は起動依存の移植であり、新しい表示機能の追加ではない。
|
||||
|
||||
Push は鍵・購読・配送状態を保持する schema のみ作成し、Inbox INSERT trigger は設置しない。
|
||||
Store の登録・claim・完了・cleanup、HTTP、キー生成、配信の入口で拒否する。
|
||||
native 定期 enqueue と claim は Push を除外し、既存定義の日時や不明な配送状態を書き換えない。
|
||||
停止されたログの期限処理と zombie GC も、機能設定の変更で再有効化できない backend 制限とする。
|
||||
|
||||
HTTP 検索の SQLite 直接生成を Store 経由に変更し、native では Path と元ファイル名を検索する。
|
||||
最新 revision の MIME/拡張子/更新日時、Object 作成日時による絞り込みを候補 LIMIT 前に適用する。
|
||||
候補は最大 1,000 件、返却は最大 200 件、SQL と権限判定の予算は 2 秒とし、
|
||||
本文ファイル・legacy body 列を検索やタイトル補完のために走査しない。
|
||||
候補 cursor を閉じてから権限判定するため、1 接続の pool でも権限問い合わせを実行できる。
|
||||
検索・サジェスト HTTP の `X-PagesWiki-Search-Profile: metadata-only` はこの制限を表す。
|
||||
対象範囲に候補が 1,000 件を超える場合、候補制限による取りこぼしはあり得る。
|
||||
|
||||
City 検索は native の read snapshot 内で種類ごと最大 1,000 件のメタデータを集め、
|
||||
transaction を閉じてから Quartier・Street を含む親階層の権限を確認する。
|
||||
Domain/Path 境界、日付条件、未定義 Spot の Street へのリンクを維持する。
|
||||
Page のファイル種別指定時には City 要素を混ぜない。
|
||||
|
||||
hosted editor は `store-adapter-sessions` に ticket/session/base revision を保全する。
|
||||
native では Store と HTTP の操作入口を拒否し、アダプタ選択肢から editor plugin を除外する。
|
||||
閲覧用 plugin と内蔵エディタはこの制限の対象外である。
|
||||
既定 editor の設定を削除したり、残存 ticket を期限切れ cleanup で消したりしない。
|
||||
|
||||
この検索・保全ガードは合成データの PostgreSQL 17 と SQLite で検証した。
|
||||
`go test ./...`、対象の race 検査、`go vet ./...`、`cmd/pageswiki` のビルドを通過した。
|
||||
検索検査には 1 接続での権限問い合わせ、Domain・親階層の拒否、文字列のリテラル一致、
|
||||
1,100 件の候補に対する LIMIT 前の絞り込み、過去 revision の除外、cancel を含む。
|
||||
検索の repository 統合検証とは別に、次の通常 HTTP 起動検証を行う。
|
||||
|
||||
`NewPostgreSQLWithDocumentRoot` は鍵と Document root を先に検査し、native schema を依存順に初期化する。
|
||||
欠落・不正な `auth.key` を生成し直さず、`PAGESWIKI_AUTH_KEY` を指定しない場合は既存の 32 byte 鍵を要求する。
|
||||
Campus/Domain 未配置、所有 Campus が存在しない Domain、Domain が存在しない Path は起動を拒否する。
|
||||
既存の無効 Campus を既定 Campus へ付け替えず、SQLite の legacy body backfill も実行しない。
|
||||
`BackfillDocuments` の native 呼び出しは明示的に拒否する。
|
||||
正本ファイル全件の hash 照合は import/restore 工程の責務であり、この constructor だけでは保証しない。
|
||||
|
||||
合成データの PostgreSQL 17 で通常 Store と `Server.NewChecked` を組み合わせ、
|
||||
実 HTTP listener の本文取得、主要画面と管理パネル、内蔵エディタ保存と競合 409、
|
||||
無効・失効セッションの 401、CalDAV/Task DAV/CardDAV の discovery を検証した。
|
||||
同じ DB と Document root で Server を停止・再初期化し、本文と認証 session の継続を確認する。
|
||||
稼働中の別 worker 起動は拒否し、停止完了後に再取得できる。
|
||||
resource event の保存は同じ job UUID で再実行しても重複しない。
|
||||
管理画面の最近の Object は native query に分岐し、Domain 内の代表 Path と最新 revision のみを扱う。
|
||||
返却上限 200 件・SQL 予算 2 秒とし、Page 本文は読み込まない。
|
||||
|
||||
全件 import と内容照合、本番 backend 選択、合成データの PostgreSQL dump/restore は接続した。
|
||||
停止切替のコマンドと制限は [PostgreSQL 移行手順](../operations/postgresql-migration.md) にまとめる。
|
||||
本番切替には、移行前の一貫したバックアップと、そのインスタンスの schema preflight・全件 import の成功が必要である。
|
||||
合成データの試験通過は、本番データの移行完了を意味しない。
|
||||
|
||||
`application_import_catalog.go` は保全対象と SQLite 専用索引・migration ledger の列を固定する。
|
||||
未知のテーブル・列・trigger/view 定義を検出したら拒否し、cache と推測して捨てない。
|
||||
移行先に既存データがある場合は schema 準備の前に拒否する。
|
||||
データ転送は単一 transaction とし、schema が用意した既定行のみを置換する。
|
||||
一時停止するのは派生状態を更新する user trigger だけで、FK・CHECK・UNIQUE は維持する。
|
||||
各テーブルの型付き内容指紋・件数、Document の SHA-256、namespace の参照を照合する。
|
||||
SQLite の削除済み最大採番も保持し、transactional identity restart で番号の再利用を防ぐ。
|
||||
タスク DAV の内部索引キーと削除 tombstone は NUL 区切りから native v1 base64url 形式に変換する。
|
||||
この変換を report に明示し、正本 JSON とクライアントに公開する href は変更しない。
|
||||
失敗時の全件 rollback、修正後の再試行、重複 import 拒否、認証 session・画像・日本語タグ、
|
||||
プロジェクト別タスク・連絡先 sync-token の継続を合成データで検証する。
|
||||
同じ正本ファイルを保持した schema 単位の `pg_dump`/`pg_restore` 後も本文・認証・DAV を検証する。
|
||||
|
||||
#### 次の実装単位と検証状況
|
||||
|
||||
工程 3 の通常保存・履歴取得・復元は Store 境界へ接続済みである。
|
||||
エディタ保存 API は Domain と期待 HEAD を明示し、PostgreSQL 分岐から本文永続化・参照固定・
|
||||
Revision・outbox を一つの契約で扱う。SQLite は既存保存動作を維持する。
|
||||
PostgreSQL の通常 HTTP 経路では保存と期待 HEAD 競合を確認済み。
|
||||
履歴復元を含む残る操作の HTTP 確認は工程 7 に残る。
|
||||
|
||||
`path_mutation.go`/`path_snapshot.go` の通常操作、`city_operations.go`/`city_organize.go`、
|
||||
City map 読み取りと Asset Store API は移植済みである。
|
||||
`city.go` の個別作成・削除・relation、`city_plan.go` の一括変更計画、ページ一覧と
|
||||
アーカイブ import 管理も移植済みである。City の作成・配置・再帰削除と計画適用は
|
||||
共通 namespace lock の中で topology version と監査イベントを更新し、途中の SQL 失敗は rollback する。
|
||||
`EnsureCitySchema` は native schema と公開制御の migration へ接続した。
|
||||
|
||||
自動生成の候補取得と名前判定は Store API に集約し、候補 cursor を閉じてから階層を解決する。
|
||||
同じ境界の解決結果は一回の plan 構築中に再利用し、DB 故障を「既存要素なし」として扱わない。
|
||||
候補は 20,000 件を上限とし、超過時に途中までの City を適用しない。
|
||||
定期・編集イベントからの実行は scheduler 移植と統合して検証する。
|
||||
|
||||
children は Domain 全件を Go へ読み込まず、対象 subtree から直下要素を SQL で抽出する。
|
||||
DB generation とプロセス内の cache epoch で別 Store の変更・取得中の失効に追従する。
|
||||
Browser と children の列挙上限は 20,000 件、問い合わせは timeout 付きとし、超過を明示する。
|
||||
PostgreSQL の Browser title は本文 cache ではなく canonical HTML の先頭 64 KiB から取得する。
|
||||
一回の title 読み取りは 32 MiB と timeout で制限するが、DocumentSize の個別 I/O は残る。
|
||||
権限付き Object metadata 一覧は既存の候補・alias 上限と継続 cursor を維持する。
|
||||
|
||||
アーカイブ import は独立 migration `store-imports` でセッション、計画、journal を作成する。
|
||||
Path rollback とセッション状態更新は一つの transaction とし、import 時と Object が一致する
|
||||
binding だけを削除する。City cleanup はそれに先行する再試行可能な別フェーズであり、
|
||||
City と Path を一括 rollback する transaction ではない。
|
||||
旧 worker の void 状態更新 API は失敗を呼び出し元へ返せないため、scheduler 移植時に
|
||||
エラー伝播・状態遷移・再試行を併せて整理する。
|
||||
|
||||
工程 3 の残件は
|
||||
`domain_paths.go` 等の legacy schema adoption と bootstrap の分離、残る直接 SQL writer の棚卸し、
|
||||
import worker のエラー伝播、Path 変更を消費するイベント処理との統合である。
|
||||
同時 GC の pin、Document root identity、巨大 payload 検証の I/O 予算も起動前のゲートとして残す。
|
||||
すべての Path/Revision writer の同じ排他契約への接続が済むまで PostgreSQL の通常起動は許可しない。
|
||||
|
||||
工程 4 は task/CalDAV、calendar、contacts/CardDAV、feeds、periodicals の順に
|
||||
保存スキーマ・変更処理・一覧・ETag/同期 token を一組ずつ移植する。
|
||||
タスクやカレンダーの処理を停止して起動検証だけを通す方式は採用しない。
|
||||
工程 5 と 6 の job claim、notification、全文検索も同様に機能契約を保つ。
|
||||
|
||||
タスク本体は `store-tasks-foundation` の native 空 DB schema と Store 操作を追加した。
|
||||
保存・削除・DAV 設定更新は権限の再確認前に共通 namespace lock を取得する。
|
||||
task head、履歴、変更 journal、outbox、DAV index、通知予約、達成度 index は
|
||||
一つの保存 transaction に含める。削除は tombstone を残し、Wiki とカレンダーを削除しない。
|
||||
一覧では JSON 抽出、文字列検索、パラメータ番号、階層 cursor の真偽値を backend 別に扱う。
|
||||
|
||||
SQLite の DAV 内部索引は NUL 区切りを含むが、PostgreSQL の TEXT は NUL を格納できない。
|
||||
native 内部キーは `v1:{base64url(project)}:{base64url(value)}` とし、既定 collection も同じ方式にする。
|
||||
外部 URI・resource 名・UID・canonical JSON は変更しない。全件 import では derived DAV index を
|
||||
canonical head から再構築し、削除 tombstone の `dav_name`/`dav_uid` も旧 NUL 形式から変換する。
|
||||
この変換なしに SQLite の該当列をそのままコピーしてはならない。
|
||||
|
||||
個人既定値、作業時間、Pomodoro、日次集計、ダッシュボードと予定枠の DB 予約は移植済みである。
|
||||
設定と配置の version を独立させ、作業時間の訂正・取消は監査履歴と同時に commit する。
|
||||
writer は権限確認前に共通 namespace lock を取り、対話的な更新は 5 秒で timeout する。
|
||||
`store-task-productivity` の追加 migration で Focus span と予定枠の title を導入し、
|
||||
既存の `store-tasks-foundation` migration は変更しない。
|
||||
|
||||
`store-notification-inbox` は Inbox のみを作成する。通知挿入は一意キーの競合を
|
||||
transaction 内で処理し、別プロセスからの重複要求も同じ UUID を返す。
|
||||
タイマー完了・期限/着手日の通知は、Inbox 挿入と元の状態更新を同じ transaction に含める。
|
||||
通知保存が失敗した場合は元の状態も rollback し、次回に再試行できる。
|
||||
活動 journal の補完は既存 outbox の冪等キーを再利用する。
|
||||
配信候補は最大 100 件・3 秒に制限し、読めなくなった所属先の情報を通知へ複製しない。
|
||||
|
||||
タスク capture/Wiki 同時作成と再作成、プロジェクト配下のメモ作成は移植済みである。
|
||||
native では Object の作成元 Domain と primary Path を明示し、本文は canonical Document に置く。
|
||||
Task・受付記録・Object・Path・Revision・outbox は同じ transaction で commit する。
|
||||
入力本文は HTML とマクロをエスケープし、削除後の明示的再作成でも既存の Wiki 本文を変更しない。
|
||||
受付記録だけ残っている不整合は自動復活させず、修復が必要なエラーとして扱う。
|
||||
|
||||
メールダイジェストの claim・送信履歴・明示的再試行も移植済みである。
|
||||
共通 namespace lock と状態条件で scheduled/manual claim を一意にし、同意・設定 version・
|
||||
所属権限を再確認する。送信結果が不明な試行は自動再送せず、本人の重複送信了承を必要とする。
|
||||
90 日経過で詳細履歴を削除しても、日次予約と再試行の受付記録は重複防止のため保持する。
|
||||
保守処理は 3 秒・中断判定 100 件・履歴削除 500 件に制限する。
|
||||
|
||||
カレンダーは `calendar-cache` migration で PostgreSQL の月別/イベント索引を作成する。
|
||||
正本は従来どおり月別 ICS と `calendar.json` の manifest であり、DB には移さない。
|
||||
明示的な backend 選択を HTTP の Repository 初期化へ接続し、予約済みタスク予定枠の
|
||||
正本作成・移動後の再試行と日次予定の cache projection を検証する。
|
||||
manifest 更新後の索引再構築失敗は transaction を rollback し、次回アクセスで修復する。
|
||||
cache 更新は 30 秒で打ち切る。全 writer は同じ正本 root と有効な flock を共有する必要があり、
|
||||
独立した filesystem を持つ replica 間の HA は未対応である。
|
||||
任意の DAV filename を UID として復号する際は UTF-8 と制御文字を検証し、
|
||||
非テキストの復号結果を PostgreSQL の TEXT パラメータへ渡さない。
|
||||
|
||||
連絡先は `store-contacts` migration で native schema と変更 journal の trigger を導入する。
|
||||
vCard 正本・履歴 hash・任意 resource 名・tombstone を維持し、更新と変更番号を同時 commit する。
|
||||
CardDAV の inventory と sync-token は PostgreSQL の REPEATABLE READ で同じ snapshot から取得する。
|
||||
metadata inventory は vCard 本文を返さず、UTF-8 の byte 長を返す。
|
||||
保存と snapshot 取得は 5 秒で timeout し、保存は権限・資格情報確認前に共通 namespace lock を取る。
|
||||
全 DB import 時は contact epoch と変更番号を保全し、identity sequence を最大値に合わせる。
|
||||
|
||||
ブログ・日記は `store-domain-entry` の設定 schema を再利用し、追加の `store-periodicals`
|
||||
migration で記事索引・変更履歴・投稿受付記録・射影設定を作成する。
|
||||
書き込みは権限確認前に共通 namespace lock を取得する。記事新規作成では Object・primary Path・
|
||||
Revision・埋め込み参照・受付記録・記事 metadata・変更履歴・outbox を同じ transaction で確定する。
|
||||
本文は canonical Document に保存し、Asset 名は当該 Domain の HEAD を不変 hash に解決して保持する。
|
||||
記事の登録解除は索引だけを削除し、Page 自体は残す。再登録は変更履歴から version を継続する。
|
||||
公開タイトルの問い合わせは許可済み navigation の UUID と Domain に限定し、入力件数も予算内に制限する。
|
||||
射影は同じ Campus の有効な local Domain 同士に限り、多段射影・循環と無効な配信元を拒否する。
|
||||
全件 import では投稿受付記録と記事変更履歴も正本として保全し、履歴の identity 採番を復元する。
|
||||
|
||||
RSS は `store-feeds` migration で購読元・記事 cache・ローカル既読状態・取り込み受付と
|
||||
FreshRSS の明示的操作 receipt を保持する。書き込みは namespace lock 取得後に
|
||||
native actor と拡張設定を検証する。読み取りは 3 秒、書き込みは 5 秒で制限する。
|
||||
FreshRSS 分類は PostgreSQL の JSONB 関数で検索し、カテゴリなしの null/空配列を扱う。
|
||||
壊れた拡張設定は当該 Domain を処理対象から外し、他の購読元の候補検索を中断させない。
|
||||
送信結果が不明な操作は購読元の変更・削除後も履歴として保持し、自動再送しない。
|
||||
期限切れ claim の回収は 1 transaction あたり 100 件・3 秒に制限する。
|
||||
次の実装単位は scheduler の native schema と claim/lease/ログ保持、各イベント登録である。
|
||||
Push 配信と scheduler のイベント登録・実行は未統合である。
|
||||
外部カレンダーの内容は検証に用いない。
|
||||
`EnsureTasksSchema` と `EnsureNotificationSchema` の native 通常起動は引き続き未対応として拒否する。
|
||||
旧 free helper を使う未移植の呼び出し元は SQLite 用であり、native Store の receiver へ順次接続する。
|
||||
DAV HTTP の discovery/REPORT/条件付き PUT/DELETE、ETag・ctag の再起動後整合性と
|
||||
カレンダー共通 endpoint の実機統合も残る。task payload 永続化中に writer transaction を保持する
|
||||
既存動作と GC pin は、Document の I/O 予算・参照固定の残件として扱う。
|
||||
|
||||
2026-11-15 の合成データによる検証では、SQLite とローカル PostgreSQL 17 を使った
|
||||
全 Go テスト、移植済み Store の共通契約・PostgreSQL migration テストの race 検出、
|
||||
`go vet ./...`、ローカルバイナリ生成が成功した。
|
||||
公開・承認、ユーザー領域・電話番号の同意、Domain 同時作成・移動、管理者継承の取消、
|
||||
Federation の token 失効・署名改ざん・replay・同時初回受信・checkpoint 故障時の rollback を含む。
|
||||
通常保存の追加試験では別 Store からの同時 CAS と無条件 append、言語別履歴、
|
||||
create/save/bind の origin 制約、別 Domain への移動後の拒否、現在の Asset HEAD を変更した後の
|
||||
履歴復元、本文・埋め込み payload の欠損、Page/Revision の outbox 故障時の rollback を確認する。
|
||||
Path/City/Asset の追加共通試験では、再帰移動・コピー・重複選択の削除、literal な `%`/`_`、
|
||||
stale snapshot の拒否、保護 namespace の拒否、コピーと filename Revision の参照保持、
|
||||
navigator の移動先重複解消、Spot 統合後の所属と URL 保持、同時 topology version 更新、
|
||||
Asset の同時 CAS・履歴復元・欠損拒否・監査保存故障時の rollback を確認する。
|
||||
City CRUD・一覧・アーカイブ import の追加試験では、stale plan、再帰削除中の監査故障、
|
||||
archived 名の再利用、literal prefix、12 件以上の指定順序、canonical H1、metadata cursor の
|
||||
重複防止、別 Store からの cache 失効、import 番号重複時の計画保持、Domain 分離、
|
||||
Path rollback と状態更新の原子性、付け替え済み Path の保護、read-only 拒否を確認する。
|
||||
タスクの追加試験では、プロジェクト別の同一 DAV UID、同一 collection 内の衝突拒否、
|
||||
既定 collection の分離、親子階層、日付・優先度・添付の絞り込みと pagination、履歴、
|
||||
完了時の通知予約削除、削除の再試行と復活拒否、DAV 資格情報の発行・失効を確認する。
|
||||
PostgreSQL の別 Store からの同時保存は一方だけ成功し、outbox 故障では保存と削除が rollback する。
|
||||
readonly Principal の書き込み拒否と、Membership 失効後の読み取り拒否も確認する。
|
||||
生産性機能の共通試験では、個人設定と配置の独立した CAS、作業時間の訂正・取消・履歴の
|
||||
pagination、Pomodoro の停止区間を除いた集計、完了通知の一度だけの登録、予定枠の状態変更、
|
||||
期限通知の再送防止と活動 journal の重複排除を確認する。
|
||||
PostgreSQL では別 Store の同時設定更新・作業開始・タイマー開始・完了処理も試験し、
|
||||
監査失敗時に作業時間/Focus span が途中で更新されないこと、Inbox 故障後の再試行、
|
||||
同時通知挿入の一意性、受信者 scope と失効後の拒否を確認する。
|
||||
capture/メモの共通試験では日本語 Path と本文、HTML/マクロの無害化、受付の再送、
|
||||
同一 Path の衝突拒否、削除後の明示的再作成と本文保持、stale project の拒否を確認する。
|
||||
PostgreSQL では受付記録の故障による全関連 metadata の rollback、別 Store からの同時 capture、
|
||||
canonical 本文の読み戻し、作成元 Domain・primary Path・cache generation を確認する。
|
||||
メール管理の共通試験では日次 claim の重複拒否、重複送信了承・受付再送・履歴 pagination、
|
||||
同意変更後の取消、保持期限後の予約・受付保持を確認する。PostgreSQL では複数 Store の
|
||||
scheduled/manual claim と、送信結果保存失敗時の rollback、中断試行の自動再送防止を確認する。
|
||||
カレンダーの共通試験では月またぎ移動、ETag 競合、DAV filename 保持、既定 calendar、
|
||||
共同編集者の読み取り権限と失効、全 cache 消去後の再構築、削除を確認する。
|
||||
PostgreSQL では別 Repository の同時編集、再構築・削除の DB 故障時の正本保持と再試行を検証する。
|
||||
タスク予定枠の再送が移動済み予定を上書きしないこと、日次 projection が現在の時刻を返すこと、
|
||||
外部 source は snapshot 読み込み前に拒否されることも合成 metadata で確認する。
|
||||
連絡先の共通試験では日本語検索、未知の vCard property 保持、同一 UID import の再送、
|
||||
削除の差分配信、履歴復元、metadata の byte 長、差分 pagination、資格情報失効を確認する。
|
||||
PostgreSQL では同時 CAS と履歴保存故障時の連絡先・同期番号の rollback を確認する。
|
||||
ブログ・日記の共通試験では日本語記事の作成・再送、変更された再送入力の拒否、
|
||||
記事 metadata の CAS、登録解除後の Page 保持と再登録、Asset HEAD 更新後の本文参照固定、
|
||||
欠損 Asset の拒否、公開タイトルの Domain 分離と件数上限、射影の循環・無効な配信元の拒否を確認する。
|
||||
PostgreSQL では変更履歴の保存故障時に Path と受付記録が rollback すること、
|
||||
別 Store からの同時投稿要求が一つの記事となること、Campus 無効化後の投稿拒否を確認する。
|
||||
RSS の共通試験では日本語・literal 検索、日時 cursor、既読状態の CAS、
|
||||
FreshRSS のカテゴリ/未分類/空フォルダ、購読 import と Wiki 取り込みの再送、
|
||||
削除済み購読元の復活拒否、外部操作の確認・期限切れ・読み取り専用再確認を検証する。
|
||||
購読元を変更・削除しても不明な外部操作を保持し、履歴の metadata 欠損を許容する。
|
||||
PostgreSQL では複数 Store の同時 claim、cache 保存故障時の lease rollback、
|
||||
100 件ずつの期限切れ回収、破損設定と Campus 無効化後の拒否を確認する。
|
||||
ジョブの共通試験では claim・完了・再試行・キャンセル・一覧・ログ・集計と read-only 拒否を確認する。
|
||||
PostgreSQL では同時定期登録の一意性、同時 claim の上限、二つ目の worker owner の拒否、
|
||||
再起動後の結果不明ジョブの保留、古い完了 token の拒否、完了ログ故障時の状態保持を確認する。
|
||||
outbox は型別・Domain 別の取得、consumer の独立性、同時 checkpoint の単調性、
|
||||
rollback と read-only 拒否を両 backend で検証する。
|
||||
HTTP 用 lookup と個人表示設定の共通試験では Domain 分離、無効 Principal、対象欠損時の拒否、
|
||||
設定 CAS を確認する。scheduler/outbox/lookup の対象テストは race detector でも検証する。
|
||||
これらは component テストであり、PostgreSQL を指定した通常アプリ起動や本番データ import の成功ではない。
|
||||
|
||||
検証は `GOPROXY=off GOSUMDB=off` とし、実 PostgreSQL の共通テストには
|
||||
`PAGESWIKI_TEST_POSTGRES_DSN` で使い捨て DB を指定する。各テストは専用 schema を作成・削除するため、
|
||||
本番 DB を指定してはならない。実際の外部カレンダー、OIDC/LDAP/SMTP、Gitea へのアクセスは不要。
|
||||
|
||||
2026-11-15 に Gitea の復旧連絡を受領した。移植中は引き続きローカルビルドで検証し、
|
||||
全 repository・通常起動・インポートのリリースゲートを満たした後に、commit/push、
|
||||
SemVer タグ、Gitea CI の image build とリリースへ進む。復旧だけを理由に未完の移植を配布しない。
|
||||
ローカルビルドの成功は DB 切替の許可条件ではなく、上記ゲートと停止状態の全件インポート検証を
|
||||
満たした後、移行前 backup を確保し、同じ成果物で隔離起動試験を経て本番を起動する。
|
||||
|
||||
未対応機能を暗黙に初期化したり、読めないテーブルを cache とみなして捨てたりしない。
|
||||
外部 RDB 障害時に SQLite へ自動 fallback する設定は作らず、二つの DB が別々に
|
||||
更新を受ける状態を防ぐ。最低 PostgreSQL 対応版と CI matrix の確定も切替条件とする。
|
||||
|
||||
#### 片方向インポートと切替の設計
|
||||
|
||||
本番切替は全ゲートが通った後、次の順で行う。全件移行ツールは
|
||||
`pageswiki migrate-postgres` であり、core リハーサルをその代用にしない。
|
||||
|
||||
1. HTTP/CalDAV/CLI、scheduler、federation を含めた全 writer と GC を停止し、保守状態を確認する。
|
||||
2. SQLite の整合した snapshot、Document、カレンダー正本、設定・鍵・instance identity を保全し、復元検証する。
|
||||
3. 空の専用 PostgreSQL へ全件移行し、件数・内容指紋・参照・採番・payload を照合する。
|
||||
4. 読み取り検証でログイン、権限、公開ナビゲーション、検索、タスク/CalDAV、管理・配信を確認する。
|
||||
5. 反映する全プロセスを一斉に PostgreSQL 側へ向け、旧 SQLite は凍結したまま、書き込み再開時点を記録する。
|
||||
|
||||
書き込み再開前にインポートや検証が失敗した場合は移行を中止し、元の SQLite を維持する。
|
||||
書き込み再開後は PostgreSQL を正本とし、障害時は PostgreSQL 側の復旧・修正を基本とする。
|
||||
移行後の更新を SQLite に反映する機能は今回提供せず、接続先を旧 SQLite へ自動で戻さない。
|
||||
この制約を運用手順にも明記し、逆移行の完成を本番切替の前提条件にはしない。
|
||||
|
||||
### S3:運用と移行
|
||||
|
||||
- [ ] 編集可能な設定例と薄い backup / release / deploy script。
|
||||
@@ -404,6 +1217,10 @@ setup 完了後は token 再利用不可。機密欄の再表示・ログ出力
|
||||
## 12. 根拠資料
|
||||
|
||||
- [SQLite WAL:network filesystem の制約](https://sqlite.org/wal.html)
|
||||
- [PostgreSQL の transaction-level advisory lock](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)
|
||||
- [PostgreSQL の identity 変更](https://www.postgresql.org/docs/current/sql-altertable.html)
|
||||
- [PostgreSQL の RESTART と transaction](https://www.postgresql.org/docs/current/sql-altersequence.html)
|
||||
- [pgx の database/sql 接続](https://pkg.go.dev/github.com/jackc/pgx/v5/stdlib)
|
||||
- [S3 の conditional writes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html)
|
||||
- [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/)
|
||||
- [PostgreSQL backup / restore](https://www.postgresql.org/docs/current/backup.html)
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
# PostgreSQL への停止移行
|
||||
|
||||
SQLite から PostgreSQL への片方向移行を、単一インスタンス・ローカルの正本ファイル配置で行う。
|
||||
全 writer を停止し、空の専用 PostgreSQL database/schema へ転送する。既存 DB への merge、
|
||||
オンライン差分同期、PostgreSQL から SQLite への逆移行は提供しない。
|
||||
|
||||
## 対応範囲と制限
|
||||
|
||||
検証対象は PostgreSQL 17。通常起動の既定値は引き続き SQLite である。
|
||||
PostgreSQL 起動は verified TLS、全件 import の完了記録、既存の鍵と同じ絶対 Document root を必須とする。
|
||||
DB 接続障害や検査失敗で SQLite に自動 fallback しない。
|
||||
|
||||
- native 検索は権限付きの Path・ファイル名・City メタデータ検索。本文全文検索は後続対応。
|
||||
- hosted editor、Web Push 配信、zombie GC、ログの自動保持期限処理は native の停止ゲート対象。
|
||||
設定・受付記録・既存データは保全する。内蔵エディタと Inbox を使用し、ログ・ファイル容量を監視する。
|
||||
- DR/HA 構成への移行は拒否する。`pageswiki dr` と旧 `schema` コマンドは PostgreSQL 設定時に拒否する。
|
||||
- DB 直結の `data/pageswiki-cli` は SQLite 専用。PostgreSQL では HTTP の `pages-cli` を使用する。
|
||||
すべてのプロセスに backend 設定を統一し、旧 SQLite 用 CLI を起動しない。
|
||||
- 外部カレンダーの実データを使った検査・再取得は行わない。検証用の予定・連絡先・タスクは合成データを使う。
|
||||
|
||||
## 移行前の準備
|
||||
|
||||
1. HTTP、CalDAV/CardDAV、CLI、scheduler、federation、外部の直接 DB writer を停止する。
|
||||
コマンドは data directory の排他ロックを取るが、旧バイナリや直接 SQLite client の停止を代替しない。
|
||||
2. 停止状態の data directory 全体を別の場所に保全する。SQLite と WAL、`documents`、カレンダー・タスク等の
|
||||
正本ファイル、設定、`auth.key`、instance identity を同じ時点で保全する。
|
||||
`PAGESWIKI_AUTH_KEY` を使用していた場合はその secret も別途保全し、移行時・起動時に同じ値を渡す。
|
||||
3. 専用 PostgreSQL database/schema と、それを所有する移行ユーザーを用意する。
|
||||
schema/table/trigger/identity の作成・変更権限が必要。共有アプリ DB を移行先にしない。
|
||||
4. PostgreSQL の CA とホスト名を検証できる DSN を secret として用意する。
|
||||
`PAGESWIKI_POSTGRES_DSN` に `sslmode=verify-full` と必要な `sslrootcert` を設定する。
|
||||
DSN はコマンドラインやログに出さない。移行先の管理者による同時 schema 変更も停止する。
|
||||
|
||||
## コマンド
|
||||
|
||||
以下は、稼働時にも `/data` を使う場合の例。移行と起動で data directory の絶対パスを一致させる。
|
||||
Docker では同じ `/data` マウントを使用する。別のホスト側絶対パスで import してから
|
||||
コンテナ内 `/data` に切り替えると、root 検査により起動を拒否する。
|
||||
|
||||
```sh
|
||||
# schema の読取り検査。移行先への接続・データコピーは行わない。
|
||||
./pageswiki migrate-postgres --data-dir /data
|
||||
|
||||
# DSN は保護された環境設定から注入済みとする。
|
||||
./pageswiki migrate-postgres --data-dir /data --apply --timeout 30m
|
||||
|
||||
# import 成功・保全確認後、同じ正本 root と鍵で起動する。
|
||||
PAGESWIKI_DB_BACKEND=postgresql PAGESWIKI_DATA_DIR=/data ./pageswiki
|
||||
```
|
||||
|
||||
`--apply` がない場合は schema preflight のみで、payload の検証成功を意味しない。
|
||||
`--allow-insecure` は隔離試験専用の移行オプションであり、通常起動の TLS 検証は緩和しない。
|
||||
未知のテーブル・列・trigger/view がある場合は処理を止め、保全分類と schema を修正して再試行する。
|
||||
不明なデータを削除して検査を通さない。
|
||||
|
||||
## 転送と照合
|
||||
|
||||
保全対象は `internal/store/application_import_catalog.go` に列挙する。
|
||||
SQLite 専用 FTS 索引・派生 latest revision index・SQLite migration ledger は除外するが、
|
||||
設定、鍵への参照、認証、ACL、タスク、連絡先、同期番号、受付履歴、ジョブ・ログ等は保持する。
|
||||
正本ファイルは同じ場所に残す。ファイル自体を別の volume へコピーするコマンドではない。
|
||||
|
||||
転送は単一 transaction。転送前に移行先の空状態を検査し、型を区別した各行の内容指紋・件数、
|
||||
参照される Document の SHA-256、namespace の参照整合性を commit 前に検査する。
|
||||
タスク DAV の内部索引だけは backend 形式の違いを明示的に変換する。変換後の内容指紋を照合し、
|
||||
クライアント用 href・正本 JSON は保持する。削除履歴と削除済み最大採番も保全する。
|
||||
|
||||
JSON report は対象テーブルの件数と指紋、除外一覧、変換内容、Document 数、採番情報を返す。
|
||||
本文や資格情報は含まない。成功時の report をバックアップと一緒に保管する。
|
||||
失敗時はデータ転送を rollback する。準備済み schema は残り得るが、既定行だけの状態なら再試行できる。
|
||||
完了済み import や既存データへの上書きは拒否する。
|
||||
|
||||
## 起動確認と復旧
|
||||
|
||||
書き込み再開前に、同じバイナリと設定で起動し、ログイン・既存 session・権限・本文・内蔵編集・
|
||||
タスクのプロジェクト所属・DAV discovery/条件付き更新・連絡先・管理画面を確認する。
|
||||
外部送信や取得を伴う worker の再開対象は事前に点検する。
|
||||
この実装は import 済み DB を開くためのもので、空の PostgreSQL から既定 Campus を新規生成しない。
|
||||
|
||||
移行前 SQLite は凍結したまま保管する。書き込み再開後の新しい更新は PostgreSQL 側にしか存在しない。
|
||||
旧 SQLite へ接続を戻すことはデータを引き継ぐ切り戻しではない。
|
||||
|
||||
PostgreSQL 運用のバックアップは、writer を停止した同じ時点の `pg_dump -Fc` と data directory 全体、
|
||||
鍵・secret を組にする。復元先は空の専用 database/schema とし、`pg_restore --exit-on-error` で復元する。
|
||||
ファイルを元と同じ絶対 mount path に復元し、接続先 DSN のみ変更する。
|
||||
import 完了記録も dump に含める。DB 単独や正本ファイル単独のバックアップでは復元条件を満たさない。
|
||||
復元後は停止状態で本文・参照・認証・DAV 同期の検証を実施してから writer を再開する。
|
||||
|
||||
## 検証とリリース前チェック
|
||||
|
||||
- 合成データで全件移行、途中失敗の rollback、再試行、上書き拒否、schema drift 拒否を検証する。
|
||||
- 日本語本文・タグ、バイナリ画像、認証 session、プロジェクト別 DAV、削除 tombstone、連絡先 sync-token を照合する。
|
||||
- 隔離した PostgreSQL 17 に対し schema 単位の dump/restore と、同じ正本 root の読み戻しを検証する。
|
||||
- `go test ./...`、対象 race test、`go vet ./...`、通常バイナリ build を通す。
|
||||
- 実インスタンスの停止バックアップと import 結果は、合成データ試験とは別に確認する。
|
||||
- image build workflow は `tools/ci/test-postgres.sh` で PostgreSQL 17 の全 Go テストを実行してから publish する。
|
||||
DB container は外部ネットワーク・公開 port を持たず、テスト container がその network namespace を共有する。
|
||||
DSN 未設定で実行したローカルテストの skip を移植検証の成功として扱わない。
|
||||
|
||||
任意のテスト DSN に本番を指定しない。`PAGESWIKI_TEST_POSTGRES_DSN` は使い捨て DB に限定する。
|
||||
CLI と verified TLS の試験は `PAGESWIKI_TEST_POSTGRES_TLS_DSN` を指定する。
|
||||
`PAGESWIKI_TEST_POSTGRES_CONTAINER` を追加指定すると、同じ隔離 DB を持つ Docker container 内の
|
||||
`pg_dump`/`pg_restore` でテスト専用 schema の復元試験を実行する。
|
||||
Reference in new issue
Block a user