# ch-database
`ch-database` provides database lifecycle, migration, and object-storage
primitives behind independent feature flags.
More information is available in the
[API documentation](https://docs.rs/ch-database).
## 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
| `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
```rust,no_run
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`](LICENSE.md).