`cargo sqlx prepare` fails with prompting the user to run `cargo sqlx prepare`

[cgonyeo]

I have found these related issues/pull requests

https://github.com/launchbadge/sqlx/issues/3023 mentions this issue but this issue isn't the central focus of it, so a new issue seems appropriate.

Description

I'm new to using sqlx, my goal is to use it to write a simple rust web server that stores some state in a sqlite database. I'm trying to set the project up to build in offline mode. Following the sqlx-cli readme, I ran:

cargo install sqlx-cli
cargo sqlx prepare

The second of these commands fails, by telling me to run cargo sqlx prepare:

~/git/claires-file-server main !2 ?1 ❯ cargo sqlx prepare
    Checking claires-file-server v0.1.0 (/home/claire/git/claires-file-server)
error: set `DATABASE_URL` to use query macros online, or run `cargo sqlx prepare` to update the query cache
  --> src/main.rs:15:20
   |
35 |     let response = sqlx::query!("SELECT filepath FROM files WHERE id = ?", id)
   |                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this error originates in the macro `$crate::sqlx_macros::expand_query` which comes from the expansion of the macro `sqlx::query` (in Nightly builds, run with -Z macro-backtrace for more info)

I'm at a bit of a loss as to what to do from here. I couldn't find an answer in your FAQ, and the error message "run cargo sqlx prepare" is less than useful when produced by the command cargo sqlx prepare. I don't know if I've stumbled into a bug, or just a bad UX scenario.

Reproduction steps

src/main.rs:

#[macro_use]
extern crate rocket;
use rocket::fairing::{self, AdHoc};
use rocket::fs::NamedFile;
use rocket_db_pools::{Database, Connection};
use rocket_db_pools::sqlx;
use rocket::{Rocket, Build};

#[derive(Database)]
#[database("files")]
struct FilesDatabase(sqlx::SqlitePool);

#[get("/get_file/<id>")]
async fn get_file(mut db: Connection<FilesDatabase>, id: String) -> Option<NamedFile> {
    let response = sqlx::query!("SELECT filepath FROM files WHERE id = ?", id)
        .fetch_one(&mut **db).await.ok()?;
    NamedFile::open(response.filepath).await.ok()
}

async fn run_migrations(rocket: Rocket<Build>) -> fairing::Result {
    match FilesDatabase::fetch(&rocket) {
        Some(db) => match sqlx::migrate!("db/migrations").run(&**db).await {
            Ok(_) => Ok(rocket),
            Err(e) => {
                error!("Failed to initialize SQLx database: {}", e);
                Err(rocket)
            }
        }
        None => Err(rocket),
    }
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .attach(FilesDatabase::init())
        .attach(AdHoc::try_on_ignite("SQLx Migrations", run_migrations))
        .mount("/", routes![get_file])
}

db/migrations/00_init.sql

CREATE TABLE files (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    filepath TEXT NOT NULL,
    creation_time INTEGER NOT NULL
);

SQLx version

0.7

Enabled SQLx features

macros, migrate

Database server and version

SQLite (I'm unsure how to check the version)

Operating system

Debian 13

Rust version

rustc 1.89.0 (29483883e 2025-08-04)

[iamjpotts]

SQLx version 0.7

Are you sure this is correct? The latest version is 0.8.6.

[abonander]

If you're using SQLx 0.7 then you need to install a compatible version of sqlx-cli.

For example, cargo install [email protected].

[jworrell]

If you're using SQLx 0.7 then you need to install a compatible version of sqlx-cli.

For example, cargo install [email protected].

~~I'm using sqlx 0.8.6 and [email protected] and running into the same problem (with SQLite also.)~~

In case this helps anyone, it was user error: I was using .env.dev and I needed to export DATABASE_URL (if it is defined in plain old .env then it gets picked up, also)