arrow_sql_server/
lib.rs

1//! High-performance Apache Arrow `RecordBatch` bulk writes for Microsoft SQL Server.
2//!
3//! Arrow SQL Server plans Arrow schemas, generates SQL Server DDL, validates
4//! target tables, and streams [`RecordBatch`] values through a SQL Server bulk
5//! writer. The production path uses TDS directly and does not require an ODBC
6//! driver.
7//!
8//! [`RecordBatch`]: arrow_array::RecordBatch
9//!
10//! # Start With a Schema
11//!
12//! Plan an Arrow schema and render matching `CREATE TABLE` SQL:
13//!
14//! ```
15//! use arrow_schema::{DataType, Field, Schema};
16//! use arrow_sql_server::{
17//!     CompatibilityLevel, MssqlProfile, MssqlVersion, PlanOptions, TableName,
18//!     create_table_sql_from_mappings,
19//! };
20//!
21//! # fn main() -> arrow_sql_server::Result<()> {
22//! let schema = Schema::new(vec![
23//!     Field::new("id", DataType::Int64, false),
24//!     Field::new("name", DataType::Utf8, true),
25//! ]);
26//! let profile = MssqlProfile::new(
27//!     MssqlVersion::SqlServer2022,
28//!     CompatibilityLevel::SQL_SERVER_2022,
29//! )?;
30//! let planned = profile
31//!     .plan_arrow_schema(&schema, PlanOptions::default())?
32//!     .into_value();
33//! let table = TableName::new("dbo", "people")?;
34//! let ddl = create_table_sql_from_mappings(&table, &planned);
35//!
36//! assert!(ddl.contains("CREATE TABLE [dbo].[people]"));
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! Follow the [Getting Started tutorial] for a complete connection, table
42//! creation, write, and row-count verification flow.
43//!
44//! [Getting Started tutorial]: https://github.com/mag1cfrog/arrow-sql-server/blob/main/docs/getting-started.md
45//!
46//! # Core API
47//!
48//! - [`MssqlProfile`] and [`PlanOptions`] plan Arrow fields for a specific SQL
49//!   Server version and compatibility level.
50//! - [`create_table_sql_from_mappings`] renders deterministic SQL Server DDL.
51//! - [`connect_mssql_client_from_ado_string`] creates a compatible asynchronous
52//!   SQL Server connection.
53//! - [`ConnectedMssqlClient::bulk_writer`] creates a writer for an existing
54//!   target table.
55//! - [`WriteOptions::default`] selects [`WriteBackend::Auto`], which currently
56//!   resolves to the optimized direct raw TDS backend.
57//! - [`Error::safe_error_info`] exposes sanitized, structured failure details
58//!   for user-facing reports.
59//!
60//! # Current Scope
61//!
62//! This crate owns reusable Arrow-to-SQL Server planning and writing. It does
63//! not provide SQL Server-to-Arrow reads, connection pooling, retries, job
64//! orchestration, migrations, or multi-table publishing workflows.
65//!
66//! [`BulkWriter`] validates target metadata before writing. It does not create
67//! or replace tables automatically.
68//!
69//! # Connection Compatibility
70//!
71//! Prefer [`connect_mssql_client_from_ado_string`] and
72//! [`ConnectedMssqlClient`] in downstream applications. They hide the exact
73//! `tiberius-raw-bulk` client and transport types that the writer requires.
74//!
75//! # Guides and Reference
76//!
77//! - [Type Mapping](https://github.com/mag1cfrog/arrow-sql-server/blob/main/docs/type-mapping.md)
78//! - [Performance](https://github.com/mag1cfrog/arrow-sql-server/blob/main/docs/performance.md)
79//! - [Observability](https://github.com/mag1cfrog/arrow-sql-server/blob/main/docs/observability.md)
80//! - [Documentation Index](https://github.com/mag1cfrog/arrow-sql-server/blob/main/docs/README.md)
81
82/// Arrow-side schema metadata.
83pub mod arrow;
84/// SQL Server connection helpers.
85pub mod connection;
86/// Directional conversion semantics between Arrow and SQL Server.
87pub(crate) mod conversion;
88/// Structured diagnostics for planning and writing.
89pub mod diagnostic;
90/// Error types for Arrow SQL Server.
91pub mod error;
92/// MSSQL-side schema metadata, identifiers, profiles, types, and DDL helpers.
93pub mod mssql;
94mod observability;
95/// Bidirectional Arrow/MSSQL schema mapping.
96pub mod schema;
97/// Write-path options and conversion policies.
98pub mod write;
99
100pub use arrow::ArrowFieldRef;
101pub use connection::{
102    ConnectedBulkWriter, ConnectedMssqlClient, SqlExecutionOutcome,
103    connect_mssql_client_from_ado_string,
104};
105pub use diagnostic::{
106    Diagnostic, DiagnosticCode, DiagnosticSet, DiagnosticSeverity, FieldRef, PlanOutcome,
107};
108pub use error::{Error, ErrorInfo, Result};
109pub use mssql::{
110    CompatibilityLevel, CreateTableOptions, Identifier, IdentifierPolicy, MssqlColumn,
111    MssqlProfile, MssqlTimePrecision, MssqlType, MssqlTypeLength, MssqlVersion, TableName,
112    create_table_sql,
113};
114#[cfg(test)]
115pub(crate) use schema::plan_arrow_schema_to_mssql_mappings;
116pub use schema::{
117    PlannedSchema, SchemaMapping, create_table_sql_from_mappings, mssql_columns_from_mappings,
118    plan_arrow_schema_to_mssql_schema,
119};
120pub use write::{
121    BinaryPolicy, BulkWriter, Date64Policy, Decimal256Policy, DecimalPolicy, FloatPolicy,
122    NanosecondPolicy, PlanOptions, SchemaCheck, StringPolicy, TimestampPolicy, TimezonePolicy,
123    UInt64Policy, WriteBackend, WriteOptions, WritePhase, WriteStats,
124    validate_arrow_schema_against_mappings, validate_record_batch_schema_against_mappings,
125};
arrow_sql_server/lib.rs

arrow_sql_server/
lib.rs
