A fondo
SaaS multiinquilino: grupos, roles y comprobación de permisos en Postgres
Publicado el · 7 min de lectura· Anton Shubin
También disponible en: العربية, Deutsch, English, Français, 日本語, Português (Brasil), Русский y 简体中文

En resumen
- En Seed el inquilino es un grupo. Cada fila lleva un group_id, y el acceso de una persona es una fila en group_members con un rol del 1 al 4.
- Quién puede hacer qué es un conjunto de funciones puras pequeñas. Cada handler lee el rol y llama a una; el WebSocket y HTTP comparten los mismos handlers.
- Cada escritura vuelve a leer el rol dentro de su transacción, con un bloqueo, así que alguien a quien acaban de quitar no puede colar una última escritura.
- No hay row-level security. Un desconocido recibe 404, nunca 403, y hay tests que comprueban que un grupo nunca ve los datos de otro.
¿Cómo se construye un SaaS multiinquilino (multi-tenant) sobre Postgres para que un equipo nunca vea
los datos de otro? En Seed, el inquilino es un grupo. Cada fila que pertenece a un inquilino
lleva un group_id, el acceso de una persona es una fila en group_members con un rol, y cada
petición comprueba ese rol en el código antes de leer o escribir. Las escrituras lo comprueban dos
veces: en el handler y otra vez dentro de su propia transacción, con un bloqueo. Una base de datos
compartida, un esquema, sin row-level security.
Este artículo es para quien construye un producto para equipos y quiere ver una respuesta completa que funciona, no un diagrama. Todo está en el código de Seed, con licencia MIT, y los fragmentos son las líneas reales, algo recortadas.
¿Qué es un inquilino en Seed?
Un grupo. No hay un tipo «personal» aparte: al registrarte se crea un grupo normal llamado «Personal», contigo como único miembro. Así, un usuario solo y un equipo de 50 pasan por el mismo código, y no hay que migrar nada cuando alguien invita a un compañero. Una persona puede estar en todos los grupos que quiera.
La pertenencia es una tabla (la migración):
CREATE TABLE group_members (
group_id UUID NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
user_id INT4 NOT NULL REFERENCES users(id) ON DELETE CASCADE,
role INT2 NOT NULL,
...
PRIMARY KEY (group_id, user_id),
CONSTRAINT group_members_role_check CHECK (role BETWEEN 1 AND 4)
);
Postgres guarda dos reglas por sí mismo: un rol va del 1 al 4, y un índice único parcial permite
exactamente un propietario por grupo. Una transferencia de propiedad degrada al antiguo propietario
antes de ascender al nuevo, en una transacción, porque ese índice no admite dos propietarios ni por
un instante. Cada fila de una funcionalidad (una nota, una etiqueta, un archivo) tiene su propia
columna group_id.
¿Qué roles hay y qué puede hacer cada uno?
Cuatro, fijos y ordenados: viewer (1), editor (2), admin (3), owner (4). Al estar ordenados, casi
todas las reglas son una comparación: «editor o superior» es role >= 2.
| Qué | Viewer | Editor | Admin | Owner |
|---|---|---|---|---|
| Leer las notas del grupo | sí | sí | sí | sí |
| Crear, editar y borrar notas | no | sí | sí | sí |
| Invitar como viewer o editor | no | no | sí | sí |
| Renombrar el grupo, ver el correo de miembros | no | no | sí | sí |
| Hacer admin a alguien | no | no | no | sí |
| Pagar, borrar el grupo, transferir la propiedad | no | no | no | sí |
Un admin gestiona viewers y editores, nunca a otro admin, y nadie salvo el propietario toca al propietario. En el plan Free, una invitación solo añade viewers: dar otros roles es lo que vende el plan de pago. Más abajo explico cómo se mantienen separados plan y rol.
¿Dónde vive la comprobación de permisos?
En funciones puras pequeñas de la librería de dominio, una por pregunta
(libs/domain/groups). La más
difícil, quién puede cambiar el rol de quién, es la más larga:
export function canManageMember(actor: GroupRole, target: GroupRole, next?: GroupRole): boolean {
if (!isGroupRole(actor) || !isGroupRole(target) || (next !== undefined && !isGroupRole(next))) {
return false
}
if (actor === GroupRole.OWNER) return true
if (actor !== GroupRole.ADMIN || target > GroupRole.EDITOR) return false
return next === undefined || next <= GroupRole.EDITOR
}
Sin base de datos, sin petición, sin framework: un test unitario la llama con todas las combinaciones de roles. Un handler lee el rol de quien actúa y lo pasa a la comprobación que toca antes de llamar al repositorio:
assertCanWriteNotes(await groups.roleOf(data.groupId, data.actor.userId))
Los transportes no tienen ninguna regla. Una llamada llega por WebSocket o como
POST /api/call/<name>, las dos llegan al mismo handler y reciben la misma respuesta. Eso permite
que el tiempo real recurra a HTTP sin un segundo
juego de comprobaciones que mantener al día.
¿Por qué comprobar el rol dos veces?
Porque un rol leído antes de escribir puede estar caducado cuando la escritura se confirma. Imagínalo: el propietario quita a un editor en el mismo instante en que el editor guarda una nota. El handler leyó «editor» hace un milisegundo, la eliminación se confirma y la nota acaba en un grupo al que su autor ya no pertenece.
Por eso cada escritura en un grupo llama primero a lockActorRole, dentro de su propia transacción
(group-change-log.ts):
const active = await sql`
SELECT 1 FROM groups WHERE id = ${groupId} AND deleted_at IS NULL FOR NO KEY UPDATE
`
if (active.length === 0) throw new GroupNotActiveError(groupId)
const member = (await sql`
SELECT group_members.role
FROM group_members
INNER JOIN users ON users.id = group_members.user_id AND users.deleted_at IS NULL
WHERE group_members.group_id = ${groupId} AND group_members.user_id = ${actorId}
FOR SHARE OF group_members
`)[0]
return member?.role ?? null
La fila del grupo se bloquea primero, en el mismo orden que usa cualquier cambio de miembros, así
que las dos operaciones se esperan en vez de bloquearse mutuamente. La fila de pertenencia se lee
FOR SHARE: una eliminación confirmada antes se ve, y una posterior espera a que termine la
escritura. Luego el repositorio comprueba el rol recibido, así que la segunda comprobación cuesta una
lectura por índice en una transacción que ya estaba abierta.
Un test lo demuestra para cada tipo de escritura de notas: mantiene abierta una eliminación o una
degradación, lanza la escritura, ve que espera, confirma el cambio y espera que la escritura se
rechace sin guardar nada («note update: refused when a removal commits while the write waits», en
tests/integration/group-write-race.integration.test.ts).
¿Por qué un desconocido recibe 404 y no 403?
Porque un 403 dice «este grupo existe, pero no es para ti». Quien no es miembro recibe
GROUP_NOT_FOUND, exactamente lo mismo que un grupo que nunca existió, así que nadie puede probar
ids para saber cuáles son reales. Un miembro sin el rol necesario recibe 403 ROLE_INSUFFICIENT,
porque ya sabe que el grupo existe.
El plan sigue la misma idea. Cuando un grupo llega al límite de su plan, la respuesta es 402 Payment Required, no 403, para que la app distinga «pide al propietario que mejore el plan» de «no tienes el rol». El rol decide quién puede actuar; el plan, cuánto recibe el grupo. La facturación por asientos y sus webhooks tienen su propio artículo.
¿Por qué no row-level security de Postgres?
La consideré y dejé escrito el compromiso en el diseño de sincronización de grupos. La row-level security pondría una segunda copia de las reglas de permisos en la base de datos, en políticas SQL, junto a la copia que los handlers necesitan igualmente para responder «eres viewer» con un error útil. Dos copias de una regla acaban divergiendo. Además, cada conexión tendría que llevar a la persona actual, lo que complica el pool de conexiones, las tareas en segundo plano y las migraciones.
El coste honesto: con filtros en el código, una consulta que olvide group_id puede filtrar datos.
Seed responde de tres formas:
- Firmas con el grupo. Un método del repositorio recibe el id del grupo como argumento, como
get(groupId, id), y su consulta filtra por los dos. No existe un «obtener nota por id» que usar mal. - Una lista de reglas para cada funcionalidad. docs/aggregates.md recoge
lo que copia una funcionalidad nueva: vive en un grupo, cada fila tiene
group_idy cada escritura vuelve a leer el rol. - Tests entre grupos. Los tests de integración corren contra un Postgres real con un desconocido en su propio grupo, en pasos como «never counts a note of another group» y «a person who is not a member is told the group does not exist».
Si tu producto necesita una garantía a nivel de base de datos, por ejemplo para una auditoría de cumplimiento, la row-level security es una buena opción y puedes añadirla encima. Para una plantilla de inicio, elegí un solo lugar para las reglas.
¿Qué no hace Seed?
- No hay roles personalizados. Cuatro roles fijos. Un producto que necesite «gestor de facturación» añade un rol y sus comprobaciones.
- No hay permisos por registro. Un rol vale para todo el grupo; no puedes compartir una nota con una sola persona.
- No hay row-level security, como ya expliqué.
- No hay un esquema ni una base de datos por inquilino. Todos los grupos comparten las tablas.
Pruébalo
Abre la demo, crea un grupo, invita a una segunda cuenta como viewer e intenta editar una nota desde ella. La versión corta está en la página de grupos, y tu primera funcionalidad muestra cómo un tipo de registro nuevo hereda todo esto copiando el código de las notas. Si tu app comprueba el rol una sola vez, antes de la transacción, esa es la carrera que yo cerraría primero.


