duroxide_pg_opt/
lib.rs

1//! # Duroxide PostgreSQL Provider
2//!
3//! A PostgreSQL-based provider implementation for [Duroxide](https://crates.io/crates/duroxide),
4//! a durable task orchestration framework for Rust.
5//!
6//! ## Usage
7//!
8//! ```rust,no_run
9//! use duroxide_pg_opt::PostgresProvider;
10//! use duroxide::runtime::Runtime;
11//! use std::sync::Arc;
12//!
13//! # async fn example() -> anyhow::Result<()> {
14//! // Create a provider with the database URL
15//! let provider = PostgresProvider::new("postgres://user:password@localhost:5432/mydb").await?;
16//!
17//! // Use with the Duroxide runtime
18//! // let runtime = Runtime::start_with_store(Arc::new(provider), activity_registry, orchestration_registry).await;
19//! # Ok(())
20//! # }
21//! ```
22//!
23//! ## Custom Schema
24//!
25//! To isolate data in a specific PostgreSQL schema (useful for multi-tenant deployments):
26//!
27//! ```rust,no_run
28//! use duroxide_pg_opt::PostgresProvider;
29//!
30//! # async fn example() -> anyhow::Result<()> {
31//! let provider = PostgresProvider::new_with_schema(
32//!     "postgres://user:password@localhost:5432/mydb",
33//!     Some("my_schema"),
34//! ).await?;
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! ## Configuration
40//!
41//! | Environment Variable | Description | Default |
42//! |---------------------|-------------|---------|
43//! | `DUROXIDE_PG_POOL_MAX` | Maximum connection pool size | `10` |
44//!
45//! ## Long-Polling
46//!
47//! The provider supports long-polling via PostgreSQL LISTEN/NOTIFY to reduce idle query load:
48//!
49//! ```rust,no_run
50//! use duroxide_pg_opt::{PostgresProvider, LongPollConfig};
51//! use std::time::Duration;
52//!
53//! # async fn example() -> anyhow::Result<()> {
54//! let config = LongPollConfig {
55//!     enabled: true,
56//!     notifier_poll_interval: Duration::from_secs(60),
57//!     timer_grace_period: Duration::from_millis(100),
58//! };
59//!
60//! let provider = PostgresProvider::new_with_options(
61//!     "postgres://user:password@localhost:5432/mydb",
62//!     Some("my_schema"),
63//!     config,
64//! ).await?;
65//! # Ok(())
66//! # }
67//! ```
68//!
69//! ## Features
70//!
71//! - Automatic schema migration on startup
72//! - Connection pooling via sqlx
73//! - Custom schema support for multi-tenant isolation
74//! - Long-polling via LISTEN/NOTIFY for reduced database load
75//! - Full implementation of the Duroxide `Provider` and `ProviderAdmin` traits
76//!
77//! ## Fault Injection (Testing)
78//!
79//! For testing resilience scenarios, enable the `test-fault-injection` feature:
80//!
81//! ```toml
82//! [dev-dependencies]
83//! duroxide-pg = { version = "0.1", features = ["test-fault-injection"] }
84//! ```
85pub mod db_metrics;
86///
87/// ## Database Metrics (Instrumentation)
88///
89/// For database operation instrumentation, enable the `db-metrics` feature:
90///
91/// ```toml
92/// [dependencies]
93/// duroxide-pg = { version = "0.1", features = ["db-metrics"] }
94/// ```
95///
96/// This enables zero-cost metrics collection for all database operations.
97/// See the [`db_metrics`] module for details.
98#[cfg(feature = "test-fault-injection")]
99pub mod fault_injection;
100pub mod migrations;
101pub mod notifier;
102pub mod provider;
103
104#[cfg(feature = "test-fault-injection")]
105pub use fault_injection::FaultInjector;
106pub use notifier::LongPollConfig;
107pub use provider::PostgresProvider;
duroxide_pg_opt/lib.rs

duroxide_pg_opt/
lib.rs
