Transacciones
Un bloque atomic ejecuta un grupo de sentencias como una sola unidad: o se
confirman todas, o ninguna. Funciona en PostgreSQL, MySQL (y MariaDB) y SQLite.
Donde los backends difieren, esta página lo dice.
Para un handle de transacción simple (transaction_pool) y bloqueos de fila,
consulta la guía del ORM.
¿Algún término aquí es nuevo para ti? Transacción, rollback — consulta el glosario.
Tabla de contenidos
- Un primer bloque
- Qué se ejecuta en el bloque
- Bloques anidados
- Después del commit
- Cuando una sentencia falla
- SQLite toma el bloqueo de escritura en el BEGIN
- Niveles de aislamiento y ajustes
- ¿Este código está en un bloque?
- Get or create en una transacción
- Las formas
_on - DDL en un bloque
- Iterar en un bloque
- Cancelación
- Errores
Un primer bloque
Los ejemplos usan este modelo y un pool: &Pool:
use rustango::sql::Auto;
use rustango::Model;
#[derive(Model, Debug, Clone)]
#[rustango(table = "accounts")]
pub struct Account {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(unique, max_length = 64)]
pub email: String,
pub balance: i64,
}
rustango::sql::atomic(&pool, closure) abre una transacción, ejecuta la
closure y confirma cuando devuelve Ok. Un Err lo revierte todo.
use rustango::sql::{atomic, ExecError, Pool};
async fn transfer(pool: &Pool, from: i64, to: i64, amount: i64) -> Result<(), ExecError> {
let p = pool.clone(); // the closure must own what it uses
atomic(pool, move |_tx| {
Box::pin(async move {
let mut a = Account::find_or_fail(from, &p).await?;
let mut b = Account::find_or_fail(to, &p).await?;
a.balance -= amount;
b.balance += amount;
a.save(&p).await?;
b.save(&p).await?;
Ok(()) // Ok commits; an Err (or a failed `?`) rolls both saves back
})
})
.await
}
La closure recibe su propio clon del pool, no un préstamo: el future del bloque
no debe tomar prestado al llamador. Clonar un Pool es barato. La macro
rustango::atomic!(&pool, |tx| { … }) escribe el Box::pin por ti.
Qué se ejecuta en el bloque
Dentro de la closure, cada llamada del ORM que recibe el mismo pool (o un clon) se ejecuta en la transacción del bloque:
- lecturas:
fetch,find,count,get_or_create, … - escrituras:
insert,save,delete, escrituras masivas, actualizaciones de queryset - SQL crudo:
raw_query_pool,raw_execute_pool - DDL (ver DDL en un bloque)
- escrituras del framework: filas de auditoría, fixtures, escrituras de ViewSet y del admin, media, registro e invitaciones SSO
Ven las filas sin confirmar del bloque, y su rollback las deshace. En SQLite, y en MySQL con su nivel por defecto (repeatable read), todas las lecturas del bloque ven una sola instantánea.
Estas se ejecutan fuera del bloque, en su propia conexión:
pool.acquire(), Tenant::conn, la caché, la toma de jobs, los cambios del
registro de tenancy, una tarea lanzada con tokio::spawn y un pool conectado
aparte (aunque sea a la misma base de datos). No ven las escrituras del bloque
y pueden esperar bloqueos que el bloque retiene.
El argumento de la closure es un AtomicTx. tx.lock().await? da un
TxGuard que se desreferencia a PoolTx, para los helpers _tx y las formas
_on: acc.insert_tx(&mut *guard). Ejecuta una sentencia cada vez: mientras
se retiene un guard, o cuando dos sentencias corren a la vez (join!), las
llamadas sobre el pool devuelven ExecError::NestedAtomic. Suelta el guard
antes de la siguiente llamada con &pool.
Coste. Una lectura o una sentencia cruda cuesta un viaje de ida y vuelta.
Una escritura del ORM cuesta tres, porque corre en su propio savepoint (así una
escritura fallida deja el bloque utilizable). Para muchas filas, escribe a
través del guard (insert_tx) o con una escritura masiva.
Bloques anidados
atomic sobre el mismo pool dentro de un bloque abre un savepoint. Su Err
revierte solo sus propias escrituras. Un Err del bloque externo lo revierte
todo, incluido el trabajo anidado.
let p = pool.clone();
atomic(pool, move |_tx| {
Box::pin(async move {
account("[email protected]", 0).insert(&p).await?;
let q = p.clone();
let inner = atomic(&p, move |_sp| {
Box::pin(async move {
account("[email protected]", 0).insert(&q).await?;
// Stands in for any failure inside the nested block.
Err::<(), _>(ExecError::Driver(rustango::sql::sqlx::Error::RowNotFound))
})
})
.await;
assert!(inner.is_err()); // b@ is rolled back, a@ is kept
Ok(())
})
})
.await?;
(account(email, balance) construye un Account con id: Auto::Unset.)
El anidamiento va por objeto pool: pasa el pool de la petición en vez de
conectar de nuevo. Un bloque anidado descartado o que hace panic se revierte.
Si una sentencia de savepoint falla por sí misma, todo el bloque se revierte
con ExecError::AtomicAborted. PostgreSQL se ralentiza a partir de 64
savepoints en una transacción, y cada escritura del ORM es uno: mantén cortos
los bloques con muchas escrituras.
Después del commit
rustango::sql::on_commit(callback) encola un callback que corre después de
que el bloque más externo confirma. Nunca corre en un rollback, y un bloque
anidado revertido descarta sus callbacks. Los callbacks corren en el orden en
que se encolaron.
use rustango::sql::on_commit;
let p = pool.clone();
atomic(pool, move |_tx| {
Box::pin(async move {
let mut acc = account("[email protected]", 0);
acc.insert(&p).await?;
on_commit(move || {
tokio::spawn(async move { /* send the welcome email */ });
});
Ok(())
})
})
.await?;
El callback es síncrono: lanza el trabajo asíncrono desde él. Un callback que
hace panic se registra en el log y los demás corren igualmente. on_commit
fuera de un bloque hace panic.
Cuando una sentencia falla
| Backend | Una lectura o sentencia cruda que falla | Una escritura del ORM que falla |
|---|---|---|
| PostgreSQL | Aborta el bloque: las sentencias siguientes y atomic devuelven ExecError::AtomicAborted | Se deshace sola (su savepoint); el bloque sigue |
| MySQL, MariaDB | Se deshace sola; el bloque sigue | Se deshace sola; el bloque sigue |
| SQLite | Se deshace sola; el bloque sigue | Se deshace sola; el bloque sigue |
Una closure que ignora un error y devuelve Ok confirma el resto del bloque
(en PostgreSQL, tras una lectura abortada, atomic devuelve en cambio
AtomicAborted).
Algunos errores terminan toda la transacción en el servidor: un deadlock de
MySQL (1213), un timeout de espera de bloqueo de MySQL (1205) cuando el
servidor revierte por ello, un rollback automático de SQLite, una conexión
perdida. Cada sentencia del ORM posterior en el bloque, y el propio atomic,
devuelven entonces ExecError::AtomicAborted. MariaDB informa de un nowait()
fallido como 1205; con el valor por defecto innodb_rollback_on_timeout = OFF
deshace solo la sentencia.
Seguir tras una lectura fallida. Para intentar un paso que puede fallar (un
bloqueo nowait(), una prueba sobre una tabla que quizá no existe), ponlo en un
bloque anidado. Su fallo deshace entonces solo ese bloque, en todos los
backends:
let p = pool.clone();
atomic(pool, move |_tx| {
Box::pin(async move {
let q = p.clone();
// A failed read in a nested block undoes only that block, even on PG.
let locked = atomic(&p, move |_sp| {
Box::pin(async move {
Account::objects()
.filter("email", "[email protected]")
.nowait()
.fetch(&q)
.await
})
})
.await;
match locked {
Ok(_rows) => { /* got the lock */ }
Err(_) => { /* row busy: the outer block goes on */ }
}
Ok(())
})
})
.await?;
El SQL crudo que termina la transacción (COMMIT, ROLLBACK o una sentencia
con la que MySQL confirma) hace que el bloque devuelva
ExecError::AtomicEndedEarly. Las sentencias posteriores corrieron sin
transacción, así que no reintentes a ciegas.
SQLite toma el bloqueo de escritura en el BEGIN
En SQLite el bloque más externo empieza con BEGIN IMMEDIATE. Un bloque que
lee y luego escribe no falla con SQLITE_BUSY en su primera escritura; en su
lugar, un segundo escritor espera en su propio BEGIN. Otras conexiones que
escriben esperan busy_timeout (5 segundos por defecto) y luego fallan con
SQLITE_BUSY; en una base de datos en memoria esperan sin límite de tiempo.
Mantén cortos los bloques de SQLite.
atomic_immediate hacía esto antes que atomic. Está obsoleto: llama a
atomic.
Niveles de aislamiento y ajustes
atomic_with(&pool, options, closure) abre el bloque más externo con un nivel
de aislamiento, ajustes de PostgreSQL, o ambos:
use rustango::sql::{atomic_with, raw_query_pool, AtomicOptions, Isolation, TxSetting};
let opts = AtomicOptions::new()
.isolation(Isolation::RepeatableRead)
.setting(TxSetting::new("app.account_id", "42")?); // PostgreSQL only
let p = pool.clone();
let seen: Vec<(Option<String>,)> = atomic_with(pool, opts, move |_tx| {
Box::pin(async move {
raw_query_pool("SELECT current_setting('app.account_id', true)", vec![], &p).await
})
})
.await?;
- Niveles:
Isolation::ReadCommitted,RepeatableRead,Serializable. PostgreSQL empieza conBEGIN ISOLATION LEVEL …. MySQL fija el nivel solo para esa transacción; el siguiente bloque en la conexión vuelve al valor por defecto del servidor. SQLite acepta cualquier nivel: siempre es serializable. Sin nivel, el bloque usa el valor por defecto del servidor (PostgreSQL: read committed; MySQL: repeatable read). - Los ajustes (
TxSetting) son solo de PostgreSQL, por ejemploapp.account_idpara políticas de seguridad de fila. Cada uno se fija conset_config(name, value, true)y desaparece al terminar el bloque. El valor se enlaza. El nombre debe llevar punto (prefix.name) y cada parte ser un identificador simple, así quesearch_pathoroledevuelvenExecError::InvalidTxSetting. En MySQL y SQLite los ajustes devuelvenExecError::Sql(SqlError::OperatorNotSupportedInDialect)antes de que empiece el bloque. - Los bloques anidados no pueden cambiarlos:
atomic_withcon opciones dentro de un bloque sobre el mismo pool devuelveExecError::InAtomic.
¿Este código está en un bloque?
rustango::sql::in_atomic(&pool) es true mientras la tarea en curso está
dentro de un bloque sobre pool (o un clon), de modo que las llamadas del ORM
que reciben pool corren en su transacción. Es false fuera y para cualquier
otro pool. Sigue siendo true en un bloque que falló o terminó antes de tiempo.
Get or create en una transacción
get_or_create_tx y update_or_create_tx toman un PoolTx abierto. En un
bloque, bloquea el guard y pásalo:
use rustango::sql::get_or_create_tx;
let email = "[email protected]".to_owned();
let (acc, created) = atomic(pool, move |tx| {
Box::pin(async move {
let mut g = tx.lock().await?;
let filter = Account::objects().filter("email", email.clone());
get_or_create_tx(
filter,
move |t| {
Box::pin(async move {
let mut acc = Account { id: Auto::Unset, email, balance: 0 };
acc.insert_tx(t).await?;
Ok(acc)
})
},
&mut *g,
)
.await
})
})
.await?;
use rustango::sql::update_or_create_tx;
let (acc, created) = atomic(pool, move |tx| {
Box::pin(async move {
let mut g = tx.lock().await?;
update_or_create_tx(
Account::objects().filter("email", "[email protected]"),
|t, mut acc: Account| {
Box::pin(async move {
acc.balance += 10;
acc.save_tx(t).await?;
Ok(acc)
})
},
|t| {
Box::pin(async move {
let mut acc = Account {
id: Auto::Unset,
email: "[email protected]".into(),
balance: 10,
};
acc.insert_tx(t).await?;
Ok(acc)
})
},
&mut *g,
)
.await
})
})
.await?;
Carreras. La closure de creación corre en un savepoint. Cuando dos
transacciones crean la misma fila a la vez, el insert del perdedor choca con la
restricción de unicidad: su savepoint se revierte y lee la fila del ganador
(created == false; update_or_create_tx la actualiza entonces). La
transacción sigue utilizable. Hace falta una restricción UNIQUE sobre las
columnas filtradas. Un get_or_create_tx dentro de la closure de creación de
otro (una fila padre y luego la hija) funciona igual.
| Backend y nivel | El perdedor recibe |
|---|---|
| PostgreSQL read committed (por defecto) | La fila del ganador |
| PostgreSQL repeatable read | El error de violación de unicidad |
| PostgreSQL serializable | Un fallo de serialización (40001) |
| MySQL, MariaDB | La fila del ganador (releída con una lectura con bloqueo) |
| SQLite | Sin carrera: los bloques corren de uno en uno |
Con repeatable read o serializable en PostgreSQL, reintenta todo el bloque.
Las formas de pool get_or_create y update_or_create se comportan igual
dentro de un bloque: sus lecturas se unen a él y la closure de creación corre en
un savepoint. No retengas el guard mientras las llamas.
Las formas _on
Los métodos _on toman cualquier ejecutor: un &Pool, una conexión retenida
(&mut PoolConn de pool.acquire()) o una transacción abierta (&mut PoolTx
de transaction_pool, o &mut *guard en un bloque). La sentencia corre sobre
lo que pasas.
fetch_on,insert_on,save_on,delete_on,upsert_onModel::bulk_insert_on,Model::bulk_upsert_on,Model::bulk_insert_or_ignore_onrustango::sql::bulk_update_onrustango::sql::fetch_dates_on,rustango::sql::fetch_datetimes_onrustango::sql::fetch_with_prefetch_onrustango::sql::model_shortcuts::increment_one_on- actualizaciones y borrados de queryset:
.update().execute_on(..),.delete_on(..)
use rustango::core::{BulkUpdateQuery, Model as _, SqlValue}; // `Model` brings `Account::SCHEMA` into scope
use rustango::sql::model_shortcuts::increment_one_on;
use rustango::sql::{bulk_update_on, transaction_pool};
let mut tx = transaction_pool(pool).await?;
let mut rows = vec![
Account { id: Auto::Unset, email: "[email protected]".into(), balance: 0 },
Account { id: Auto::Unset, email: "[email protected]".into(), balance: 0 },
];
Account::bulk_insert_on(&mut rows, &mut tx).await?;
// MySQL leaves `Auto` ids unset after a bulk insert: read them back.
let ids: Vec<i64> = Account::objects()
.order_by(&[("id", false)])
.fetch_on(&mut tx)
.await?
.iter()
.filter_map(|a| a.id.get().copied())
.collect();
let set_100 = BulkUpdateQuery::new(
Account::SCHEMA,
vec!["balance"],
ids.iter()
.map(|id| vec![SqlValue::from(*id), SqlValue::from(100_i64)])
.collect(),
);
bulk_update_on(&mut tx, &set_100).await?;
increment_one_on::<Account, _>("id", SqlValue::from(ids[0]), "balance", 5, &mut tx).await?;
tx.commit().await?; // or drop `tx` to roll it all back
En un modelo auditado, las escrituras _on derivadas e increment_one_on
devuelven ExecError::AuditUnsupported: no pueden escribir las filas de
auditoría. Usa ahí las formas de pool.
DDL en un bloque
- PostgreSQL y SQLite: el DDL corre en la transacción del bloque y se revierte con ella.
- MySQL: el DDL confirma la transacción.
run_ddl_idempotent(y los helpersensure_tableconstruidos sobre él) se niega dentro de un bloque con unsqlx::Error::Protocolcuyo mensaje empieza porDDL on MySQL is refused inside an atomic block on its pool. El DDL crudo víaraw_execute_poolcorre, confirma el trabajo hecho hasta entonces, y el bloque devuelveExecError::AtomicEndedEarly. - Cualquier backend: una migración con
"atomic": falsedevuelveMigrateError::Exec(ExecError::InAtomic { .. }).
Ejecuta el DDL y las migraciones antes o después del bloque.
Iterar en un bloque
Dentro de un bloque sobre el mismo pool, .iterator(n) ejecuta cada chunk en la
transacción del bloque. Ve las escrituras del bloque, conserva los bloqueos de
fila de select_for_update() y pagina por clave primaria (WHERE pk > last)
en lugar de OFFSET. Las filas que el bucle saca del filtro no se saltan:
let p = pool.clone();
atomic(pool, move |_tx| {
Box::pin(async move {
let mut it = Account::objects()
.filter("balance", 0_i64)
.order_by(&[("id", false)]) // primary key only, or no order
.iterator(500)?;
while let Some(chunk) = it.next_chunk(&p).await? {
for mut acc in chunk {
acc.balance = 1; // leaves the filter; paging by key still reaches every row
acc.save(&p).await?;
}
}
Ok(())
})
})
.await?;
El queryset debe estar ordenado por la clave primaria (en cualquier sentido) o
no estar ordenado, seleccionar la clave primaria y no ser un union /
intersection / difference. Si no, next_chunk devuelve
ExecError::InAtomic.
Cancelación
Descartar el future de un bloque (un tokio::time::timeout, un cliente que se
va) revierte el bloque, y sus callbacks on_commit nunca corren:
use std::time::Duration;
let p = pool.clone();
let slow = atomic(pool, move |_tx| {
Box::pin(async move {
Account { id: Auto::Unset, email: "[email protected]".into(), balance: 0 }
.insert(&p)
.await?;
tokio::time::sleep(Duration::from_secs(5)).await; // stands in for slow work
Ok(())
})
});
// Dropping the block (here on timeout) rolls it back.
assert!(tokio::time::timeout(Duration::from_millis(100), slow).await.is_err());
Si una sentencia estaba corriendo cuando se descartó el bloque, el servidor no la detiene. La conexión sigue ocupada hasta que el servidor termina esa sentencia; luego corre el rollback y la conexión vuelve al pool. Mientras tanto, a un pool pequeño le pueden faltar conexiones. Un bloque anidado descartado se revierte en el siguiente uso del bloque.
Errores
| Error | Significado |
|---|---|
ExecError::NestedAtomic | Una sentencia corrió mientras se retenía un TxGuard, o dos corrieron a la vez (join!) |
ExecError::AtomicAborted | La transacción se revirtió tras una sentencia o un savepoint fallido |
ExecError::AtomicEndedEarly | El SQL crudo confirmó o terminó la transacción; algunas escrituras pueden estar confirmadas |
ExecError::InAtomic | La operación se rechaza dentro de un bloque sobre su pool |
ExecError::InvalidTxSetting | Un nombre de TxSetting no es un prefix.name con punto |