transact-rs/sqlx · error

DATABASE_URL must be set

Error message

DATABASE_URL must be set

What it means

MySQL `cleanup_test_dbs` removes leftover `_sqlx_test_databases` entries and needs to connect directly to the server, so it reads `DATABASE_URL` via `dotenvy::var(..).expect(..)`. It panics when the variable is not set in the environment or a `.env` file.

Source

Thrown at sqlx-mysql/src/testing/mod.rs:40

impl TestSupport for MySql {
    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 = MySqlConnection::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. Create a `.env` file in the crate root containing `DATABASE_URL=mysql://user:pass@localhost/db`.
2. Export DATABASE_URL in the shell/CI before running tests.
3. Run `cargo test` from the directory containing the `.env` file.
4. For CI, add the DATABASE_URL environment variable to the test job configuration.

Example fix

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

// Validate before invoking cleanup:
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("mysql://"), "DATABASE_URL must be a MySQL URL");

When it happens

Trigger: Invoking `cleanup_test_dbs` (e.g. via the testing cleanup entry point) without `DATABASE_URL` in the environment and without a `.env` file in the working directory.

Common situations: Running `cargo test` from a subdirectory so `.env` at the repo root isn't found; CI pipeline missing the DATABASE_URL secret; dotenvy only loads `.env` from the crate's cwd at runtime.

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

• cleanup_test() invoked outside `#[sqlx::test]`
• failed to parse DATABASE_URL
• DATABASE_URL must be set
• 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/1d9f50bdfd4ee7fa. Report an issue: GitHub.