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
| Feature | Provides |
|---|---|
mariadb | SQLx pools, URL validation/redaction, retries, and migrations; enabled by default |
spacetimedb | Connection lifecycle, serialized subscriptions, endpoint state, and read-failure handling |
s3 | Local 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_lockandrun_migrations_with_lock_timeoutwithrun_migrationsand pass the timeout explicitly. - Pass an owned
Migrator. An embeddedsqlx::migrate!migrator can be aconstinstead of astaticwhen reused by value. - Empty lock names return
MigrationError::InvalidLockNameinstead of disabling the advisory lock. MigrationErrorhas four variants:InvalidLockName,LockUnavailable,Database(sqlx::Error), andApply(MigrateError). The migration functions returnResult<(), MigrationError>directly;MigrationResultandDEFAULT_MIGRATION_LOCK_TIMEOUTwere 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.