SeaQL/sea-orm · error

Fail to parse database URL

Error message

Fail to parse database URL

What it means

`DbBackend::is_prefix_of` parses the given `base_url` with `Url::parse(...).expect("Fail to parse database URL")` to compare its scheme against the backend. If the string is not a valid URL, the expect panics. The function is also used by `assert_database_connection_traits`, so invalid connection strings surface as a panic rather than a returned error.

Solutions

1. Validate the URL before calling: `Url::parse(db_url)?` in your own code and surface a friendly error.
2. Ensure the URL starts with a supported scheme: postgres://, postgresql://, mysql://, or sqlite://.
3. Percent-encode special characters in passwords (e.g. @ -> %40) inside the connection string.

Example fix

// before
assert_database_connection_traits(DbBackend::MySql, std::env::var("DATABASE_URL")?);
// after
let url = std::env::var("DATABASE_URL")?;
url::Url::parse(&url).map_err(|_| anyhow!("Invalid DATABASE_URL: {url}"))?; // scheme must be mysql://
assert_database_connection_traits(DbBackend::MySql, &url);

use url::Url;
fn validate_db_url(u: &str) -> Result<(), String> {
    let parsed = Url::parse(u).map_err(|e| format!("invalid DATABASE_URL '{u}': {e}"))?;
    match parsed.scheme() {
        "postgres" | "postgresql" | "mysql" | "sqlite" => Ok(()),
        s => Err(format!("unsupported scheme '{s}'")),
    }
}

fn is_valid_db_url(s: &str) -> bool { url::Url::parse(s).is_ok() }

When it happens

Trigger: Calling `is_prefix_of` / `assert_database_connection_traits` with a database URL that is not parseable by the `url` crate — missing scheme (`localhost/db`), spaces, stray characters, or a malformed host.

Common situations: DATABASE_URL env var set from a .env file with quotes or unencoded special characters; forgetting the `postgres://`, `mysql://`, or `sqlite://` prefix; typos like `postgresql//host`.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Fail to parse database URL
• Already checked arity
• Already checked arity
• Already checked arity
• Audit not supported for

AI-assisted analysis of SeaQL/sea-orm@e29bcd1b41 (2026-09-10). Data as JSON: /api/errors/b41107f8aa25332e. Report an issue: GitHub.

Appendix: source

Thrown at src/database/db_connection.rs:870

    /// Panics if [DbConn] is not a SQLite connection.
    #[cfg(feature = "sqlx-sqlite")]
    pub fn get_sqlite_connection_pool(&self) -> &sqlx::SqlitePool {
        match &self.inner {
            DatabaseConnectionType::SqlxSqlitePoolConnection(conn) => &conn.pool,
            _ => panic!("Not SQLite Connection"),
        }
    }
}

impl DbBackend {
    /// Check if the URI is the same as the specified database backend.
    /// Returns true if they match.
    ///
    /// # Panics
    ///
    /// Panics if `base_url` cannot be parsed as `Url`.
    pub fn is_prefix_of(self, base_url: &str) -> bool {
        let base_url_parsed = Url::parse(base_url).expect("Fail to parse database URL");
        match self {
            Self::Postgres => {
                base_url_parsed.scheme() == "postgres" || base_url_parsed.scheme() == "postgresql"
            }
            Self::MySql => base_url_parsed.scheme() == "mysql",
            Self::Sqlite => base_url_parsed.scheme() == "sqlite",
        }
    }

    /// Build an SQL [Statement]
    pub fn build<S>(&self, statement: &S) -> Statement
    where
        S: StatementBuilder,
    {
        statement.build(self)
    }

    /// Check if the database supports `RETURNING` syntax on insert and update

View on GitHub (pinned to e29bcd1b41)