diff --git a/README.md b/README.md index 42cce52..c6e1630 100644 --- a/README.md +++ b/README.md @@ -50,15 +50,30 @@ Steda requires PostgreSQL 18+. See [MSRV](#msrv) for supported Rust versions. cargo add steda ``` -Download `steda.sql` from the matching [Steda release](https://github.com/selemis-com/steda/releases) and apply it atomically before starting producers or workers: +Apply [`steda::SCHEMA_SQL`](https://docs.rs/steda/latest/steda/constant.SCHEMA_SQL.html) +atomically before starting producers or workers. This is the recommended integration path because +the bundled schema always matches the linked Steda crate release. + +For example, applications that already use SQLx can apply it during database bootstrap: + +```rust +sqlx::raw_sql(steda::SCHEMA_SQL).execute(&pool).await?; +``` + +If schema installation is managed outside Rust, each +[Steda release](https://github.com/selemis-com/steda/releases) also publishes the same schema as +`steda.sql`: ```sh psql "$DATABASE_URL" --single-transaction -v ON_ERROR_STOP=1 -f steda.sql ``` -Applications that own database bootstrap can instead apply [`steda::SCHEMA_SQL`](https://docs.rs/steda/latest/steda/constant.SCHEMA_SQL.html) from the linked crate release in the same atomic manner. - -When upgrading Steda, apply the new release's `steda.sql` the same way before starting binaries built against that release. Database upgrades remain compatible within a major release line. A future major release may introduce breaking storage changes and require an explicit migration procedure, such as draining workers or running a one-time upgrade script. Any such requirements will be documented in the release notes. Mixed-version deployments are not guaranteed unless a release explicitly states otherwise. +When upgrading Steda, reapply `SCHEMA_SQL` from the new crate release, or the matching +`steda.sql` artifact, before starting binaries built against that release. Database upgrades remain +compatible within a major release line. A future major release may introduce breaking storage +changes and require an explicit migration procedure, such as draining workers or running a one-time +upgrade script. Any such requirements will be documented in the release notes. Mixed-version +deployments are not guaranteed unless a release explicitly states otherwise. ## Features diff --git a/examples/README.md b/examples/README.md index 05305ca..1934265 100644 --- a/examples/README.md +++ b/examples/README.md @@ -11,9 +11,10 @@ Set `DATABASE_URL` to a PostgreSQL database that the current user can use: export DATABASE_URL=postgres://steda:steda@127.0.0.1:5432/steda_test ``` -Every example applies the bundled `sql/steda.sql` schema and creates its own `example-*` queue. -Production deployments apply the matching release's `steda.sql` before starting producers and -workers. +Every example applies [`steda::SCHEMA_SQL`](https://docs.rs/steda/latest/steda/constant.SCHEMA_SQL.html) +and creates its own `example-*` queue. Production Rust applications should likewise apply the bundled schema +atomically before starting producers and workers; deployments that install schemas outside Rust can use the +equivalent `steda.sql` release artifact. ## `basic_task` diff --git a/examples/common/mod.rs b/examples/common/mod.rs index f851fc2..c8740ba 100644 --- a/examples/common/mod.rs +++ b/examples/common/mod.rs @@ -8,7 +8,7 @@ use std::{ time::{SystemTime, UNIX_EPOCH}, }; -use steda::{Error, Result, Steda, Worker}; +use steda::{Error, Result, SCHEMA_SQL, Steda, Worker}; use tokio::{sync::oneshot, task::JoinHandle}; /// Connect to `PostgreSQL` and apply the bundled Steda schema for an example run. @@ -25,7 +25,7 @@ pub(super) async fn connect() -> Result { ) })?; let steda = Steda::connect(&database_url).await?; - sqlx::raw_sql(include_str!("../../sql/steda.sql")).execute(steda.pool()).await?; + sqlx::raw_sql(SCHEMA_SQL).execute(steda.pool()).await?; Ok(steda) } diff --git a/src/lib.rs b/src/lib.rs index 82706dd..e9783dd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,10 +10,11 @@ //! //! # Installation //! -//! Add the `steda` crate and apply the `sql/steda.sql` file from the same release to the target -//! database before producers or workers start. Apply it atomically. With `psql`, use -//! `--single-transaction -v ON_ERROR_STOP=1`. Reapply the new release's `steda.sql` the same way -//! when upgrading. +//! Add the `steda` crate and apply [`SCHEMA_SQL`] atomically to the target database before +//! producers or workers start. This is the recommended installation path because the bundled +//! schema always matches the linked Steda crate release. Reapply [`SCHEMA_SQL`] from the new +//! release when upgrading. Deployments that install schemas outside Rust can use the equivalent +//! `steda.sql` artifact published with each release. //! //! Steda has no default crate features. Enable `tls-rustls` or `tls-native-tls` when //! [`Steda::connect`] needs TLS support. @@ -208,8 +209,10 @@ //! //! ## Schema and queue lifecycle //! -//! Apply the `sql/steda.sql` file from the Steda release before code that depends on that schema -//! begins spawning or claiming work. Apply the new release's file again when upgrading. +//! Apply [`SCHEMA_SQL`] atomically before code that depends on the Steda schema begins spawning +//! or claiming work. Reapply the value bundled with the new crate release when upgrading. The +//! release `steda.sql` artifact contains the same schema for deployments that install it outside +//! Rust. //! //! [`Steda::queue`] creates a lightweight handle only. [`Queue::create`] creates its durable //! queue-specific `PostgreSQL` storage and is idempotent for a healthy existing queue. Repeated @@ -322,8 +325,10 @@ pub mod middleware { /// Complete re-applicable PostgreSQL schema artifact for this Steda release. /// -/// Applications that own database bootstrap may apply this SQL atomically before starting -/// producers or workers. Reapply the value from the new Steda release when upgrading. +/// Applying this SQL atomically during database bootstrap is the recommended way to install +/// Steda's schema because it always matches the linked crate release. Reapply the value from the +/// new Steda release when upgrading. Deployments that install schemas outside Rust can use the +/// equivalent `steda.sql` release artifact. pub const SCHEMA_SQL: &str = include_str!("../sql/steda.sql"); pub use context::{TaskContext, TaskWait};