sqlx-odbc

Independent ODBC driver crate for SQLx.

This crate is a standalone top-level crate. It depends only on crates published to crates.io and is not wired into the sqlx facade crate, so examples use sqlx-core directly.

Minimal Query

[dependencies]
sqlx-odbc = "0.0.1"
sqlx-core = "=0.9.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use sqlx_core::connection::Connection;
use sqlx_core::row::Row;
use sqlx_odbc::OdbcConnection;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let mut conn = OdbcConnection::connect("Driver=DuckDB;Database=/tmp/example.duckdb").await?;

    let row = sqlx_core::query::query("SELECT 1")
        .fetch_one(&mut conn)
        .await?;

    let value: i32 = row.try_get(0)?;
    println!("{value}");

    conn.close().await?;
    Ok(())
}

OdbcConnection::connect() accepts a standard ODBC connection string, a bare DSN name, or the legacy odbc: prefix.

Any Driver

Install this crate explicitly before opening ODBC URLs through SQLx AnyConnection:

use sqlx_core::connection::Connection;

sqlx_core::any::driver::install_drivers(&[sqlx_odbc::any::DRIVER])?;

let mut conn = sqlx_core::any::AnyConnection::connect(
    "odbc:Driver=DuckDB;Database=/tmp/example.duckdb",
)
.await?;

ODBC Setup

ODBC uses two native pieces outside this crate:

1. A driver manager. On Linux and macOS this is usually unixODBC; on Windows, the driver manager is built in.
2. A database-specific ODBC driver. Install the driver, then either configure a DSN or pass a full connection string using Driver=....

For the fastest local smoke test, install the DuckDB ODBC driver and run:

./scripts/test-driver.sh duckdb

To test the same suite through the PostgreSQL ODBC driver, start PostgreSQL locally and run:

./scripts/test-driver.sh postgres

To test another installed driver, set a connection string and use custom:

ODBC_DATABASE_URL='Driver=ODBC Driver 18 for SQL Server;Server=localhost;TrustServerCertificate=yes' \
    ./scripts/test-driver.sh custom

DuckDB currently works through the default unbuffered fetch path. Some DuckDB ODBC builds reject the column-wise row binding attribute used by buffered fetching, so leave OdbcConnectOptions::max_column_size(None) for DuckDB.

Useful setup guides:

• unixODBC documentation index: https://www.unixodbc.org/doc/
• unixODBC command-line configuration guide: https://www.unixodbc.org/odbcinst.html
• odbc-api installation notes: https://docs.rs/odbc-api/latest/odbc_api/#installation
• DuckDB ODBC: https://duckdb.org/docs/stable/clients/odbc/overview.html
• Microsoft ODBC Driver for SQL Server: https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server

Static unixODBC

If you ship an application on Linux or macOS and do not want users to install the unixODBC driver manager separately, enable this crate's vendored feature:

[dependencies]
sqlx-odbc = { version = "0.0.1", features = ["vendored-unix-odbc"] }
sqlx-core = "=0.9.0"

That feature forwards to odbc-api/vendored-unix-odbc, which builds and statically links the unixODBC driver manager through odbc-sys. It removes the driver-manager install step on Linux and macOS, but your users still need the database-specific ODBC driver itself and any configuration files or connection string values that driver requires. Vendored unixODBC is LGPL-2.1-or-later, so review the licensing implications before distributing statically linked artifacts.

For local development, run fast checks with ./scripts/ci.sh. Run e2e tests against one installed driver with ./scripts/test-driver.sh duckdb or ODBC_DATABASE_URL=... ./scripts/test-driver.sh custom.