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//!     plan_arrow_schema_to_mssql_mappings,
25//! };
26//!
27//! # fn main() -> arrow_tiberius::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 outcome = plan_arrow_schema_to_mssql_mappings(
34//!     &schema,
35//!     MssqlProfile::sql_server_2016_compat_100(),
36//!     PlanOptions::default(),
37//! )?;
38//!
39//! let table = TableName::new("dbo", "people")?;
40//! let ddl = create_table_sql_from_mappings(&table, outcome.value());
41//! assert!(ddl.contains("CREATE TABLE [dbo].[people]"));
42//! # Ok(())
43//! # }
44//! ```
45//!
46//! Write a planned batch to an existing table:
47//!
48//! ```no_run
49//! use arrow_array::RecordBatch;
50//! use arrow_tiberius::{
51//!     BulkWriter, MssqlProfile, PlanOptions, TableName, WriteBackend,
52//!     WriteOptions, plan_arrow_schema_to_mssql_mappings,
53//! };
54//! use futures_util::io::{AsyncRead, AsyncWrite};
55//!
56//! async fn write_batch<S>(
57//!     client: &mut tiberius::Client<S>,
58//!     batch: &RecordBatch,
59//! ) -> arrow_tiberius::Result<()>
60//! where
61//!     S: AsyncRead + AsyncWrite + Unpin + Send,
62//! {
63//!     let outcome = plan_arrow_schema_to_mssql_mappings(
64//!         batch.schema().as_ref(),
65//!         MssqlProfile::sql_server_2016_compat_100(),
66//!         PlanOptions::default(),
67//!     )?;
68//!
69//!     let mut writer = BulkWriter::new(
70//!         client,
71//!         TableName::new("dbo", "people")?,
72//!         outcome.value().to_vec(),
73//!         WriteOptions {
74//!             backend: WriteBackend::DirectRawBulk,
75//!             ..WriteOptions::default()
76//!         },
77//!     )
78//!     .await?;
79//!
80//!     writer.write_batch(batch).await?;
81//!     writer.finish().await?;
82//!     Ok(())
83//! }
84//! ```
85//!
86//! [`BulkWriter`] validates target table metadata before writing. It does not
87//! create tables automatically; callers can use [`create_table_sql_from_mappings`]
88//! when they want this crate to produce a table definition.
89//!
90//! # Main Modules
91//!
92//! - [`schema`] plans Arrow fields into SQL Server column mappings and DDL
93//!   metadata.
94//! - [`mssql`] contains SQL Server identifiers, profiles, types, and DDL
95//!   helpers.
96//! - [`diagnostic`] exposes structured planning and runtime diagnostics.
97//! - The [`write` module](crate::write) contains write policies, backend
98//!   selection, and [`BulkWriter`].
99//!
100//! # Writer Backends
101//!
102//! [`WriteBackend::Auto`] is the default selection and currently resolves to
103//! [`WriteBackend::DirectRawBulk`].
104//! [`WriteBackend::DirectRawBulk`] is the optimized direct Arrow-to-TDS path for
105//! supported mappings. [`WriteBackend::BaselineTokenRow`] remains available as a
106//! compatibility and reference path through Tiberius `TokenRow` bulk load.
107//! [`WriteBackend::DirectFramedBulk`] uses the direct row encoder through
108//! Tiberius framed writes.
109//!
110//! # SQL Server Compatibility
111//!
112//! The initial profile is [`MssqlProfile::sql_server_2016_compat_100`], which
113//! targets SQL Server 2016 with database compatibility level 100.
114//!
115//! # Tiberius Dependency Model
116//!
117//! This crate depends on the published `tiberius-raw-bulk` package as the crate
118//! name `tiberius`. Downstream crates that construct the Tiberius client passed
119//! to [`BulkWriter`] should use the same package identity:
120//!
121//! ```toml
122//! [dependencies]
123//! arrow-tiberius = "0.1"
124//! tiberius = { package = "tiberius-raw-bulk", version = "=0.12.3-raw-bulk.13", default-features = false, features = [
125//!     "tds73",
126//!     "winauth",
127//!     "native-tls",
128//! ] }
129//! ```
130//!
131//! Depending on upstream `tiberius` separately creates a distinct crate type and
132//! will not produce a client compatible with [`BulkWriter`].
133//!
134//! # Feature Flags
135//!
136//! - `bench-profile`: benchmark-only direct write profiling hooks.
137//! - `integration-tests`: SQL Server integration tests that are normally run
138//!   through `cargo xtask sqlserver-test`.
139//!
140//! Docs.rs is configured to build with all features so feature-gated public
141//! items are visible in API documentation. Normal library use does not require
142//! either feature.
143//!
144//! # More Documentation
145//!
146//! - [Arrow to SQL Server Type Mapping](https://github.com/mag1cfrog/arrow-tiberius/blob/main/docs/type-mapping.md)
147//! - [Integration Tests](https://github.com/mag1cfrog/arrow-tiberius/blob/main/docs/integration-tests.md)
148//! - [Writer Benchmarks](https://github.com/mag1cfrog/arrow-tiberius/blob/main/docs/benchmarks.md)
149
150/// Arrow-side schema metadata.
151pub mod arrow;
152/// Directional conversion semantics between Arrow and SQL Server.
153pub(crate) mod conversion;
154/// Structured diagnostics for planning and writing.
155pub mod diagnostic;
156/// Error types for `arrow-tiberius`.
157pub mod error;
158/// MSSQL-side schema metadata, identifiers, profile, and DDL helpers.
159pub mod mssql;
160/// Bidirectional Arrow/MSSQL schema mapping.
161pub mod schema;
162/// Write-path options and conversion policies.
163pub mod write;
164
165pub use arrow::ArrowFieldRef;
166pub use diagnostic::{
167    Diagnostic, DiagnosticCode, DiagnosticSet, DiagnosticSeverity, FieldRef, PlanOutcome,
168};
169pub use error::{Error, Result};
170pub use mssql::{
171    CompatibilityLevel, CreateTableOptions, Identifier, IdentifierPolicy, MssqlColumn,
172    MssqlProfile, MssqlTimePrecision, MssqlType, MssqlTypeLength, MssqlVersion, TableName,
173    create_table_sql,
174};
175pub use schema::{
176    SchemaMapping, create_table_sql_from_mappings, mssql_columns_from_mappings,
177    plan_arrow_schema_to_mssql_mappings,
178};
179pub use write::{
180    BinaryPolicy, BulkWriter, Date64Policy, Decimal256Policy, DecimalPolicy, FloatPolicy,
181    NanosecondPolicy, PlanOptions, SchemaCheck, StringPolicy, TimezonePolicy, UInt64Policy,
182    WriteBackend, WriteOptions, WriteStats,
183};
arrow_tiberius/lib.rs

arrow_tiberius/
lib.rs
