arrow-sql-server 0.3.1

High-performance Apache Arrow RecordBatch bulk writer for Microsoft SQL Server.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

# Integration Tests

This is a maintainer guide for validating Arrow SQL Server itself. Application
developers do not need this harness to use the crate.

Default validation does not require SQL Server:

```bash
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
```

SQL Server validation is opt-in through the xtask runner:

```bash
cargo xtask sqlserver-test
cargo xtask sqlserver-compat-probe
```

`sqlserver-test` is the normal broad integration test path. The xtask runner
starts a local SQL Server container, waits for readiness, creates the test
database, sets compatibility level 100, runs the feature-gated integration
tests, and removes the container when the command exits.

`sqlserver-compat-probe` is the focused compatibility probe path. It runs a
small SQL Server behavior probe for one engine version and one database
compatibility level, using SQL Server itself to derive expected values for
behavior that can vary by compatibility level.

Plain `cargo test` must remain independent of SQL Server.

## Container Runtime

The runner supports Docker-compatible runtimes such as Docker and Podman. Runtime selection uses:

1. `--container-runtime`
2. `ARROW_SQL_SERVER_CONTAINER_RUNTIME`
3. `docker` on `PATH`
4. `podman` on `PATH`

Examples:

```bash
cargo xtask sqlserver-test --container-runtime podman
ARROW_SQL_SERVER_CONTAINER_RUNTIME=podman cargo xtask sqlserver-test
```

Shell aliases such as `alias docker=podman` are not used by the Rust process. Use the flag or environment variable when you need a specific runtime.

## Defaults

The default image is:

```text
mcr.microsoft.com/mssql/server:2017-latest
```

The default database is:

```text
arrow_sql_server_integration
```

SQL Server is configured with:

```sql
ALTER DATABASE [arrow_sql_server_integration] SET COMPATIBILITY_LEVEL = 100;
```

This gives local coverage for SQL Server 2017 running at database compatibility
level 100, matching the profile used by the broad integration harness.

## Compatibility Probe

Run a focused probe for a specific SQL Server image, engine version, and
database compatibility level:

```bash
cargo xtask sqlserver-compat-probe \
  --image mcr.microsoft.com/mssql/server:2022-latest \
  --version 2022 \
  --compatibility-level 160
```

Supported `--version` values are `2017`, `2019`, `2022`, and `2025`.
Use `--compatibility-level` to select the database compatibility level to set
before the probe runs.

## Existing SQL Server

To use an existing SQL Server instead of a local container:

```bash
cargo xtask sqlserver-test \
  --connection-string 'server=tcp:127.0.0.1,1433;user id=sa;password=...;TrustServerCertificate=true' \
  --database arrow_sql_server_integration
```

The xtask runner passes these environment variables to the feature-gated integration tests:

```text
ARROW_SQL_SERVER_TEST_MSSQL_URL
ARROW_SQL_SERVER_TEST_MSSQL_DATABASE
ARROW_SQL_SERVER_TEST_MSSQL_COMPATIBILITY_LEVEL
ARROW_SQL_SERVER_TEST_MSSQL_VERSION
```

The lower-level command is only for CI/debugging when SQL Server is already configured and those environment variables are set:

```bash
cargo test --features integration-tests
```

Prefer `cargo xtask sqlserver-test` for local development.

## CI

GitHub Actions runs the same xtask entrypoints in `.github/workflows/ci.yml`.
The fast Rust job runs formatting, clippy, and normal workspace tests first.
The broad SQL Server job then runs:

```bash
cargo xtask sqlserver-test
```

The compatibility probe job runs one CI job per SQL Server version and loops
over the selected compatibility levels for that version:

```bash
cargo xtask sqlserver-compat-probe \
  --image <version image> \
  --version <year> \
  --compatibility-level <level>
```

CI currently probes SQL Server 2017, 2019, 2022, and 2025 images. The SQL
Server jobs assume a Linux runner with Docker available and network access to
pull the configured `mcr.microsoft.com/mssql/server` images. Container startup,
readiness, database creation, compatibility-level setup, test execution, and
cleanup remain owned by the xtask harness.

## Debugging

Keep the container after a failed run:

```bash
cargo xtask sqlserver-test --keep-container
```

Change the SQL Server image:

```bash
cargo xtask sqlserver-test --image mcr.microsoft.com/mssql/server:2017-latest
cargo xtask sqlserver-compat-probe --image mcr.microsoft.com/mssql/server:2022-latest --version 2022 --compatibility-level 160
```