Unidad 4.1: Integración de base de datos y caché
Introducción
La capa de base de datos de TaskBoard de la Unidad 2.5 está en funcionamiento: un clúster de PostgreSQL y un clúster de In-Memory DB en la LAN privada de bases de datos. Ahora su código de API debe utilizarlos. Debe abrir conexiones TLS que verifiquen el servidor, compartir un número limitado de conexiones de base de datos entre muchas solicitudes y mantener las lecturas frecuentes alejadas de la base de datos.
Las instancias de espera de PostgreSQL proporcionan alta disponibilidad, no capacidad de lectura, por lo que cada consulta llega al nodo primario y la caché es su capa de escalado de lecturas. En esta unidad, escribirá el código de conexión de PostgreSQL, agregará un pool de conexiones, construirá la caché en In-Memory DB y aplicará el mismo patrón a MariaDB y MongoDB. También configurará la recuperación: recuperación en un punto en el tiempo (PITR) a través de la API y volcados programados.
1. Conexión a DBaaS para 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])
El host es el nombre de DNS del clúster, el atributo dns_name de ionoscloud_pg_cluster_v2 y metadata.dnsName en la API. Tiene el aspecto de pg-abc123.postgresql.de-txl.ionos.com. El puerto 5432 es el predeterminado.
1.1 TLS Siempre Está Activado: Verificar el Servidor
Todas las conexiones del cliente se cifran con TLS. El modo SSL predeterminado es prefer, y los clientes no pueden desactivar el cifrado. El cifrado por sí solo no demuestra que usted se comunique con su clúster, por lo que su código establece sslmode=verify-full.
Para verify-ca y verify-full, el cliente necesita el certificado raíz ISRG Root X1. Los certificados del servidor son emitidos por Let's Encrypt para el nombre de DNS del clúster:
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'
Las bibliotecas de cliente deben admitir la autenticación SCRAM-SHA-256. Una versión reciente de psycopg o asyncpg la admite. El acceso a la base de datos utiliza usuarios y contraseñas de PostgreSQL.
1.2 Código asíncrono con asyncpg
La API de TaskBoard se ejecuta en uvicorn, por lo que los controladores asíncronos utilizan asyncpg con 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. Puesta en pool de conexiones dentro del límite
El valor de max_connections de PostgreSQL se calcula a partir del tamaño de la RAM de las instancias:
| Tamaño de RAM | max_connections |
|---|---|
| 4GB | 384 |
| 5GB | 512 |
| 6GB | 640 |
| 7GB | 768 |
| 8GB | 896 |
| > 8GB | 1000 |
La plataforma reserva 11 de estas conexiones para uso interno. El clúster de TaskBoard de la Unidad 2.5 tiene 4 GB por instancia, por lo que su aplicación dispone de 373 conexiones. Distribuya ese presupuesto entre todos los procesos que abren un pool: pods de API, el worker, las migraciones y sus propias sesiones de psql.
2.1 Puesta en pool a nivel de aplicación con 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,
)
Con 2 réplicas de la API, 2 trabajadores uvicorn en cada una y pool_size + max_overflow = 15, la API puede mantener 60 conexiones. Escale la fórmula con su número de réplicas antes de aumentar el tamaño del grupo de conexiones. pool_pre_ping es importante porque los nodos en espera no aceptan conexiones de lectura: solo ocurren desconexiones de nodos primarios, y después de un cambio de estado, el cliente debe reconectarse.
2.2 El agrupador de conexiones administrado
Cuando su aplicación abre muchas conexiones de corta duración, o las conexiones del cliente pueden exceder max_connections, active el agrupador de conexiones administrado (pgbouncer). Es un argumento en el clúster:
resource "ionoscloud_pg_cluster_v2" "taskboard" {
# ... arguments from Unit 2.5
connection_pooler = "TRANSACTION" # DISABLED, TRANSACTION or SESSION
}
El pooler es accesible mediante el mismo nombre de DNS. En el modo TRANSACTION, cada conexión de servidor regresa al pooler después de cada transacción, por lo que debe evitar las funciones a nivel de sesión, como las sentencias preparadas y los bloqueos consultivos. Para asyncpg detrás de un pooler de transacciones, desactive su caché de sentencias con statement_cache_size=0. Para las consultas analíticas de larga duración, use una conexión directa en su lugar.
3. Caché con DBaaS para In-Memory DB
In-Memory DB ejecuta Valkey y funciona con clientes compatibles con Redis, como redis-py. Conéctese al dns_name del clúster, que apunta a la instancia principal, mediante 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()
Todos los certificados de IONOS CLOUD DBaaS se emiten mediante Let's Encrypt. Si el almacén de confianza de su sistema está actualizado, puede omitir ssl_ca_certs. Sentinel no se admite, por lo que no utilice un cliente de Sentinel: conéctese directamente al nombre de DNS.
3.1 Cache-Aside para listas de tareas
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 lee primero la caché, carga desde PostgreSQL en caso de fallo y almacena el resultado con un TTL. Una falla de la caché degrada la operación a lecturas de base de datos en lugar de hacer que la solicitud falle.
3.2 Write-Through y sesiones
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)
Escriba primero en PostgreSQL y luego actualice o invalide la caché. Las sesiones residen únicamente en la caché con un TTL. La política de expulsión allkeys-lru de la Unidad 2.5 elimina las claves antiguas cuando la memoria está llena, por lo que un almacén de sesiones que no puede perderse requiere persistencia y su propia planificación de espacio de claves.
Obtiene todas las categorías de comandos, excepto la categoría "peligrosa"; INFO, KEYS y SORT están permitidos.
4. Clientes de MariaDB y MongoDB
4.1 DBaaS para 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,
)
Todas las conexiones de cliente se cifran con TLS, con certificados de servidor emitidos por Let's Encrypt para el nombre de DNS del clúster. El clúster se ejecuta en el puerto 3306 y no puede cambiarse. Cada usuario tiene 250 conexiones y max_connections está configurado en 500, por lo que debe asignar un usuario propio a cada servicio y mantener el tamaño de su pool por debajo 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
}
El connection_string utiliza el formato mongodb+srv, y la comunicación entre el cliente y el clúster se protege con TLS mediante Let's Encrypt. La URL +srv permite que el controlador descubra los miembros del conjunto de réplicas, por lo que no es necesario que usted liste los hosts ni el nombre del conjunto de réplicas. No existe un pooler administrado para MongoDB, por lo que maxPoolSize en cada cliente es su único medio de control. Conéctese desde una VM o un pool de nodos en la LAN del clúster.
5. Recuperación: PITR y volcados programados
Backup Service no realiza copias de seguridad de los clústeres de DBaaS administrados. Sus herramientas de recuperación son las copias de seguridad PITR integradas y los volcados lógicos que usted programa.
5.1 Recuperación en un punto en el tiempo mediante la API
PITR restaura un clúster a cualquier momento dentro de la ventana de copia de seguridad. La retención de copias de seguridad es configurable desde 1 hasta 365 días. Primero, busque una copia de seguridad activa:
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}'
Existen dos rutas de restauración. Para verificar los datos antes de reemplazar nada, cree un clúster nuevo con restoreFromBackup que contenga sourceBackupId y un recoveryTargetDatetime opcional. En Terraform, este es el bloque restore_from_backup de ionoscloud_pg_cluster_v2.
Para restaurar el clúster existente en su ubicación original, envíe el objeto completo del clúster con solo 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
La API de PostgreSQL v2 utiliza un patrón de Ensure: un PUT reemplaza la configuración y cualquier campo que omita se restablece a su valor predeterminado. Por eso, el código envía todas las propiedades. Una restauración in situ sobrescribe todos los datos actuales y no se puede deshacer. Realice consultas periódicas a metadata.state hasta que sea AVAILABLE, tal como se hizo en la Unidad 1.1.
5.2 Volcados lógicos programados
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 }]
El acceso de superusuario no está disponible en el clúster, por lo que debe volcar por base de datos con pg_dump en lugar de pg_dumpall. Utilice una imagen de cliente cuya versión principal sea al menos la misma que la de su clúster. El contenedor de carga escribe el volcado en IONOS Cloud Object Storage con una Access Key y una Secret Key, temas que se abordan en la Unidad 4.2. Para MariaDB, la herramienta equivalente es mariadb-dump.
Tarjeta rápida de referencia de la API
Endpoints clave de la API de PostgreSQL v2 para esta unidad:
| Método | Endpoint | Descripción |
|---|---|---|
GET |
/clusters/{clusterId} |
Leer metadata.dnsName, metadata.state y la configuración completa |
GET |
/backups?filter.clusterId={clusterId} |
Listar copias de seguridad con isActive y la ventana de recuperación |
POST |
/clusters |
Crear un clúster; con restoreFromBackup.sourceBackupId se restaura en un clúster nuevo |
PUT |
/clusters/{clusterId} |
Garantizar la configuración completa; con restoreFromBackup.recoveryTargetDatetime se restaura en el mismo lugar |
URL base: https://postgresql.de-txl.ionos.com/v2 (regional, por ejemplo https://postgresql.de-fra.ionos.com/v2)
Autenticación: Authorization: Bearer <token> (solo autenticación por token)
Laboratorio de código
Objetivo: Conectar la API de TaskBoard con PostgreSQL e In-Memory DB, insertar tareas, cachear lecturas y demostrar que las conexiones están verificadas mediante TLS.
Requisitos previos:
- La capa de base de datos de la Unidad 2.5, aplicada, y el servidor de API con una NIC en la LAN de la base de datos
- Python 3.12 en el servidor de API con
psycopg[binary],sqlalchemyyredis PG_PASSWORDyCACHE_PASSWORDde su almacén de secretos
Paso 1: Exportar los detalles de conexión
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
Salida esperada:
-----BEGIN CERTIFICATE-----
Paso 2: Verificar TLS hacia 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();"
Salida esperada:
t
Paso 3: Crear el esquema e insertar tareas
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")
Salida esperada:
inserted
Paso 4: Conectar con la caché
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())
Salida esperada:
True
Paso 5: Leer el caché dos veces
Agregue list_tasks() de la sección 3.1 y luego mida el tiempo de dos llamadas:
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")
Salida esperada:
0 2 miss ... ms
1 2 hit ... ms
Paso 6: Invalidar al escribir
update_task(task_id=1, board_id=1, done=True)
print(cache.exists("tasks:board:1"), list_tasks(1)[0]["done"])
Salida esperada:
0 True
Lista de verificación de validación:
- [ ]
pg_stat_sslmuestrassl = tpara la conexión de la API - [ ] La segunda llamada a
list_tasks()se sirve desde la caché - [ ] Una actualización elimina la lista en caché, y la siguiente lectura devuelve el nuevo valor
- [ ] Ninguna contraseña aparece en el código, en el estado de Terraform o en Git
Limpieza:
psql "host=$PG_HOST dbname=taskboard user=taskboard sslmode=verify-full sslrootcert=isrg-root-x1.pem" -c "drop table tasks;"
Mantenga los clústeres de las unidades 4.3 y 4.4, o elimínelos con terraform destroy -auto-approve.
Errores comunes
Errores de desarrollo a evitar con el tema de esta unidad:
-
Tráfico de lectura enviado a una "réplica"
- Problema: Configura un segundo motor para lecturas contra un nodo en espera, y este nunca se conecta, o toda la carga sigue cayendo en un solo nodo.
- Por qué ocurre: Las instancias en espera sirven para la alta disponibilidad, y no se permiten conexiones de lectura a nodos en espera. No existen réplicas de lectura.
- Solución: Utilice un motor contra el nombre de DNS y escale las lecturas con la caché (sección 3).
-
Pools que agotan max_connections
- Problema: Después de escalar el despliegue de la API, las nuevas solicitudes fallan con
FATAL: sorry, too many clients already. - Por qué ocurre: Cada pod multiplica
pool_size + max_overflow, y el total supera el límite basado en RAM menos las 11 conexiones reservadas. - Solución: Asigne un presupuesto de conexiones por proceso (sección 2.1), aumente la RAM de la instancia, o habilite el pooler administrado en modo
TRANSACTION.
- Problema: Después de escalar el despliegue de la API, las nuevas solicitudes fallan con
-
Restauración in situ rechazada
- Problema: Su restauración
PUTdevuelve400, o una posteriorPUTrestablece silenciosamente las configuraciones. - Por qué ocurre: Una restauración in situ solo acepta
recoveryTargetDatetime;sourceBackupIdes válido solo en la creación. El patrón Ensure también restablece cada campo omitido. - Solución: Envíe todas las propiedades desde una nueva
GETy solo{"recoveryTargetDatetime": ...}enrestoreFromBackup.
- Problema: Su restauración
Resumen
Ahora puede conectar TaskBoard a sus bases de datos administradas de la manera que el código de producción requiere: TLS con verificación completa de certificados, conexiones en pool que respetan el límite basado en RAM, y una caché Valkey que absorbe el tráfico de lectura. MariaDB y MongoDB utilizan los mismos componentes. Para la recuperación, restaura a través de la API de PostgreSQL v2 y programa pg_dump usted mismo.
Puntos clave:
- Conéctese con
sslmode=verify-fulle ISRG Root X1; el cifrado siempre está activado, la verificación es su responsabilidad - Los standby de PostgreSQL no aceptan conexiones de lectura, por lo que la caché es la capa de escalado de lectura
- Asigne los pools en función de
max_connectionsmenos las 11 conexiones reservadas; habilite pgbouncer para muchas conexiones cortas - Los clientes de In-Memory DB se conectan al nombre de DNS con TLS; Sentinel no está admitido
- Restaure en el lugar original solo con
PUTyrecoveryTargetDatetime; Backup Service no cubre DBaaS, por lo que programe volcados
Terminología importante:
- verify-full: El modo SSL de libpq que verifica la cadena de certificados y que el certificado coincide con el nombre del host
- Presupuesto de conexiones: La parte de
max_connectionsque un proceso puede mantener a través de su pool - Cache-aside: Lea de la caché, cargue de la base de datos si no hay coincidencia, y luego almacene con un TTL
- Write-through: Actualice la base de datos, y luego escriba o invalide las entradas de caché correspondientes en la misma ruta de código
- Restauración en el lugar original: Un PITR que sobrescribe los datos del clúster existente con su estado en
recoveryTargetDatetime
Próximos pasos
Siga aprendiendo: Unidad 4.2: Integración de Object Storage
Temas relacionados: