Einheit 4.1: Integration von Datenbanken und Caching
Einführung
Die Datenbank-Ebene von TaskBoard aus Einheit 2.5 läuft: ein PostgreSQL-Cluster und ein In-Memory DB-Cluster im privaten DB-LAN. Jetzt muss Ihr API-Code diese nutzen. Er muss TLS-Verbindungen öffnen, die den Server verifizieren, eine begrenzte Anzahl von Datenbankverbindungen über viele Anfragen hinweg teilen und häufig gelesene Daten von der Datenbank fernhalten.
PostgreSQL-Standby-Instanzen bieten Hochverfügbarkeit, nicht Lese-Kapazität, daher trifft jede Abfrage die Primärinstanz und der Cache ist Ihre Skalierungsebene für Lesezugriffe. In dieser Einheit schreiben Sie den PostgreSQL-Verbindungscode, fügen Pooling hinzu, bauen den Cache auf In-Memory DB auf und wenden dasselbe Muster auf MariaDB und MongoDB an. Sie richten auch die Wiederherstellung ein: point-in-time recovery (PITR) über die API und geplante Dumps.
1. Verbindung mit DBaaS für PostgreSQL
import os
import psycopg
conn = psycopg.connect(
host=os.environ["PG_HOST"], # terraform output pg_host (the cluster dns_name)
port=5432,
dbname="taskboard",
user="taskboard",
password=os.environ["PG_PASSWORD"], # from your secret store, never from Terraform state
sslmode="verify-full",
sslrootcert="/etc/taskboard/isrg-root-x1.pem",
)
with conn.cursor() as cur:
cur.execute("select version()")
print(cur.fetchone()[0])
Der Host ist der DNS-Name des Clusters, das Attribut dns_name von ionoscloud_pg_cluster_v2 und metadata.dnsName in der API. Er sieht wie pg-abc123.postgresql.de-txl.ionos.com aus. Port 5432 ist der Standardwert.
1.1 TLS ist immer aktiv: Server verifizieren
Alle Client-Verbindungen werden mit TLS verschlüsselt. Der Standard-SSL-Modus ist prefer, und Clients können die Verschlüsselung nicht deaktivieren. Die Verschlüsselung allein beweist nicht, dass Sie mit Ihrem Cluster kommunizieren, daher setzt Ihr Code sslmode=verify-full.
Für verify-ca und verify-full benötigt der Client das Stammzertifikat ISRG Root X1. Die Serverzertifikate werden von Let's Encrypt für den DNS-Namen des Clusters ausgestellt:
curl -s https://crt.sh/?q=9314791 > /etc/taskboard/isrg-root-x1.pem
export PGSSLROOTCERT=/etc/taskboard/isrg-root-x1.pem
export PGSSLMODE=verify-full
psql -h "$PG_HOST" -U taskboard taskboard -c 'select 1'
Client-Bibliotheken müssen die SCRAM-SHA-256-Authentifizierung unterstützen. Ein aktuelles psycopg oder asyncpg tut dies. Der Datenbankzugriff verwendet PostgreSQL-Benutzer und Passwörter.
1.2 Async-Code mit asyncpg
Die API von TaskBoard läuft auf uvicorn, daher verwenden asynchrone Handler asyncpg mit einem ssl.SSLContext:
import ssl, asyncpg
ctx = ssl.create_default_context(cafile="/etc/taskboard/isrg-root-x1.pem")
ctx.check_hostname = True
pool = await asyncpg.create_pool(
host=os.environ["PG_HOST"], port=5432,
database="taskboard", user="taskboard",
password=os.environ["PG_PASSWORD"],
ssl=ctx, min_size=2, max_size=10,
)
row = await pool.fetchrow("select count(*) from tasks where done = false")
2. Verbindungspooling innerhalb des Limits
Der Wert von max_connections für PostgreSQL wird aus dem RAM-Größe der Instanzen berechnet:
| RAM-Größe | max_connections |
|---|---|
| 4GB | 384 |
| 5GB | 512 |
| 6GB | 640 |
| 7GB | 768 |
| 8GB | 896 |
| > 8GB | 1000 |
Die Plattform reserviert 11 dieser Verbindungen für den internen Gebrauch. Der Cluster von TaskBoard aus Einheit 2.5 hat 4 GB pro Instanz, daher stehen Ihrer Anwendung 373 Verbindungen zur Verfügung. Verteilen Sie dieses Kontingent auf alle Prozesse, die einen Pool öffnen: API-Pods, der Worker, Migrationen und Ihre eigenen psql-Sitzungen.
2.1 Anwendungsebene: Pooling mit SQLAlchemy
from sqlalchemy import create_engine
engine = create_engine(
f"postgresql+psycopg://taskboard:{os.environ['PG_PASSWORD']}@{os.environ['PG_HOST']}:5432/taskboard",
connect_args={"sslmode": "verify-full", "sslrootcert": "/etc/taskboard/isrg-root-x1.pem"},
pool_size=10, # steady connections per process
max_overflow=5, # short bursts
pool_pre_ping=True, # drop dead connections after a failover
pool_recycle=1800,
)
Mit 2 API-Replikaten, jeweils 2 uvicorn-Workern und pool_size + max_overflow = 15 kann die API 60 Verbindungen halten. Skalieren Sie die Formel anhand Ihrer Replikatanzahl, bevor Sie die Poolgröße erhöhen. pool_pre_ping ist relevant, da Standby-Knoten keine Leseverbindungen akzeptieren: Es treten nur Trennungen der primären Verbindung auf, und nach einem Failover muss der Client neu verbinden.
2.2 Der verwaltete Pooler
Wenn Ihre Anwendung viele kurzlebige Verbindungen öffnet oder die Client-Verbindungen max_connections überschreiten können, aktivieren Sie den verwalteten Verbindungspooler (pgbouncer). Er ist ein Argument auf dem Cluster:
resource "ionoscloud_pg_cluster_v2" "taskboard" {
# ... arguments from Unit 2.5
connection_pooler = "TRANSACTION" # DISABLED, TRANSACTION or SESSION
}
Der Pooler ist über denselben DNS-Namen erreichbar. Im TRANSACTION-Modus wird jede Serververbindung nach jeder Transaktion wieder an den Pool zurückgegeben. Vermeiden Sie daher Sitzungsebenen-Funktionen wie vorbereitete Anweisungen und Advisory Locks. Für asyncpg hinter einem Transaktionspooler deaktivieren Sie den Statement-Cache mit statement_cache_size=0. Für langlaufende analytische Abfragen verwenden Sie stattdessen eine direkte Verbindung.
3. Caching mit DBaaS für In-Memory DB
In-Memory DB verwendet Valkey und funktioniert mit Redis-kompatiblen Clients wie redis-py. Verbinden Sie sich mit TLS mit dem dns_name des Clusters, der auf die primäre Instanz zeigt:
import redis
cache = redis.Redis(
host=os.environ["CACHE_HOST"],
username="taskboard",
password=os.environ["CACHE_PASSWORD"], # the plain password behind the SHA-256 hash
ssl=True,
ssl_ca_certs="/etc/taskboard/isrg-root-x1.pem",
decode_responses=True,
socket_timeout=0.5,
)
cache.ping()
Alle IONOS CLOUD DBaaS-Zertifikate werden von Let's Encrypt ausgestellt. Wenn Ihr Systemvertrauensspeicher aktuell ist, können Sie ssl_ca_certs weglassen. Sentinel wird nicht unterstützt, daher keinen Sentinel-Client verwenden: Verwenden Sie eine direkte Verbindung zum DNS-Namen.
3.1 Cache-Aside für Aufgabenlisten
import json
from sqlalchemy import text
def list_tasks(board_id: int) -> list[dict]:
key = f"tasks:board:{board_id}"
try:
hit = cache.get(key)
if hit is not None:
return json.loads(hit)
except redis.RedisError:
pass # cache down: fall through to the database
with engine.connect() as c:
rows = c.execute(text("select id, title, done from tasks where board_id = :b"),
{"b": board_id}).mappings().all()
tasks = [dict(r) for r in rows]
try:
cache.set(key, json.dumps(tasks), ex=60)
except redis.RedisError:
pass
return tasks
Cache-aside liest zuerst aus dem Cache, lädt bei einem Cache-Miss aus PostgreSQL und speichert das Ergebnis mit einer TTL. Ein Cache-Ausfall führt zu Datenbank-Lesevorgängen, anstatt dass die Anfrage fehlschlägt.
3.2 Write-Through und Sitzungen
def update_task(task_id: int, board_id: int, done: bool) -> None:
with engine.begin() as c:
c.execute(text("update tasks set done = :d where id = :i"), {"d": done, "i": task_id})
cache.delete(f"tasks:board:{board_id}") # invalidate the list
cache.hset(f"task:{task_id}", mapping={"done": int(done)}) # write-through the item
def save_session(sid: str, user_id: int) -> None:
cache.set(f"session:{sid}", user_id, ex=3600)
Schreiben Sie zuerst in PostgreSQL und aktualisieren oder ungültig machen Sie anschließend den Cache. Sitzungen existieren nur im Cache mit einer TTL. Die allkeys-lru-Ausräumungsstrategie aus Einheit 2.5 entfernt alte Schlüssel, wenn der Arbeitsspeicher voll ist. Daher benötigt ein Sitzungsspeicher, der nicht verloren gehen darf, Persistenz und eine eigene Planung des Schlüsselraums.
Sie erhalten alle Befehlskategorien, mit Ausnahme der Kategorie „gefährlich“; INFO, KEYS und SORT sind zulässig.
4. MariaDB- und MongoDB-Clients
4.1 DBaaS für MariaDB
import mysql.connector
db = mysql.connector.connect(
host=os.environ["MARIADB_HOST"], # ionoscloud_mariadb_cluster_v2 dns_name
port=3306,
user="app", password=os.environ["MARIADB_PASSWORD"], database="app",
ssl_ca="/etc/taskboard/isrg-root-x1.pem",
ssl_verify_identity=True,
)
Alle Client-Verbindungen werden mit TLS verschlüsselt, wobei Serverzertifikate von Let's Encrypt für den DNS-Namen des Clusters ausgestellt werden. Der Cluster läuft auf Port 3306, und dieser kann nicht geändert werden. Jeder Benutzer hat 250 Verbindungen und max_connections ist auf 500 festgelegt. Vergeben Sie daher für jeden Dienst einen eigenen Benutzer und halten Sie die Größe seines Verbindungspools deutlich unter 250.
4.2 MongoDB
from pymongo import MongoClient
client = MongoClient(
os.environ["MONGO_URL"], # connection_string output, mongodb+srv://m-....mongodb.de-txl.ionos.com
username="app", password=os.environ["MONGO_PASSWORD"],
authSource="app",
maxPoolSize=20,
)
client.admin.command("ping")
output "mongo_url" {
value = ionoscloud_mongo_cluster.reports.connection_string
}
Das connection_string verwendet das mongodb+srv-Format, und die Kommunikation zwischen Client und Cluster wird mit TLS über Let's Encrypt gesichert. Die +srv-URL ermöglicht es dem Treiber, die Mitglieder der Replikatsammlung zu erkennen, sodass Sie keine Hosts oder einen Namen der Replikatsammlung selbst angeben müssen. Es gibt keinen verwalteten Pooler für MongoDB, daher ist maxPoolSize in jedem Client Ihre einzige Steuerungsmöglichkeit. Stellen Sie die Verbindung von einer VM oder einem Knotenpool im LAN des Clusters her.
5. Wiederherstellung: PITR und geplante Dumps
Backup Service sichert verwaltete DBaaS-Cluster nicht. Ihre Wiederherstellungswerkzeuge sind die integrierten PITR-Sicherungen und logische Dumps, die Sie selbst planen.
5.1 Wiederherstellung zu einem bestimmten Zeitpunkt über die API
PITR stellt einen Cluster auf einen beliebigen Zeitpunkt innerhalb des Sicherungsfensters wieder her. Die Aufbewahrungsdauer der Sicherungen ist von 1 bis 365 Tage konfigurierbar. Finden Sie zunächst eine aktive Sicherung:
API=https://postgresql.de-txl.ionos.com/v2
curl -s -H "Authorization: Bearer $IONOS_TOKEN" \
"$API/backups?filter.clusterId=$CLUSTER_ID" \
| jq '.items[] | {id, active: .properties.isActive,
from: .properties.earliestRecoveryTargetTime, to: .properties.latestRecoveryTargetTime}'
Es gibt zwei Wiederherstellungspfade. Um Daten zu überprüfen, bevor etwas ersetzt wird, erstellen Sie einen neuen Cluster mit restoreFromBackup, der sourceBackupId und einen optionalen recoveryTargetDatetime enthält. In Terraform ist dies der restore_from_backup-Block von ionoscloud_pg_cluster_v2.
Um den vorhandenen Cluster an Ort und Stelle wiederherzustellen, senden Sie das vollständige Clusterobjekt mit nur recoveryTargetDatetime:
import requests
def restore_in_place(cluster_id: str, target_iso: str) -> None:
url = f"{API}/clusters/{cluster_id}"
h = {"Authorization": f"Bearer {os.environ['IONOS_TOKEN']}"}
props = requests.get(url, headers=h, timeout=30).json()["properties"]
props["restoreFromBackup"] = {"recoveryTargetDatetime": target_iso} # no sourceBackupId here
r = requests.put(url, headers=h, json={"properties": props}, timeout=30)
r.raise_for_status() # 200, cluster goes UPDATING, then AVAILABLE
Die PostgreSQL v2 API verwendet ein Ensure-Muster: Ein PUT ersetzt die Konfiguration, und jedes Feld, das Sie weglassen, wird auf seinen Standardwert zurückgesetzt. Aus diesem Grund sendet der Code die vollständigen Eigenschaften. Ein In-Place-Restore überschreibt alle aktuellen Daten und kann nicht rückgängig gemacht werden. Führen Sie ein Abfrageverfahren (Polling) für metadata.state durch, bis dieser Wert AVAILABLE ist, wie in Einheit 1.1 beschrieben.
5.2 Geplante logische Dumps
apiVersion: batch/v1
kind: CronJob
metadata: { name: taskboard-pg-dump }
spec:
schedule: "15 2 * * *"
jobTemplate:
spec:
template:
spec:
restartPolicy: OnFailure
volumes: [{ name: dump, emptyDir: {} }]
initContainers:
- name: pg-dump
image: postgres:17
envFrom: [{ secretRef: { name: taskboard-db } }] # DATABASE_URL from Unit 3.2
command: ["sh", "-c", "pg_dump -F c -f /dump/tb.dump \"$DATABASE_URL\""]
volumeMounts: [{ name: dump, mountPath: /dump }]
containers:
- name: upload
image: amazon/aws-cli
envFrom: [{ secretRef: { name: taskboard-s3 } }] # AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
command: ["sh", "-c", "aws s3 cp /dump/tb.dump s3://taskboard-backups-7f3a/pg/$(date +%F).dump --endpoint-url https://s3.eu-central-3.ionoscloud.com"]
volumeMounts: [{ name: dump, mountPath: /dump }]
Superuser-Zugriff ist auf dem Cluster nicht verfügbar, daher wird stattdessen pro Datenbank mit pg_dump statt mit pg_dumpall ein Dump erstellt. Verwenden Sie ein Client-Image, dessen Hauptversion mindestens der Version Ihres Clusters entspricht. Der Upload-Container schreibt das Dump mit einem Access Key und Secret Key in IONOS Cloud Object Storage, was in Einheit 4.2 behandelt wird. Für MariaDB ist das entsprechende Tool mariadb-dump.
Schnellkarte zur API-Referenz
Wichtige PostgreSQL v2 API-Endpunkte für diese Einheit:
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET |
/clusters/{clusterId} |
metadata.dnsName, metadata.state und die vollständige Konfiguration lesen |
GET |
/backups?filter.clusterId={clusterId} |
Sicherungen mit isActive und dem Wiederherstellungsfenster auflisten |
POST |
/clusters |
Cluster erstellen; mit restoreFromBackup.sourceBackupId wird in ein neues Cluster wiederhergestellt |
PUT |
/clusters/{clusterId} |
Die vollständige Konfiguration sicherstellen; mit restoreFromBackup.recoveryTargetDatetime wird an Ort und Stelle wiederhergestellt |
Basis-URL: https://postgresql.de-txl.ionos.com/v2 (regional, beispielsweise https://postgresql.de-fra.ionos.com/v2)
Authentifizierung: Authorization: Bearer <token> (nur Token-Authentifizierung)
Code Lab
Ziel: Verbinde die TaskBoard API mit PostgreSQL und In-Memory DB, füge Aufgaben ein, cache Lesevorgänge und beweise, dass die Verbindungen TLS-verifiziert sind.
Voraussetzungen:
- Die Datenbank-Ebene aus Einheit 2.5, angewendet, und der API-Server mit einer NIC im DB-LAN
- Python 3.12 auf dem API-Server mit
psycopg[binary],sqlalchemyundredis PG_PASSWORDundCACHE_PASSWORDaus deinem Secret Store
Schritt 1: Exportiere die Verbindungsdaten
export PG_HOST=$(terraform output -raw pg_host)
export CACHE_HOST=$(terraform output -raw cache_host)
curl -s https://crt.sh/?q=9314791 > isrg-root-x1.pem && head -1 isrg-root-x1.pem
Erwartete Ausgabe:
-----BEGIN CERTIFICATE-----
Schritt 2: TLS zu PostgreSQL überprüfen
psql "host=$PG_HOST dbname=taskboard user=taskboard sslmode=verify-full sslrootcert=isrg-root-x1.pem" \
-tc "select ssl from pg_stat_ssl where pid = pg_backend_pid();"
Erwartete Ausgabe:
t
Schritt 3: Schema erstellen und Aufgaben einfügen
import os
from sqlalchemy import create_engine, text
PG_HOST, PG_PASSWORD = os.environ["PG_HOST"], os.environ["PG_PASSWORD"]
engine = create_engine(f"postgresql+psycopg://taskboard:{PG_PASSWORD}@{PG_HOST}:5432/taskboard",
connect_args={"sslmode": "verify-full", "sslrootcert": "isrg-root-x1.pem"}, pool_pre_ping=True)
with engine.begin() as c:
c.execute(text("create table if not exists tasks (id serial primary key, board_id int, title text, done bool default false)"))
c.execute(text("insert into tasks (board_id, title) values (1, 'Write unit tests'), (1, 'Ship v1')"))
print("inserted")
Erwartete Ausgabe:
inserted
Schritt 4: Verbindung mit dem Cache herstellen
import redis
CACHE_HOST, CACHE_PASSWORD = os.environ["CACHE_HOST"], os.environ["CACHE_PASSWORD"]
cache = redis.Redis(host=CACHE_HOST, username="taskboard", password=CACHE_PASSWORD,
ssl=True, ssl_ca_certs="isrg-root-x1.pem", decode_responses=True)
print(cache.ping())
Erwartete Ausgabe:
True
Schritt 5: Cache zweimal durchlesen
Fügen Sie list_tasks() aus Abschnitt 3.1 hinzu und messen Sie die Zeit für zwei Aufrufe:
import time
for i in range(2):
cached = cache.exists("tasks:board:1")
t = time.perf_counter(); n = len(list_tasks(1))
print(i, n, "hit" if cached else "miss", f"{(time.perf_counter()-t)*1000:.1f} ms")
Erwartete Ausgabe:
0 2 miss ... ms
1 2 hit ... ms
Schritt 6: Bei Schreibvorgängen ungültig machen
update_task(task_id=1, board_id=1, done=True)
print(cache.exists("tasks:board:1"), list_tasks(1)[0]["done"])
Erwartete Ausgabe:
0 True
Prüfliste:
- [ ]
pg_stat_sslzeigtssl = tfür die Verbindung der API - [ ] Der zweite
list_tasks()-Aufruf wird aus dem Cache bedient - [ ] Eine Aktualisierung entfernt die zwischengespeicherte Liste, und der nächste Lesevorgang gibt den neuen Wert zurück
- [ ] Kein Passwort erscheint im Code, im Terraform-Zustand oder in Git
Aufräumarbeiten:
psql "host=$PG_HOST dbname=taskboard user=taskboard sslmode=verify-full sslrootcert=isrg-root-x1.pem" -c "drop table tasks;"
Behalten Sie die Cluster für die Einheiten 4.3 und 4.4 bei oder entfernen Sie sie mit terraform destroy -auto-approve.
Häufige Fehler
Fehler von Entwicklerinnen und Entwicklern, die bei diesem Thema der Einheit zu vermeiden sind:
-
Leseverkehr, der an eine „Replikate" gesendet wird
- Problem: Sie konfigurieren eine zweite Engine für Lesezugriffe auf einen Standby, und diese verbindet sich nie, oder die gesamte Last landet weiterhin auf einem einzigen Knoten.
- Ursache: Standby-Instanzen dienen der Hochverfügbarkeit, und Leseverbindungen zu Standby-Knoten sind nicht zulässig. Es gibt keine Lese-Repliken.
- Lösung: Verwenden Sie eine Engine gegen den DNS-Namen und skalieren Sie Lesezugriffe über den Cache (Abschnitt 3).
-
Pools, die max_connections erschöpfen
- Problem: Nach dem Skalieren des API-Deployment schlagen neue Anfragen mit
FATAL: sorry, too many clients alreadyfehl. - Ursache: Jeder Pod multipliziert
pool_size + max_overflow, und die Gesamtzahl überschreitet das RAM-basierte Limit abzüglich der 11 reservierten Verbindungen. - Lösung: Verbindungen pro Prozess planen (Abschnitt 2.1), den RAM der Instanz erhöhen oder den verwalteten Pooler im
TRANSACTION-Modus aktivieren.
- Problem: Nach dem Skalieren des API-Deployment schlagen neue Anfragen mit
-
In-Place-Wiederherstellung wird abgelehnt
- Problem: Ihre Wiederherstellung
PUTgibt400zurück, oder ein späteresPUTsetzt Einstellungen stillschweigend zurück. - Ursache: Eine In-Place-Wiederherstellung akzeptiert nur
recoveryTargetDatetime;sourceBackupIdist nur bei der Erstellung gültig. Das Ensure-Muster setzt außerdem jedes weggelassene Feld zurück. - Lösung: Senden Sie die vollständigen Eigenschaften aus einer neuen
GETund nur{"recoveryTargetDatetime": ...}inrestoreFromBackup.
- Problem: Ihre Wiederherstellung
Zusammenfassung
Sie können TaskBoard nun so mit seinen verwalteten Datenbanken verbinden, wie es der Produktionscode erfordert: TLS mit vollständiger Zertifikatsprüfung, Verbindungspools, die das auf dem RAM basierende Limit einhalten, und einen Valkey-Cache, der den Leseverkehr auffängt. MariaDB und MongoDB verwenden dieselben Bausteine. Für die Wiederherstellung stellen Sie über die PostgreSQL v2 API wieder her und planen pg_dump selbst ein.
Wichtige Punkte:
- Verbinden Sie sich mit
sslmode=verify-fullund ISRG Root X1; die Verschlüsselung ist immer aktiviert, die Prüfung liegt in Ihrer Verantwortung - PostgreSQL-Standbys akzeptieren keine Leseverbindungen, daher ist der Cache die Skalierungsebene für Lesezugriffe
- Planen Sie Pools anhand von
max_connectionsabzüglich der 11 reservierten Verbindungen; aktivieren Sie pgbouncer für viele kurze Verbindungen - In-Memory DB-Clients verbinden sich mit dem DNS-Namen über TLS; Sentinel wird nicht unterstützt
- Wiederherstellung an Ort und Stelle nur mit
PUTundrecoveryTargetDatetime; Backup Service deckt DBaaS nicht ab, daher Dumps einplanen
Wichtige Begriffe:
- verify-full: Der libpq-SSL-Modus, der die Zertifikatskette prüft und dass das Zertifikat mit dem Hostnamen übereinstimmt
- Verbindungsbudget: Der Anteil von
max_connections, den ein Prozess über seinen Pool halten darf - Cache-aside: Aus dem Cache lesen, bei einem Miss aus der Datenbank laden und anschließend mit einer TTL speichern
- Write-through: Die Datenbank aktualisieren und anschließend die passenden Cache-Einträge im selben Codepfad schreiben oder ungültig machen
- Wiederherstellung an Ort und Stelle: Ein PITR, der die Daten des vorhandenen Clusters mit seinem Zustand bei
recoveryTargetDatetimeüberschreibt
Nächste Schritte
Weiterlernen: Einheit 4.2: Object Storage Integration
Verwandte Themen: