Unité 4.1 : Intégration de la base de données et de la mise en cache
Introduction
La couche de base de données de TaskBoard de l'Unité 2.5 est opérationnelle : un cluster PostgreSQL et un cluster In-Memory DB sont déployés sur le LAN de base de données privé. Votre code API doit désormais les utiliser. Il doit ouvrir des connexions TLS qui vérifient le serveur, partager un nombre limité de connexions de base de données entre de nombreuses requêtes, et éviter que les lectures fréquentes n'interrogent directement la base de données.
Les instances PostgreSQL en mode standby assurent la haute disponibilité, mais ne fournissent pas de capacité de lecture supplémentaire. Par conséquent, chaque requête est dirigée vers l'instance principale, et le cache constitue votre couche de mise à l'échelle pour les lectures. Dans cette unité, vous rédigez le code de connexion PostgreSQL, ajoutez le pool de connexions, construisez le cache sur In-Memory DB, et appliquez le même schéma à MariaDB et MongoDB. Vous configurez également la récupération : la récupération à un instant donné (PITR) via l'API et les sauvegardes planifiées.
1. Connexion à DBaaS pour 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])
L'hôte est le nom DNS du cluster, l'attribut dns_name de ionoscloud_pg_cluster_v2 et metadata.dnsName dans l'API. Il ressemble à pg-abc123.postgresql.de-txl.ionos.com. Le port 5432 est le port par défaut.
1.1 TLS est toujours activé : vérifier le serveur
Toutes les connexions client sont chiffrées avec TLS. Le mode SSL par défaut est prefer, et les clients ne peuvent pas désactiver le chiffrement. Le chiffrement seul ne prouve pas que vous communiquez avec votre cluster, donc votre code définit sslmode=verify-full.
Pour verify-ca et verify-full, le client a besoin du certificat racine ISRG Root X1. Les certificats serveur sont émis par Let's Encrypt pour le nom DNS du cluster :
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'
Les bibliothèques clientes doivent prendre en charge l'authentification SCRAM-SHA-256. Une version récente de psycopg ou d'asyncpg le permet. L'accès à la base de données utilise les utilisateurs et mots de passe de PostgreSQL.
1.2 Code asynchrone avec asyncpg
L'API de TaskBoard fonctionne sur uvicorn, les gestionnaires asynchrones utilisent donc asyncpg avec un 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. Mutualisation des connexions dans la limite autorisée
La valeur max_connections de PostgreSQL est calculée à partir de la taille de la RAM des instances :
| Taille de RAM | max_connections |
|---|---|
| 4 Go | 384 |
| 5 Go | 512 |
| 6 Go | 640 |
| 7 Go | 768 |
| 8 Go | 896 |
| > 8 Go | 1000 |
La plateforme réserve 11 de ces connexions pour un usage interne. Le cluster de TaskBoard de l'Unité 2.5 dispose de 4 Go par instance, votre application dispose donc de 373 connexions. Répartissez ce budget entre tous les processus qui ouvrent une pool : pods API, le worker, les migrations et vos propres sessions psql.
2.1 Mutualisation au niveau de l'application avec 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,
)
Avec 2 répliques API, 2 workers uvicorn chacune et pool_size + max_overflow = 15, l'API peut maintenir 60 connexions. Ajustez la formule en fonction du nombre de répliques avant d'augmenter la taille du pool. pool_pre_ping est important car les nœuds en mode standby n'acceptent aucune connexion de lecture : seules les déconnexions des nœuds primaires se produisent, et après une bascule, le client doit se reconnecter.
2.2 Le pooler de connexions géré
Lorsque votre application ouvre de nombreuses connexions de courte durée, ou que les connexions clients peuvent dépasser max_connections, activez le pooler de connexions géré (pgbouncer). Il s'agit d'un argument sur le cluster :
resource "ionoscloud_pg_cluster_v2" "taskboard" {
# ... arguments from Unit 2.5
connection_pooler = "TRANSACTION" # DISABLED, TRANSACTION or SESSION
}
Le pooler est accessible sur le même nom DNS. En mode TRANSACTION, chaque connexion serveur retourne dans le pool après chaque transaction ; évitez donc les fonctionnalités de niveau session, telles que les instructions préparées et les verrous consultatifs. Pour asyncpg derrière un pooler de transactions, désactivez son cache d'instructions avec statement_cache_size=0. Pour les requêtes analytiques de longue durée, utilisez plutôt une connexion directe.
3. Mise en cache avec DBaaS pour In-Memory DB
In-Memory DB exécute Valkey et fonctionne avec des clients compatibles Redis, tels que redis-py. Connectez-vous à l'adresse dns_name du cluster, qui pointe vers l'instance principale, en utilisant TLS :
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()
Tous les certificats IONOS CLOUD DBaaS sont émis par Let's Encrypt. Si votre magasin de confiance système est à jour, vous pouvez omettre ssl_ca_certs. Sentinel n'est pas pris en charge ; n'utilisez donc pas un client Sentinel : connectez-vous directement au nom DNS.
3.1 Cache-Aside pour les listes de tâches
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
La lecture en mode Cache-aside interroge d'abord le cache, charge les données depuis PostgreSQL en cas de manqué et stocke le résultat avec une durée de vie (TTL). En cas de défaillance du cache, le système bascule sur des lectures de base de données au lieu d'échouer la requête.
3.2 Write-Through et sessions
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)
Écrivez d'abord dans PostgreSQL, puis mettez à jour ou invalidez le cache. Les sessions ne résident que dans le cache avec une durée de vie (TTL). La politique d'éviction allkeys-lru de l'unité 2.5 supprime les anciennes clés lorsque la mémoire est pleine, de sorte qu'un magasin de sessions que vous ne pouvez pas perdre nécessite une persistance et sa propre planification d'espace de clés.
Vous obtenez toutes les catégories de commandes, à l'exception de la catégorie « dangereuse » ; INFO, KEYS et SORT sont autorisés.
4. Clients MariaDB et MongoDB
4.1 DBaaS pour 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,
)
Toutes les connexions client sont chiffrées avec TLS, les certificats serveur étant émis par Let's Encrypt pour le nom DNS du cluster. Le cluster fonctionne sur le port 3306, et vous ne pouvez pas le modifier. Chaque utilisateur dispose de 250 connexions et max_connections est défini sur 500 ; attribuez donc un utilisateur distinct à chaque service et maintenez la taille de son pool de connexions bien en dessous de 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
}
Le connection_string utilise le format mongodb+srv, et la communication entre les clients et le cluster est sécurisée par TLS au moyen de Let's Encrypt. L'URL +srv permet au pilote de découvrir les membres du jeu de répliques, vous n'avez donc pas à lister vous-même les hôtes ou le nom du jeu de répliques. Il n'existe pas de pooler géré pour MongoDB, de sorte que maxPoolSize dans chaque client est votre seul moyen de contrôle. Établissez la connexion depuis une VM ou un pool de nœuds du LAN du cluster.
5. Restauration : PITR et sauvegardes planifiées
Backup Service ne sauvegarde pas les clusters DBaaS gérés. Vos outils de restauration sont les sauvegardes PITR intégrées et les dumps logiques que vous planifiez vous-même.
5.1 Restauration à un instant donné via l'API
PITR restaure un cluster à n'importe quel moment au sein de la fenêtre de sauvegarde. La rétention des sauvegardes est configurable de 1 à 365 jours. Trouvez d'abord une sauvegarde active :
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}'
Deux chemins de restauration existent. Pour vérifier les données avant de remplacer quoi que ce soit, créez un nouveau cluster avec restoreFromBackup contenant sourceBackupId et un recoveryTargetDatetime facultatif. Dans Terraform, il s'agit du bloc restore_from_backup de ionoscloud_pg_cluster_v2.
Pour restaurer le cluster existant sur place, envoyez l'objet cluster complet avec uniquement 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
L'API PostgreSQL v2 utilise un modèle Ensure : un PUT remplace la configuration, et tout champ omis est réinitialisé à sa valeur par défaut. C'est pourquoi le code transmet l'ensemble des propriétés. Une restauration sur place écrase toutes les données actuelles et ne peut pas être annulée. Interrogez metadata.state jusqu'à ce qu'il soit AVAILABLE, comme dans l'unité 1.1.
5.2 Sauvegardes logiques planifiées
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 }]
L'accès en tant que superutilisateur n'est pas disponible sur le cluster. Effectuez donc une sauvegarde par base de données avec pg_dump au lieu de pg_dumpall. Utilisez une image de client dont la version majeure est au moins égale à celle de votre cluster. Le conteneur de téléversement écrit la sauvegarde dans IONOS Cloud Object Storage à l'aide d'une Access Key et d'une Secret Key, ce qui est abordé dans l'Unité 4.2. Pour MariaDB, l'outil équivalent est mariadb-dump.
Fiche de référence rapide de l'API
Points de terminaison clés de l'API PostgreSQL v2 pour cette unité :
| Méthode | Point de terminaison | Description |
|---|---|---|
GET |
/clusters/{clusterId} |
Lire metadata.dnsName, metadata.state et la configuration complète |
GET |
/backups?filter.clusterId={clusterId} |
Lister les sauvegardes avec isActive et la fenêtre de récupération |
POST |
/clusters |
Créer un cluster ; avec restoreFromBackup.sourceBackupId, il restaure dans un nouveau cluster |
PUT |
/clusters/{clusterId} |
Garantir la configuration complète ; avec restoreFromBackup.recoveryTargetDatetime, il restaure sur place |
URL de base : https://postgresql.de-txl.ionos.com/v2 (régional, par exemple https://postgresql.de-fra.ionos.com/v2)
Authentification : Authorization: Bearer <token> (authentification par jeton uniquement)
Atelier de code
Objectif : Connecter l'API TaskBoard à PostgreSQL et à In-Memory DB, insérer des tâches, mettre en cache les lectures et prouver que les connexions sont vérifiées par TLS.
Prérequis :
- La couche base de données de l'Unité 2.5, appliquée, et le serveur API avec une carte réseau dans le LAN de la base de données
- Python 3.12 sur le serveur API avec
psycopg[binary],sqlalchemyetredis PG_PASSWORDetCACHE_PASSWORDdepuis votre coffre de secrets
Étape 1 : Exporter les détails de connexion
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
Sortie attendue :
-----BEGIN CERTIFICATE-----
Étape 2 : Vérifier TLS vers PostgreSQL
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();"
Sortie attendue :
t
Étape 3 : Créer le schéma et insérer les tâches
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")
Sortie attendue :
inserted
Étape 4 : Connexion au cache
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())
Sortie attendue :
True
Étape 5 : Lire le cache deux fois
Ajoutez list_tasks() de la section 3.1, puis mesurez la durée de deux appels :
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")
Sortie attendue :
0 2 miss ... ms
1 2 hit ... ms
Étape 6 : Invalidation lors de l'écriture
update_task(task_id=1, board_id=1, done=True)
print(cache.exists("tasks:board:1"), list_tasks(1)[0]["done"])
Sortie attendue :
0 True
Liste de contrôle de validation :
- [ ]
pg_stat_sslaffichessl = tpour la connexion de l'API - [ ] Le second appel
list_tasks()est servi depuis le cache - [ ] Une mise à jour supprime la liste mise en cache, et la lecture suivante renvoie la nouvelle valeur
- [ ] Aucun mot de passe n'apparaît dans le code, l'état Terraform ou Git
Nettoyage :
psql "host=$PG_HOST dbname=taskboard user=taskboard sslmode=verify-full sslrootcert=isrg-root-x1.pem" -c "drop table tasks;"
Conservez les clusters pour les Unités 4.3 et 4.4, ou supprimez-les avec terraform destroy -auto-approve.
Erreurs courantes
Erreurs de développement à éviter concernant le sujet de cette unité :
-
Trafic de lecture envoyé à une « réplique »
- Problème : Vous configurez un second moteur pour les lectures vers un nœud en attente, et il ne se connecte jamais, ou toute la charge se concentre toujours sur un seul nœud.
- Cause : Les instances en attente servent à la haute disponibilité, et les connexions de lecture vers les nœuds en attente ne sont pas autorisées. Il n'existe pas de répliques de lecture.
- Correction : Utilisez un seul moteur vers le nom DNS et mettez à l'échelle les lectures avec le cache (section 3).
-
Pools qui épuisent max_connections
- Problème : Après la mise à l'échelle du déploiement API, les nouvelles requêtes échouent avec
FATAL: sorry, too many clients already. - Cause : Chaque pod multiplie
pool_size + max_overflow, et le total dépasse la limite basée sur la RAM, moins les 11 connexions réservées. - Correction : Prévoyez le nombre de connexions par processus (section 2.1), augmentez la RAM de l'instance, ou activez le pooler géré en mode
TRANSACTION.
- Problème : Après la mise à l'échelle du déploiement API, les nouvelles requêtes échouent avec
-
Restauration sur place rejetée
- Problème : Votre restauration
PUTrenvoie400, ou unPUTultérieur réinitialise silencieusement les paramètres. - Cause : Une restauration sur place n'accepte que
recoveryTargetDatetime;sourceBackupIdn'est valide qu'à la création. Le motif Ensure réinitialise également tout champ omis. - Correction : Envoyez l'ensemble des propriétés à partir d'un
GETnouveau, et uniquement{"recoveryTargetDatetime": ...}dansrestoreFromBackup.
- Problème : Votre restauration
Résumé
Vous pouvez désormais connecter TaskBoard à ses bases de données gérées de la manière dont le code de production l'exige : TLS avec vérification complète des certificats, connexions mutualisées qui respectent la limite basée sur la RAM, et un cache Valkey qui absorbe le trafic de lecture. MariaDB et MongoDB utilisent les mêmes composants. Pour la récupération, vous restaurez via l'API PostgreSQL v2 et planifiez pg_dump vous-même.
Points clés :
- Connectez-vous avec
sslmode=verify-fullet ISRG Root X1 ; le chiffrement est toujours activé, la vérification est votre responsabilité - Les serveurs PostgreSQL en mode standby n'acceptent aucune connexion de lecture, le cache constitue donc la couche de mise à l'échelle de la lecture
- Dimensionnez les pools en fonction de
max_connectionsmoins les 11 connexions réservées ; activez pgbouncer pour de nombreuses connexions de courte durée - Les clients In-Memory DB se connectent au nom DNS avec TLS ; Sentinel n'est pas pris en charge
- Restaurez sur place uniquement avec
PUTetrecoveryTargetDatetime; Backup Service ne couvre pas DBaaS, planifiez donc des sauvegardes
Terminologie importante :
- verify-full : Le mode SSL de libpq qui vérifie la chaîne de certificats et que le certificat correspond au nom d'hôte
- Budget de connexions : La part de
max_connectionsqu'un processus peut détenir via son pool - Cache-aside : Lire depuis le cache, charger depuis la base de données en cas de non-correspondance, puis stocker avec une durée de vie (TTL)
- Write-through : Mettre à jour la base de données, puis écrire ou invalider les entrées de cache correspondantes dans le même chemin de code
- Restauration sur place : Une PITR qui écrase les données du cluster existant avec son état à
recoveryTargetDatetime
Prochaines étapes
Continuer l'apprentissage : Unité 4.2 : Intégration Object Storage
Sujets connexes :