Cómo evitar las dobles reservas: que la base de datos tenga la última palabra

Por qué comprobar antes no basta

La versión obvia lee las reservas, decide que el hueco está libre e inserta la nueva. Cada paso es correcto. El problema es el hueco entre ellos: dos peticiones pueden leer antes de que ninguna escriba, y las dos ven el hueco libre.

Hacer la comprobación más rápida, añadir una caché o pasarla al navegador solo estrecha la ventana. Con carga, o con un cliente que reintenta, una ventana pequeña se sigue abriendo. La solución es dejar de pedirle a la aplicación que garantice algo que no puede ver: lo que se está escribiendo en ese mismo instante.

La regla, escrita en la base de datos

PostgreSQL puede imponer por sí solo que «no haya dos reservas confirmadas que se solapen» con una restricción de exclusión. Una restricción única dice que no puede haber dos filas iguales; una de exclusión lo generaliza a cualquier operador, aquí && (se solapan) entre dos rangos de tiempo. Esta es la tabla, sacada de nuestra migración:

create extension if not exists btree_gist;

create table bookings (
  id uuid primary key default gen_random_uuid(),
  starts_at timestamptz not null,
  ends_at timestamptz not null,
  status text not null default 'confirmed'
    check (status in ('confirmed', 'cancelled')),
  -- ...
  constraint bookings_ends_after_start check (ends_at > starts_at),
  constraint bookings_no_overlap
    exclude using gist (tstzrange(starts_at, ends_at) with &&)
    where (status = 'confirmed')
);

• tstzrange(starts_at, ends_at) es la reserva como un rango de instantes. Sus límites por defecto son [), cerrado al empezar y abierto al acabar, así que una reserva de 10:00 a 10:30 y la siguiente de 10:30 a 11:00 no se solapan y caben las dos.
• with && significa que dos filas chocan cuando sus rangos se solapan. PostgreSQL lo comprueba con un índice GiST que crea para la restricción, así que sigue siendo rápido aunque la tabla crezca.
• where (status = 'confirmed') limita la regla a las reservas vivas: cancelar una libera su hueco sin borrar la fila, y el historial se conserva.
• btree_gist es la extensión que deja a GiST indexar valores normales junto a los rangos. Con un solo calendario no hace falta de verdad; con varios recursos sí (más abajo).

Repite ahora las dos peticiones. Las dos leen el hueco libre, las dos insertan, y PostgreSQL acepta la primera y rechaza la segunda con el error 23P01, exclusion_violation. La carrera sigue existiendo; simplemente ahora tiene árbitro.

el código de PostgreSQL cuando una fila incumple la restricción de exclusión

23P01

lo que responde entonces nuestra API: el hueco está ocupado

409

rangos semiabiertos, para que una reserva empiece cuando acaba otra

[ )

De un error de la base de datos a una respuesta clara

Una violación de la restricción solo sirve si la aplicación la convierte en algo que una persona entienda. Nuestra API (Rust, con sqlx) traduce ese código concreto a un conflicto y deja pasar cualquier otro error de la base de datos como lo que es:

const EXCLUSION_VIOLATION: &str = "23P01";

fn slot_taken_on_overlap(error: sqlx::Error) -> ApiError {
    let overlapped = error
        .as_database_error()
        .and_then(|database| database.code())
        .is_some_and(|code| code == EXCLUSION_VIOLATION);

    if overlapped {
        return ApiError::slot_taken(); // 409 SLOT_TAKEN
    }
    error.into()
}

La web decide por el estado, nunca por el mensaje: ante un 409, la página de reservas avisa de que ese hueco se acaba de ocupar y recarga los libres, así que quien reserva elige otro sin empezar de cero. Mover una reserva a otra hora pasa por las mismas comprobaciones y es una actualización bajo la misma restricción, así que tampoco puede caer encima de otra.

Lo que la aplicación sigue comprobando antes

La restricción tiene la última palabra, no la única. Antes de insertar, la API calcula si la hora pedida se puede reservar, y esas reglas viven en la aplicación porque cambian con los ajustes y con el mundo de fuera:

• El horario de cada día de la semana, una antelación mínima, cuántos días por delante se puede reservar, un máximo por día y los días bloqueados, todo ajustes del panel y no código.
• Un margen alrededor de cada reserva (15 minutos por defecto), para que nunca haya dos llamadas seguidas.
• Lo que el Google Calendar del equipo dice que está ocupado. Si no se puede leer, la API lo deja anotado y ofrece huecos solo con las reservas, en vez de cerrar la página.
• No más de cinco reservas por hora desde el mismo cliente, que responde 429 y evita que un script llene el calendario.

Lo que la restricción no cubre

Ser preciso con los límites también es diseño. Nuestra restricción protege las reservas, no el margen: el margen lo comprueba la aplicación. Dos peticiones que compiten por huecos vecinos podrían, en teoría, confirmarse más cerca de lo que pide el margen. Nunca se solaparían, que es el fallo que importa, y aceptamos ese compromiso a propósito, porque el margen es un ajuste y una restricción lo congelaría en el esquema.

Si el margen tuviera que ser absoluto, el rango de la restricción puede llevarlo: tstzrange(starts_at - interval '15 minutes', ends_at + interval '15 minutes'). El precio es una migración cada vez que cambie. Lo mismo vale para el máximo diario: es una política, que se aplica en el código, no una invariante de los datos.

Retener un hueco mientras alguien paga es otro problema

Una llamada queda confirmada en cuanto se guarda. Un alquiler no: entre elegir las fechas y que el pago se complete puede pasar un minuto o dos, y en ese tiempo nadie más debería poder quedarse el hueco. En Boathous, el marketplace de alquiler de barcos que construimos, el hueco se retiene cinco minutos mientras el cliente paga, la comprobación y la retención ocurren en un solo paso atómico, y la confirmación del pago comprueba que la retención es de quien paga.

Se guarde donde se guarde la retención, importan tres cosas: comprobar y retener en una sola operación atómica, una caducidad para que un pago abandonado libere el hueco y una última comprobación al confirmar. Una variante apoyada en la base de datos es guardar la retención como una reserva con su propio estado y su caducidad, bajo la misma restricción de exclusión, para que el árbitro sea el mismo en los dos casos.

Varios barcos, salas o personas

Casi todos los sistemas reales reservan más de una cosa. La restricción dice entonces que dos reservas chocan solo si son del mismo recurso y sus horas se solapan, y esa igualdad sobre una columna normal es justo lo que btree_gist hace indexable junto al rango:

exclude using gist (
  boat_id with =,
  tstzrange(starts_at, ends_at) with &&
) where (status = 'confirmed')

Si un sistema de reservas es el corazón de lo que estás construyendo, esta es la clase de decisión que tomamos con el equipo en las primeras semanas de un proyecto de software a medida: escribir qué reglas no se pueden romper nunca y poner cada una donde nadie se la pueda saltar.