ch-database 0.2.1

Database and object storage primitives for SQLx, SpacetimeDB, and S3
Documentation
# 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

| 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

```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).