1Insert the record and enqueue its job on one transaction
connection is a SqliteConnection the program opens on Acta's own connection string, so the orders table and Acta's tables are in one database. The transaction is yours: Acta writes the job through it and never commits it, rolls it back, or retries it. No worker sees the job before the commit.
// A run of its own, so a second run against the same file adds its own two orders.
var run = Guid.NewGuid().ToString("N")[..8];
var (kept, dropped) = ($"order-{run}-kept", $"order-{run}-dropped");
EnqueueJobResponse committed;
await using (var transaction = connection.BeginTransaction())
{
await ExecuteAsync(transaction, "INSERT INTO shop_orders (order_id) VALUES (@id)", kept);
committed = await jobs.EnqueueAsync(transaction, new FulfilOrder(kept));
await transaction.CommitAsync();
}2Roll back, and neither the record nor the job exists
The answer of an enqueue is provisional until the commit. After a rollback its job ref names nothing.
EnqueueJobResponse rolledBack;
await using (var transaction = connection.BeginTransaction())
{
await ExecuteAsync(transaction, "INSERT INTO shop_orders (order_id) VALUES (@id)", dropped);
rolledBack = await jobs.EnqueueAsync(transaction, new FulfilOrder(dropped));
await transaction.RollbackAsync();
}
await jobs.WaitAsync(committed.JobRef);
Console.WriteLine($"committed: order row {await OrderExistsAsync(kept)}, job {await JobAsync(committed.JobRef)}");
Console.WriteLine($"rolled back: order row {await OrderExistsAsync(dropped)}, job {await JobAsync(rolledBack.JobRef)}");
await host.StopAsync();3The job it acts on
public static class FulfilOrderJob
{
[Job("fulfil-order")]
public static void Handle(FulfilOrder order) => Console.WriteLine($"[{order.OrderId[^4..]}] order fulfilled");
}4Run it and check the output
From a clone of the Acta repository, with the .NET 10 SDK:
dotnet run --project learn/000-fundamentals/029-enqueue-in-transaction[kept] order fulfilled
committed: order row yes, job succeeded
rolled back: order row no, job noneChecked every release. Before each release, Acta Verify runs this program and checks that its output contains these lines.
Remember
- The transaction is yours. Acta never opens, commits, rolls back, disposes, or retries it, and any exception inside it means rolling back the whole of it.
- The answer of the enqueue is provisional until the commit and dead after a rollback. Keep or show the job's ref only once the commit has returned.
- No wake-up is published for an enqueue in a transaction, so a worker finds the job on its next poll after the commit.
- There is no
CallAsyncin a transaction and no handle: the job is invisible until the commit, so nothing could wait for it. - The record's table has to live in the database Acta uses. Work for a separate database is handed over through an outbox.
- A request that may arrive twice still needs a deduplication key on the enqueue, as in keep a repeated request from creating a second job.
Check yourself
The transaction rolls back after the enqueue. What happens to the job?
Show the answer
It never existed. The job's row was written through the same transaction as the order's row, so the rollback took both, and no worker ever saw the job.
The whole program
Every file of learn/000-fundamentals/029-enqueue-in-transaction, as it is compiled.
UseLocalDatabase is a helper of the Acta repository, not of the packages. In your own app, register the database with UseSqlite, UsePostgres or UseSqlServer, as in how to run your first job.
enqueue-in-transaction.cs103 lines
// How to save a record and start its job in one transaction
// `EnqueueAsync` takes your open transaction, so the order row and the job that fulfils it commit together, or
// neither exists.
using Acta;
using Acta.Learn.EnqueueInTransaction;
using Microsoft.Data.Sqlite;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
var provider = LocalDatabase.ResolveProvider(builder.Configuration);
if (!LocalDatabase.IsSqlite(provider))
{
Console.WriteLine("This how-to keeps its orders table in the same SQLite file as Acta's tables.");
Console.WriteLine("Unset ACTA_LOCAL_PROVIDER (or set it to sqlite) and run again.");
return;
}
builder.Services.UseActa(j =>
{
j.UseLocalDatabase(builder.Configuration);
j.Run<EnqueueInTransactionJobs>("enqueue-in-transaction");
});
using var host = builder.Build();
await host.StartAsync();
var jobs = host.Services.GetRequiredService<IJobs>();
// The application's own table lives in the database Acta uses, which is what lets one transaction cover both.
await using var connection = new SqliteConnection(LocalDatabase.ResolveConnectionString(builder.Configuration, provider));
await connection.OpenAsync();
await ExecuteAsync(null, "CREATE TABLE IF NOT EXISTS shop_orders (order_id TEXT PRIMARY KEY)");
// A run of its own, so a second run against the same file adds its own two orders.
var run = Guid.NewGuid().ToString("N")[..8];
var (kept, dropped) = ($"order-{run}-kept", $"order-{run}-dropped");
// learn: 1. Insert the record and enqueue its job on one transaction
// `connection` is a `SqliteConnection` the program opens on Acta's own connection string, so the orders table and
// Acta's tables are in one database.
// The transaction is yours: Acta writes the job through it and never commits it, rolls it back, or retries it. No
// worker sees the job before the commit.
EnqueueJobResponse committed;
await using (var transaction = connection.BeginTransaction())
{
await ExecuteAsync(transaction, "INSERT INTO shop_orders (order_id) VALUES (@id)", kept);
committed = await jobs.EnqueueAsync(transaction, new FulfilOrder(kept));
await transaction.CommitAsync();
}
// learn: end
// learn: 2. Roll back, and neither the record nor the job exists
// The answer of an enqueue is provisional until the commit. After a rollback its job ref names nothing.
EnqueueJobResponse rolledBack;
await using (var transaction = connection.BeginTransaction())
{
await ExecuteAsync(transaction, "INSERT INTO shop_orders (order_id) VALUES (@id)", dropped);
rolledBack = await jobs.EnqueueAsync(transaction, new FulfilOrder(dropped));
await transaction.RollbackAsync();
}
// learn: end
await jobs.WaitAsync(committed.JobRef);
Console.WriteLine($"committed: order row {await OrderExistsAsync(kept)}, job {await JobAsync(committed.JobRef)}");
Console.WriteLine($"rolled back: order row {await OrderExistsAsync(dropped)}, job {await JobAsync(rolledBack.JobRef)}");
await host.StopAsync();
async Task<string> JobAsync(JobRef jobRef) => (await jobs.GetAsync(jobRef))?.Status.Code ?? "none";
async Task<string> OrderExistsAsync(string orderId)
{
await using var command = connection.CreateCommand();
command.CommandText = "SELECT COUNT(*) FROM shop_orders WHERE order_id = @id";
command.Parameters.AddWithValue("@id", orderId);
return (long)(await command.ExecuteScalarAsync())! == 1 ? "yes" : "no";
}
async Task ExecuteAsync(SqliteTransaction? transaction, string sql, string? orderId = null)
{
await using var command = connection.CreateCommand();
command.Transaction = transaction;
command.CommandText = sql;
if (orderId is not null)
{
command.Parameters.AddWithValue("@id", orderId);
}
await command.ExecuteNonQueryAsync();
}
namespace Acta.Learn.EnqueueInTransaction
{
public sealed record FulfilOrder(string OrderId);
public static class FulfilOrderJob
{
[Job("fulfil-order")]
public static void Handle(FulfilOrder order) => Console.WriteLine($"[{order.OrderId[^4..]}] order fulfilled");
}
}