arrow_sql_server/
lib.rs

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

arrow_sql_server/
lib.rs
