Drop automatic migration relocation for a documented manual step

Remove the auto relocation + checksum re-stamp from setup() and the
public relocate_legacy_migrations_table / reconcile_migration_checksums helpers.
setup() now just runs migrations.

Docs now cover the two failure modes (function-already-exists on a blind
upgrade, and the empty apalis._sqlx_migrations that then blocks the
ALTER TABLE).

Author: tysen

CHANGELOG.md

@@ -6,10 +6,7 @@
   - `generate_ulid` is now `apalis.generate_ulid` and no longer depends on `pgcrypto` — its random bytes come from core `gen_random_uuid()`. The sole caller (`apalis.push_job`) is repointed and the `public.generate_ulid` copy is dropped (via a new forward migration; existing migrations are not rewritten).
   - The sqlx migrations table is tracked in `apalis._sqlx_migrations` instead of `public._sqlx_migrations` (configured in a new `sqlx.toml`). This also isolates apalis's migration history from a user's own sqlx migrations on the same database, which previously collided over the shared default table name.
 - bump: upgrade `sqlx` 0.8 → 0.9 (required for `sqlx.toml`); remap the runtime/TLS cargo features since 0.9 removed the combined `runtime-*-tls` flags.
-- **Upgrade is automatic when you use `PostgresStorage::setup()`.** On first run it relocates an existing `public._sqlx_migrations` into the `apalis` schema and re-stamps checksums before running migrations, so existing deployments migrate with no manual steps and nothing is re-run. (The only edited migration is the first one — `CREATE SCHEMA` → `CREATE SCHEMA IF NOT EXISTS`, needed so the `apalis` schema can be created before the tracking table on fresh installs — whose checksum is healed automatically.)
-- **If you apply migrations yourself**, `setup()` doesn't run, so on an existing database you perform the one-time transition before upgrading (no-op on fresh databases). The relocation and checksum re-stamp are exposed as `PostgresStorage::relocate_legacy_migrations_table` and `PostgresStorage::reconcile_migration_checksums`:
-  - sqlx CLI, or you copied the migration files into your own project: run the relocation + re-stamp SQL documented under "Upgrading to 1.0" in the README.
-  - you merge `PostgresStorage::migrations()` into your own `Migrator`: your migrator keeps its own tracking table, so don't relocate — just call `reconcile_migration_checksums(&pool, "<your table>")` before running it to heal the one edited migration's checksum.
+- **Existing databases need a one-time manual step before upgrading** (fresh databases need nothing — `sqlx.toml` creates the `apalis` schema and tracking table). Move the migration history into the `apalis` schema and re-stamp the one edited migration's checksum — the first migration changed `CREATE SCHEMA` → `CREATE SCHEMA IF NOT EXISTS` so the `apalis` schema can be created before the tracking table on fresh installs. See "Upgrading to 1.0" in the README for the SQL; it applies to every apply path (`setup()`, sqlx-cli, copied migrations, or a merged `Migrator`).
 - note: `pgcrypto` is no longer used by apalis but is left where an earlier version installed it (usually `public`). If nothing else needs it, you can `DROP EXTENSION pgcrypto;`.
 
 ## [1.0.0-rc.8] - 2026-05-08

README.md

@@ -227,39 +227,33 @@ Track your jobs using [apalis-board](https://github.com/apalis-dev/apalis-board)
 - The sqlx migrations table is now tracked in `apalis._sqlx_migrations` (configured in `sqlx.toml`) instead of `public._sqlx_migrations`. This also keeps apalis's migration history from colliding with your own sqlx migrations on the same database.
 - `generate_ulid()` is now `apalis.generate_ulid()` and no longer depends on the `pgcrypto` extension — its random bytes come from core `gen_random_uuid()`. The `public.generate_ulid()` copy is dropped.
 
-### If you use `PostgresStorage::setup()`
+### Existing databases: one-time manual step
 
-Nothing to do. On the next start, `setup()` relocates an existing `public._sqlx_migrations` into the `apalis` schema and re-stamps checksums before running migrations, so the upgrade is automatic and nothing is re-run.
-
-### If you apply migrations yourself (sqlx-cli, or you copied the migration files into your own project)
-
-`setup()` is what performs the relocation, so paths that bypass it need one manual, one-time step **before** running the 1.0 migrations against an existing database:
+This applies to **every** way of applying migrations — `PostgresStorage::setup()`, sqlx-cli, copied migration files, or a merged `Migrator`. Run this **once per database, before upgrading**:
 
 ```sql
 -- Move apalis's existing migration history into the apalis schema.
 ALTER TABLE public._sqlx_migrations SET SCHEMA apalis;
 
 -- The first migration gained `IF NOT EXISTS` (so the apalis schema can be
 -- created before the tracking table on fresh installs). Re-stamp its checksum
--- so sqlx doesn't reject it as modified:
+-- so the migrator doesn't reject it as modified:
 UPDATE apalis._sqlx_migrations
    SET checksum = decode('d0839c6f57a379769dc27ccd581feb3d2709239c8f138e05271c9e3c760c4517a78a4d8912ab3d63b074b28d15ec74e9', 'hex')
  WHERE version = 20220530084123;
 ```
 
-Fresh databases need none of this — `sqlx.toml` creates the `apalis` schema and tracking table for you.
+Run it **before** upgrading. If you upgrade first without it, the migrator re-runs the first migration against your existing objects and fails with e.g. `function "notify_new_jobs" already exists`. If you've already hit that failure, an empty `apalis._sqlx_migrations` may have been created, which makes the `ALTER TABLE` above fail because the name is taken — drop it first:
 
-### If you merge `PostgresStorage::migrations()` into your own `Migrator`
+```sql
+DROP TABLE apalis._sqlx_migrations;
+```
 
-Your migrator owns its own tracking table, so it doesn't move to `apalis` and you don't run the relocation above. You only need to heal the one edited migration's checksum so your migrator doesn't reject it as modified. On an existing database, before running your migrator:
+then run the two statements above.
 
-```rust
-// `_sqlx_migrations` (or whatever table your Migrator uses)
-PostgresStorage::reconcile_migration_checksums(&pool, "_sqlx_migrations").await?;
-merged_migrator.run(&pool).await?;
-```
+If you maintain your **own** `Migrator` (merging in `PostgresStorage::migrations()`), your tracking table stays where it is — skip the `ALTER TABLE` and run only the `UPDATE`, targeting your table name.
 
-It is a no-op on fresh databases.
+Fresh databases need none of this — `sqlx.toml` creates the `apalis` schema and tracking table for you.
 
 ### `pgcrypto`
 

src/lib.rs

@@ -113,85 +113,16 @@ impl<Args, Compact, Codec, Fetcher: Clone> Clone
 impl PostgresStorage<(), (), ()> {
     /// Perform migrations for storage.
     ///
-    /// On an existing database this also performs the one-time `1.0` migration
-    /// history transition before running migrations, so upgrades are automatic.
-    /// If you instead merge [`migrations()`](Self::migrations) into your own
-    /// [`Migrator`](sqlx::migrate::Migrator), you bypass `setup()` — call
-    /// [`reconcile_migration_checksums`](Self::reconcile_migration_checksums)
-    /// against that migrator's table before running it.
+    /// On an existing (pre-`1.0`) database, run the one-time transition documented
+    /// under "Upgrading to 1.0" in the README before calling this — `setup()` no
+    /// longer relocates the migration history automatically. Fresh databases need
+    /// no manual steps.
     #[cfg(feature = "migrate")]
     pub async fn setup(pool: &PgPool) -> Result<(), sqlx::Error> {
-        Self::relocate_legacy_migrations_table(pool).await?;
-        Self::reconcile_migration_checksums(pool, "apalis._sqlx_migrations").await?;
         Self::migrations().run(pool).await?;
         Ok(())
     }
 
-    /// Move apalis's pre-`1.0` migration history from `public._sqlx_migrations`
-    /// into `apalis._sqlx_migrations`, where `1.0` tracks it. No-op once the
-    /// `apalis` table exists or on fresh databases. Does not re-stamp checksums.
-    #[cfg(feature = "migrate")]
-    pub async fn relocate_legacy_migrations_table(pool: &PgPool) -> Result<(), sqlx::Error> {
-        let needs_relocation: bool = sqlx::query_scalar(
-            "SELECT to_regclass('public._sqlx_migrations') IS NOT NULL \
-                AND to_regclass('apalis._sqlx_migrations') IS NULL",
-        )
-        .fetch_one(pool)
-        .await?;
-        if !needs_relocation {
-            return Ok(());
-        }
-
-        // Only adopt a table that is apalis's: a user's own won't have this row.
-        let is_apalis_table: bool = sqlx::query_scalar(
-            "SELECT EXISTS (SELECT 1 FROM public._sqlx_migrations WHERE version = 20220530084123)",
-        )
-        .fetch_one(pool)
-        .await?;
-        if !is_apalis_table {
-            return Ok(());
-        }
-
-        sqlx::query("CREATE SCHEMA IF NOT EXISTS apalis")
-            .execute(pool)
-            .await?;
-        sqlx::query("ALTER TABLE public._sqlx_migrations SET SCHEMA apalis")
-            .execute(pool)
-            .await?;
-        Ok(())
-    }
-
-    /// Re-stamp the checksum of any migration whose content changed in `1.0` (only
-    /// the first, which gained `IF NOT EXISTS`) so an existing table isn't rejected
-    /// as modified. `setup()` calls this; call it yourself only when merging
-    /// [`migrations()`](Self::migrations) into your own
-    /// [`Migrator`](sqlx::migrate::Migrator), passing its table (e.g.
-    /// `"_sqlx_migrations"`), before you run it. No-op if `table` is fresh or absent.
-    #[cfg(feature = "migrate")]
-    pub async fn reconcile_migration_checksums(
-        pool: &PgPool,
-        table: &str,
-    ) -> Result<(), sqlx::Error> {
-        let table_exists: bool = sqlx::query_scalar("SELECT to_regclass($1) IS NOT NULL")
-            .bind(table)
-            .fetch_one(pool)
-            .await?;
-        if !table_exists {
-            return Ok(());
-        }
-
-        let update =
-            format!("UPDATE {table} SET checksum = $1 WHERE version = $2 AND checksum <> $1");
-        for migration in Self::migrations().iter() {
-            sqlx::query(sqlx::AssertSqlSafe(update.clone()))
-                .bind(migration.checksum.as_ref())
-                .bind(migration.version)
-                .execute(pool)
-                .await?;
-        }
-        Ok(())
-    }
-
     /// Get postgres migrations without running them
     #[cfg(feature = "migrate")]
     pub fn migrations() -> sqlx::migrate::Migrator {