transact-rs/sqlx · error

DATABASE_URL must be set

Error message

DATABASE_URL must be set

What it means

This is a panic (via expect) raised during sqlx's test harness startup when `#[sqlx::test]` needs to clean up leftover test databases. The cleanup routine requires a live PostgreSQL connection string to reach the master database, and it reads that connection from the DATABASE_URL environment variable. It fires when the variable is not set in the environment (and not present in a .env file, since dotenvy::var is used), meaning no Postgres server is configured for the test run. Set DATABASE_URL to a Postgres connection URL with master-database privileges before running tests.

Source

Thrown at sqlx-postgres/src/testing/mod.rs:42

impl TestSupport for Postgres {
    fn test_context(
        args: &TestArgs,
    ) -> impl Future<Output = Result<TestContext<Self>, Error>> + Send + '_ {
        test_context(args)
    }

    async fn cleanup_test(db_name: &str) -> Result<(), Error> {
        let mut conn = MASTER_POOL
            .get()
            .expect("cleanup_test() invoked outside `#[sqlx::test]`")
            .acquire()
            .await?;

        do_cleanup(&mut conn, db_name).await
    }

    async fn cleanup_test_dbs() -> Result<Option<usize>, Error> {
        let url = dotenvy::var("DATABASE_URL").expect("DATABASE_URL must be set");

        let mut conn = PgConnection::connect(&url).await?;

        let delete_db_names: Vec<String> = query_scalar("select db_name from _sqlx_test.databases")
            .fetch_all(&mut conn)
            .await?;

        if delete_db_names.is_empty() {
            return Ok(None);
        }

        let mut deleted_db_names = Vec::with_capacity(delete_db_names.len());

        let mut builder = QueryBuilder::new("drop database if exists ");

        for db_name in &delete_db_names {
            builder.push(db_name);

View on GitHub (pinned to 03af8bcc57)

Solutions

1. Provide `.env` at the crate root: `DATABASE_URL=postgres://user:pass@localhost/postgres`.
2. Export DATABASE_URL in the shell or CI job before running tests.
3. Run tests from the workspace/crate directory containing `.env`.
4. Confirm dotenvy is reachable (feature enabled) if you rely on `.env` loading.

Example fix

// .env
// before (missing)
// after
DATABASE_URL=postgres://postgres:password@localhost/postgres

let url = std::env::var("DATABASE_URL")
    .or_else(|_| dotenvy::var("DATABASE_URL"))
    .unwrap_or_else(|_| panic!("DATABASE_URL must be set (env or .env) before cleanup_test_dbs"));
assert!(url.starts_with("postgres://") || url.starts_with("postgresql://"));

When it happens

Trigger: Invoking `cleanup_test_dbs` without DATABASE_URL in env and without a `.env` file in the process working directory.

Common situations: CI missing the DATABASE_URL variable; running tests from a directory without the `.env`; renaming the env var or forgetting to source it after shell re-login.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• DATABASE_URL must be set
• cleanup_test() invoked outside `#[sqlx::test]`
• failed to parse DATABASE_URL
• failed to close setup connection
• cleanup_test() invoked outside `#[sqlx::test]`

AI-assisted analysis of transact-rs/sqlx@03af8bcc57 (2026-09-03). Data as JSON: /api/errors/cee922f2afe36d59. Report an issue: GitHub.