feat(postgres): add locking attribute to #[sqlx::test]

Add a `locking` parameter to `#[sqlx::test]` that controls whether an
advisory lock is acquired before creating the test database schema.
Defaults to `true` to preserve existing PostgreSQL behavior.

Setting `locking = false` allows `#[sqlx::test]` to work with databases
that speak the PostgreSQL wire protocol but do not implement advisory
locks, such as CockroachDB. When disabled, migrator locking is also
skipped so the entire test setup is advisory-lock-free.

Follows the same pattern as `Migrator::set_locking()` (PR #2063).

Author: mpecan

sqlx-core/src/testing/mod.rs

@@ -66,6 +66,7 @@ pub struct TestArgs {
     pub test_path: &'static str,
     pub migrator: Option<&'static Migrator>,
     pub fixtures: &'static [TestFixture],
+    pub locking: bool,
 }
 
 pub trait TestFn {
@@ -158,6 +159,7 @@ impl TestArgs {
             test_path,
             migrator: None,
             fixtures: &[],
+            locking: true,
         }
     }
 
@@ -168,6 +170,10 @@ impl TestArgs {
     pub fn fixtures(&mut self, fixtures: &'static [TestFixture]) {
         self.fixtures = fixtures;
     }
+
+    pub fn set_locking(&mut self, locking: bool) {
+        self.locking = locking;
+    }
 }
 
 impl TestTermination for () {
@@ -255,7 +261,24 @@ async fn setup_test_db<DB: Database>(
         .await
         .expect("failed to connect to test database");
 
-    if let Some(migrator) = args.migrator {
+    if let Some(static_migrator) = args.migrator {
+        // When test locking is disabled, also disable locking in the migrator.
+        // This is required for databases that don't support advisory locks (e.g. CockroachDB).
+        let owned_migrator;
+        let migrator = if args.locking {
+            static_migrator
+        } else {
+            owned_migrator = Migrator {
+                locking: false,
+                migrations: static_migrator.migrations.clone(),
+                ignore_missing: static_migrator.ignore_missing,
+                no_tx: static_migrator.no_tx,
+                table_name: static_migrator.table_name.clone(),
+                create_schemas: static_migrator.create_schemas.clone(),
+            };
+            &owned_migrator
+        };
+
         migrator
             .run_direct(None, &mut conn)
             .await

sqlx-macros-core/src/test_attr.rs

@@ -6,6 +6,7 @@ use syn::parse::Parser;
 struct Args {
     fixtures: Vec<(FixturesType, Vec<syn::LitStr>)>,
     migrations: MigrationsOpt,
+    locking: Option<bool>,
 }
 
 #[cfg(feature = "migrate")]
@@ -143,6 +144,11 @@ fn expand_advanced(args: AttributeArgs, input: syn::ItemFn) -> crate::Result<Tok
         fixtures.append(&mut res)
     }
 
+    let locking = args
+        .locking
+        .map(|value| quote! { args.set_locking(#value); })
+        .unwrap_or_default();
+
     let migrations = match args.migrations {
         MigrationsOpt::ExplicitPath(path) => {
             let migrator = crate::migrate::expand(Some(path))?;
@@ -180,6 +186,8 @@ fn expand_advanced(args: AttributeArgs, input: syn::ItemFn) -> crate::Result<Tok
 
             args.fixtures(&[#(#fixtures),*]);
 
+            #locking
+
             // We need to give a coercion site or else we get "unimplemented trait" errors.
             let f: fn(#(#fn_arg_types),*) -> _ = #name;
 
@@ -197,6 +205,7 @@ fn parse_args(attr_args: AttributeArgs) -> syn::Result<Args> {
 
     let mut fixtures = Vec::new();
     let mut migrations = MigrationsOpt::InferredPath;
+    let mut locking = None;
 
     for arg in attr_args {
         let path = arg.path().clone();
@@ -292,10 +301,28 @@ fn parse_args(attr_args: AttributeArgs) -> syn::Result<Args> {
 
                 migrations = MigrationsOpt::ExplicitMigrator(lit.parse()?);
             }
+            Meta::NameValue(MetaNameValue { value, .. }) if path.is_ident("locking") => {
+                if locking.is_some() {
+                    return Err(syn::Error::new_spanned(
+                        path,
+                        "cannot have more than one `locking` arg",
+                    ));
+                }
+
+                let Expr::Lit(syn::ExprLit {
+                    lit: Lit::Bool(lit),
+                    ..
+                }) = value
+                else {
+                    return Err(syn::Error::new_spanned(path, "expected `true` or `false`"));
+                };
+
+                locking = Some(lit.value);
+            }
             arg => {
                 return Err(syn::Error::new_spanned(
                     arg,
-                    r#"expected `fixtures("<filename>", ...)` or `migrations = "<path>" | false` or `migrator = "<rust path>"`"#,
+                    r#"expected `fixtures("<filename>", ...)` or `migrations = "<path>" | false` or `migrator = "<rust path>"` or `locking = true | false`"#,
                 ))
             }
         }
@@ -304,6 +331,7 @@ fn parse_args(attr_args: AttributeArgs) -> syn::Result<Args> {
     Ok(Args {
         fixtures,
         migrations,
+        locking,
     })
 }
 

sqlx-postgres/src/testing/mod.rs

@@ -125,31 +125,44 @@ async fn test_context(args: &TestArgs) -> Result<TestContext<Postgres>, Error> {
 
     let mut conn = master_pool.acquire().await?;
 
-    // language=PostgreSQL
-    conn.execute(
-        // Explicit lock avoids this latent bug: https://stackoverflow.com/a/29908840
-        // I couldn't find a bug on the mailing list for `CREATE SCHEMA` specifically,
-        // but a clearly related bug with `CREATE TABLE` has been known since 2007:
-        // https://www.postgresql.org/message-id/200710222037.l9MKbCJZ098744%40wwwmaster.postgresql.org
-        // magic constant 8318549251334697844 is just 8 ascii bytes 'sqlxtest'.
+    // Explicit lock avoids this latent bug: https://stackoverflow.com/a/29908840
+    // I couldn't find a bug on the mailing list for `CREATE SCHEMA` specifically,
+    // but a clearly related bug with `CREATE TABLE` has been known since 2007:
+    // https://www.postgresql.org/message-id/200710222037.l9MKbCJZ098744%40wwwmaster.postgresql.org
+    // magic constant 8318549251334697844 is just 8 ascii bytes 'sqlxtest'.
+    //
+    // The lock and DDL must be in a single `execute` call so they share one implicit
+    // transaction — `pg_advisory_xact_lock` is released at transaction end.
+    //
+    // Can be disabled with `#[sqlx::test(locking = false)]` for databases that do not
+    // implement advisory locks, such as CockroachDB.
+    let lock_sql = if args.locking {
+        "select pg_advisory_xact_lock(8318549251334697844);"
+    } else {
+        ""
+    };
+
+    let setup_sql = format!(
+        // language=PostgreSQL
         r#"
-        select pg_advisory_xact_lock(8318549251334697844);
+            {lock_sql}
+
+            create schema if not exists _sqlx_test;
 
-        create schema if not exists _sqlx_test;
+            create table if not exists _sqlx_test.databases (
+                db_name text primary key,
+                test_path text not null,
+                created_at timestamptz not null default now()
+            );
 
-        create table if not exists _sqlx_test.databases (
-            db_name text primary key,
-            test_path text not null,
-            created_at timestamptz not null default now()
-        );
+            create index if not exists databases_created_at
+                on _sqlx_test.databases(created_at);
 
-        create index if not exists databases_created_at 
-            on _sqlx_test.databases(created_at);
+            create sequence if not exists _sqlx_test.database_ids;
+        "#
+    );
 
-        create sequence if not exists _sqlx_test.database_ids;
-    "#,
-    )
-    .await?;
+    conn.execute(AssertSqlSafe(setup_sql)).await?;
 
     let db_name = Postgres::db_name(args);
     do_cleanup(&mut conn, &db_name).await?;

src/macros/test.md

@@ -226,4 +226,34 @@ Multiple `fixtures` attributes can be used to combine different operating modes.
 <sup>3</sup>Ordering for test fixtures is entirely up to the application, and each test may choose which fixtures to
 apply and which to omit. However, since each fixture is applied separately (sent as a single command string, so wrapped
 in an implicit `BEGIN` and `COMMIT`), you will want to make sure to order the fixtures such that foreign key
-requirements are always satisfied, or else you might get errors. 
+requirements are always satisfied, or else you might get errors.
+
+### Disabling Advisory Locking (requires `migrate` feature)
+
+By default, `#[sqlx::test]` acquires a PostgreSQL advisory lock (`pg_advisory_xact_lock`) before creating the test
+database schema and also locks during migrations. This prevents a race condition when multiple tests run concurrently.
+
+Some databases speak the PostgreSQL wire protocol but do not implement advisory locks.
+For example, CockroachDB does not support `pg_advisory_xact_lock`
+(see [cockroachdb/cockroach#13546](https://github.com/cockroachdb/cockroach/issues/13546)).
+
+You can disable locking with the `locking` attribute:
+
+```rust,no_run
+# #[cfg(all(feature = "migrate", feature = "postgres"))]
+# mod example {
+use sqlx::PgPool;
+
+#[sqlx::test(locking = false)]
+async fn test_on_cockroachdb(pool: PgPool) -> sqlx::Result<()> {
+    // The test database was created without advisory locks.
+    // Migrations also run without advisory locks.
+    Ok(())
+}
+# }
+```
+
+This follows the same pattern as [`Migrator::set_locking(false)`](crate::migrate::Migrator::set_locking).
+
+**Note:** Disabling locking means concurrent test processes may race during schema setup. The DDL statements
+use `IF NOT EXISTS` so this is generally safe, but you should be aware of the trade-off.

tests/postgres/test-attr.rs

@@ -199,3 +199,26 @@ macro_rules! macro_using_test {
     };
 }
 macro_using_test!("tests/postgres/migrations");
+
+// Verify that `locking = false` compiles and produces a valid test.
+//
+// This test is NOT safe to run concurrently with other `#[sqlx::test]` tests against the
+// same Postgres server because the advisory lock exists to guard a race in
+// `CREATE SCHEMA IF NOT EXISTS`. The `locking = false` flag is intended for databases
+// like CockroachDB that serialize DDL and don't support advisory locks.
+//
+// We use `migrations = false` and `#[ignore]` so this compiles (proving the attribute
+// parses correctly) but doesn't race with other tests in CI.
+#[sqlx::test(migrations = false, locking = false)]
+#[ignore]
+async fn it_works_without_locking(pool: PgPool) -> sqlx::Result<()> {
+    let mut conn = pool.acquire().await?;
+
+    let db_name: String = sqlx::query_scalar("SELECT current_database()")
+        .fetch_one(&mut *conn)
+        .await?;
+
+    assert!(db_name.starts_with("_sqlx_test"), "dbname: {db_name:?}");
+
+    Ok(())
+}