Struct PostgresUriRegister 

pub struct PostgresUriRegister { /* private fields */ }

PostgreSQL-based URI register implementation with configurable caching

This implementation uses a PostgreSQL table to store URI-to-ID mappings with an in-memory cache (W-TinyLFU by default, or LRU) to reduce database round-trips. It’s designed for high concurrency with connection pooling and batch operations.

Prerequisites

The database schema must be initialized before using this service. See schema.sql for the DDL statements.

URI Validation

All URIs are validated before registration to ensure they conform to RFC 3986. Invalid URIs will return an error.

Performance

With default logged tables on typical hardware:

• Batch insert: ~10K-50K URIs/sec
• Batch lookup (cached): ~100K-1M+ URIs/sec (no DB round-trip)
• Batch lookup (uncached): ~100K-200K URIs/sec
• Query overhead: ~2-10ms per query (2 round-trips)

The cache (W-TinyLFU or LRU) significantly improves performance for repeated URI lookups. Cache strategy and size are configurable when creating the register instance.

For faster writes at the cost of durability, the table can be configured as UNLOGGED (see schema.sql for options).

Implementations

impl PostgresUriRegister

pub async fn new( database_url: &str, table_name: &str, max_connections: u32, cache_size: usize, ) -> Result<Self>

Create a new PostgreSQL URI register service with configurable cache

Arguments

• database_url - PostgreSQL connection string (e.g., “postgres://user:password@host:port/database”)
• table_name - Name of the database table to use (must be a valid SQL identifier, default: “uri_register”)
• max_connections - Maximum number of connections in the pool (recommended: 10-50)
• cache_size - Number of URI-to-ID mappings to cache in memory (recommended: 1,000-100,000)
• cache_strategy - Cache strategy to use (Moka/W-TinyLFU is default and recommended for most workloads)

Prerequisites

The database schema must be initialized before using this service. See the schema.sql file and README.md for setup instructions.

Example

use uri_register::PostgresUriRegister;

#[tokio::main]
async fn main() -> uri_register::Result<()> {
    let register = PostgresUriRegister::new(
        "postgres://localhost/mydb",
        "uri_register",  // table name
        20,              // max connections
        10_000           // cache size (defaults to Moka/W-TinyLFU)
    ).await?;
    Ok(())
}

pub async fn new_with_cache_strategy( database_url: &str, table_name: &str, max_connections: u32, cache_size: usize, cache_strategy: Option<CacheStrategy>, use_tls: Option<bool>, ) -> Result<Self>

Create a new PostgreSQL URI register with a specific cache strategy and TLS

This is identical to new() but allows specifying a cache strategy and TLS option. Most users should use new() which defaults to the recommended Moka (W-TinyLFU) cache and no TLS.

Arguments

• cache_strategy - Optional cache strategy (None = Moka default, or specify CacheStrategy::Lru)
• use_tls - Optional TLS flag (None/false = no TLS, true = TLS with webpki root certificates)

Example

use uri_register::{CacheStrategy, PostgresUriRegister};

#[tokio::main]
async fn main() -> uri_register::Result<()> {
    // Use LRU instead of default Moka, with TLS enabled
    let register = PostgresUriRegister::new_with_cache_strategy(
        "postgres://localhost/mydb",
        "uri_register",
        20,
        10_000,
        Some(CacheStrategy::Lru),
        Some(true)  // Enable TLS
    ).await?;
    Ok(())
}

pub async fn stats(&self) -> Result<RegisterStats>

Get statistics about the URI register

Returns the total number of URIs and the storage size.

Example

use uri_register::PostgresUriRegister;

#[tokio::main]
async fn main() -> uri_register::Result<()> {
    let register = PostgresUriRegister::new(
        "postgres://localhost/mydb",
        "uri_register",
        20,
        10_000
    ).await?;
    let stats = register.stats().await?;
    println!("Total URIs: {}", stats.total_uris);
    println!("Size: {} bytes", stats.size_bytes);
    Ok(())
}

Trait Implementations

impl UriService for PostgresUriRegister

fn register_uri<'life0, 'life1, 'async_trait>( &'life0 self, uri: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<u64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Register a single URI and return its ID

fn register_uri_batch<'life0, 'life1, 'async_trait>( &'life0 self, uris: &'life1 [String], ) -> Pin<Box<dyn Future<Output = Result<Vec<u64>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Register multiple URIs in batch and return their IDs

fn register_uri_batch_hashmap<'life0, 'life1, 'async_trait>( &'life0 self, uris: &'life1 [String], ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, u64>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Register multiple URIs in batch and return a HashMap of URI-to-ID mappings