sqlx_odbc/
lib.rs

1//! ODBC driver for SQLx.
2//!
3//! `sqlx-odbc` connects SQLx to databases exposed through an ODBC driver
4//! manager. Use it directly with `sqlx-core` native APIs, or install its
5//! [`Any` driver][any::DRIVER] when an application wants to open ODBC connection
6//! strings through `AnyConnection`.
7//!
8//! # Native connection
9//!
10//! ```no_run
11//! use sqlx_core::connection::Connection;
12//! use sqlx_core::row::Row;
13//! use sqlx_odbc::OdbcConnection;
14//!
15//! # async fn run() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
16//! let mut conn = OdbcConnection::connect("Driver=DuckDB;Database=/tmp/example.duckdb").await?;
17//!
18//! let row = sqlx_core::query::query("SELECT 1")
19//!     .fetch_one(&mut conn)
20//!     .await?;
21//!
22//! let value: i32 = row.try_get(0)?;
23//! assert_eq!(value, 1);
24//!
25//! conn.close().await?;
26//! # Ok(())
27//! # }
28//! ```
29//!
30//! `OdbcConnection::connect()` accepts a standard ODBC connection string, a bare
31//! DSN name, or the legacy `odbc:` prefix.
32//!
33//! # `AnyConnection`
34//!
35//! Install this driver before connecting through SQLx `Any` APIs:
36//!
37//! ```no_run
38//! use sqlx_core::connection::Connection;
39//!
40//! # async fn run() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
41//! sqlx_core::any::driver::install_drivers(&[sqlx_odbc::any::DRIVER])?;
42//!
43//! let mut conn = sqlx_core::any::AnyConnection::connect(
44//!     "odbc:Driver=DuckDB;Database=/tmp/example.duckdb",
45//! )
46//! .await?;
47//!
48//! conn.close().await?;
49//! # Ok(())
50//! # }
51//! ```
52//!
53//! To combine split drivers, install all of them once at application startup:
54//!
55//! ```ignore
56//! fn install() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
57//! sqlx_core::any::driver::install_drivers(&[
58//!     sqlx_sqlserver::any::DRIVER,
59//!     sqlx_odbc::any::DRIVER,
60//! ])?;
61//! Ok(())
62//! }
63//! ```
64//!
65//! # Native ODBC requirements
66//!
67//! On Linux and macOS, install a driver manager such as unixODBC plus a
68//! database-specific ODBC driver. On Windows, the driver manager is built in,
69//! but the database-specific driver is still required. DSNs can be configured in
70//! the driver manager, or callers can pass a full `Driver=...;...` connection
71//! string.
72//!
73//! Enable the `vendored-unix-odbc` feature to statically link the unixODBC
74//! driver manager into your application on Linux or macOS. The actual database
75//! ODBC driver still needs to be installed and discoverable at runtime.
76//!
77//! Buffered fetching can improve throughput, but long text or binary values may
78//! be truncated when `max_column_size` is set. Use unbuffered mode for values
79//! that may exceed that limit.
80
81#![deny(missing_docs)]
82#![deny(rustdoc::broken_intra_doc_links)]
83#![warn(future_incompatible, rust_2018_idioms)]
84
85pub mod any;
86mod arguments;
87mod column;
88mod connection;
89mod database;
90mod error;
91mod options;
92mod query_result;
93mod row;
94mod statement;
95mod transaction;
96mod type_info;
97mod value;
98
99pub use arguments::{OdbcArgumentValue, OdbcArguments, OdbcParameterCollection};
100pub use column::OdbcColumn;
101pub use connection::OdbcConnection;
102pub use database::Odbc;
103pub use error::{OdbcDatabaseError, OdbcError, Result};
104pub use options::{OdbcBufferSettings, OdbcConnectOptions};
105pub use query_result::OdbcQueryResult;
106pub use row::OdbcRow;
107pub use statement::OdbcStatement;
108pub use transaction::OdbcTransactionManager;
109pub use type_info::{DataTypeExt, OdbcTypeInfo};
110pub use value::{OdbcValue, OdbcValueKind};
111
112/// An alias for [`Pool`][sqlx_core::pool::Pool], specialized for ODBC.
113pub type OdbcPool = sqlx_core::pool::Pool<Odbc>;
114
115/// An alias for [`PoolOptions`][sqlx_core::pool::PoolOptions], specialized for ODBC.
116pub type OdbcPoolOptions = sqlx_core::pool::PoolOptions<Odbc>;
117
118/// An alias for [`Transaction`][sqlx_core::transaction::Transaction], specialized for ODBC.
119pub type OdbcTransaction<'c> = sqlx_core::transaction::Transaction<'c, Odbc>;
120
121/// An alias for [`Executor<'_, Database = Odbc>`][sqlx_core::executor::Executor].
122pub trait OdbcExecutor<'c>: sqlx_core::executor::Executor<'c, Database = Odbc> {}
123impl<'c, T> OdbcExecutor<'c> for T where T: sqlx_core::executor::Executor<'c, Database = Odbc> {}
sqlx_odbc/lib.rs

sqlx_odbc/
lib.rs
