From 959e69802506cf677dc4d93cc92ac3fd54f38cc6 Mon Sep 17 00:00:00 2001 From: zerosnacks <95942363+zerosnacks@users.noreply.github.com> Date: Sat, 19 Sep 2026 18:33:38 +0200 Subject: [PATCH] docs: recommend the bundled schema Recommend steda::SCHEMA_SQL as the default way for Rust applications to install and upgrade the Steda database schema, keeping the database artifact tied directly to the linked crate release. Document the standalone steda.sql release artifact as the equivalent option for deployments that manage schema installation outside Rust. Update the runnable examples to use the public bundled schema rather than reading the repository SQL file directly. --- README.md | 23 +++++++++++++++++++---- examples/README.md | 7 ++++--- examples/common/mod.rs | 4 ++-- src/lib.rs | 21 +++++++++++++-------- 4 files changed, 38 insertions(+), 17 deletions(-) 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};