本頁由英文頁面機器翻譯而成。內容以英文頁面為準。 閱讀英文頁面
資料庫:初始化、升級與重新建立
說明營運者如何建立資料庫、將它升級到新版本,以及(僅限開發與測試用實例)清除它。
結構描述(schema)存放在 schema/ 中,每個模組一個目錄,每種資料庫一個檔案(schema/<NN>-<module>/sqlite.sql 與 postgres.sql)。伺服器執行檔內含其版本的結構描述,由 my schema apply 套用:每種部署方式都會在伺服器之前,以伺服器映像檔與伺服器的資料庫設定,將它作為一次性任務執行,因此一個實例只需要伺服器映像檔這一個映像檔。my serve 絕不會套用結構描述。在沒有結構描述的資料庫上啟動時,伺服器會在 /readyz 回應 503(請參閱啟動伺服器)。
結構描述變更時需要轉移的資料(一個欄位拆成兩個、某個值移到新的資料表),會由伺服器映像檔本身的 my db upgrade 改寫;它在套用結構描述之後,每個版本執行一次。完整的順序請見升級。
初始化(套用結構描述)
Section titled “初始化(套用結構描述)”my schema apply 只會執行讓資料庫符合其版本結構描述所需的陳述式:在空的資料庫上會建立所有內容,在已是最新狀態的資料庫上則什麼也不做。執行幾次都是安全的,每次升級也都會再執行它。
使用 my schema apply
Section titled “使用 my schema apply”my schema apply 會讀取伺服器設定中的資料庫設定(database、database_url 與 database_dev_url,來自 -config <file> 或環境變數;不需要其他設定),並讓資料庫符合該執行檔版本的結構描述:
my schema apply -dry-run # print the SQL statements it would run, and change nothingmy schema apply # run them- 它會印出所執行的 SQL 陳述式,並在一個交易中執行:只要有一個失敗,就不會留下任何變更。已符合結構描述的資料庫不會被變更(
ok: the database matches the schema; nothing to apply)。 - 會刪除資料表或欄位的計畫會被拒絕,什麼都不會執行,除非指定了
-allow-destructive。只有在版本說明要求時、並在備份之後才指定它。為了變更 SQLite 資料表而重建該資料表,不算是刪除。 - 在 PostgreSQL 上,它會在同一個資料庫的暫時 schema 中建立用來比較的結構描述,並在結束時(包括失敗時)刪除它;角色需要在那裡建立 schema 的權限。若沒有這個權限,請把
database_dev_url設為另一個有權限的資料庫(database_dev_url)。對同一個資料庫的多次執行會互相等待,因此同時執行兩次也都會成功。 - 它支援
database = sqlite與database = postgres,當因錯誤或拒絕刪除而沒有套用任何內容時,會以1結束。
從 v0.1.0 開始,受支援版本之間的升級絕不會包含會遺失資料的差異;v0.1.0 之前的版本可能會刪除欄位與資料表,因此需要 -allow-destructive。每次升級前都請用 -dry-run 閱讀 SQL(請參閱升級)。
my schema apply 必須直接連線到資料庫。它會持有工作階段層級的鎖,而交易模式的連線池(PgBouncer 的 transaction pooling、Neon 的 pooled 連線字串)不會保留這種鎖:透過這種連線池,同時執行兩次會卡住而不是失敗。請把直接連線的 URL 設為 database_url。pool_max_conns 與其他 pool_* 參數可以保留在其中,也可以保留在 database_dev_url 與 stream_postgres_url 中:不開啟連線池的指令會忽略它們。my db upgrade、my db upgrade -check 與主控台也使用同一個 URL。
my serve 可以使用交易模式的連線池,只要:
- 連線池能處理協定層級的預備陳述式(prepared statement),伺服器的每個查詢都會使用它:PgBouncer 1.21 或更新版本,且
max_prepared_statements大於 0,Neon 的 pooled 連線字串就符合這個條件。在不支援的連線池後方,陳述式會隨機以prepared statement ... does not exist或already exists失敗:請在 URL 中加上default_query_exec_mode=exec,這樣就能避開它們,代價是每個查詢多一次往返。 stream = postgres時,stream_postgres_url要使用直接連線的 URL,因為LISTEN屬於工作階段。使用經過連線池的 URL 的監聽者雖然能連線,卻收不到任何東西。- URL 中沒有
search_path或其他連線池在連線時會拒絕的參數:除非ignore_startup_parameters列出了這些參數,否則 PgBouncer 會關閉這樣的連線。
Docker Compose
Section titled “Docker Compose”在 deploy/docker/compose.yaml 中,伺服器映像檔的三個一次性服務會依下列順序執行,每一個都要在前一個成功之後才會執行,最後才啟動伺服器(my):
| 服務 | 執行內容 |
|---|---|
upgrade-check |
my db upgrade -check(空的資料庫會通過) |
schema |
my schema apply,對象為 /data/my.db,或在使用 compose.postgres.yaml 層時為其 PostgreSQL(Docker Compose 檔案) |
upgrade |
my db upgrade |
cd deploy/dockerdocker compose up -d # pulls the image of MY_VERSION; the three one-off services run in order, then my startscurl -fsS localhost:8080/readyz # ready when it answers {"status":"ok"}docker compose exec -T my my admin create -username alice -email alice@example.com < password.txt- 只要三者中有一個失敗,
my就不會啟動。請用docker compose logs upgrade-check(或schema、upgrade)閱讀其輸出。 - 建立管理員的方法請見管理員與角色。
不使用 Compose 時,請以與伺服器相同的資料庫設定,將伺服器映像檔的 my schema apply 作為一次性任務執行(Kubernetes Job 或 init 容器、Cloud Run 任務等):
# SQLite: mount the volume that holds the database file at /datadocker run --rm -v my_data:/data -e MY_DATABASE=sqlite -e MY_DATABASE_URL=/data/my.db my schema apply
# PostgreSQLdocker run --rm -e MY_DATABASE=postgres -e MY_DATABASE_URL='postgres://my:...@db.example/my' my schema applyPostgreSQL 的連線池遵循 database_url 的 pool_* 參數:pool_max_conns(預設為 4 與 CPU 數量中較大的一個)與 pool_min_conns(沒有請求時仍保留的連線數),並由 pool_max_conn_idle_time(30 分鐘)關閉其餘的連線。如果實例的請求間隔很長,請設定 pool_min_conns,否則每個請求都要開啟一條連線。
SQLite 也接受 pool_max_conns(預設值相同),以及 pool_max_idle_conns,也就是它最多保留的閒置連線數。它是上限,而不是像 pool_min_conns 那樣的下限(預設為全部保留,也不會因時間而關閉任何連線,所以閒置的實例能立即回應)。新的連線在第一次查詢之前會先解析結構描述,這就是連線池要保留連線的原因。
升級到新版本時,一律使用新版本的伺服器映像檔,依下列順序執行這些步驟:
- 備份資料庫(使用檔案系統 blob 儲存時,也要備份媒體)。請參閱備份。
my db upgrade -check。它不會變更任何東西。當新的結構會刪除資料庫尚未轉移的資料時,它會以1結束,並指出要先升級到哪個版本;這時請停下來,依照跳過版本處理。空的資料庫會通過。my schema apply,做法同初始化。請先用-dry-run檢查 SQL。my db upgrade。它會執行該版本中資料庫尚未記錄的每個資料升級步驟,重建這些步驟所指名的投影,並記錄每個步驟。再次執行時它不會做任何事。如果某個步驟失敗,它會以1結束;已完成的步驟仍保持記錄,再次執行會從失敗的那一步繼續。- 啟動新的伺服器。 在該版本的每個資料升級步驟都被記錄之前,它會在
/readyz回應503,並記錄缺少的步驟。
my serve 從不執行 my db upgrade -check、my schema apply 或 my db upgrade;它們都是一次性的任務。對同一個資料庫一次只能執行其中一個。
在一個任務中執行這些步驟
Section titled “在一個任務中執行這些步驟”my upgrade 會在 my config check 的檢查之後,於同一個程序中執行步驟 2 到 4,讓單一的一次性任務(Cloud Run 任務的一次執行、ECS 任務、Kubernetes Job)就能完成整個遷移:
my config checkmy db upgrade -checkmy schema apply,若給my upgrade指定了-allow-destructive,這裡也會帶上my db upgrade
它會在第一個失敗的步驟停下,並以該步驟的結束碼結束;之後的步驟不會執行。每個步驟都會印出一行標明它的訊息(例如 ==> my schema apply),接著是該指令的輸出,因此任務的日誌會顯示它停在哪裡。修正原因之後再次執行 my upgrade:已完成的步驟會發現沒有剩下的事要做。-config <file> 會傳給每個步驟。
my upgrade -dry-run 會執行 my config check、my db upgrade -check 與 my schema apply -dry-run,不會變更任何東西:請在升級之前閱讀它印出的 SQL。如同步驟 1,請在 my upgrade 之前備份資料庫;它不會切換到維護模式,也不會啟動伺服器。
大多數版本不會新增資料升級步驟:my db upgrade -check 會輸出 ok: the database can be upgraded to this release,而在已記錄先前版本步驟的資料庫上,my db upgrade 會輸出 ok: no data upgrade step to run。新的資料庫會在第一次 my db upgrade 時記錄該版本的所有步驟,沒有任何東西需要改寫。兩者還是都要執行,這樣流程就不必仰賴閱讀每一份版本說明。
版本說明的升級一節會列出每個版本的步驟。
升級期間的伺服器
Section titled “升級期間的伺服器”不保證能零停機升級。在步驟 3 到 5 之間的短暫時間內,舊版伺服器仍能在新的結構描述上運作,但無法參與資料升級步驟。升級時請切換到維護模式:在維護模式下,my serve 不會開啟任何資料庫連線,因此備份會保持一致,執行步驟期間也不會有任何寫入。請把維護時段控制在幾個小時以內(多久)。
從圖的上方往下:
- 舊版本。伺服器照常執行,
/readyz回應200與{"status":"ok"}。 - 維護模式。以
MY_MAINTENANCE=true重新部署。從這時起到新版本啟動為止,/readyz會回應200與{"status":"maintenance"},因此負載平衡器會保留這些執行個體,同時沒有任何請求會到達資料庫。 - 1. 備份資料庫與媒體。
- 2 到 4:新映像檔的一次性任務。
my db upgrade -check不會變更任何東西;my schema apply要在你閱讀過它的-dry-run之後執行;my db upgrade執行資料升級步驟。 - 5. 啟動新版本,不設定
MY_MAINTENANCE。當該版本的每個資料升級步驟都已記錄時,/readyz會回應200與{"status":"ok"};仍有缺少的步驟(或尚未套用結構描述)時則回應503。
使用 Docker Compose 時,docker compose up 會在一次性任務執行之前取代維護模式的容器,因此在步驟 2 到 4 期間,/readyz 不會有任何回應(Docker Compose)。
用 -dry-run 檢查 SQL
Section titled “用 -dry-run 檢查 SQL”在步驟 3 套用任何東西之前,請執行 my schema apply -dry-run,閱讀它將會執行的內容。大多數版本包含的是新增(CREATE TABLE、ADD COLUMN、CREATE INDEX)。投影資料表也可能被重建,之後再由 my db upgrade 從其事件重新填入。對其他任何東西的 DROP 或型別變更,應該列在版本說明的 Breaking changes 一節中;若沒有列出,請在套用前停下來並回報。除非指定了 -allow-destructive,否則 my schema apply 會拒絕刪除資料表或欄位的計畫。
Docker Compose
Section titled “Docker Compose”docker compose up -d 會自行依序執行步驟 2 到 5(請參閱初始化中的表格)。只要其中一個失敗,新的伺服器就不會啟動。
cd deploy/docker
# 1. Switch to the maintenance mode. --no-deps keeps the one-off services from running.MY_MAINTENANCE=true docker compose up -d --no-deps --force-recreate my
# 2. Back up the volume (database and media) while the maintenance mode holds no connection.docker run --rm -v my_data:/data -v "$PWD":/backup busybox tar czf /backup/my-data-$(date +%Y%m%d%H%M).tar.gz -C /data .
# 3. Set MY_VERSION in .env to the new version (0.2.0, or its digest form 0.2.0@sha256:... from the notes), and pull it.docker compose pull
# 4. Check the SQL that the schema service will run.docker compose run --rm --no-deps upgrade-checkdocker compose run --rm --no-deps schema schema apply -dry-run
# 5. Upgrade: upgrade-check, schema, upgrade, then my starts again without the maintenance mode.docker compose up -dcurl -fsS localhost:8080/readyzdocker compose up 會在一次性服務執行之前取代 my 容器,並且只在三者都成功之後才啟動新的容器。若其中一個失敗,docker compose up 會回報,伺服器則保持停止:這段期間請在前方放置匯出的維護頁面。閱讀 docker compose logs <service>,然後修正原因後再次執行 docker compose up -d,或是回復。磁碟區名稱 my_data 是 Compose 專案名稱(my)加上磁碟區名稱(data)。
升級時唯一要變更的是 MY_VERSION,而且不會有任何東西自動替你變更它:沒有 latest 標籤,0.1 也只會在 v0.1 之內移動。使用 MY_VERSION=0.1 時,步驟 3 只需要 docker compose pull,就會取得最新的修補版本。若改為從原始碼建置,請簽出新版本的標籤,在步驟 3 使用 docker compose -f compose.yaml -f compose.build.yaml build,並在其他步驟使用相同的 -f 選項。
Kubernetes
Section titled “Kubernetes”在推出新映像檔之前,把步驟 2 到 4 作為一個 Job 執行。init 容器會一個接一個執行,每一個都要在前一個成功之後才執行,主容器則最後執行,因此只要失敗,Job 就會在下一個步驟之前停止。請給這些容器與 Deployment 相同的設定。
apiVersion: batch/v1kind: Jobmetadata: name: my-upgrade-v0-2-0spec: backoffLimit: 0 template: spec: restartPolicy: Never initContainers: - name: upgrade-check image: ghcr.io/mycroblog/my:0.2.0 args: [db, upgrade, -check] envFrom: [{ secretRef: { name: my-config } }] # the Deployment's settings - name: schema image: ghcr.io/mycroblog/my:0.2.0 args: [schema, apply] envFrom: [{ secretRef: { name: my-config } }] containers: - name: upgrade image: ghcr.io/mycroblog/my:0.2.0 args: [db, upgrade] envFrom: [{ secretRef: { name: my-config } }]kubectl set env deployment/my MY_MAINTENANCE=true && kubectl rollout status deployment/my# back up, and check the SQL with a one-off Pod of the new image: my schema apply -dry-runkubectl apply -f my-upgrade-v0-2-0.yamlkubectl wait --for=condition=complete --timeout=30m job/my-upgrade-v0-2-0kubectl set image deployment/my my=ghcr.io/mycroblog/my:0.2.0kubectl set env deployment/my MY_MAINTENANCE-kubectl rollout status deployment/my若 Job 失敗,kubectl logs job/my-upgrade-v0-2-0 -c upgrade-check(或 -c schema、-c upgrade)會顯示原因,而 Deployment 會維持在舊的映像檔。若在磁碟區上使用 SQLite,請在 Job 中掛載同一個磁碟區,並先停止 Deployment 的 Pod:SQLite 只接受一個寫入者。
Cloud Run
Section titled “Cloud Run”使用 OpenTofu 模組時,升級就是套用新版本:它會在服務換用新映像檔之前,於遷移任務中執行 my upgrade,失敗時就停在那裡:請參閱在 Cloud Run 上部署。手動進行時:
Cloud Run 任務各自只執行一個容器,因此請為每個步驟建立一個任務,並以 --wait 依序執行,任務失敗時它也會失敗。請給這些任務與服務相同的環境變數與密鑰。
gcloud run services update my --region=asia-northeast1 --update-env-vars=MY_MAINTENANCE=true# back up (see below)
gcloud run jobs deploy my-upgrade-check --region=asia-northeast1 --image=ghcr.io/mycroblog/my:0.2.0 \ --args=db,upgrade,-check --set-env-vars=... --set-secrets=...gcloud run jobs deploy my-schema --region=asia-northeast1 --image=ghcr.io/mycroblog/my:0.2.0 \ --args=schema,apply --set-env-vars=... --set-secrets=...gcloud run jobs deploy my-upgrade --region=asia-northeast1 --image=ghcr.io/mycroblog/my:0.2.0 \ --args=db,upgrade --set-env-vars=... --set-secrets=...
gcloud run jobs execute my-upgrade-check --region=asia-northeast1 --wait && gcloud run jobs execute my-schema --region=asia-northeast1 --wait && gcloud run jobs execute my-upgrade --region=asia-northeast1 --wait && gcloud run deploy my --region=asia-northeast1 --image=ghcr.io/mycroblog/my:0.2.0 --remove-env-vars=MY_MAINTENANCE若要先檢查 SQL,請以 --args=schema,apply,-dry-run 部署 schema 任務並執行,閱讀它的日誌之後,再為了套用而重新部署它。
請在伺服器停止寫入之後(處於維護模式或已停止)、升級的任何步驟之前進行備份。備份與還原完整說明了每個部分;就升級而言:
-
SQLite:在沒有任何程序開啟資料庫檔案時,連同其
-wal與-shm檔案一起複製。使用 Compose 時,上面對磁碟區執行的tar也涵蓋了/data/blobs中的媒體。 -
PostgreSQL:以
pg_restore能讀取的自訂格式執行pg_dump。終端機視窗 pg_dump --format=custom --file=my-$(date +%Y%m%d%H%M).dump "postgres://my:...@db.example/my"也可以使用託管資料庫本身的備份(Cloud SQL 的隨選備份、RDS 快照);請在同一個時間點進行。
-
媒體:檔案系統 blob 儲存區是一個要與資料庫一起複製的目錄。
-
KEK 不在資料庫中。請把它保留在原處;還原的資料庫需要同一個 KEK。
沒有反向遷移。若要回到原本的狀態,請還原升級前的備份,然後啟動舊版本:
- 停止新的伺服器(或將它切換到維護模式)。
- 還原備份:使用 Compose 時,把封存檔解壓縮到清空後的磁碟區(
docker run --rm -v my_data:/data -v "$PWD":/backup busybox sh -c 'rm -rf /data/* && tar xzf /backup/<archive> -C /data');使用 PostgreSQL 時,執行pg_restore --clean --if-exists --dbname=<url> <dump>。 - 啟動舊版本的映像檔(使用 Compose 時,把
MY_VERSION改回舊版本,然後執行docker compose up -d)。
新版本在升級後寫入的所有內容都會遺失,所以請在升級後盡快回復,趁實例還沒有進行太多聯邦通訊之前。
每個版本都支援從同一個次要版本升級(例如從 v0.2.1 到 v0.2.4),以及從前一個次要版本的最新修補版本升級(從最新的 v0.1.x 到 v0.2.y)。修補版本絕不會移除欄位或資料表,因此在同一個次要版本之內,任何順序都可以。
若要跨越一個以上的次要版本,請依序經過每個次要版本的最新修補版本升級,每次都執行完整的程序。例如從 v0.1.3 到 v0.4.0:先升到最新的 v0.1.x,再到最新的 v0.2.x,再到最新的 v0.3.x,最後到 v0.4.0。my db upgrade -check 會阻止會遺失資料的跳躍,並指出必須經過的版本;在那個時間點,什麼都還沒有變更。
檢查與重建投影
Section titled “檢查與重建投影”有些資料表是投影:伺服器從其模組的事件與資源推導出它們(例如從帳號的審核處分推導出該帳號的限制)。worker 每天會檢查每個投影一次,並修正找到的任何差異。若要手動檢查或修正:
my projection list # each projection with its module and tablesmy projection verify [<name>] # derive every projection, or the one named, and print the rows that differ; changes nothingmy projection rebuild [<name>] # derive them the same way and write the difference<name>是投影或其資料表之一。verify會印出資料表中有、但來源推導不出來的列(-),以及來源推導得出、但資料表中沒有的列(+),只要有任何差異就以1結束。rebuild每個交易最多寫入 500 列,因此讀取者絕不會看到被清空的投影。請在實例較空閒時執行:在重建期間變更的列會保留新的值,之後的verify會回報任何剩下的差異。
重新建立(清除所有列)
Section titled “重新建立(清除所有列)”重新建立是指清空資料庫並再次套用結構描述。從 v0.1.0 開始,重新建立僅限開發與測試用的實例。絕對不要重新建立與其他伺服器聯邦的公開實例。
所有列都會遺失且無法復原。以金鑰加密金鑰(KEK)包裝的帳號金鑰也會遺失,因此在相同主機名稱下重新建立的帳號會得到不同的金鑰,對其他伺服器而言是不同的 Actor,它與遠端的追蹤關係也不會恢復。無法套用結構描述變更的公開實例,應改為從備份回復。
沒有任何 my 指令能清除資料庫:請用資料庫的工具移除它,然後再次套用結構描述。空的資料庫沒有記錄 host 與 account_domain,因此下次啟動時會記錄設定的值。
Docker Compose
Section titled “Docker Compose”cd deploy/dockerdocker compose stop my # stop the serverdocker run --rm -v my_data:/data busybox rm -f /data/my.db /data/my.db-wal /data/my.db-shmdocker compose up -d # the one-off services apply the schema to the empty database, then my starts- 上傳與處理過的媒體(
/data/blobs)會保留下來。若要連同資料庫一起清除,請用docker compose down -v移除具名磁碟區,然後執行docker compose up -d。不加-v時,磁碟區會被保留。 - 若要先保留一份複本,請停止伺服器,並從磁碟區複製
my.db(連同其-wal與-shm檔案)。
PostgreSQL
Section titled “PostgreSQL”刪除資料庫,再以相同的擁有者重新建立一個空的資料庫(或使用託管資料庫的主控台),然後執行 my schema apply:
# stop every server and job that uses the database firstdropdb --maintenance-db="postgres://postgres:...@db.example/postgres" mycreatedb --maintenance-db="postgres://postgres:...@db.example/postgres" --owner=my mymy schema apply供 LLM 與程式設計代理使用:llms.txt,llms-full.txt, llms-small.txt