Skip to main content

JobsRepo

Struct JobsRepo 

Source
pub struct JobsRepo { /* private fields */ }
Expand description

Repository providing atomic database operations for job queue management.

Handles enqueueing, transactional batch leasing (SKIP LOCKED), execution completion, re-scheduling retries, moving jobs to DLQ, and replay.

§Examples

use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;

Implementations§

Source§

impl JobsRepo

§Examples

use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub fn new(pool: Pool<Postgres>) -> JobsRepo

Creates a new JobsRepo wrapping a SQLx PostgreSQL connection pool.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub fn new_with_url( pool: Pool<Postgres>, database_url: impl Into<String>, ) -> JobsRepo

Creates a new JobsRepo with a dedicated database_url for unpooled LISTEN connections.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn enqueue(&self, job: NewJob) -> Result<Uuid, Error>

Inserts a new job into the queue database.

Automatically routes the job to the appropriate dataset partition based on run_at.

§Examples
use azums::{Job, JobsRepo, make_pool};

let pool = make_pool("postgres://localhost/flow").await?;
let repo = JobsRepo::new(pool);
let job_id = repo
    .enqueue(Job::new("email_send", serde_json::json!({"to": "user@example.com"})).into())
    .await?;
Source

pub async fn enqueue_in_tx( &self, tx: &mut Transaction<'_, Postgres>, job: NewJob, ) -> Result<Uuid, Error>

Inserts a new job using the caller’s PostgreSQL transaction.

Use this when an application state mutation and job enqueue must commit or roll back together. The pg_notify call is executed inside the same transaction, so PostgreSQL only delivers the wake-up notification if the transaction commits.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn enqueue_now( &self, queue: &str, job_type: &str, payload_json: Value, ) -> Result<Uuid, Error>

Enqueues a job for immediate execution (run_at = Utc::now()).

§Examples
use azums::{JobsRepo, make_pool};

let pool = make_pool("postgres://localhost/flow").await?;
let repo = JobsRepo::new(pool);
let id = repo.enqueue_now("default", "send_welcome", serde_json::json!({"id": 123})).await?;
Source

pub async fn enqueue_in( &self, queue: &str, job_type: &str, payload_json: Value, delay_secs: i64, ) -> Result<Uuid, Error>

Schedules a job for future execution delayed by delay_secs seconds.

§Examples
use azums::{JobsRepo, make_pool};

let pool = make_pool("postgres://localhost/flow").await?;
let repo = JobsRepo::new(pool);
let id = repo.enqueue_in("default", "send_reminder", serde_json::json!({}), 300).await?;
Source

pub async fn enqueue_at( &self, queue: &str, job_type: &str, payload_json: Value, run_at: DateTime<Utc>, ) -> Result<Uuid, Error>

Schedules a job to run at a specific UTC timestamp (run_at).

§Examples
use azums::{JobsRepo, make_pool};
use chrono::Utc;

let pool = make_pool("postgres://localhost/flow").await?;
let repo = JobsRepo::new(pool);
let run_at = Utc::now() + chrono::Duration::hours(1);
let id = repo.enqueue_at("default", "scheduled_report", serde_json::json!({}), run_at).await?;
Source

pub async fn get_job(&self, job_id: Uuid) -> Result<Option<Job>, Error>

Fetches a single Job record by primary key job_id.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn extend_lease( &self, job_id: Uuid, worker_id: &str, lease_seconds: i64, ) -> Result<bool, Error>

Extends the lock expiration timestamp for a running job.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn list_jobs( &self, queue: Option<&str>, status: Option<&str>, limit: i64, cursor_created_at: Option<DateTime<Utc>>, cursor_id: Option<Uuid>, ) -> Result<Vec<JobListItem>, Error>

Cursor-paginated list of jobs. Cursor is (created_at, id) ordered DESC.

  • queue/status are optional filters
  • limit is clamped to [1, 500]
§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn metrics_snapshot(&self) -> Result<(i64, i64, i64, i64), Error>

Returns: (queued, running, succeeded_last_60s, failed_or_dlq_last_60s)

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn lease_jobs_batch( &self, queue: &str, worker_id: &str, lease_seconds: i64, batch_size: i64, ) -> Result<Vec<Job>, Error>

Lease up to batch_size runnable jobs for this worker.

Correctness: SELECT … FOR UPDATE SKIP LOCKED

Storm-control gates (per queue):

  • max_in_flight (jobs.status=‘running’)
  • max_attempts_per_minute (attempts started in last 60s)

If exceeded:

  • write a row into policy_decisions
  • reschedule one candidate slightly (throttle_delay_ms)
  • return an empty batch
§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn lease_jobs_batch_with_ordering( &self, queue: &str, worker_id: &str, lease_seconds: i64, batch_size: i64, ordering: QueueOrdering, ) -> Result<Vec<Job>, Error>

Lease up to batch_size runnable jobs for this worker using specified azums_core::QueueOrdering.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn lease_one_job( &self, queue: &str, worker_id: &str, lease_seconds: i64, ) -> Result<Option<Job>, Error>

Compatibility helper for call sites/tests that still lease one-by-one.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn reap_expired_locks(&self) -> Result<u64, Error>

Fails active attempts whose leases expired, clears ownership, and requeues their jobs.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn mark_succeeded_batch( &self, job_ids: &[Uuid], worker_id: &str, ) -> Result<u64, Error>

Fast-path for successful batch execution: transitions many jobs in one statement.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn mark_succeeded_batch_for_dataset( &self, dataset_id: &str, job_ids: &[Uuid], worker_id: &str, ) -> Result<u64, Error>

Dataset-aware fast-path for partition-pruned successful batch updates.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn mark_succeeded( &self, job_id: Uuid, worker_id: &str, ) -> Result<(), Error>

Completes a running job only when worker_id owns its active lease.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn reschedule_for_retry( &self, job_id: Uuid, next_run_at: DateTime<Utc>, last_error_code: Option<&str>, last_error_message: Option<&str>, ) -> Result<(), Error>

Returns a running job to queued retry wait with its latest error and eligibility time.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn mark_failed( &self, job_id: Uuid, worker_id: &str, last_error_code: Option<&str>, last_error_message: Option<&str>, ) -> Result<(), Error>

Applies the legacy failed status to a running job owned by worker_id.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn mark_dlq( &self, job_id: Uuid, worker_id: &str, reason_code: &str, last_error_code: Option<&str>, last_error_message: Option<&str>, ) -> Result<(), Error>

Moves a running job owned by worker_id into the terminal dead-letter queue.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn cancel_job( &self, job_id: Uuid, worker_id: Option<&str>, ) -> Result<(), Error>

Cancels queued work or running work owned by the supplied worker.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn replay_job( &self, job_id: Uuid, override_queue: Option<&str>, override_run_at: Option<DateTime<Utc>>, ) -> Result<Uuid, Error>

Creates a new queued job from retained history and records replay lineage.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;
Source

pub async fn subscribe( &self, queue: &str, ) -> Result<Pin<Box<dyn Stream<Item = ()> + Send>>, Error>

Subscribes to PostgreSQL LISTEN events for job enqueueing on a channel named azums_job_enqueued_<queue>.

§Examples
use azums::JobsRepo;
use sqlx::postgres::PgPoolOptions;

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:postgres@localhost/azums")?;
let jobs = JobsRepo::new(pool);
let _ = jobs;

Trait Implementations§

Source§

impl Clone for JobsRepo

Source§

fn clone(&self) -> JobsRepo

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more