docs: recommend the bundled schema

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
 

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`
 

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<Steda> {
         )
     })?;
     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)
 }
 

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};