Patrón Multi-Tenant Data Isolation
Aísla los datos de cada tenant en infraestructura compartida con row-level security, schema-per-tenant o database-per-tenant. Un patrón para aplicaciones SaaS.
Visión General
El patrón Multi-Tenant Data Isolation garantiza que cada tenant de una aplicación SaaS solo pueda acceder a sus propios datos. Existen tres estrategias principales: database-per-tenant (el aislamiento más fuerte), schema-per-tenant (buen aislamiento dentro de una base de datos compartida) y row-level security (schema compartido, con columna de tenant + RLS). Cada estrategia equilibra cuánto aísla frente a lo que cuesta mantenerla.
Los ejemplos de abajo son deliberadamente mínimos — para una implementación ejecutable con resolución de tenant, caché y onboarding, consulta la receta de multi-tenancy.
Cuándo Usar
Usa el patrón Multi-Tenant Data Isolation cuando:
- Estás construyendo una aplicación SaaS que sirve a múltiples organizaciones
- Los tenants nunca deben ver los datos de otros tenants
- Necesitas equilibrar aislamiento, costo y complejidad operativa
- Requisitos de cumplimiento (GDPR, HIPAA, SOC2) exigen aislamiento de datos
- Necesitas backup, migración o borrado por tenant
No lo uses cuando solo filtras registros por usuario — una clave foránea user_id con las comprobaciones de autorización habituales es más simple y cumple el mismo objetivo. La infraestructura de aislamiento justifica su complejidad solo cuando el límite lo marcan organizaciones enteras, no individuos.
Solución
Estrategia 1: Row-Level Security (Schema Compartido)
from sqlalchemy import create_engine, Column, String, Integer, text
from sqlalchemy.orm import declarative_base, Session
from contextlib import contextmanager
Base = declarative_base()
class Document(Base):
__tablename__ = "documents"
id = Column(Integer, primary_key=True)
tenant_id = Column(Integer, nullable=False, index=True)
title = Column(String, nullable=False)
content = Column(String)
engine = create_engine("postgresql://user:pass@localhost/saas_db")
# Activa RLS a nivel de base de datos. FORCE hace que la política también
# aplique al propietario de la tabla — sin él, el rol de la app puede
# saltarse RLS por completo.
with engine.connect() as conn:
conn.execute(text("ALTER TABLE documents ENABLE ROW LEVEL SECURITY"))
conn.execute(text("ALTER TABLE documents FORCE ROW LEVEL SECURITY"))
conn.execute(text("""
CREATE POLICY tenant_isolation ON documents
USING (tenant_id = current_setting('app.tenant_id', true)::int)
"""))
conn.commit()
@contextmanager
def tenant_session(tenant_id: int):
session = Session(engine)
try:
# Limita el GUC del tenant a esta transacción. Un SET a secas
# persistiría en la conexión del pool y se filtraría al
# siguiente request.
session.execute(
text("SELECT set_config('app.tenant_id', :tid, true)"),
{"tid": str(tenant_id)},
)
yield session
session.commit()
except Exception:
session.rollback()
raise
finally:
session.close()
# Uso — el tenant 1 solo puede ver sus documentos
with tenant_session(tenant_id=1) as session:
docs = session.query(Document).all() # RLS filtra automáticamente
print(f"Tenant 1 has {len(docs)} documents")
# El tenant 2 obtiene un conjunto distinto
with tenant_session(tenant_id=2) as session:
docs = session.query(Document).all()
print(f"Tenant 2 has {len(docs)} documents")
Estrategia 2: Schema-Per-Tenant
import re
from sqlalchemy import create_engine, Column, String, Integer, text
from sqlalchemy.orm import declarative_base, sessionmaker
Base = declarative_base()
class Document(Base):
__tablename__ = "documents"
id = Column(Integer, primary_key=True)
title = Column(String, nullable=False)
content = Column(String)
engine = create_engine("postgresql://user:pass@localhost/saas_db")
def tenant_schema(tenant_name: str) -> str:
# Los nombres de tenant vienen del usuario — nunca los interpolamos
# en crudo dentro de un DDL.
slug = re.sub(r"[^a-z0-9_]", "_", tenant_name.lower())
return f"tenant_{slug}"
def provision_tenant(tenant_name: str):
schema = tenant_schema(tenant_name)
# create_all debe correr en la misma conexión donde se fijó el
# search_path — con `engine` crearía las tablas en `public`.
with engine.connect() as conn:
conn.execute(text(f"CREATE SCHEMA IF NOT EXISTS {schema}"))
conn.execute(text(f"SET search_path TO {schema}"))
Base.metadata.create_all(conn)
conn.commit()
def get_tenant_engine(tenant_name: str):
schema = tenant_schema(tenant_name)
return create_engine(
"postgresql://user:pass@localhost/saas_db",
connect_args={"options": f"-csearch_path={schema}"},
)
# Uso — cada tenant obtiene un schema aislado
provision_tenant("acme")
provision_tenant("globex")
acme_engine = get_tenant_engine("acme")
AcmeSession = sessionmaker(bind=acme_engine)
session = AcmeSession()
docs = session.query(Document).all()
Estrategia 3: Database-Per-Tenant
const { Pool } = require("pg");
const tenantPools = new Map();
function getTenantPool(tenantId) {
if (!tenantPools.has(tenantId)) {
const pool = new Pool({
host: "localhost",
port: 5432,
user: "saas_app",
password: process.env.DB_PASSWORD,
database: `tenant_${tenantId}`,
max: 10,
});
tenantPools.set(tenantId, pool);
}
return tenantPools.get(tenantId);
}
async function getDocuments(tenantId) {
const pool = getTenantPool(tenantId);
const result = await pool.query(
"SELECT id, title, content FROM documents ORDER BY id"
);
return result.rows;
}
async function createDocument(tenantId, title, content) {
const pool = getTenantPool(tenantId);
const result = await pool.query(
"INSERT INTO documents (title, content) VALUES ($1, $2) RETURNING id",
[title, content]
);
return result.rows[0];
}
// Uso — en un servicio real, cierra los pools al apagar y expulsa
// los de tenants eliminados o migrados a otra instancia.
async function main() {
const acmeDocs = await getDocuments("acme");
console.log("Acme docs:", acmeDocs.length);
const doc = await createDocument("globex", "Q3 Report", "Confidential");
console.log("Created doc:", doc.id);
}
main().catch(console.error);
Middleware de Resolución de Tenant (Java)
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
@Component
public class TenantInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response, Object handler) {
String tenantId = request.getHeader("X-Tenant-ID");
if (tenantId == null || tenantId.isBlank()) {
response.setStatus(401);
return false;
}
TenantContext.setTenantId(tenantId);
return true;
}
@Override
public void afterCompletion(HttpServletRequest request,
HttpServletResponse response, Object handler, Exception ex) {
TenantContext.clear();
}
}
// Contexto de tenant con ThreadLocal — en un proyecto real va en su
// propio archivo.
public class TenantContext {
private static final ThreadLocal<String> CONTEXT = new ThreadLocal<>();
public static void setTenantId(String tenantId) {
CONTEXT.set(tenantId);
}
public static String getTenantId() {
return CONTEXT.get();
}
public static void clear() {
CONTEXT.remove();
}
}
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Repository;
import java.util.List;
import java.util.Map;
@Repository
public class DocumentRepository {
private final JdbcTemplate jdbc;
public DocumentRepository(JdbcTemplate jdbc) {
this.jdbc = jdbc;
}
public List<Map<String, Object>> findAll() {
String tenant = TenantContext.getTenantId();
// El header es entrada controlada por el atacante. Concatenarlo
// en crudo aquí es SQL injection — valida el nombre del schema
// antes de interpolarlo.
if (!tenant.matches("[a-z0-9_]{1,32}")) {
throw new IllegalArgumentException("Invalid tenant id");
}
return jdbc.queryForList(
"SELECT id, title, content FROM tenant_" + tenant + ".documents"
);
}
}
Explicación
Las tres opciones equilibran aislamiento frente a costo:
- Row-Level Security (RLS): Todos los tenants comparten un schema. Una columna
tenant_iden cada tabla. Las políticas RLS de PostgreSQL filtran las consultas automáticamente. Es la opción más barata y escalable, pero el aislamiento más débil — un bug en la política filtra datos. Dos trampas: sinFORCE ROW LEVEL SECURITYel propietario de la tabla se salta las políticas por completo, ycurrent_settinglanza un error si el GUC no está definido — pásalemissing_oky gestiona el null en el código. - Schema-Per-Tenant: Cada tenant tiene su propio schema dentro de una base de datos compartida. Buen aislamiento a nivel de schema. Necesitarás migraciones por tenant. Costo moderado.
- Database-Per-Tenant: Cada tenant vive en su propia base de datos. El aislamiento más fuerte, y el backup, la migración y el borrado por tenant se vuelven triviales. Lo pagas en costo y en trabajo operativo.
Conceptos clave:
- Contexto de tenant: Una variable thread-local o con alcance de request que guarda el tenant ID actual. La fija el middleware desde un JWT, una API key o un header — siempre después de validar que el usuario pertenece a ese tenant.
- Contexto con alcance de transacción: El mecanismo que transporta el tenant hasta la base de datos (un
SETdel GUC, unsearch_path, la elección de pool) debe limitarse a un request o transacción. Los ajustes a nivel de sesión en conexiones compartidas son la forma clásica de que los tenants se filtren datos entre sí. - Consultas cross-tenant: Operaciones de administración que abarcan varios tenants. Deben saltarse RLS o consultar todos los schemas/bases de datos de forma explícita, y pertenecen en rutas de código auditadas.
- Migraciones por tenant: Schema-per-tenant y database-per-tenant requieren ejecutar migraciones para cada tenant. Automatízalo con un migration runner y registra las versiones por tenant.
Variantes
| Estrategia | Aislamiento | Costo | Migración | Backup | Usar Cuando |
|---|---|---|---|---|---|
| Row-Level Security | Débil (bug en política = fuga) | Bajo | Única | Compartido | Muchos tenants pequeños, sensible al costo |
| Schema-Per-Tenant | Medio (límite de schema) | Medio | Por tenant | Por schema | Tenants medianos, aislamiento moderado |
| Database-Per-Tenant | Fuerte (límite de DB completo) | Alto | Por tenant | Por DB | Tenants grandes, cumplimiento, enterprise |
Lo que Funciona
- Usa RLS para eficiencia de costo — miles de tenants en una base de datos, sobrecarga mínima
- Usa schema-per-tenant para SaaS medianos — buen equilibrio entre aislamiento y costo
- Usa database-per-tenant para enterprise — el aislamiento más fuerte, SLA por tenant
- Fija siempre el contexto de tenant en el middleware — nunca dependas de que el código de aplicación filtre
- Valida la membresía del tenant — comprueba que el usuario pertenece al tenant en cada petición
- Indexa la columna tenant_id — RLS filtra por tenant_id en cada consulta
- Automatiza las migraciones por tenant — escribe un migration runner que itere sobre todos los tenants
- Ofrece APIs de aprovisionamiento y borrado — automatiza el onboarding y el offboarding
- Monitoriza las consultas cross-tenant — las consultas de admin que se saltan el aislamiento deben auditarse
Errores Comunes
- Olvidar fijar el contexto de tenant en un job en segundo plano — el job corre sin aislamiento
- Depender del filtrado a nivel de aplicación en lugar de RLS — un
WHERE tenant_id = ?omitido filtra datos - Fijar el contexto de tenant con un
SETa nivel de sesión — el valor sobrevive en la conexión del pool y se filtra al siguiente request - No indexar tenant_id — cada consulta hace un escaneo completo de la tabla filtrado por RLS
- Correr una sola migración en lugar de migraciones por tenant — algunos tenants quedan con schemas desfasados
- No probar el aislamiento — escribe tests de integración que verifiquen que el tenant A no puede leer los datos del tenant B
- Compartir pools de conexiones entre tenants en database-per-tenant — las conexiones se fugan a la DB equivocada
- Interpolar nombres o IDs de tenant en el SQL — los headers son entrada del atacante; valida con una lista blanca primero
- No limpiar los datos del tenant en el offboarding — los datos de tenants eliminados persisten en tablas compartidas
- Usar tenant_id en las URLs sin validación — el spoofing del ID permite acceso cross-tenant
Ver También
- Receta de arquitectura multi-tenancy — implementaciones ejecutables de las tres estrategias
- Patrón sharding — particionado horizontal cuando los tenants superan un solo nodo
- PostgreSQL Row-Level Security — documentación oficial sobre políticas,
FORCEycurrent_setting - Ejemplos ejecutables del companion — código de aislamiento multi-tenant en
resources/patterns/architecture/
Preguntas frecuentes
¿Qué estrategia debo elegir?
Empieza con row-level security si tienes muchos tenants pequeños y el costo te preocupa. Usa schema-per-tenant para SaaS medianos con necesidades de aislamiento moderadas. Usa database-per-tenant para clientes enterprise con requisitos de cumplimiento estrictos o SLAs por tenant.
¿Cómo gestiono las migraciones por tenant?
Con un pequeño runner que recorra todos los tenants — un schema por pasada en schema-per-tenant, una conexión por base de datos en database-per-tenant. Registra la versión aplicada por tenant para que un fallo a mitad de camino no te deje a ciegas.
¿Puedo mezclar estrategias?
Claro — y muchos sistemas en producción lo hacen. Mantén a los tenants pequeños con RLS en una base de datos compartida y promociona los grandes a una base propia a medida que crezcan. Enruta cada petición según la configuración del tenant. Es el enfoque híbrido o por niveles.
¿Por qué mi política RLS deja que el rol de la app vea todas las filas?
Porque los propietarios de tabla se saltan row-level security por defecto. Ejecuta ALTER TABLE … FORCE ROW LEVEL SECURITY, o asegúrate de que el rol de base de datos de la aplicación no sea propietario de las tablas que consulta.
¿Cómo pruebo que el aislamiento funciona de verdad?
Escribe un test de integración que inserte una fila como tenant A, consulte como tenant B y verifique que no devuelve nada. Repítelo para una ruta de administración con privilegios y para un request sin contexto de tenant — ahí es donde el aislamiento suele fallar.
Recursos Relacionados
Arquitectura Multi-Tenancy
Sirve a muchos tenants desde un solo despliegue con el nivel de aislamiento correcto: tablas compartidas con row-level security, schema por tenant o base de datos por tenant.
PatternPatron de Sharding
Divide un dataset grande en particiones mas pequenas distribuidas entre multiples servidores para mejorar crecimiento, rendimiento y disponibilidad.
PatternPatrón Federated Identity
Delega la autenticación a proveedores de identidad externos. Un patrón para integrar OAuth2, OIDC, SAML y SSO entre múltiples servicios y organizaciones.
RecipeConfigurar connection pooling para bases de datos y HTTP
Configura connection pooling para PostgreSQL, MySQL, Redis y clientes HTTP en Python, JavaScript y Java. Reduce latencia y evita agotamiento de conexiones.
RecipeCredenciales en Vivo de Base de Datos con HashiCorp Vault
Como usar HashiCorp Vault para generar credenciales de base de datos de corta duracion, eliminando passwords hardcodeados y reduciendo secret sprawl
RecipeImplementar Rate Limiting de APIs con Redis
Protege APIs del abuso con limitadores token bucket y ventana deslizante respaldados por Redis, con ráfagas controladas y coordinación distribuida