sqlx-mssql-odbc

Microsoft SQL Server driver for SQLx via ODBC.

This crate connects SQLx to Microsoft SQL Server through an ODBC driver manager (unixODBC on Linux/macOS, built-in on Windows). It depends only on crates published to crates.io and examples use sqlx-core directly.

Minimal Query

[dependencies]
sqlx-mssql-odbc = "0.1.4"
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_mssql_odbc::MssqlConnection;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let mut conn = MssqlConnection::connect(
        "mssql://sa:MyPass@localhost:1433/testdb",
    ).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(())
}

MssqlConnection::connect() accepts:

• A standard mssql:// URL: mssql://user:password@host:port/database?params
• A raw ODBC connection string: Driver={ODBC Driver 18 for SQL Server};Server=...
• A bare DSN name: MyMssqlDSN

URL query parameters

Builder methods

let mut options = MssqlConnectOptions::from_str("mssql://localhost/testdb")?;
options.encrypt(true)
       .trust_certificate(true)
       .batch_size(128)
       .statement_cache_capacity(200);
let conn = options.connect().await?;

ODBC Setup

ODBC uses two native pieces outside this crate:

1. A driver manager - unixODBC on Linux/macOS (built into Windows).
2. The Microsoft ODBC Driver for SQL Server - version 17 or 18.

Enable the vendored-unix-odbc feature to statically link the unixODBC driver manager into your application on Linux or macOS.

Linux (Debian/Ubuntu)

curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -
curl https://packages.microsoft.com/config/ubuntu/22.04/prod.list > /etc/apt/sources.list.d/mssql-release.list
apt-get update
ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev

macOS

brew install unixodbc
brew install msodbcsql18

Windows

The ODBC driver manager is built into Windows. Install the Microsoft ODBC Driver for SQL Server.

Platform note: CI currently verifies Linux only. macOS and Windows are expected to work but are not exercised by automated tests. Community PRs for platform-specific fixes are welcome.

Connection Pooling

use sqlx_mssql_odbc::MssqlPoolOptions;

let pool = MssqlPoolOptions::new()
    .max_connections(10)
    .connect("mssql://sa:MyPass@localhost:1433/testdb")
    .await?;

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

Features

CLI (sqlx-mssql)

A thin wrapper around sqlx-cli for managing MSSQL databases, running migrations, and preparing offline query data.

Install

cargo install sqlx-mssql-odbc-cli

After installation, the sqlx-mssql binary is available on your PATH.

Usage

All standard sqlx-cli subcommands are supported. Provide your database URL via --database-url or the DATABASE_URL environment variable (or a .env file).

# Create / drop the database
sqlx-mssql database create
sqlx-mssql database drop

# Create and run migrations
sqlx-mssql migrate add <name>
sqlx-mssql migrate run

# Revert the last migration
sqlx-mssql migrate revert

# List migration status
sqlx-mssql migrate info

# Prepare offline query data (for compile-time checked queries)
sqlx-mssql prepare

Environment variable (add to .env in your project root):

DATABASE_URL=mssql://sa:Password1!@localhost:1433/my_database

Or use the --database-url flag:

sqlx-mssql migrate run --database-url mssql://sa:Password1!@localhost:1433/my_database

Run without installing

cargo run -p sqlx-mssql-odbc-cli -- migrate run

Running Tests

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=MyPass" \
  -p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest

MSSQL_DATABASE_URL="mssql://sa:MyPass@localhost:1433/testdb" \
MSSQL_TEST_REQUIRED=1 \
cargo test --test mssql