arrow_tiberius/lib.rs
1//! Apache Arrow and SQL Server bridge through Tiberius.
2//!
3//! `arrow-tiberius` bridges Apache Arrow and Microsoft SQL Server through the
4//! Tiberius TDS driver. The crate is designed around a bidirectional boundary:
5//! Arrow schemas and [`RecordBatch`] values can be planned and written to SQL
6//! Server, and future read-side APIs can map SQL Server metadata and rows back
7//! to Arrow.
8//!
9//! The v0.1 API implements the Arrow-to-SQL Server write path first: plan an
10//! Arrow schema for SQL Server, render deterministic DDL, inspect structured
11//! diagnostics, and bulk load one or more record batches. SQL Server-to-Arrow
12//! reads are reserved for a later release.
13//!
14//! [`RecordBatch`]: arrow_array::RecordBatch
15//!
16//! # Quick Start
17//!
18//! Plan an Arrow schema and render `CREATE TABLE` SQL:
19//!
20//! ```
21//! use arrow_schema::{DataType, Field, Schema};
22//! use arrow_tiberius::{
23//! MssqlProfile, PlanOptions, TableName, create_table_sql_from_mappings,
24//! };
25//!
26//! # fn main() -> arrow_tiberius::Result<()> {
27//! let schema = Schema::new(vec![
28//! Field::new("id", DataType::Int64, false),
29//! Field::new("name", DataType::Utf8, true),
30//! ]);
31//!
32//! let profile = MssqlProfile::sql_server_2016_compat_100();
33//! let outcome = profile.plan_arrow_schema(&schema, PlanOptions::default())?;
34//!
35//! let table = TableName::new("dbo", "people")?;
36//! let ddl = create_table_sql_from_mappings(&table, outcome.mappings());
37//! assert!(ddl.contains("CREATE TABLE [dbo].[people]"));
38//! # Ok(())
39//! # }
40//! ```
41//!
42//! Connect through the crate-owned Tiberius compatibility boundary:
43//!
44//! ```no_run
45//! use arrow_tiberius::{
46//! ConnectedMssqlClient, connect_mssql_client_from_ado_string,
47//! };
48//!
49//! async fn connect(
50//! connection_string: &str,
51//! ) -> arrow_tiberius::Result<ConnectedMssqlClient> {
52//! connect_mssql_client_from_ado_string(connection_string).await
53//! }
54//! ```
55//!
56//! [`BulkWriter`] validates target table metadata before writing. It does not
57//! create tables automatically; callers can use [`create_table_sql_from_mappings`]
58//! when they want this crate to produce a table definition.
59//!
60//! # Main Modules
61//!
62//! - [`schema`] plans Arrow fields into SQL Server column mappings and DDL
63//! metadata.
64//! - [`mssql`] contains SQL Server identifiers, profiles, types, and DDL
65//! helpers.
66//! - [`diagnostic`] exposes structured planning and runtime diagnostics.
67//! - The [`write` module](crate::write) contains write policies, backend
68//! selection, and [`BulkWriter`].
69//!
70//! # Writer Backends
71//!
72//! [`WriteBackend::Auto`] is the default selection and currently resolves to
73//! [`WriteBackend::DirectRawBulk`].
74//! [`WriteBackend::DirectRawBulk`] is the optimized direct Arrow-to-TDS path for
75//! supported mappings. [`WriteBackend::BaselineTokenRow`] remains available as a
76//! compatibility and reference path through Tiberius `TokenRow` bulk load.
77//! [`WriteBackend::DirectFramedBulk`] uses the direct row encoder through
78//! Tiberius framed writes.
79//!
80//! # SQL Server Compatibility
81//!
82//! Choose the [`MssqlProfile`] that matches the SQL Server version and database
83//! compatibility level you plan to write against. The original
84//! [`MssqlProfile::sql_server_2016_compat_100`] profile remains available. The
85//! profile surface also models SQL Server 2016, 2017, 2019, 2022, and 2025
86//! version/compatibility-level pairs through [`MssqlProfile::new`].
87//!
88//! # Tiberius Dependency Model
89//!
90//! This crate depends on the published `tiberius-raw-bulk` package as the crate
91//! name `tiberius` and owns that compatibility boundary. Downstream crates
92//! should use [`connect_mssql_client_from_ado_string`] and
93//! [`ConnectedMssqlClient`] instead of constructing a raw Tiberius client for
94//! [`BulkWriter`].
95//!
96//! ```toml
97//! [dependencies]
98//! arrow-tiberius = "0.1"
99//! ```
100//!
101//! Depending on upstream `tiberius` separately creates a distinct crate type and
102//! will not produce a client compatible with this crate's writer internals.
103//!
104//! # Feature Flags
105//!
106//! - `bench-profile`: benchmark-only direct write profiling hooks.
107//! - `integration-tests`: SQL Server integration tests that are normally run
108//! through `cargo xtask sqlserver-test`.
109//!
110//! Docs.rs is configured to build with all features so feature-gated public
111//! items are visible in API documentation. Normal library use does not require
112//! either feature.
113//!
114//! # More Documentation
115//!
116//! - [Arrow to SQL Server Type Mapping](https://github.com/mag1cfrog/arrow-tiberius/blob/main/docs/type-mapping.md)
117//! - [Observability](https://github.com/mag1cfrog/arrow-tiberius/blob/main/docs/observability.md)
118//! - [Integration Tests](https://github.com/mag1cfrog/arrow-tiberius/blob/main/docs/integration-tests.md)
119//! - [Writer Benchmarks](https://github.com/mag1cfrog/arrow-tiberius/blob/main/docs/benchmarks.md)
120
121/// Arrow-side schema metadata.
122pub mod arrow;
123/// SQL Server connection helpers.
124pub mod connection;
125/// Directional conversion semantics between Arrow and SQL Server.
126pub(crate) mod conversion;
127/// Structured diagnostics for planning and writing.
128pub mod diagnostic;
129/// Error types for `arrow-tiberius`.
130pub mod error;
131/// MSSQL-side schema metadata, identifiers, profile, and DDL helpers.
132pub mod mssql;
133mod observability;
134/// Bidirectional Arrow/MSSQL schema mapping.
135pub mod schema;
136/// Write-path options and conversion policies.
137pub mod write;
138
139pub use arrow::ArrowFieldRef;
140pub use connection::{
141 ConnectedBulkWriter, ConnectedMssqlClient, SqlExecutionOutcome,
142 connect_mssql_client_from_ado_string,
143};
144pub use diagnostic::{
145 Diagnostic, DiagnosticCode, DiagnosticSet, DiagnosticSeverity, FieldRef, PlanOutcome,
146};
147pub use error::{Error, ErrorInfo, Result};
148pub use mssql::{
149 CompatibilityLevel, CreateTableOptions, Identifier, IdentifierPolicy, MssqlColumn,
150 MssqlProfile, MssqlTimePrecision, MssqlType, MssqlTypeLength, MssqlVersion, TableName,
151 create_table_sql,
152};
153#[cfg(test)]
154pub(crate) use schema::plan_arrow_schema_to_mssql_mappings;
155pub use schema::{
156 PlannedSchema, SchemaMapping, create_table_sql_from_mappings, mssql_columns_from_mappings,
157 plan_arrow_schema_to_mssql_schema,
158};
159pub use write::{
160 BinaryPolicy, BulkWriter, Date64Policy, Decimal256Policy, DecimalPolicy, FloatPolicy,
161 NanosecondPolicy, PlanOptions, SchemaCheck, StringPolicy, TimestampPolicy, TimezonePolicy,
162 UInt64Policy, WriteBackend, WriteOptions, WritePhase, WriteStats,
163 validate_arrow_schema_against_mappings, validate_record_batch_schema_against_mappings,
164};