15 min de lecture

Objectifs d'apprentissage

À la fin de ce module, vous serez en mesure de:

  • Connecter le code applicatif à DBaaS pour PostgreSQL via TLS avec vérification des certificats, en utilisant psycopg et asyncpg
  • Configurer le multiplexage de connexions au niveau applicatif qui reste dans la limite de connexions PostgreSQL, et décider quand activer le multiplexeur géré
  • Mettre en œuvre la mise en cache cache-aside et write-through avec redis-py pour DBaaS pour In-Memory DB
  • Se connecter à DBaaS pour MariaDB et MongoDB avec TLS, en utilisant les détails de connexion issus des sorties Terraform
  • Déclencher une restauration à un instant donné pour PostgreSQL via l'API et planifier des déchargements logiques depuis le code

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], sqlalchemy et redis
  • PG_PASSWORD et CACHE_PASSWORD depuis 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_ssl affiche ssl = t pour 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é :

  1. 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).
  2. 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.
  3. Restauration sur place rejetée

    • Problème : Votre restauration PUT renvoie 400, ou un PUT ultérieur réinitialise silencieusement les paramètres.
    • Cause : Une restauration sur place n'accepte que recoveryTargetDatetime ; sourceBackupId n'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 GET nouveau, et uniquement {"recoveryTargetDatetime": ...} dans restoreFromBackup.

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-full et 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_connections moins 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 PUT et recoveryTargetDatetime ; 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_connections qu'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 :