Adding `distributed_lock_postgres` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add distributed-lock-postgres

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

distributed-lock-postgres = "0.2.0"

The distributed_lock_postgres library will be automatically available globally. Read the distributed_lock_postgres library documentation.

Back to the crate overview.

Readme

distributed-lock-rs

Distributed locks for Rust with multiple backend support. This library provides distributed synchronization primitives (mutex locks, reader-writer locks, semaphores) that work across processes and machines.

Features

🔒 Exclusive Locks: Mutual exclusion across processes
📖 Reader-Writer Locks: Multiple readers or single writer
🎫 Semaphores: Limit concurrent access to N processes
⚡ Async/Await: Full async support with tokio
🔄 Backend Agnostic: Swap backends without changing application code
🔍 Handle Loss Detection: Detect when locks are lost due to connection issues
🚀 Production Ready: Connection pooling, automatic lease extension, RedLock support

Backends

PostgreSQL

Uses PostgreSQL advisory locks. Production-ready with connection pooling and transaction-scoped locks.

[dependencies]
distributed-lock-postgres = "0.1"
tokio = { version = "1", features = ["full"] }

MySQL

Uses MySQL user-defined variables and database tables. Supports reader-writer locks through automatic table creation.

Note: Reader-writer locks require creating a distributed_locks table in your MySQL database. This table is created automatically when needed, as MySQL doesn't provide built-in reader-writer lock primitives like PostgreSQL.

[dependencies]
distributed-lock-mysql = "0.1"
tokio = { version = "1", features = ["full"] }

Or use the meta-crate:

[dependencies]
distributed-lock = { version = "0.1", features = ["mysql"] }
tokio = { version = "1", features = ["full"] }

Redis

Uses Redis with RedLock algorithm for multi-server deployments. Supports semaphores and automatic lease extension.

[dependencies]
distributed-lock-redis = "0.1"
tokio = { version = "1", features = ["full"] }

File System

Uses OS-level file locking. Simple and requires no external services.

[dependencies]
distributed-lock-file = "0.1"
tokio = { version = "1", features = ["full"] }

MongoDB

Uses MongoDB's atomic document updates and aggregation pipelines. Production-ready with support for TTL-based expiration.

[dependencies]
distributed-lock-mongo = "0.1"
tokio = { version = "1", features = ["full"] }

Meta-Crate (All Backends)

Or use the meta-crate to get all backends:

[dependencies]
distributed-lock = "0.1"
tokio = { version = "1", features = ["full"] }

You can also enable specific backends:

[dependencies]
distributed-lock = { version = "0.1", features = ["mysql", "postgres"] }
tokio = { version = "1", features = ["full"] }

Quick Start

Basic Usage

use distributed_lock::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a provider (example: file backend)
    let provider = FileLockProvider::builder()
        .directory("/tmp/locks")
        .build()?;

    // Create a lock by name
    let lock = provider.create_lock("my-resource");

    // Acquire the lock with a timeout
    let handle = lock.acquire(Some(Duration::from_secs(5))).await?;

    // Critical section - we have exclusive access
    println!("Doing critical work...");

    // Release the lock (also happens automatically on drop)
    handle.release().await?;

    Ok(())
}

PostgreSQL Example

use distributed_lock_postgres::PostgresLockProvider;
use distributed_lock_core::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = PostgresLockProvider::builder()
        .connection_string("postgresql://user:pass@localhost/db")
        .build()
        .await?;

    let lock = provider.create_lock("my-resource");
    let handle = lock.acquire(Some(Duration::from_secs(5))).await?;

    // Critical section
    do_work().await?;

    handle.release().await?;
    Ok(())
}

MySQL Example

use distributed_lock_mysql::MySqlLockProvider;
use distributed_lock_core::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = MySqlLockProvider::builder()
        .connection_string("mysql://user:pass@localhost/db")
        .build()
        .await?;

    // Basic mutex lock
    let lock = provider.create_lock("my-resource");
    let handle = lock.acquire(Some(Duration::from_secs(5))).await?;
    do_work().await?;
    handle.release().await?;

    // Reader-writer lock (creates distributed_locks table automatically)
    let rw_lock = provider.create_reader_writer_lock("shared-resource");
    let read_handle = rw_lock.acquire_read(None).await?;
    read_data().await;
    read_handle.release().await?;

    Ok(())
}

Redis Example

use distributed_lock_redis::RedisLockProvider;
use distributed_lock_core::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let provider = RedisLockProvider::builder()
        .add_server("redis://localhost:6379")
        .build()
        .await?;

    let lock = provider.create_lock("my-resource");
    let handle = lock.acquire(Some(Duration::from_secs(5))).await?;

    // Lock is automatically extended in the background
    do_long_running_work().await?;

    handle.release().await?;
    Ok(())
}

MongoDB Example

use distributed_lock_mongo::MongoDistributedLock;
use distributed_lock_core::prelude::*;
use std::time::Duration;
use mongodb::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::with_uri_str("mongodb://localhost:27017").await?;
    let database = client.database("my_database");

    let lock = MongoDistributedLock::new(
        "my-resource".to_string(),
        database,
        None, // Default collection "DistributedLocks"
        None  // Default options
    );

    let handle = lock.acquire(Some(Duration::from_secs(5))).await?;
    do_work().await?;
    handle.release().await?;
    Ok(())
}

Reader-Writer Locks

use distributed_lock_postgres::PostgresLockProvider;
use distributed_lock_core::prelude::*;

async fn cache_example(provider: &PostgresLockProvider) -> Result<(), LockError> {
    let rw_lock = provider.create_reader_writer_lock("cache");

    // Multiple readers can hold the lock simultaneously
    {
        let read_handle = rw_lock.acquire_read(None).await?;
        let data = read_from_cache().await;
        read_handle.release().await?;
    }

    // Writers get exclusive access
    {
        let write_handle = rw_lock.acquire_write(None).await?;
        update_cache().await;
        write_handle.release().await?;
    }

    Ok(())
}

Semaphores

use distributed_lock_redis::RedisLockProvider;
use distributed_lock_core::prelude::*;
use std::time::Duration;

async fn rate_limit_example(provider: &RedisLockProvider) -> Result<(), LockError> {
    // Allow at most 5 concurrent database connections
    let semaphore = provider.create_semaphore("db-pool", 5);

    // Acquire a "ticket"
    let ticket = semaphore.acquire(Some(Duration::from_secs(10))).await?;

    // Use the limited resource
    query_database().await?;

    // Release the ticket
    ticket.release().await?;
    Ok(())
}

Try-Acquire Pattern

Use try_acquire when you want to check if a lock is available without waiting:

match lock.try_acquire().await? {
    Some(handle) => {
        // We got the lock!
        do_work().await;
        handle.release().await?;
    }
    None => {
        // Someone else has it
        println!("Lock unavailable");
    }
}

Error Handling

use distributed_lock_core::prelude::*;

match lock.acquire(Some(Duration::from_secs(5))).await {
    Ok(handle) => {
        // Got the lock
        handle.release().await?;
    }
    Err(LockError::Timeout(duration)) => {
        eprintln!("Timed out after {:?}", duration);
    }
    Err(LockError::Connection(e)) => {
        eprintln!("Connection error: {}", e);
    }
    Err(e) => {
        eprintln!("Error: {}", e);
    }
}

Architecture

This library is organized as a Cargo workspace with separate crates:

distributed-lock-core: Core traits and types
distributed-lock-file: File system backend
distributed-lock-mysql: MySQL backend
distributed-lock-postgres: PostgreSQL backend
distributed-lock-redis: Redis backend
distributed-lock-mongo: MongoDB backend
distributed-lock: Meta-crate re-exporting all backends

Each backend implements the same trait interfaces, allowing you to swap backends without changing application code.

Requirements

Rust 1.88 or later
Tokio async runtime (for async operations)
Backend-specific requirements:
- PostgreSQL: PostgreSQL 9.5+ with pg_advisory_lock support
- MySQL: MySQL 5.7+ or MariaDB 10.0+ (reader-writer locks create a distributed_locks table)
- Redis: Redis 2.6+ (Redis 3.0+ recommended)
- MongoDB: MongoDB 4.4+ (uses aggregation pipelines in updates)
- File: Any POSIX-compliant filesystem

License

Licensed under the MIT License (LICENSE or http://opensource.org/licenses/MIT).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

This library is inspired by the DistributedLock C# library, ported to Rust with idiomatic patterns and async/await support.

Adding distributed_lock_postgres library as a dependency

Adding `distributed_lock_postgres` library as a dependency