duroxide_pg/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::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::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//! ## Microsoft Entra ID Authentication
40//!
41//! Connect to Azure Database for PostgreSQL Flexible Server using an Entra
42//! access token. A background task refreshes the token before expiry. See
43//! [`EntraAuthOptions`] for tunables.
44//!
45//! ```rust,no_run
46//! use duroxide_pg::{EntraAuthOptions, PostgresProvider};
47//!
48//! # async fn example() -> anyhow::Result<()> {
49//! let provider = PostgresProvider::new_with_entra(
50//! "myserver.postgres.database.azure.com",
51//! 5432,
52//! "mydb",
53//! "my-entra-principal@contoso.onmicrosoft.com",
54//! EntraAuthOptions::new(),
55//! )
56//! .await?;
57//! # Ok(())
58//! # }
59//! ```
60//!
61//! All Entra connections use `PgSslMode::VerifyFull`. The default credential
62//! chain is `[WorkloadIdentityCredential (added only when AKS federated env
63//! vars are present), ManagedIdentityCredential, DeveloperToolsCredential]`,
64//! which works for AKS Workload Identity, other Azure-hosted managed
65//! identities, and developer workstations logged in via `az login`.
66//!
67//! ## Configuration
68//!
69//! | Environment Variable | Description | Default |
70//! |---------------------|-------------|---------|
71//! | `DUROXIDE_PG_POOL_MAX` | Maximum connection pool size | `10` |
72//!
73//! ## Features
74//!
75//! - Automatic schema migration on startup
76//! - Connection pooling via sqlx
77//! - Custom schema support for multi-tenant isolation
78//! - Full implementation of the Duroxide `Provider` and `ProviderAdmin` traits
79
80pub mod entra;
81pub mod migrations;
82pub mod provider;
83
84pub use entra::EntraAuthOptions;
85pub use provider::PostgresProvider;