Skip to main content

Crate ch_database

Crate ch_database 

Source
Expand description

§ch-database

ch-database provides database lifecycle, migration, and object-storage primitives behind independent feature flags.

More information is available in the API documentation.

§High-level features

  • SQLx connection pools with retries and bounded migration locking
  • SpacetimeDB connection lifecycle and serialized subscriptions
  • Local and S3-compatible object storage through a common API
  • Redacted diagnostics for connection strings and credentials

Schemas, account models, and authorization policy belong to the consuming application.

§Feature flags

FeatureProvides
mariadbSQLx pools, URL validation/redaction, retries, and migrations; enabled by default
spacetimedbConnection lifecycle, serialized subscriptions, endpoint state, and read-failure handling
s3Local filesystem and S3-compatible object storage

§Usage

use std::{path::Path, time::Duration};

use ch_database::mariadb::{
    migrate::run_migrations,
    pool::{MySqlPoolSettings, connect_mysql_pool_with_options},
};
use sqlx::{migrate::Migrator, mysql::MySqlConnectOptions};

async fn initialize() -> Result<(), Box<dyn std::error::Error>> {
    let options = MySqlConnectOptions::new()
        .host("localhost")
        .username("app")
        .password("database-password")
        .database("app");
    let pool = connect_mysql_pool_with_options(options, &MySqlPoolSettings::default()).await?;
    let migrator = Migrator::new(Path::new("./migrations")).await?;

    run_migrations(&pool, migrator, "app.migrations", Duration::from_secs(30)).await?;
    Ok(())
}

Pass credentials as separate SQLx options when possible. An existing MySQL URL can be passed directly to connect_mysql_pool; SQLx handles percent decoding. URL credentials containing /, ?, #, or a literal % must be percent-encoded. The public normalize_mysql_url helper remains available for existing callers; pool creation does not require a separate normalization step.

All runners for one migration set must use the same non-empty lock name. The timeout limits the server’s lock wait, with server-specific precision, and does not limit migration execution. One connection owns the lock and migrations; closing that connection releases the lock after success, failure, or cancellation.

§Upgrading from 0.1.x

  • Replace run_migrations_with_lock and run_migrations_with_lock_timeout with run_migrations and pass the timeout explicitly.
  • Pass an owned Migrator. An embedded sqlx::migrate! migrator can be a const instead of a static when reused by value.
  • Empty lock names return MigrationError::InvalidLockName instead of disabling the advisory lock.
  • MigrationError has four variants: InvalidLockName, LockUnavailable, Database(sqlx::Error), and Apply(MigrateError). The migration functions return Result<(), MigrationError> directly; MigrationResult and DEFAULT_MIGRATION_LOCK_TIMEOUT were removed.

§Object storage

With s3 enabled, ObjectStoreClient supports local directories, Amazon S3, MinIO, and compatible endpoints. Object keys reject path traversal, absolute paths, and ambiguous separators. Buffered reads have a 64 MiB default limit; get_object exposes a streaming result for larger objects.

§Minimum supported Rust version

ch-database requires Rust 1.99 or newer.

§License

Licensed under the Sustainable Use License 1.0. See LICENSE.md.

Modules§

mariadb
MariaDB and SQLx integration. MariaDB helpers built on top of SQLx.
migration
SQL migration statement parsing.
s3
Local and S3-compatible object storage.
spacetimedb
SpacetimeDB connection lifecycle helpers. Shared SpacetimeDB helper utilities.