Crate uri_register 

URI Register

A URI to integer registration service with PostgreSQL backend.

This library provides a bidirectional mapping between URIs (strings) and integer IDs, optimised for batch operations and designed for use in distributed systems where stateless compute nodes need fast access to a global identifier registry.

API: Both async (PostgresUriRegister) and sync (SyncPostgresUriRegister) APIs available. It is designed to mirror the API and behaviour of the Python py-json-register library.

Features

• Async-only - Built on tokio/sqlx for high concurrency
• Batch operations - Efficiently lookup or create thousands of mappings at once
• PostgreSQL backend - Durable, scalable, with connection pooling
• Configurable caching - W-TinyLFU (Moka) or LRU caching for frequently accessed URIs
• Flexible table types - Support for both logged (durable) and unlogged (faster) tables

Use Cases

• String interning systems
• URL/URI deduplication and ID assignment
• Global identifier systems
• Any system needing global, persistent string-to-ID mappings

Example

use uri_register::{PostgresUriRegister, UriService};

#[tokio::main]
async fn main() -> uri_register::Result<()> {
    // Connect to PostgreSQL (schema must be initialized first)
    let register = PostgresUriRegister::new(
        "postgres://localhost/mydb",
        "uri_register",  // table name
        20,              // max connections
        10_000,          // cache size (uses Moka/W-TinyLFU by default)
        3,               // max retries
        100,             // initial backoff (ms)
        5000             // max backoff (ms)
    ).await?;

    // Register a single URI
    let id = register.register_uri("http://example.org/resource/1").await?;
    println!("URI registered with ID: {}", id);

    // Register multiple URIs in batch (much faster!)
    let uris = vec![
        "http://example.org/resource/2".to_string(),
        "http://example.org/resource/3".to_string(),
        "http://example.org/resource/4".to_string(),
    ];
    let ids = register.register_uri_batch(&uris).await?;

    // IDs maintain order: ids[i] corresponds to uris[i]
    for (uri, id) in uris.iter().zip(ids.iter()) {
        println!("{} -> {}", uri, id);
    }

    Ok(())
}

Structs

CacheStats

Cache performance statistics for observability

PoolStats

Connection pool statistics for observability

PostgresUriRegister

PostgreSQL-based URI register implementation with configurable caching

RegisterStats

Statistics about the URI register for observability and OpenTelemetry

SyncPostgresUriRegister

Synchronous PostgreSQL URI register

Enums

CacheStrategy

Cache strategy for URI-to-ID mapping

ConfigurationError

Configuration error types with specific variants

Error

Error types for URI register operations

Traits

UriService

A service for registering URIs and assigning unique integer IDs

Type Aliases

Result

Result type alias for URI register operations