Crate sqlx_mssql_odbc

Expand description

MSSQL driver for SQLx via ODBC.

sqlx-mssql-odbc connects SQLx to Microsoft SQL Server through an ODBC driver manager. This is the facade crate — it re-exports everything from [sqlx-mssql-odbc-core].

§Quick start

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

use sqlx_core::connection::Connection;
use sqlx_core::row::Row;
use sqlx_mssql_odbc::MssqlConnection;

let mut conn = MssqlConnection::connect(
    "mssql://user:password@localhost:1433/database"
).await?;

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

let value: i32 = row.try_get(0)?;
assert_eq!(value, 42);

conn.close().await?;

MssqlConnection::connect() accepts a standard mssql:// URL, a raw ODBC connection string, or a bare DSN name.

§Usage patterns

§Connection pooling

use sqlx_mssql_odbc::MssqlPoolOptions;

let pool = MssqlPoolOptions::new()
    .max_connections(10)
    .connect("mssql://user:password@localhost:1433/database")
    .await?;

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

pool.close().await;

§Parameterised queries

use sqlx_core::row::Row;
use sqlx_mssql_odbc::MssqlConnection;
use sqlx_core::connection::Connection;

let mut conn = MssqlConnection::connect("mssql://…").await?;

let row = sqlx_core::query::query("SELECT @p1 + @p2")
    .bind(10i32)
    .bind(20i32)
    .fetch_one(&mut conn)
    .await?;

let total: i32 = row.try_get(0)?;
assert_eq!(total, 30);

§Compile-time checked queries (`macros` feature)

Enable the macros feature to get compile-time validation of SQL against a live database:

[dependencies]
sqlx-mssql-odbc = { version = "0.1", features = ["macros"] }

let mut conn = MssqlConnection::connect("…").await?;

// The column name and type are checked at compile time.
let row = sqlx_mssql_odbc::query!("SELECT 1 AS one")
    .fetch_one(&mut conn)
    .await?;
assert_eq!(row.one, 1i32);

// Bind parameters with $1, $2, etc.
let row = sqlx_mssql_odbc::query!("SELECT @p1 + @p2 AS total", 10i32, 20i32)
    .fetch_one(&mut conn)
    .await?;
assert_eq!(row.total, 30);

For CI or offline builds, use cargo sqlx prepare to cache the schema so the macros can check queries without a live database.

§Derive macros (`derive` feature)

[dependencies]
sqlx-mssql-odbc = { version = "0.1", features = ["derive"] }

use sqlx_mssql_odbc::FromRow;

#[derive(Debug, FromRow)]
struct User {
    id: i32,
    name: String,
    email: Option<String>,
}

let users = sqlx_mssql_odbc::query_as!(User, "SELECT id, name, email FROM users")
    .fetch_all(&mut conn)
    .await?;

§Transactions

use sqlx_core::connection::Connection;
use sqlx_core::executor::Executor;
use sqlx_mssql_odbc::MssqlConnection;

let mut conn = MssqlConnection::connect("mssql://…").await?;

conn.begin().await?;
sqlx_core::query::query("INSERT INTO users (name) VALUES (@p1)")
    .bind("Alice")
    .execute(&mut conn)
    .await?;
conn.commit().await?;

§URL parameters

Parameter	Description
`encrypt=true`	Enable TLS encryption
`trust_certificate=true`	Skip certificate validation
`driver=…`	Custom ODBC driver name (default: `ODBC Driver 18 for SQL Server`)

§Requirements

On Linux and macOS you need both a driver manager (unixODBC) and the Microsoft ODBC Driver for SQL Server (version 17 or 18). See the repository README for platform-specific installation instructions.

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

§Features

Feature	Description
`bigdecimal`	[`BigDecimal`] type support
`chrono`	[`chrono`] datetime types
`rust_decimal` / `decimal`	[`rust_decimal::Decimal`] support
`json`	[`serde_json::Value`] support
`time`	[`time`] crate datetime types
`uuid`	[`uuid::Uuid`] support
`macros`	`query!()`, `query_as!()` and other proc macros
`derive`	`Encode`, `Decode`, `Type`, `FromRow` derive macros
`offline`	Compile-time query checking with `query!()`
`migrate`	Database migration support
`runtime-tokio`	Tokio runtime support
`tls-none`	No TLS (default)
`spatial`	[`geo_types`] spatial type support
`vendored-unix-odbc`	Statically link unixODBC

Re-exports§

pub use sqlx_mssql_odbc_core as core;

Modules§

type_checking: Type-checking support for compile-time query macros.

Macros§

expand_querymacros
querymacros: Compile-time checked SQL query for MSSQL via ODBC.
query_asmacros: Compile-time checked SQL query for MSSQL via ODBC, mapping to a named struct.
query_filemacros: Compile-time checked SQL query read from a file at compile time.
query_file_asmacros: Compile-time checked SQL query read from a file, mapping to a named struct.
query_file_scalarmacros: Compile-time checked SQL query read from a file, returning a single scalar.
query_scalarmacros: Compile-time checked SQL query for MSSQL via ODBC, returning a single scalar value.

Structs§

Mssql: MSSQL database marker for SQLx-core traits.
MssqlArguments: Values that can be bound to MSSQL ODBC parameters.
MssqlBufferSettings: Fetch-buffer settings used by the MSSQL ODBC driver.
MssqlColumn: Column metadata for an MSSQL result set via ODBC.
MssqlConnectOptions: Connection options for an MSSQL ODBC data source.
MssqlConnection: MSSQL connection backed by an actor thread that owns the ODBC connection.
MssqlDatabaseError: Database error details extracted from ODBC diagnostics.
MssqlParameterCollection: Owned MSSQL ODBC parameter storage ready to bind with odbc-api.
MssqlQueryResult: Result summary for an MSSQL query via ODBC.
MssqlRow: Minimal MSSQL row container used by the SQLx-core skeleton.
MssqlStatement: Prepared statement metadata for MSSQL via ODBC.
MssqlTransactionManager: Transaction manager for MSSQL via ODBC.
MssqlTypeInfo: Type information for an MSSQL ODBC value.
MssqlValue: A small owned MSSQL ODBC value representation.

Enums§

MssqlArgumentValue: Values that can currently be bound to MSSQL ODBC parameters.
MssqlError: Error type returned by this crate.
MssqlValueKind: Supported owned MSSQL ODBC value kinds.

Traits§

DataTypeExt: Helper predicates for odbc-api data type groups.
MssqlExecutor: An alias for Executor<'_, Database = Mssql>.

Type Aliases§

MssqlPool: An alias for Pool, specialized for MSSQL.
MssqlPoolOptions: An alias for PoolOptions, specialized for MSSQL.
MssqlTransaction: An alias for Transaction, specialized for MSSQL.
Result: Result alias for this crate.

Derive Macros§

Decodederive
Encodederive
FromRowderive
Typederive