diff --git a/.github/workflows/pr-code-security.yml b/.github/workflows/pr-code-security.yml
index fde10666c..3448776aa 100644
--- a/.github/workflows/pr-code-security.yml
+++ b/.github/workflows/pr-code-security.yml
@@ -4,13 +4,34 @@ on:
pull_request:
branches: [main]
+permissions:
+ contents: read
+
jobs:
secret-detection:
name: Secret Detection
- if: github.event_name == 'pull_request'
- uses: prisma/.github/.github/workflows/secret_detection.yml@main
- secrets: inherit
- code-scanning:
- name: Code Scanning
- if: github.event_name == 'pull_request'
- uses: prisma/.github/.github/workflows/code_scanning.yml@main
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ # Full history so gitleaks can scan every commit in the PR range.
+ fetch-depth: 0
+ persist-credentials: false
+ # We run the gitleaks CLI directly rather than gitleaks-action: the
+ # action wrapper requires a paid license for repos under a GitHub
+ # organization, while the gitleaks binary itself is MIT-licensed and
+ # free. Pinned by version and verified by SHA-256 before use.
+ - name: Install gitleaks
+ env:
+ GITLEAKS_VERSION: 8.30.1
+ GITLEAKS_SHA256: 551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
+ run: |
+ set -euo pipefail
+ url="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+ curl -sSfL "$url" -o gitleaks.tar.gz
+ echo "${GITLEAKS_SHA256} gitleaks.tar.gz" | sha256sum -c -
+ tar -xzf gitleaks.tar.gz gitleaks
+ sudo install gitleaks /usr/local/bin/gitleaks
+ gitleaks version
+ - name: Scan git history for secrets
+ run: gitleaks git --no-banner --redact --exit-code 1 --config .gitleaks.toml .
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
new file mode 100644
index 000000000..71985011d
--- /dev/null
+++ b/.github/workflows/security.yml
@@ -0,0 +1,29 @@
+name: Security audit
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ schedule:
+ # Re-run weekly so newly-published advisories are caught even without a push.
+ - cron: "0 6 * * 1"
+
+permissions:
+ contents: read
+
+jobs:
+ cargo-deny:
+ name: cargo-deny (advisories, bans, sources, licenses)
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+ with:
+ toolchain: stable
+ # Run cargo-deny on the runner directly (the musl container action conflicts with the repo's rust-toolchain file).
+ - name: Install cargo-deny
+ uses: taiki-e/install-action@cargo-deny
+ - name: Check advisories, bans, sources, licenses
+ run: cargo deny check advisories bans sources licenses
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index fec4c17a0..4de9c1fdc 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -1,39 +1,132 @@
name: Cargo tests
on:
+ # qa + manual dispatch run the integration tier
push:
branches:
- main
+ - qa
pull_request:
+ workflow_dispatch:
jobs:
clippy:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v1
- - uses: actions-rs/toolchain@v1
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
- components: clippy
- override: true
- - name: Install dependencies
- run: sudo apt install -y openssl libkrb5-dev
- - uses: actions-rs/clippy-check@v1
+ persist-credentials: false
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
with:
- token: ${{ secrets.GITHUB_TOKEN }}
- args: --features=all
+ toolchain: stable
+ components: clippy
+ - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+ - name: Install dependencies
+ run: sudo apt-get update && sudo apt-get install -y openssl libkrb5-dev
+ - name: Clippy
+ # Advisory here: modernizes the retired actions-rs/clippy-check and reports
+ # lints without gating. The strict `-D warnings` gate lands together with its
+ # baseline-lint fixes in the feature stack, so main is never red in between.
+ run: cargo clippy --features=all
format:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v2
- - uses: actions-rs/toolchain@v1
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
- components: rustfmt
- override: true
- - uses: mbrobbel/rustfmt-check@master
+ persist-credentials: false
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
with:
- token: ${{ secrets.GITHUB_TOKEN }}
+ toolchain: stable
+ components: rustfmt
+ - name: Rustfmt
+ run: cargo fmt --check
- cargo-test-linux:
+ msrv:
+ name: MSRV (1.88)
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ # Keep this in sync with `rust-version` in Cargo.toml.
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+ with:
+ toolchain: "1.88"
+ - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+ - name: Install dependencies
+ run: sudo apt-get update && sudo apt-get install -y openssl libkrb5-dev
+ - name: Check on MSRV
+ run: cargo check --features all
+
+ # The `rustls-webpki-roots` feature (and the rustls trust-store code paths in
+ # general) are excluded from `--features=all` because the three TLS backends
+ # are mutually exclusive, so neither the clippy nor the MSRV job above builds
+ # them. This server-less lane keeps them clippy-clean, buildable, and unit-
+ # tested so a regression (e.g. a `webpki-roots` major bump changing
+ # `TLS_SERVER_ROOTS`) is caught in CI.
+ rustls-features:
+ name: rustls trust-store (unit)
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+ with:
+ toolchain: stable
+ - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+ - name: Install dependencies
+ run: sudo apt-get update && sudo apt-get install -y openssl libkrb5-dev
+ # Build + unit-test both rustls feature sets. `--lib` needs no live server.
+ # (Strict `-D warnings` clippy is deferred repo-wide until the baseline
+ # lints land, matching the advisory `clippy` job above.)
+ - name: Unit tests (rustls)
+ run: cargo test --no-default-features --features rustls,chrono,time,tds73 --lib
+ - name: Unit tests (rustls-webpki-roots)
+ run: cargo test --no-default-features --features rustls-webpki-roots,chrono,time,tds73 --lib
+
+ semver:
+ name: semver-checks (advisory)
+ if: github.event_name == 'pull_request'
+ runs-on: ubuntu-latest
+ # Advisory during 0.x: reports API-breaking changes vs the target branch
+ # without blocking (breaking changes are allowed pre-1.0, but should be
+ # visible in review).
+ continue-on-error: true
+ steps:
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ fetch-depth: 0
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+ with:
+ toolchain: stable
+ - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+ - name: Install dependencies
+ run: sudo apt-get update && sudo apt-get install -y openssl libkrb5-dev
+ - name: Install cargo-semver-checks
+ uses: taiki-e/install-action@cargo-semver-checks
+ - name: Fetch baseline branch
+ # `actions/checkout` leaves the PR base branch without a local ref, so
+ # `--baseline-rev origin/` can't be resolved; fetch it explicitly
+ # and compare against FETCH_HEAD.
+ run: git fetch --no-tags --depth=100 origin "${{ github.base_ref }}"
+ - name: Check for semver-breaking changes
+ # Scope to one coherent, non-conflicting feature set. Checking all
+ # features at once enables the mutually-exclusive TLS backends
+ # (native-tls + rustls + vendored-openssl) together, whose duplicate
+ # `TlsStream` definitions make rustdoc fail to build (E0428). These are
+ # also the crate's original features, so they exist in every baseline
+ # slice this PR is compared against.
+ run: >-
+ cargo semver-checks --baseline-rev FETCH_HEAD
+ --only-explicit-features
+ --features rustls,chrono,time,tds73,rust_decimal,bigdecimal
+
+ smoke:
+ name: integration smoke (SQL 2022)
+ # Fast real-server signal on the dev lane; the full matrix runs on qa.
+ if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == 'refs/heads/dev')
runs-on: ubuntu-latest
strategy:
@@ -51,34 +144,143 @@ jobs:
- "--no-default-features --features=time"
- "--no-default-features --features=rustls"
- "--no-default-features --features=vendored-openssl"
+ - "--no-default-features --features=rustls,chrono,time,tds73,rust_decimal,bigdecimal"
env:
TIBERIUS_TEST_CONNECTION_STRING: "server=tcp:localhost,1433;user=SA;password=;TrustServerCertificate=true"
RUSTFLAGS: "-Dwarnings"
steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
- - uses: actions-rs/toolchain@v1
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+ with:
+ toolchain: stable
+
+ - name: Compute cache key
+ shell: bash
+ run: |
+ key="${{ matrix.features }}"
+ key="${key//,/+}"
+ echo "RUST_CACHE_KEY=$key" >> "$GITHUB_ENV"
- - uses: actions/cache@v2
+ - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
with:
- path: |
- ~/.cargo/registry
- ~/.cargo/git
- target
- key: ${{ runner.os }}-cargo-${{ matrix.features }}
+ shared-key: ${{ env.RUST_CACHE_KEY }}
- name: Start SQL Server ${{matrix.database}}
- run: DOCKER_BUILDKIT=1 docker-compose -f docker-compose.yml up -d mssql-${{matrix.database}}
+ run: DOCKER_BUILDKIT=1 docker compose -f docker-compose.yml up -d mssql-${{matrix.database}}
- name: Install dependencies
- run: sudo apt install -y openssl libkrb5-dev
+ run: sudo apt-get update && sudo apt-get install -y openssl libkrb5-dev
+
+ - name: Wait for SQL Server
+ # A listening port is not readiness: SQL Server binds 1433 before the SA
+ # login and databases finish initializing, so tests started too early race
+ # it and hit sporadic connection/login failures. Gate on an authenticated
+ # `SELECT 1` from a throwaway mssql-tools container (works uniformly across
+ # the full server images and azure-sql-edge, which ships no in-box sqlcmd).
+ run: |
+ pw=''
+ for _ in $(seq 1 60); do
+ if docker run --rm --network host mcr.microsoft.com/mssql-tools \
+ /opt/mssql-tools/bin/sqlcmd -S localhost,1433 -U SA -P "$pw" -Q "SELECT 1" >/dev/null 2>&1; then
+ echo "SQL Server ready (authenticated login succeeded)"; exit 0
+ fi
+ sleep 3
+ done
+ echo "SQL Server did not accept an authenticated login in time" >&2
+ docker compose -f docker-compose.yml logs mssql-${{matrix.database}} || true
+ exit 1
- name: Run tests
run: cargo test ${{matrix.features}}
- cargo-test-windows:
+ integration-macos:
+ name: macos (SQL 2022 via colima)
+ if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/qa')
+ # Intel runner: hosted macOS has no Linux Docker daemon, so we host the
+ # linux/amd64 SQL Server container inside a colima (Lima) Linux VM. An x86_64
+ # runner runs that image natively — no qemu emulation — which keeps the VM
+ # fast enough for the full integration suite instead of build + unit only.
+ runs-on: macos-15-intel
+ continue-on-error: ${{ matrix.soft_fail }}
+ strategy:
+ fail-fast: false
+ matrix:
+ # Exercise every TLS backend:
+ include:
+ # rustls (TLS 1.3)
+ - features: "--no-default-features --features=rustls,chrono,time,tds73,rust_decimal,bigdecimal"
+ soft_fail: false
+ # vendored-openssl (opentls, statically-linked OpenSSL) — cross-platform.
+ - features: "--no-default-features --features=vendored-openssl,chrono,time,tds73,rust_decimal,bigdecimal"
+ soft_fail: false
+ # NOTE: a `--features=all` lane is intentionally omitted here. On macOS
+ # `native-tls` resolves to Apple Secure Transport, which cannot complete
+ # the SQL Server TLS handshake (it works on Linux=OpenSSL and
+ # Windows=SChannel, both covered elsewhere). Running it here could only
+ # ever fail, so the two TLS backends that do work on macOS (rustls and
+ # vendored-openssl, above) provide the macOS integration coverage.
+ env:
+ TIBERIUS_TEST_CONNECTION_STRING: "server=tcp:localhost,1433;user=SA;password=;TrustServerCertificate=true"
+ RUSTFLAGS: "-Dwarnings"
+ steps:
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+ with:
+ toolchain: stable
+ - name: Compute cache key
+ run: |
+ key="${{ matrix.features }}"
+ key="${key//,/+}"
+ echo "RUST_CACHE_KEY=$key" >> "$GITHUB_ENV"
+ - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+ with:
+ shared-key: ${{ env.RUST_CACHE_KEY }}
+ - name: Install build dependencies (openssl, krb5)
+ run: |
+ brew install openssl krb5
+ # krb5 is keg-only; expose its pkg-config so integrated-auth-gssapi
+ # and any openssl-linking features build against Homebrew's copy.
+ echo "PKG_CONFIG_PATH=$(brew --prefix krb5)/lib/pkgconfig:$(brew --prefix openssl)/lib/pkgconfig" >> "$GITHUB_ENV"
+ - name: Start Docker (colima)
+ run: |
+ brew install colima docker docker-compose
+ # SQL Server wants ~2 GB RAM; give the VM headroom for it + the build.
+ colima start --cpu 3 --memory 6 --disk 20
+ docker version
+ - name: Start SQL Server 2022
+ run: docker compose -f docker-compose.yml up -d mssql-2022
+ - name: Wait for SQL Server
+ # A listening port is not readiness: SQL Server binds 1433 before the SA
+ # login and databases finish initializing, so the connection-heavy bulk
+ # tests can race it and hit "Login failed for user 'SA'" (18456). Gate on
+ # an actual authenticated `SELECT 1` succeeding instead.
+ run: |
+ pw=''
+ for _ in $(seq 1 60); do
+ for bin in /opt/mssql-tools18/bin/sqlcmd /opt/mssql-tools/bin/sqlcmd; do
+ if docker compose -f docker-compose.yml exec -T mssql-2022 \
+ "$bin" -S localhost -U SA -P "$pw" -C -Q "SELECT 1" >/dev/null 2>&1; then
+ echo "SQL Server ready (authenticated login succeeded)"; exit 0
+ fi
+ done
+ sleep 3
+ done
+ echo "SQL Server did not accept an authenticated login in time" >&2
+ docker compose -f docker-compose.yml logs mssql-2022 || true
+ exit 1
+ - name: Run tests
+ run: cargo test ${{ matrix.features }}
+
+ integration-windows:
+ name: windows (SQL 2019, integrated auth)
+ if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/qa')
runs-on: windows-latest
strategy:
@@ -96,41 +298,39 @@ jobs:
TIBERIUS_TEST_CONNECTION_STRING: "server=tcp:127.0.0.1,1433;IntegratedSecurity=true;TrustServerCertificate=true"
steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+
+ - uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # v1
+ with:
+ toolchain: stable
+
+ - name: Compute cache key
+ shell: bash
+ run: |
+ key="${{ matrix.features }}"
+ key="${key//,/+}"
+ echo "RUST_CACHE_KEY=$key" >> "$GITHUB_ENV"
- - uses: actions-rs/toolchain@v1
+ - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+ with:
+ shared-key: ${{ env.RUST_CACHE_KEY }}
- name: Set required PowerShell modules
id: psmodulecache
- uses: potatoqualitee/psmodulecache@v1
+ uses: potatoqualitee/psmodulecache@ee5e9494714abf56f6efbfa51527b2aec5c761b8 # v6.2.1
with:
modules-to-cache: SqlServer
- - name: Setup PowerShell module cache
- id: cacher
- uses: actions/cache@v2
- with:
- path: ${{ steps.psmodulecache.outputs.modulepath }}
- key: ${{ steps.psmodulecache.outputs.keygen }}
-
- name: Setup Chocolatey download cache
id: chococache
- uses: actions/cache@v2
+ uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
with:
path: C:\Users\runneradmin\AppData\Local\Temp\chocolatey\
key: chocolatey-install
- - name: Setup Cargo build cache
- uses: actions/cache@v2
- with:
- path: |
- C:\Users\runneradmin\.cargo\registry
- C:\Users\runneradmin\.cargo\git
- target
- key: ${{ runner.os }}-cargo
-
- name: Install required PowerShell modules
- if: steps.cacher.outputs.cache-hit != 'true'
shell: powershell
run: |
Set-PSRepository PSGallery -InstallationPolicy Trusted
@@ -187,31 +387,3 @@ jobs:
- name: Run normal tests
shell: powershell
run: cargo test ${{matrix.features}}
-
- cargo-test-macos:
- runs-on: macos-12
-
- strategy:
- fail-fast: false
- matrix:
- database:
- - 2019
- features:
- - "--no-default-features --features=rustls,chrono,time,tds73,sql-browser-async-std,sql-browser-tokio,sql-browser-smol,integrated-auth-gssapi,rust_decimal,bigdecimal"
- - "--no-default-features --features=vendored-openssl"
-
- env:
- TIBERIUS_TEST_CONNECTION_STRING: "server=tcp:localhost,1433;user=SA;password=;TrustServerCertificate=true"
-
- steps:
- - uses: actions/checkout@v2
-
- - uses: actions-rs/toolchain@v1
-
- - uses: docker-practice/actions-setup-docker@master
-
- - name: Start SQL Server ${{matrix.database}}
- run: DOCKER_BUILDKIT=1 docker-compose -f docker-compose.yml up -d mssql-${{matrix.database}}
-
- - name: Run tests
- run: cargo test ${{matrix.features}}
diff --git a/.gitleaks.toml b/.gitleaks.toml
new file mode 100644
index 000000000..3439483e1
--- /dev/null
+++ b/.gitleaks.toml
@@ -0,0 +1,10 @@
+# gitleaks config for the PR secret scan: full default rule set, with the
+# self-signed TLS test fixtures under docker/certs/ allowlisted.
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Self-signed TLS test fixtures for the local integration-test SQL Server container"
+paths = [
+ '''docker/certs/.*''',
+]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fed7001e5..42611d30c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,83 @@
# Changes
+## Version 0.13.0
+
+- feat: TLS trust configuration is revamped around two orthogonal axes plus a
+ bypass, unifying community PRs #330 and #290:
+ - `Config::trust_cert_ca_bundle(bytes)` (and the `ConfigBuilder` mirror) trusts
+ additional CA certificates supplied as in-memory bytes, without writing them
+ to a temporary file. The bytes are auto-detected: a `-----BEGIN` marker is
+ parsed as a multi-certificate PEM bundle (e.g. the AWS RDS root bundle),
+ otherwise they are treated as a single DER certificate.
+ - `Config::trust_webpki_roots()` (and the `ConfigBuilder` mirror) bases trust
+ on a compiled-in snapshot of Mozilla's root CA store instead of the OS trust
+ store. rustls-only, behind the new `rustls-webpki-roots` feature. Note: the
+ bundled roots are a pinned snapshot that goes stale (missing newly added or
+ newly distrusted CAs) unless the dependency is updated and the app rebuilt.
+ - `Config::trust_cert_ca(path)` now accepts **multi-certificate** files (the
+ previous "exactly one certificate" restriction is lifted); every certificate
+ in the file is trusted, on all three TLS backends.
+- BREAKING: repeated `trust_cert_ca` calls now **accumulate** rather than
+ replace-last-wins. `trust_cert_ca(a); trust_cert_ca(b)` (and any mix with
+ `trust_cert_ca_bundle`) trusts every supplied CA, layered on top of the base
+ trust anchors. Code that relied on a later call overriding an earlier one must
+ now set the CA only once.
+- fix: a CA source (file or in-memory bundle) that yields zero usable
+ certificates is now a hard error naming the source, on every backend, instead
+ of silently degrading to base-roots-only trust. The `native-tls` and
+ `vendored-openssl` backends also now load *all* certificates from a
+ multi-certificate CA file/bundle (previously only the first was used) and
+ preserve the path plus underlying I/O error in load failures, matching rustls.
+- BREAKING: the connection-string `encrypt` default is now `Required` (was
+ `Off`) when a TLS backend is enabled, matching modern ADO.NET; without a TLS
+ backend it remains `NotSupported`.
+- BREAKING: removed the `sql-browser-async-std` feature and the async-std SQL
+ Browser integration.
+- feat: `Command`/RPC API for parameterized stored-procedure calls, plus a
+ `#[derive(TableValueRow)]` macro (in `tiberius-macros`) for table-valued
+ parameters.
+- feat: `sspi-rs` feature for Windows-style SSPI/NTLM authentication on Unix via
+ the pure-Rust `sspi` crate (no Kerberos required).
+- feat: `serde` feature adding `Serialize`/`Deserialize` impls for query result
+ types (`Row`, `Column`, `ColumnData`, `Numeric`, and the time/xml types).
+- feat: client-certificate authentication, including PEM/DER key files
+ (`Config::client_certificate`) and PKCS#12 bundles
+ (`Config::client_certificate_pkcs12`).
+- BREAKING: credentials (SQL Server / Windows passwords, the AAD bearer token
+ and the PKCS#12 password) are now stored as `secrecy::SecretString` instead of
+ `zeroize::Zeroizing`. They are still zeroized on drop, and their
+ `Debug` now renders as `SecretBox([REDACTED])` (was ``). The
+ `AuthMethod::AADToken` tuple variant consequently holds a `SecretString`: code
+ that pattern-matched it and read the token via `Deref`/`Display` must now call
+ `secrecy::ExposeSecret::expose_secret`. Constructing auth via
+ `AuthMethod::aad_token`/`sql_server`/`windows` is unchanged.
+- feat: connection & command timeouts (closes #375 and #360), matching
+ ADO.NET's two-knob model and backed by a runtime-agnostic timer so they apply
+ under any async runtime:
+ - `Config::handshake_timeout` bounds the whole post-TCP handshake (prelogin,
+ TLS negotiation and login), surfacing a `TimedOut` error instead of hanging
+ forever when a server accepts the TCP connection and then stalls
+ mid-handshake — the reported failure against `azure-sql-edge` on macOS
+ (#375) and the stalled-peer case in #360. Defaults to 15s (ADO.NET
+ `Connect Timeout` parity). The handshake also emits per-stage `tracing`
+ DEBUG events so a stall can be pinpointed.
+ - `Config::command_timeout` bounds each server round-trip while reading
+ command results (`query`/`execute`/`simple_query`, the `bulk_insert`
+ acknowledgement and `column_metadata`). It measures per-round-trip stall,
+ not total enumeration: the deadline resets on every delivered token, so a
+ slow consumer never trips it — only a stalled server does. Defaults to 30s
+ (ADO.NET `Command Timeout` parity).
+ - BREAKING: both knobs now default to a bounded value (15s handshake / 30s
+ command) where pre-0.13 they were effectively unbounded. A command that
+ legitimately runs longer than 30s between server round-trips (e.g. a long
+ `WAITFOR`, a big sort/aggregate or a slow stored procedure) will now fail
+ with a `TimedOut` error unless you raise or disable `command_timeout`. Pass
+ `None` to either knob to restore the pre-0.13 wait-indefinitely behaviour.
+- chore: upgraded the rustls stack to 0.23 (tokio-rustls 0.26) and resolved the
+ associated advisories.
+- fix: numerous decode-path hardening fixes (protocol errors instead of panics
+ or stream desyncs on hostile server input across the codec/token modules).
+
## Version 0.12.3
- feat: improve column type accuracy (#347)
- fix: encoding of zero-length values for large varlen columns (#315)
diff --git a/Cargo.toml b/Cargo.toml
index fb45b46e5..16bd8b76c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -8,24 +8,24 @@ authors = [
description = "A TDS (MSSQL) driver"
documentation = "https://docs.rs/tiberius/"
edition = "2021"
+rust-version = "1.88"
keywords = ["tds", "mssql", "sql"]
license = "MIT/Apache-2.0"
name = "tiberius"
readme = "README.md"
repository = "https://github.com/prisma/tiberius"
-version = "0.12.3"
+version = "0.13.0"
[workspace]
-members = ["runtimes-macro"]
+members = ["runtimes-macro", "tiberius-macros"]
[[test]]
path = "tests/query.rs"
name = "query"
[[test]]
-path = "tests/named-instance-async.rs"
-name = "named-instance-async"
-required-features = ["sql-browser-async-std"]
+path = "tests/command.rs"
+name = "command"
[[test]]
path = "tests/named-instance-tokio.rs"
@@ -37,29 +37,46 @@ path = "tests/named-instance-smol.rs"
name = "named-instance-smol"
required-features = ["sql-browser-smol"]
+[[test]]
+path = "tests/serde.rs"
+name = "serde"
+required-features = ["serde"]
+
+[[example]]
+name = "named-pipes"
+path = "examples/named-pipes.rs"
+
[dependencies]
enumflags2 = "0.7"
byteorder = "1.0"
encoding_rs = "0.8"
once_cell = "1.3"
-thiserror = "1.0"
+thiserror = "2"
bytes = "1.0"
-pretty-hex = "0.3"
+pretty-hex = "0.4"
pin-project-lite = "0.2"
-asynchronous-codec = "0.6"
+asynchronous-codec = "0.7"
async-trait = "0.1"
connection-string = "0.2"
num-traits = "0.2"
uuid = "1.0"
-
-winauth = { version = "0.0.4", optional = true }
+zeroize = "1.8.2"
+secrecy = "0.10"
+
+# Cross-platform: the NTLMv2 client (`winauth::NtlmV2Client`) is pure Rust and
+# backs `AuthMethod::Windows` on every target. Only its `windows` SSPI module
+# (used by `AuthMethod::Integrated`) is Windows-specific.
+[dependencies.winauth]
+version = "0.0.5"
+optional = true
[target.'cfg(unix)'.dependencies]
-libgssapi = { version = "0.8.1", optional = true, default-features = false }
+libgssapi = { version = "0.11", optional = true, default-features = false }
+sspi = { version = "0.18", optional = true }
+libc = "0.2"
[dependencies.async-native-tls]
-version = "0.4"
-features = ["runtime-async-std"]
+version = "0.6"
optional = true
[dependencies.tokio]
@@ -72,11 +89,6 @@ version = "0.7"
features = ["compat"]
optional = true
-[dependencies.async-std]
-version = "1"
-optional = true
-features = ["attributes"]
-
[dependencies.chrono]
version = "0.4"
optional = true
@@ -91,6 +103,13 @@ version = "0.3"
default-features = false
features = ["io", "sink"]
+# Runtime-agnostic timer used to bound the connection handshake (see
+# `Config::handshake_timeout`). Its `Delay` future works under any executor, so
+# the generic, runtime-agnostic `Connection::connect` path can enforce a timeout
+# without depending on tokio/smol timers.
+[dependencies.futures-timer]
+version = "3"
+
[dependencies.tracing]
features = ["log"]
version = "0.1"
@@ -100,33 +119,55 @@ version = "1.6"
optional = true
[dependencies.bigdecimal_]
-version = "0.3"
+version = "0.4"
optional = true
package = "bigdecimal"
+[dependencies.serde]
+version = "1.0"
+optional = true
+features = ["derive", "rc"]
+
[dependencies.async-io]
-version = "1.8"
+version = "2"
optional = true
[dependencies.async-net]
-version = "1.7"
+version = "2"
optional = true
[dependencies.futures-lite]
-version = "1.12.0"
+version = "2"
optional = true
[dependencies.tokio-rustls]
-version = "0.24.0"
+version = "0.26.4"
+optional = true
+
+[dependencies.rustls-native-certs]
+version = "0.8"
+optional = true
+
+# Version-floor pin for RUSTSEC-2026-0104 (rustls-webpki < 0.103.13); pulled in via tokio-rustls.
+[dependencies.rustls-webpki]
+version = "0.103.13"
optional = true
-features = ["dangerous_configuration"]
+default-features = false
-[dependencies.rustls-pemfile]
+# Shared certificate DER/PEM types used by the backend-agnostic CA loader
+# (`src/client/tls_stream/certs.rs`). Enabled by every TLS backend so all three
+# parse trust anchors through one code path. This is the same `rustls-pki-types`
+# crate `tokio-rustls` re-exports, so the `CertificateDer` handed to rustls is
+# the exact same type.
+[dependencies.rustls-pki-types]
version = "1"
optional = true
-[dependencies.rustls-native-certs]
-version = "0.6"
+# Compiled-in Mozilla root CA bundle for the `rustls-webpki-roots` feature.
+# Pinned to its current major (1.x). Note: this is a *pinned snapshot* that goes
+# stale unless the dependency is updated.
+[dependencies.webpki-roots]
+version = "1"
optional = true
[dependencies.opentls]
@@ -161,50 +202,74 @@ features = [
]
version = "1.0"
-[dev-dependencies.async-std]
-features = ["attributes"]
-version = "1"
+[dev-dependencies.smol]
+version = "2"
[dev-dependencies.runtimes-macro]
path = "./runtimes-macro"
+[dependencies.tiberius-macros]
+path = "./tiberius-macros"
+version = "0.1.0"
+
[dev-dependencies]
names = "0.14"
anyhow = "1"
-env_logger = "0.9"
-azure_identity = "0.5.0"
-oauth2 = "4.2.3"
-url = "2.2.2"
-reqwest = "0.11.10"
+env_logger = "0.11"
+azure_identity = "1.0"
+azure_core = "1"
+url = "2.5"
+reqwest = "0.13"
paste = "1.0"
-indicatif = "0.17"
+indicatif = "0.18"
chrono = "0.4.38"
-indoc = "1.0.7"
+indoc = "2"
+serde_json = "1.0"
[package.metadata.docs.rs]
-features = ["all", "docs"]
+features = ["all"]
+# docs.rs builds on nightly with this cfg set, enabling #[doc(cfg(...))]
+# annotations (feature(doc_cfg)) without requiring nightly for normal builds.
+rustdoc-args = ["--cfg", "docsrs"]
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(docsrs)'] }
[features]
all = [
"chrono",
"time",
"tds73",
- "sql-browser-async-std",
+ "tds80",
"sql-browser-tokio",
"sql-browser-smol",
"integrated-auth-gssapi",
"rust_decimal",
"bigdecimal",
"native-tls",
+ "serde",
+ "sspi-rs",
]
-default = ["tds73", "winauth", "native-tls"]
+default = ["tds80", "winauth", "native-tls"]
tds73 = []
-docs = []
-sql-browser-async-std = ["async-std"]
+# Enables TDS 8.0 support, including the `Strict` encryption level (TLS before
+# the TDS prelogin, TDS 8.0 "strict" mode). Requires a TLS backend.
+tds80 = ["tds73"]
sql-browser-tokio = ["tokio", "tokio-util"]
sql-browser-smol = ["async-io", "async-net", "futures-lite"]
integrated-auth-gssapi = ["libgssapi"]
bigdecimal = ["bigdecimal_"]
-rustls = ["tokio-rustls", "tokio-util", "rustls-pemfile", "rustls-native-certs"]
-native-tls = ["async-native-tls"]
-vendored-openssl = ["opentls", "schannel"]
+rustls = ["tokio-rustls", "tokio-util", "rustls-native-certs", "rustls-webpki", "rustls-pki-types"]
+# Bundle a compiled-in snapshot of Mozilla's root CA store, selectable via
+# `Config::trust_webpki_roots()` (rustls only). Implies `rustls`; the bundled
+# roots are a pinned snapshot that goes stale without dependency updates.
+rustls-webpki-roots = ["rustls", "dep:webpki-roots"]
+native-tls = ["async-native-tls", "rustls-pki-types"]
+vendored-openssl = ["opentls", "rustls-pki-types", "schannel"]
+# Enables Windows-style SSPI/NTLM authentication (`AuthMethod::Windows`) on Unix
+# platforms without requiring Kerberos, via the pure-Rust `sspi` crate. On
+# Windows the same authentication is provided by the `winauth` feature.
+sspi-rs = ["sspi"]
+# Optional serde Serialize/Deserialize impls for query result types
+# (Row, Column, ColumnData, Numeric, ColumnType and time/xml types).
+serde = ["dep:serde", "uuid/serde"]
diff --git a/README.md b/README.md
index 44398dc55..84a102ea7 100644
--- a/README.md
+++ b/README.md
@@ -44,10 +44,12 @@ A native Microsoft SQL Server (TDS) client for Rust.
| `time` | Read and write date and time values using `time` crate types. | `disabled` |
| `rust_decimal` | Read and write `numeric`/`decimal` values using `rust_decimal`'s `Decimal`. | `disabled` |
| `bigdecimal` | Read and write `numeric`/`decimal` values using `bigdecimal`'s `BigDecimal`. | `disabled` |
-| `sql-browser-async-std` | SQL Browser implementation for the `TcpStream` of async-std. | `disabled` |
| `sql-browser-tokio` | SQL Browser implementation for the `TcpStream` of Tokio. | `disabled` |
| `sql-browser-smol` | SQL Browser implementation for the `TcpStream` of smol. | `disabled` |
| `integrated-auth-gssapi` | Support for using Integrated Auth via GSSAPI | `disabled` |
+| `winauth` | Windows-only SSPI/NTLM integrated authentication (`AuthMethod::Windows`). | `enabled` |
+| `sspi-rs` | Windows-style SSPI/NTLM authentication on Unix via the pure-Rust `sspi` crate (no Kerberos required). | `disabled` |
+| `serde` | `serde` `Serialize`/`Deserialize` impls for query result types (`Row`, `Column`, `ColumnData`, `Numeric`, etc.). | `disabled` |
### Supported protocols
diff --git a/deny.toml b/deny.toml
new file mode 100644
index 000000000..f515700c0
--- /dev/null
+++ b/deny.toml
@@ -0,0 +1,43 @@
+# Run locally with: cargo deny check advisories bans sources
+# CI runs the same via .github/workflows/security.yml.
+#
+# Policy: a vulnerability or yanked crate in the default-built graph fails the build; ignored advisories are only reachable via dev-deps or opt-in features.
+
+[advisories]
+yanked = "deny"
+ignore = [
+ # The following are ALL dev-dependency-only (test harness + the aad-auth
+ # example) and are never compiled into the published library.
+ { id = "RUSTSEC-2024-0375", reason = "atty: dev-dependency only (via `names` -> clap 3); not shipped" },
+ { id = "RUSTSEC-2024-0370", reason = "proc-macro-error: dev-dependency only (via `names` -> clap 3); not shipped" },
+ { id = "RUSTSEC-2024-0436", reason = "paste: dev/test only (tests/bulk.rs + azure_identity example); not shipped" },
+]
+
+[licenses]
+# Allow-list for the current dependency graph (verified locally with
+# `cargo deny check licenses`). Every crate resolves to at least one of these
+# via its SPDX expression; add new entries here rather than loosening the policy.
+allow = [
+ "MIT",
+ "MIT-0",
+ "Apache-2.0",
+ "Apache-2.0 WITH LLVM-exception",
+ "BSD-1-Clause",
+ "BSD-2-Clause",
+ "BSD-3-Clause",
+ "ISC",
+ "CC0-1.0",
+ "Unicode-3.0",
+ "Unlicense",
+]
+# Confidence threshold for detecting a license from its text (0.0 - 1.0).
+confidence-threshold = 0.8
+
+[bans]
+multiple-versions = "warn"
+wildcards = "allow"
+
+[sources]
+unknown-registry = "deny"
+unknown-git = "deny"
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
diff --git a/docker-compose.yml b/docker-compose.yml
index db5f3a39a..2aef9c6e4 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,6 +1,7 @@
version: "3"
services:
mssql-2022:
+ platform: linux/amd64
build:
context: docker/
dockerfile: docker-mssql-2022.dockerfile
@@ -12,6 +13,7 @@ services:
- "1433:1433"
mssql-2019:
+ platform: linux/amd64
build:
context: docker/
dockerfile: docker-mssql-2019.dockerfile
@@ -23,6 +25,7 @@ services:
- "1433:1433"
mssql-2017:
+ platform: linux/amd64
build:
context: docker/
dockerfile: docker-mssql-2017.dockerfile
@@ -34,6 +37,7 @@ services:
- "1433:1433"
mssql-azure-sql-edge:
+ platform: linux/amd64
build:
context: docker/
dockerfile: docker-azure-sql-edge.dockerfile
diff --git a/docker/certs/customCA.srl b/docker/certs/customCA.srl
index 618df7789..a02a6570a 100644
--- a/docker/certs/customCA.srl
+++ b/docker/certs/customCA.srl
@@ -1 +1 @@
-0DAEECC45C07F5E06E0DD1B05115C3CFD1A46D9C
+0DAEECC45C07F5E06E0DD1B05115C3CFD1A46D9D
diff --git a/docker/certs/generate-signed-cert.sh b/docker/certs/generate-signed-cert.sh
index dc3086f29..db3858cca 100755
--- a/docker/certs/generate-signed-cert.sh
+++ b/docker/certs/generate-signed-cert.sh
@@ -5,8 +5,10 @@ set -o pipefail
# Skript creates a custom-signed certificate
# Parameter1 = name of the cert
+# Parameter2 = validity in days (default 1825)
CERT_KEY_NAME=$1
+CERT_DAYS=${2:-1825}
CERT_FILE=$CERT_KEY_NAME.crt
export CERT_CN=$CERT_KEY_NAME
@@ -32,7 +34,7 @@ openssl x509 -req \
-CAserial customCA.srl \
-out $CERT_FILE \
-passin file:passphrase.txt \
- -days 200
+ -days $CERT_DAYS
echo Generating PEM format
openssl rsa -in ${CERT_KEY_NAME}.key -out ${CERT_KEY_NAME}-nopassword.key
diff --git a/docker/certs/server-full.crt b/docker/certs/server-full.crt
index 31ceafd70..1128cc190 100644
--- a/docker/certs/server-full.crt
+++ b/docker/certs/server-full.crt
@@ -1,33 +1,33 @@
-----BEGIN CERTIFICATE-----
-MIIFVDCCAzygAwIBAgIUDa7sxFwH9eBuDdGwURXDz9GkbZwwDQYJKoZIhvcNAQEL
-BQAwDzENMAsGA1UEAwwEQWNtZTAeFw0yNDA2MDMxMTQwMzNaFw0yNDEyMjAxMTQw
-MzNaMEAxCzAJBgNVBAYTAkRFMQ0wCwYDVQQKDARBY21lMREwDwYDVQQLDAhUaWJl
+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
-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
+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
-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
-HTMZ5IJXU9f1XKtMHLdGRpx0YiEGTw0e
+BQcDAjAdBgNVHQ4EFgQUKTH2Ri4hNDGnL4ifUg7HEbEwhbQwHwYDVR0jBBgwFoAU
+RHcTzm1u6x8WiXeAWDblHzwBt9kwDQYJKoZIhvcNAQELBQADggIBAByBbh6Mj+jp
+z0Rb2vdiEV4sK0o+ad96p74ZJdiyeTLki8fLSxtKlnlrlhAzY/YFr49KQJKOzbHM
+X1aoieL4Si72eprWREyNcXuD2N7tuVnw8/p3WpqW7IKBXSDDdqkdppc1B+LvTBwI
++FXSdou7dPuHgim8fHmoz/ogj+Zf1gvog3ohcnAtj9kN0zfQoBjeyjQ7v81uQ0sx
+K8AO+yg/P/IWSNfzEMEGRxT91as9IrV+nmvIfe7k14ljDdJDsf+FRkea9UBOhtJW
+G7cqFeWTCBV7W8bjFB0kBF9HE09E2B7hUtYZwOpVruhxXdy7WdzQzx8RWXG/bJnS
+qML1bw+sdY+RtfbOr1jy8ctcAg+OmBbR0qLDQeuWlXqjTtxoHViMZpa6lNtIuD8+
+1e3+iFJ53djOSgSZ6XW163HI9353nrr1dXtlx7kdPZsb5Z3FXvL940rLiIx69ftR
+dP4hP7iWstrUsrwnk6E3OmVwzc+pD8f72ztFhcqI81rmvgJ/MufGvaKoB254OibT
+ng4pgs4NF2kKSFmqhXG1dTen2XRlg4ZecLrcCcotdcFX4qPEGcPjjQ4UEEaYhgFW
+yWmTUWJEMO9BtqSxUFTZiQ8Ul0cJs16CyAC+oxGhaM92r7w/2xZ7fH4MHGyzJcm6
+WY7hfVHCK4+xjXMLn+k5qZYVEPUPe+0s
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIE/zCCAuegAwIBAgIUATFLyERaRfsQiPasMC5l0vrBMUMwDQYJKoZIhvcNAQEL
diff --git a/docker/certs/server.crt b/docker/certs/server.crt
index 95e4d43e4..2804eb8af 100644
--- a/docker/certs/server.crt
+++ b/docker/certs/server.crt
@@ -1,31 +1,31 @@
-----BEGIN CERTIFICATE-----
-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
+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
-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
+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
-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
-HTMZ5IJXU9f1XKtMHLdGRpx0YiEGTw0e
+BQcDAjAdBgNVHQ4EFgQUKTH2Ri4hNDGnL4ifUg7HEbEwhbQwHwYDVR0jBBgwFoAU
+RHcTzm1u6x8WiXeAWDblHzwBt9kwDQYJKoZIhvcNAQELBQADggIBAByBbh6Mj+jp
+z0Rb2vdiEV4sK0o+ad96p74ZJdiyeTLki8fLSxtKlnlrlhAzY/YFr49KQJKOzbHM
+X1aoieL4Si72eprWREyNcXuD2N7tuVnw8/p3WpqW7IKBXSDDdqkdppc1B+LvTBwI
++FXSdou7dPuHgim8fHmoz/ogj+Zf1gvog3ohcnAtj9kN0zfQoBjeyjQ7v81uQ0sx
+K8AO+yg/P/IWSNfzEMEGRxT91as9IrV+nmvIfe7k14ljDdJDsf+FRkea9UBOhtJW
+G7cqFeWTCBV7W8bjFB0kBF9HE09E2B7hUtYZwOpVruhxXdy7WdzQzx8RWXG/bJnS
+qML1bw+sdY+RtfbOr1jy8ctcAg+OmBbR0qLDQeuWlXqjTtxoHViMZpa6lNtIuD8+
+1e3+iFJ53djOSgSZ6XW163HI9353nrr1dXtlx7kdPZsb5Z3FXvL940rLiIx69ftR
+dP4hP7iWstrUsrwnk6E3OmVwzc+pD8f72ztFhcqI81rmvgJ/MufGvaKoB254OibT
+ng4pgs4NF2kKSFmqhXG1dTen2XRlg4ZecLrcCcotdcFX4qPEGcPjjQ4UEEaYhgFW
+yWmTUWJEMO9BtqSxUFTZiQ8Ul0cJs16CyAC+oxGhaM92r7w/2xZ7fH4MHGyzJcm6
+WY7hfVHCK4+xjXMLn+k5qZYVEPUPe+0s
-----END CERTIFICATE-----
diff --git a/docker/certs/server.key b/docker/certs/server.key
index 7e60bb02e..71c4e52fd 100644
--- a/docker/certs/server.key
+++ b/docker/certs/server.key
@@ -1,52 +1,52 @@
-----BEGIN PRIVATE KEY-----
-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
-Oeu1HE+LelnM2vOc9TtbJC9FrC8nYw==
+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
+6FJg2C5WHHHhAOWiS+gM1HBaeLSLwA==
-----END PRIVATE KEY-----
diff --git a/docker/certs/server.pem b/docker/certs/server.pem
index 7acbb192f..4fc2c9526 100644
--- a/docker/certs/server.pem
+++ b/docker/certs/server.pem
@@ -1,83 +1,83 @@
-----BEGIN PRIVATE KEY-----
-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
-Oeu1HE+LelnM2vOc9TtbJC9FrC8nYw==
+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
+6FJg2C5WHHHhAOWiS+gM1HBaeLSLwA==
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
-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
+MIIFVDCCAzygAwIBAgIUDa7sxFwH9eBuDdGwURXDz9GkbZ0wDQYJKoZIhvcNAQEL
+BQAwDzENMAsGA1UEAwwEQWNtZTAeFw0yNjA1MTExOTA2MzlaFw0yNzExMDIxOTA2
+MzlaMEAxCzAJBgNVBAYTAkRFMQ0wCwYDVQQKDARBY21lMREwDwYDVQQLDAhUaWJl
cml1czEPMA0GA1UEAwwGc2VydmVyMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIIC
-CgKCAgEAztKC7UloJuxGMaOslWm7vEDcd8YkcC9P4PMqDTS0qgr/IXeK1LB1Pt2w
-iEY4Bz/Bd3boj2IMgRzT9gjtJoD6Y3Aa32UWp1TgrDtLQ6Bns30d6sNdk7xJ5m9v
-qM3ZpJSdLNKolvldcdbUWQkthKUCArNQzHUoHI70PNZGKE6iikWoqvOv4xUq3L8J
-e5Ows8fw8NY8TyaJAiHE8zOH0kUyRGaVp2+ku6qNHLFPaLk/iJjlMs1CfsdUNjNN
-/N5YhwYxF7ikIhsnNXV7/AHKQeM0z5jlD74VwnquuyXc0Mgq4I99xg7nJXQNLKdU
-X7thDJ8BJdKM7i8KKn/UgDoU2USIiF1x8GsqZzFR//LS9lt+n/utduEdBX7Ut0rr
-nv2lQZhL4313hyzdv0f5gaEjCAndQXu/oq9SutJDAa3uszHejiyBEWgpfY7xiaTT
-xf5XMTue+hbwruXLlX+H0tdH9W/BWuT7+RR3H35nKZ4FLyNG0g3joL5la3WIhRHb
-9PP5hZSB6Mf1mnWuBWiJ63MJzAVsfuwyBMir8feRbj+YvI6azPXfkz874OdWnN9F
-Zi6GUWy3z4UAwnC0OXO5WwH56gHfZi9u2S70Zho4jPPnF3OP2KrVJSQNrc9qwC1M
-0HJNcYw9O4ERnI5OYkclEafrK98VVRPhnuKLDak31jenUh4nwNECAwEAAaN3MHUw
+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
-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
-HTMZ5IJXU9f1XKtMHLdGRpx0YiEGTw0e
+BQcDAjAdBgNVHQ4EFgQUKTH2Ri4hNDGnL4ifUg7HEbEwhbQwHwYDVR0jBBgwFoAU
+RHcTzm1u6x8WiXeAWDblHzwBt9kwDQYJKoZIhvcNAQELBQADggIBAByBbh6Mj+jp
+z0Rb2vdiEV4sK0o+ad96p74ZJdiyeTLki8fLSxtKlnlrlhAzY/YFr49KQJKOzbHM
+X1aoieL4Si72eprWREyNcXuD2N7tuVnw8/p3WpqW7IKBXSDDdqkdppc1B+LvTBwI
++FXSdou7dPuHgim8fHmoz/ogj+Zf1gvog3ohcnAtj9kN0zfQoBjeyjQ7v81uQ0sx
+K8AO+yg/P/IWSNfzEMEGRxT91as9IrV+nmvIfe7k14ljDdJDsf+FRkea9UBOhtJW
+G7cqFeWTCBV7W8bjFB0kBF9HE09E2B7hUtYZwOpVruhxXdy7WdzQzx8RWXG/bJnS
+qML1bw+sdY+RtfbOr1jy8ctcAg+OmBbR0qLDQeuWlXqjTtxoHViMZpa6lNtIuD8+
+1e3+iFJ53djOSgSZ6XW163HI9353nrr1dXtlx7kdPZsb5Z3FXvL940rLiIx69ftR
+dP4hP7iWstrUsrwnk6E3OmVwzc+pD8f72ztFhcqI81rmvgJ/MufGvaKoB254OibT
+ng4pgs4NF2kKSFmqhXG1dTen2XRlg4ZecLrcCcotdcFX4qPEGcPjjQ4UEEaYhgFW
+yWmTUWJEMO9BtqSxUFTZiQ8Ul0cJs16CyAC+oxGhaM92r7w/2xZ7fH4MHGyzJcm6
+WY7hfVHCK4+xjXMLn+k5qZYVEPUPe+0s
-----END CERTIFICATE-----
diff --git a/docker/docker-azure-sql-edge.dockerfile b/docker/docker-azure-sql-edge.dockerfile
index 14279c405..d4a009035 100644
--- a/docker/docker-azure-sql-edge.dockerfile
+++ b/docker/docker-azure-sql-edge.dockerfile
@@ -1,5 +1,9 @@
FROM mcr.microsoft.com/azure-sql-edge:latest
-COPY --chmod=440 certs/server.* /certs/
-COPY --chmod=440 certs/customCA.* /certs/
+USER root
+COPY certs/server.* /certs/
+RUN chmod 440 /certs/server.*
+COPY certs/customCA.* /certs/
+RUN chmod 440 /certs/customCA.*
COPY --chown=mssql docker-mssql.conf /var/opt/mssql/mssql.conf
+USER mssql
diff --git a/docker/docker-mssql-2017.dockerfile b/docker/docker-mssql-2017.dockerfile
index 28a3dd4f4..ec4ccf451 100644
--- a/docker/docker-mssql-2017.dockerfile
+++ b/docker/docker-mssql-2017.dockerfile
@@ -1,5 +1,8 @@
FROM mcr.microsoft.com/mssql/server:2017-latest
-COPY --chmod=440 certs/server.* /certs/
-COPY --chmod=440 certs/customCA.* /certs/
+USER root
+COPY certs/server.* /certs/
+RUN chmod 440 /certs/server.*
+COPY certs/customCA.* /certs/
+RUN chmod 440 /certs/customCA.*
COPY docker-mssql.conf /var/opt/mssql/mssql.conf
diff --git a/docker/docker-mssql-2019.dockerfile b/docker/docker-mssql-2019.dockerfile
index 02ffdec0d..097a1d24d 100644
--- a/docker/docker-mssql-2019.dockerfile
+++ b/docker/docker-mssql-2019.dockerfile
@@ -1,5 +1,9 @@
FROM mcr.microsoft.com/mssql/server:2019-latest
-COPY --chmod=440 certs/server.* /certs/
-COPY --chmod=440 certs/customCA.* /certs/
+USER root
+COPY certs/server.* /certs/
+RUN chmod 440 /certs/server.*
+COPY certs/customCA.* /certs/
+RUN chmod 440 /certs/customCA.*
COPY --chown=mssql docker-mssql.conf /var/opt/mssql/mssql.conf
+USER mssql
diff --git a/docker/docker-mssql-2022.dockerfile b/docker/docker-mssql-2022.dockerfile
index 930d3026c..aefdd64e6 100644
--- a/docker/docker-mssql-2022.dockerfile
+++ b/docker/docker-mssql-2022.dockerfile
@@ -1,5 +1,9 @@
FROM mcr.microsoft.com/mssql/server:2022-latest
-COPY --chmod=444 certs/server.* /certs/
-COPY --chmod=444 certs/customCA.* /certs/
+USER root
+COPY certs/server.* /certs/
+RUN chmod 444 /certs/server.*
+COPY certs/customCA.* /certs/
+RUN chmod 444 /certs/customCA.*
COPY --chown=mssql docker-mssql.conf /var/opt/mssql/mssql.conf
+USER mssql
diff --git a/docker/test-server.sh b/docker/test-server.sh
new file mode 100755
index 000000000..a0239280c
--- /dev/null
+++ b/docker/test-server.sh
@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+#
+# Start a SQL Server for the test suite, with podman or docker.
+#
+# ./docker/test-server.sh up # build, start, wait until it accepts connections
+# ./docker/test-server.sh down # stop and remove
+# ./docker/test-server.sh logs # follow the server log
+#
+# Then:
+#
+# export TIBERIUS_TEST_CONNECTION_STRING='server=tcp:localhost,1433;user=SA;password=;IntegratedSecurity=true;TrustServerCertificate=true'
+# cargo test
+#
+# IMAGE selects the flavour; the default works on both x86_64 and arm64.
+# The full SQL Server images are x86_64 only, so on an arm64 machine
+# (Apple silicon) they either refuse to run or run under emulation.
+
+set -euo pipefail
+
+ENGINE="${ENGINE:-$(command -v podman >/dev/null 2>&1 && echo podman || echo docker)}"
+NAME="${NAME:-tiberius-test-mssql}"
+PORT="${PORT:-1433}"
+IMAGE="${IMAGE:-azure-sql-edge}"
+PASSWORD=''
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+case "${1:-up}" in
+ up)
+ echo "engine: $ENGINE image: $IMAGE port: $PORT"
+ "$ENGINE" build -q -f "$HERE/docker-$IMAGE.dockerfile" -t "$NAME:local" "$HERE"
+ "$ENGINE" rm -f "$NAME" >/dev/null 2>&1 || true
+ "$ENGINE" run -d --name "$NAME" \
+ -e ACCEPT_EULA=Y \
+ -e "MSSQL_SA_PASSWORD=$PASSWORD" \
+ -e "SA_PASSWORD=$PASSWORD" \
+ -p "$PORT:1433" \
+ "$NAME:local" >/dev/null
+
+ # The port opens well before the server will answer, so poll the log
+ # rather than the socket.
+ #
+ # The log is captured into a variable and matched there, rather than
+ # piped into `grep -q`. Under `set -o pipefail`, `grep -q` exits on the
+ # first match, the writer upstream dies of SIGPIPE, and the pipeline
+ # reports failure even though the match succeeded — so the wait never
+ # ends.
+ echo -n "waiting for SQL Server"
+ for _ in $(seq 1 120); do
+ logs="$("$ENGINE" logs "$NAME" 2>&1 || true)"
+
+ case "$logs" in
+ *"SQL Server is now ready for client connections"*)
+ echo " — ready"
+ exit 0
+ ;;
+ esac
+
+ running="$("$ENGINE" ps --format '{{.Names}}' || true)"
+ case "$running" in
+ *"$NAME"*) ;;
+ *)
+ echo " — container exited:"
+ "$ENGINE" logs --tail 30 "$NAME" || true
+ exit 1
+ ;;
+ esac
+
+ echo -n .
+ sleep 2
+ done
+ echo " — gave up; last lines:"
+ "$ENGINE" logs --tail 30 "$NAME"
+ exit 1
+ ;;
+ down)
+ "$ENGINE" rm -f "$NAME" >/dev/null 2>&1 || true
+ echo "removed $NAME"
+ ;;
+ logs)
+ "$ENGINE" logs -f "$NAME"
+ ;;
+ *)
+ echo "usage: $0 {up|down|logs}" >&2
+ exit 2
+ ;;
+esac
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
new file mode 100644
index 000000000..11e5683d0
--- /dev/null
+++ b/docs/GUIDE.md
@@ -0,0 +1,325 @@
+# Tiberius Guide
+
+A practical tour of the driver. For the full API see [docs.rs](https://docs.rs/tiberius).
+Every example imports the crate as `tiberius` (the package is `tiberius`; see
+the [README](../README.md#installation)).
+
+- [Connecting](#connecting)
+- [Configuration](#configuration)
+- [Encryption & TLS](#encryption--tls)
+- [Authentication](#authentication)
+- [Querying](#querying)
+- [Reading rows](#reading-rows)
+- [Bulk insert](#bulk-insert)
+- [Stored procedures, OUT params & TVPs](#stored-procedures-out-params--tvps)
+- [Transactions](#transactions)
+- [`IN (…)` lists](#in--lists)
+- [Named instances (SQL Browser)](#named-instances-sql-browser)
+- [Query cancellation](#query-cancellation)
+- [Connection pooling](#connection-pooling)
+- [Error handling](#error-handling)
+
+## Connecting
+
+Tiberius is runtime-independent: you create the `TcpStream` and hand it to the
+[`Client`].
+
+**Tokio** (wrap the stream with `tokio_util::compat`):
+
+```rust
+use tiberius::{Client, Config, AuthMethod};
+use tokio::net::TcpStream;
+use tokio_util::compat::TokioAsyncWriteCompatExt;
+
+# async fn f() -> anyhow::Result<()> {
+let mut config = Config::new();
+config.host("localhost");
+config.port(1433);
+config.authentication(AuthMethod::sql_server("SA", ""));
+config.trust_cert(); // dev only
+
+let tcp = TcpStream::connect(config.get_addr()).await?;
+tcp.set_nodelay(true)?;
+let mut client = Client::connect(config, tcp.compat_write()).await?;
+# Ok(()) }
+```
+
+**smol** (pass the stream directly — no compat layer):
+
+```rust,ignore
+let tcp = smol::net::TcpStream::connect(config.get_addr()).await?;
+tcp.set_nodelay(true)?;
+let mut client = tiberius::Client::connect(config, tcp).await?;
+```
+
+## Configuration
+
+Build a [`Config`] fluently, or parse a connection string:
+
+```rust,ignore
+// ADO.NET
+let config = Config::from_ado_string(
+ "Server=tcp:localhost,1433;User Id=SA;Password=pw;Encrypt=strict;",
+)?;
+
+// JDBC
+let config = Config::from_jdbc_string(
+ "jdbc:sqlserver://localhost:1433;user=SA;password=pw;encrypt=true",
+)?;
+
+// Builder
+let config = Config::builder()
+ .host("localhost")
+ .port(1433)
+ .authentication(AuthMethod::sql_server("SA", "pw"))
+ .build();
+```
+
+## Encryption & TLS
+
+TLS is on by default. Pick a backend via a feature flag (mutually exclusive):
+`native-tls` (default), `rustls`, or `vendored-openssl`.
+
+Encryption levels (`Config::encryption`): `NotSupported`, `Off`, `Required`
+(default), and **`Strict`** — TDS 8.0, TLS *before* the pre-login, with the
+`tds/8.0` ALPN (requires the `tds80` feature; native-tls or rustls).
+
+```rust,ignore
+use tiberius::EncryptionLevel;
+config.encryption(EncryptionLevel::Strict);
+config.hostname_in_certificate("my-sql-host"); // validate against a specific CN/SAN
+config.client_certificate("client.pem", "client.key"); // mutual TLS
+// or: config.client_certificate_pkcs12("client.pfx", "password");
+```
+
+## Authentication
+
+```rust,ignore
+// SQL Server login (password buffers are zeroized)
+config.authentication(AuthMethod::sql_server("user", "pw"));
+
+// Windows integrated auth: SSPI on Windows (winauth), NTLM on Unix (sspi-rs)
+config.authentication(AuthMethod::windows("user", "pw"));
+
+// Kerberos on Unix (integrated-auth-gssapi feature)
+config.authentication(AuthMethod::Integrated);
+
+// Azure AD access token
+config.authentication(AuthMethod::aad_token(token));
+```
+
+## Querying
+
+From the [`Client`] when parameters are known at the call site:
+
+```rust,ignore
+// Rows back
+let stream = client.query("SELECT @P1, @P2", &[&1i32, &"foo"]).await?;
+
+// Rows affected
+let result = client.execute("UPDATE t SET x = @P1 WHERE id = @P2", &[&1i32, &2i32]).await?;
+println!("{} rows", result.total());
+```
+
+For dynamic or owned parameters, use the [`Query`] object:
+
+```rust,ignore
+use tiberius::Query;
+let mut select = Query::new("SELECT @P1, @P2");
+for p in ["a", "b"] { select.bind(p); }
+let stream = select.query(&mut client).await?;
+```
+
+## Reading rows
+
+A query returns a stream. Collect it, or take the first row:
+
+```rust,ignore
+// All rows of the first result set
+let rows = client.query("SELECT id, name FROM users", &[]).await?
+ .into_first_result().await?;
+
+for row in rows {
+ let id: i32 = row.get("id").unwrap();
+ let name: &str = row.get("name").unwrap();
+}
+
+// Just the first row
+let row = client.query("SELECT 1 AS n", &[]).await?.into_row().await?.unwrap();
+let n: i32 = row.get("n").unwrap();
+```
+
+Type mappings are available via `FromSql`/`ToSql`, with optional `chrono`,
+`time`, `rust_decimal`, `bigdecimal`, and `serde` support behind their features.
+`Client::column_metadata()` exposes column type, size, precision/scale,
+nullability and identity flags.
+
+## Bulk insert
+
+Efficiently stream many rows into a table:
+
+```rust,ignore
+use tiberius::IntoRow;
+
+let mut req = client.bulk_insert("dbo.target").await?; // all columns
+// or a specific column list:
+// let mut req = client.bulk_insert_columns("dbo.target", &["foo", "bar"]).await?;
+
+for i in 0..1000i32 {
+ req.send(i.into_row()).await?;
+}
+let res = req.finalize().await?;
+println!("{} rows", res.total());
+```
+
+## Stored procedures, OUT params & TVPs
+
+Named RPC with input, output and table-valued parameters is supported via the
+[`Command`] API. A TVP row type derives `TableValueRow`:
+
+```rust,ignore
+use tiberius::{Command, TableValueRow};
+
+// Fields may be `Copy` scalars (`i32`, `Numeric`, `Uuid`, …), owned columns
+// (`String`, `Vec`), or borrowed `&str`/`&[u8]` (with a struct lifetime).
+#[derive(TableValueRow)]
+struct Item {
+ #[colname = "Id"] id: i32,
+ #[colname = "Name"] name: String,
+}
+
+let rows = vec![
+ Item { id: 1, name: "one".to_owned() },
+ Item { id: 2, name: "two".to_owned() },
+];
+
+let mut cmd = Command::new("dbo.InsertItems");
+cmd.bind_table_with_dbtype("items", "dbo.ItemList", rows);
+let mut stream = cmd.exec(&mut client).await?;
+```
+
+## Transactions
+
+Real Transaction Manager requests (not T-SQL batches), with isolation levels:
+
+```rust,ignore
+client.begin_transaction().await?;
+// ... work ...
+client.commit_transaction().await?;
+// or client.rollback_transaction().await?;
+```
+
+## `IN (…)` lists
+
+Helpers make variable-length `IN` lists and the 2,100-parameter limit ergonomic —
+see the `Query` docs on docs.rs for `in_clause`/parameter-expansion helpers.
+
+## Named instances (SQL Browser)
+
+On Windows, a named instance's port is resolved through SQL Browser. Enable
+`sql-browser-tokio` or `sql-browser-smol` and use the `SqlBrowser` extension:
+
+```rust,ignore
+use tiberius::SqlBrowser;
+use tokio::net::TcpStream;
+use tokio_util::compat::TokioAsyncWriteCompatExt;
+
+config.port(1434);
+config.instance_name("INSTANCE");
+let tcp = TcpStream::connect_named(&config).await?;
+let mut client = Client::connect(config, tcp.compat_write()).await?;
+```
+
+## Query cancellation
+
+```rust,ignore
+client.cancel_query().await?; // sends a TDS Attention signal
+```
+
+## Connection pooling
+
+Pooling is delegated to the async pool crates rather than built in. This keeps
+Tiberius runtime-agnostic (a pool has to pick a runtime's timers and tasks) and
+lets the connection lifecycle — sizing, health checks, idle reaping — evolve
+independently of the driver. Use [`bb8`](https://crates.io/crates/bb8),
+[`deadpool`](https://crates.io/crates/deadpool), or
+[`mobc`](https://crates.io/crates/mobc) with a small connection manager.
+
+Because Tiberius has no MARS (one in-flight request per connection), a pool is
+also the natural way to get concurrency: check out a connection per task.
+
+Here is a minimal [`bb8`](https://crates.io/crates/bb8) manager over Tokio:
+
+```rust,ignore
+use bb8::{ManageConnection, Pool};
+use tiberius::{Client, Config};
+use tokio::net::TcpStream;
+use tokio_util::compat::{Compat, TokioAsyncWriteCompatExt};
+
+struct TiberiusManager {
+ config: Config,
+}
+
+#[async_trait::async_trait]
+impl ManageConnection for TiberiusManager {
+ type Connection = Client>;
+ type Error = tiberius::error::Error;
+
+ async fn connect(&self) -> Result {
+ let tcp = TcpStream::connect(self.config.get_addr()).await?;
+ tcp.set_nodelay(true)?;
+ Client::connect(self.config.clone(), tcp.compat_write()).await
+ }
+
+ async fn is_valid(&self, conn: &mut Self::Connection) -> Result<(), Self::Error> {
+ // Cheap round-trip to confirm the connection is still alive.
+ conn.simple_query("SELECT 1").await?.into_row().await?;
+ Ok(())
+ }
+
+ fn has_broken(&self, _conn: &mut Self::Connection) -> bool {
+ false
+ }
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+ let mut config = Config::new();
+ config.host("localhost");
+ config.port(1433);
+ config.authentication(tiberius::AuthMethod::sql_server("SA", ""));
+ config.trust_cert(); // don't do this in production
+
+ let pool = Pool::builder()
+ .max_size(16)
+ .build(TiberiusManager { config })
+ .await?;
+
+ // Check out a connection; it returns to the pool on drop.
+ let mut conn = pool.get().await?;
+ let row = conn
+ .query("SELECT @P1 AS n", &[&1i32])
+ .await?
+ .into_row()
+ .await?
+ .unwrap();
+ assert_eq!(Some(1i32), row.get("n"));
+ Ok(())
+}
+```
+
+The [`deadpool`](https://crates.io/crates/deadpool) and
+[`mobc`](https://crates.io/crates/mobc) integrations follow the same shape —
+implement their manager trait with the `connect`/`is_valid` logic above.
+
+## Error handling
+
+All fallible calls return `tiberius::Result` (`Err` is [`tiberius::error::Error`]).
+Server-side errors surface as `Error::Server(TokenError { .. })` carrying the SQL
+Server error code, state, class, message, procedure and line.
+
+[`Client`]: https://docs.rs/tiberius/latest/tiberius/struct.Client.html
+[`Config`]: https://docs.rs/tiberius/latest/tiberius/struct.Config.html
+[`Query`]: https://docs.rs/tiberius/latest/tiberius/struct.Query.html
+[`Command`]: https://docs.rs/tiberius/latest/tiberius/struct.Command.html
+[`tiberius::error::Error`]: https://docs.rs/tiberius/latest/tiberius/error/enum.Error.html
diff --git a/docs/TDS_COMPATIBILITY.md b/docs/TDS_COMPATIBILITY.md
new file mode 100644
index 000000000..2349b86aa
--- /dev/null
+++ b/docs/TDS_COMPATIBILITY.md
@@ -0,0 +1,98 @@
+# TDS Protocol Compatibility
+
+This document tracks `tiberius`'s coverage of the Microsoft Tabular Data
+Stream (MS-TDS) protocol. It is a maintained snapshot — code references may
+drift; treat the ratings as the source of truth and file an issue for
+discrepancies.
+
+Legend: ✅ full · 🟡 partial · ❌ missing · N/A not applicable.
+
+## Protocol-version support
+
+| TDS version | SQL Server | Rating | Notes |
+|---|---|---|---|
+| **8.0** | 2022 | ✅ Full | TLS-before-prelogin "strict" mode (`EncryptionLevel::Strict`), `tds/8.0` ALPN, and client-certificate (mutual-TLS) login on native-tls + rustls. 8.0 reuses 7.4 tokens over mandatory TLS; the only backend caveat is that opentls cannot advertise ALPN (see below). |
+| **7.4** | 2012–2019 | ✅ Full | Login (`FeatureLevel::SqlServerN`), routing ENVCHANGE, `fReadOnlyIntent`, FedAuth prelogin option + FeatureExt, FEATUREEXTACK, FEDAUTHINFO (0xEE), SESSIONSTATE (0xE4). The only deferral is *transparent reconnect* — SESSIONSTATE is decoded and stored, but not yet replayed to silently re-establish a dropped session. |
+| **7.3 A/B** | 2008 / R2 | ✅ Full (`tds73`) | date / time / datetime2 / datetimeoffset types, NBCROW. |
+| **7.2** | 2005 | ✅ Full | PLP / varchar(max), XML, MARS / transaction-descriptor headers, SQL_VARIANT (read + write), UDT (0xF0) raw-value decode. |
+| **7.1** | 2000 | ✅ Full | Collation, UCS-2 strings, `n`-prefixed var-len types, LOGIN7 layout. |
+| **7.0** | 7.0 | ❌ None | Legacy fixed non-nullable types unsupported; the client only negotiates 7.4. Not a target. |
+
+There is **no Microsoft "TDS 6.0"** — the Microsoft protocol line is
+7.0 → 7.1 → 7.2 → 7.3A → 7.3B → 7.4 → 8.0. Sybase-era TDS 4.2/5.0 predate
+MS-TDS and are a separate protocol lineage, out of scope for this driver.
+TDS 8.0 has no distinct LOGIN7 version — it reuses 7.4 tokens over mandatory
+TLS, so "8.0" is a transport/ALPN distinction.
+
+**Summary:** TDS 7.1 through 8.0 are fully supported. The only remaining
+elements are optional and rarely used: transparent session recovery (the
+SESSIONSTATE token is decoded and stored, just not replayed on reconnect),
+CLR UDT *object* deserialization (raw bytes are surfaced), and `tds/8.0` ALPN
+on the opentls backend (an upstream-crate limitation) — none of which any
+standard query, bulk-load, RPC, or transaction path depends on.
+
+## Feature matrix
+
+### Client → server messages
+| Message | Status |
+|---|---|
+| PRELOGIN (0x12) | ✅ (VERSION/ENCRYPTION/INSTOPT/THREADID/MARS emitted; server options decoded and INSTOPT validated) |
+| LOGIN7 (0x10) | ✅ |
+| SQL Batch (0x01) | ✅ |
+| RPC request (0x03) | ✅ by-ID procs and named procs, incl. OUT params and table-valued parameters (#328) |
+| Bulk load (0x07) | ✅ whole-table and column-list |
+| SSPI (0x11) | ✅ |
+| FedAuth token | ✅ via LOGIN7 FeatureExt |
+| Attention / cancel (0x06) | ✅ (`Client::cancel_query`) |
+| Transaction Manager request (0x14) | ✅ (`begin`/`commit`/`rollback` with isolation levels) |
+
+### Server → client tokens
+| Token | Status |
+|---|---|
+| COLMETADATA, ROW, NBCROW, DONE/PROC/INPROC | ✅ |
+| ENVCHANGE, ERROR/INFO, LOGINACK | ✅ |
+| RETURNVALUE, RETURNSTATUS, ORDER, SSPI | ✅ |
+| FEATUREEXTACK | ✅ |
+| ALTMETADATA / ALTROW (compute-by) | ✅ |
+| COLINFO (0xA5) | ✅ |
+| TABNAME (0xA4) | ✅ |
+| FEDAUTHINFO (0xEE) | ✅ (STSURL + SPN surfaced for AAD flows) |
+| SESSIONSTATE (0xE4) | ✅ decoded + stored (transparent-reconnect replay not yet implemented) |
+
+### Data types
+| Type | Status |
+|---|---|
+| Fixed-len ints/bit/float/money/datetime(4) | ✅ |
+| Nullable var-len (Intn/Bitn/Floatn/Guid/Money/Datetimen/Decimaln/Numericn) | ✅ |
+| Char/binary + collation, Text/NText/Image | ✅ |
+| PLP (max types), XML | ✅ |
+| date / time / datetime2 / datetimeoffset (7.3) | ✅ (`tds73`) |
+| Numeric / Decimal (incl. automatic scale rescaling of params) | ✅ |
+| SQL_VARIANT (0x62) | ✅ read + write |
+| UDT (0xF0) | ✅ raw-value decode (surfaced as bytes; CLR object deserialization out of scope) |
+
+### Encryption & auth
+| Feature | Status |
+|---|---|
+| Encryption NotSupported / Off / On / Required | ✅ |
+| Strict (TDS 8.0, TLS-first) | ✅ (`tds80`) |
+| `tds/8.0` ALPN | 🟡 native-tls + rustls ✅, opentls ❌ (backend cannot advertise ALPN) |
+| ENCRYPT_CLIENT_CERT (mutual TLS) | ✅ (`Config::client_certificate` / `client_certificate_pkcs12`) |
+| SQL auth (zeroized) | ✅ |
+| Windows NTLM/SSPI (Windows `winauth`; Unix `sspi-rs`) | ✅ |
+| Kerberos/GSSAPI (Unix `integrated-auth-gssapi`) | ✅ |
+| AAD / federated token | ✅ (`AuthMethod::aad_token`) |
+
+## Remaining optional items
+
+None of the following block standard operation; they are tracked for
+completeness and would be additive, backward-compatible features:
+
+- **Transparent session recovery** — the SESSIONSTATE token is already decoded
+ and stored; replaying it to silently re-establish a dropped connection is the
+ remaining step.
+- **CLR UDT object deserialization** — UDT values are decoded to raw bytes;
+ interpreting them into CLR objects (e.g. `geometry`) is left to the caller.
+- **opentls `tds/8.0` ALPN** — verified infeasible with `opentls` 0.2.1's public
+ API (no ALPN setter; the wrapped `SslConnector` is private). Use native-tls or
+ rustls for TDS 8.0 strict mode. Tracked upstream against the `opentls` crate.
diff --git a/examples/aad-auth.rs b/examples/aad-auth.rs
index 8ef41c472..ebc23165b 100644
--- a/examples/aad-auth.rs
+++ b/examples/aad-auth.rs
@@ -8,41 +8,32 @@
//! - CLIENT_SECRET: service principal secret;
//! - TENANT_ID: tenant id of service principal and sql instance;
//! - SERVER: SQL server URI
-use azure_identity::client_credentials_flow;
-use oauth2::{ClientId, ClientSecret};
-use std::{env, sync::Arc};
+use azure_core::credentials::{Secret, TokenCredential};
+use azure_identity::ClientSecretCredential;
+use std::env;
use tiberius::{AuthMethod, Client, Config, Query};
use tokio::net::TcpStream;
use tokio_util::compat::TokioAsyncWriteCompatExt;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
- // following code will retrive token with AAD Service Principal Auth
- let client_id =
- ClientId::new(env::var("CLIENT_ID").expect("Missing CLIENT_ID environment variable."));
- let client_secret = ClientSecret::new(
- env::var("CLIENT_SECRET").expect("Missing CLIENT_SECRET environment variable."),
- );
+ let client_id = env::var("CLIENT_ID").expect("Missing CLIENT_ID environment variable.");
+ let client_secret =
+ env::var("CLIENT_SECRET").expect("Missing CLIENT_SECRET environment variable.");
let tenant_id = env::var("TENANT_ID").expect("Missing TENANT_ID environment variable.");
- let client = Arc::new(reqwest::Client::new());
- // This will give you the final token to use in authorization.
- let token = client_credentials_flow::perform(
- client,
- &client_id,
- &client_secret,
- &["https://management.azure.com/"],
- &tenant_id,
- )
- .await?;
+ let credential =
+ ClientSecretCredential::new(&tenant_id, client_id, Secret::new(client_secret), None)?;
+
+ let token = credential
+ .get_token(&["https://database.windows.net/.default"], None)
+ .await?;
let mut config = Config::new();
let server = env::var("SERVER").expect("Missing SERVER environment variable.");
config.host(server);
config.port(1433);
- config.authentication(AuthMethod::AADToken(
- token.access_token().secret().to_string(),
- ));
+ config.authentication(AuthMethod::aad_token(token.token.secret()));
config.trust_cert();
let tcp = TcpStream::connect(config.get_addr()).await?;
diff --git a/examples/async-std.rs b/examples/async-std.rs
deleted file mode 100644
index 88fcf1c8d..000000000
--- a/examples/async-std.rs
+++ /dev/null
@@ -1,50 +0,0 @@
-use async_std::net::TcpStream;
-use once_cell::sync::Lazy;
-use std::env;
-use tiberius::{Client, Config};
-
-static CONN_STR: Lazy = Lazy::new(|| {
- env::var("TIBERIUS_TEST_CONNECTION_STRING").unwrap_or_else(|_| {
- "server=tcp:localhost,1433;IntegratedSecurity=true;TrustServerCertificate=true".to_owned()
- })
-});
-
-#[cfg(not(all(windows, feature = "sql-browser-async-std")))]
-#[async_std::main]
-async fn main() -> anyhow::Result<()> {
- let config = Config::from_ado_string(&CONN_STR)?;
-
- let tcp = TcpStream::connect(config.get_addr()).await?;
- tcp.set_nodelay(true)?;
-
- let mut client = Client::connect(config, tcp).await?;
-
- let stream = client.query("SELECT @P1", &[&1i32]).await?;
- let row = stream.into_row().await?.unwrap();
-
- println!("{:?}", row);
- assert_eq!(Some(1), row.get(0));
-
- Ok(())
-}
-
-#[cfg(all(windows, feature = "sql-browser-async-std"))]
-#[async_std::main]
-async fn main() -> anyhow::Result<()> {
- use tiberius::SqlBrowser;
-
- let config = Config::from_ado_string(&CONN_STR)?;
-
- let tcp = TcpStream::connect_named(&config).await?;
- tcp.set_nodelay(true)?;
-
- let mut client = Client::connect(config, tcp).await?;
-
- let stream = client.query("SELECT @P1", &[&1i32]).await?;
- let row = stream.into_row().await?.unwrap();
-
- println!("{:?}", row);
- assert_eq!(Some(1), row.get(0));
-
- Ok(())
-}
diff --git a/examples/named-pipes.rs b/examples/named-pipes.rs
new file mode 100644
index 000000000..fb135dbb2
--- /dev/null
+++ b/examples/named-pipes.rs
@@ -0,0 +1,43 @@
+//! Connecting to SQL Server over a Windows named pipe.
+//!
+//! SQL Server exposes a named pipe endpoint (by default
+//! `\\.\pipe\sql\query` for the default instance). Because a named pipe
+//! implements `AsyncRead`/`AsyncWrite`, it can be handed to
+//! [`Client::connect`] exactly like a TCP stream once it is wrapped with the
+//! `tokio-util` compatibility layer.
+//!
+//! Named pipes are a Windows-only transport, so the real example is compiled
+//! only on Windows; on other platforms `main` panics with an unsupported
+//! message. See tiberius issues #131 and #53 for background.
+
+#[cfg(windows)]
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+ use tiberius::{AuthMethod, Client, Config};
+ use tokio::net::windows::named_pipe::ClientOptions;
+ use tokio_util::compat::TokioAsyncWriteCompatExt;
+
+ // The default named pipe for a default SQL Server instance. A named
+ // instance uses `\\.\pipe\MSSQL$\sql\query`.
+ const PIPE_NAME: &str = r"\\.\pipe\sql\query";
+
+ let mut config = Config::new();
+ config.authentication(AuthMethod::Integrated);
+ config.trust_cert();
+
+ let pipe = ClientOptions::new().open(PIPE_NAME)?;
+ let mut client = Client::connect(config, pipe.compat_write()).await?;
+
+ let stream = client.query("SELECT @P1", &[&1i32]).await?;
+ let row = stream.into_row().await?.unwrap();
+
+ println!("{row:?}");
+ assert_eq!(Some(1), row.get(0));
+
+ Ok(())
+}
+
+#[cfg(not(windows))]
+fn main() {
+ panic!("Named pipe connections are only supported on Windows.");
+}
diff --git a/runtimes-macro/Cargo.toml b/runtimes-macro/Cargo.toml
index 6bf114b2a..4b0f68311 100644
--- a/runtimes-macro/Cargo.toml
+++ b/runtimes-macro/Cargo.toml
@@ -1,14 +1,19 @@
+# Test-only helper crate (dev-dependency, path-only): the `#[test_on_runtimes]`
+# attribute that runs each integration test on tokio and smol. Not shipped, not
+# published. `license`/`publish` set so the cargo-deny license gate is satisfied
+# and it can never be accidentally published.
[package]
name = "runtimes-macro"
version = "0.1.0"
authors = ["Eric Sheppard "]
-edition = "2018"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+publish = false
[lib]
proc-macro = true
[dependencies]
quote = "1"
-syn = "1"
-darling = "0.14"
+syn = { version = "2", features = ["full"] }
proc-macro2 = "1"
diff --git a/runtimes-macro/src/lib.rs b/runtimes-macro/src/lib.rs
index cc1d2cabc..94a6b0464 100644
--- a/runtimes-macro/src/lib.rs
+++ b/runtimes-macro/src/lib.rs
@@ -1,50 +1,70 @@
+//! Internal test-only proc-macro for tiberius.
+//!
+//! `#[test_on_runtimes]` takes an `async fn(client) -> Result<()>` and generates
+//! one integration test per supported async runtime, so every test proves the
+//! (runtime-independent) driver works on each of them. Currently: **tokio** and
+//! **smol**.
extern crate proc_macro;
-use darling::FromMeta;
-#[derive(Debug, FromMeta)]
-struct MacroArgs {
- #[darling(default)]
- connection_string: Option,
+use proc_macro::TokenStream;
+use quote::{format_ident, quote};
+use syn::{parse_macro_input, ItemFn, LitStr};
+
+/// Optional `connection_string = "IDENT"` attribute argument naming the `&str`
+/// constant to connect with. Defaults to `CONN_STR`.
+struct Args {
+ conn_str: String,
}
-#[proc_macro_attribute]
-pub fn test_on_runtimes(
- args: proc_macro::TokenStream,
- input: proc_macro::TokenStream,
-) -> proc_macro::TokenStream {
- let attr_args = syn::parse_macro_input!(args as syn::AttributeArgs);
-
- let args = match MacroArgs::from_list(&attr_args) {
- Ok(v) => v,
- Err(e) => {
- return proc_macro::TokenStream::from(e.write_errors());
- }
- };
+impl syn::parse::Parse for Args {
+ fn parse(input: syn::parse::ParseStream<'_>) -> syn::Result {
+ let mut conn_str = String::from("CONN_STR");
- let func = syn::parse_macro_input!(input as syn::ItemFn);
+ if !input.is_empty() {
+ let ident: syn::Ident = input.parse()?;
+ if ident != "connection_string" {
+ return Err(syn::Error::new(
+ ident.span(),
+ "expected `connection_string = \"...\"`",
+ ));
+ }
+ input.parse::()?;
+ let lit: LitStr = input.parse()?;
+ conn_str = lit.value();
+ }
- let conn_str_ident_str = args.connection_string.unwrap_or_else(|| "CONN_STR".into());
+ Ok(Args { conn_str })
+ }
+}
- let conn_str_ident =
- proc_macro2::Ident::new(&conn_str_ident_str, proc_macro2::Span::call_site());
+#[proc_macro_attribute]
+pub fn test_on_runtimes(args: TokenStream, input: TokenStream) -> TokenStream {
+ let args = parse_macro_input!(args as Args);
+ let func = parse_macro_input!(input as ItemFn);
+ let conn_str_ident = format_ident!("{}", args.conn_str);
let func_name = func.sig.ident.clone();
- let async_std_test = quote::format_ident!("{}_{}", func_name, "async_std");
- let tokio_test = quote::format_ident!("{}_{}", func_name, "tokio");
+ let tokio_test = format_ident!("{}_tokio", func_name);
+ let smol_test = format_ident!("{}_smol", func_name);
- let tokens = quote::quote! {
+ let tokens = quote! {
#func
#[test]
- fn #async_std_test()-> Result<()> {
+ fn #tokio_test() -> Result<()> {
LOGGER_SETUP.call_once(|| {
- env_logger::init();
+ let _ = env_logger::builder().is_test(true).try_init();
});
- async_std::task::block_on(async {
+
+ use tokio_util::compat::TokioAsyncWriteCompatExt;
+
+ let rt = tokio::runtime::Runtime::new()?;
+
+ rt.block_on(async {
let config = tiberius::Config::from_ado_string(&#conn_str_ident)?;
- let tcp = async_std::net::TcpStream::connect(config.get_addr()).await?;
+ let tcp = tokio::net::TcpStream::connect(config.get_addr()).await?;
tcp.set_nodelay(true)?;
- let mut client = tiberius::Client::connect(config, tcp).await?;
+ let client = tiberius::Client::connect(config, tcp.compat_write()).await?;
#func_name(client).await?;
Ok(())
@@ -52,19 +72,16 @@ pub fn test_on_runtimes(
}
#[test]
- fn #tokio_test()-> Result<()> {
+ fn #smol_test() -> Result<()> {
LOGGER_SETUP.call_once(|| {
- env_logger::init();
+ let _ = env_logger::builder().is_test(true).try_init();
});
- use tokio_util::compat::TokioAsyncWriteCompatExt;
-
- let mut rt = tokio::runtime::Runtime::new()?;
- rt.block_on(async {
+ smol::block_on(async {
let config = tiberius::Config::from_ado_string(&#conn_str_ident)?;
- let tcp = tokio::net::TcpStream::connect(config.get_addr()).await?;
+ let tcp = smol::net::TcpStream::connect(config.get_addr()).await?;
tcp.set_nodelay(true)?;
- let mut client = tiberius::Client::connect(config, tcp.compat_write()).await?;
+ let client = tiberius::Client::connect(config, tcp).await?;
#func_name(client).await?;
Ok(())
@@ -72,5 +89,5 @@ pub fn test_on_runtimes(
}
};
- proc_macro::TokenStream::from(tokens)
+ TokenStream::from(tokens)
}
diff --git a/src/bulk_options.rs b/src/bulk_options.rs
new file mode 100644
index 000000000..45da4b7a5
--- /dev/null
+++ b/src/bulk_options.rs
@@ -0,0 +1,64 @@
+//! Options controlling the behaviour of a bulk-insert (`INSERT BULK`)
+//! operation, mirroring the knobs exposed by `SqlBulkCopyOptions` in
+//! ADO.NET's `SqlBulkCopy`.
+
+use enumflags2::{bitflags, BitFlags};
+
+/// A single bulk-copy option. Combine several with the `|` operator to build a
+/// [`SqlBulkCopyOptions`] set, e.g.
+/// `SqlBulkCopyOption::KeepIdentity | SqlBulkCopyOption::TableLock`.
+///
+/// See the MS docs for `SqlBulkCopyOptions`:
+///
+#[bitflags]
+#[repr(u32)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SqlBulkCopyOption {
+ /// Preserve source identity values. When not specified, identity values are
+ /// assigned by the destination. Implemented by keeping the identity column
+ /// in the bulk column list (the `INSERT BULK` `WITH (...)` grammar has no
+ /// `KEEP_IDENTITY` keyword), matching ADO.NET's `SqlBulkCopy`.
+ KeepIdentity = 1 << 0,
+ /// Check constraints while data is being inserted. By default, constraints
+ /// are not checked. Emits `CHECK_CONSTRAINTS`.
+ CheckConstraints = 1 << 1,
+ /// Obtain a bulk update lock for the duration of the bulk-copy operation.
+ /// When not specified, row locks are used. Emits `TABLOCK`.
+ TableLock = 1 << 2,
+ /// Preserve null values in the destination table regardless of the settings
+ /// for default values. When not specified, null values are replaced by
+ /// default values where applicable. Emits `KEEP_NULLS`.
+ KeepNulls = 1 << 3,
+ /// Cause the server to fire the insert triggers for the rows being inserted
+ /// into the database. Emits `FIRE_TRIGGERS`.
+ FireTriggers = 1 << 4,
+}
+
+/// A set of [`SqlBulkCopyOption`] flags controlling an `INSERT BULK`.
+///
+/// Build one by combining flags with `|`, or use [`SqlBulkCopyOptions::empty`]
+/// (also the [`Default`]) for no options:
+///
+/// ```
+/// # use tiberius::{SqlBulkCopyOption, SqlBulkCopyOptions};
+/// let opts: SqlBulkCopyOptions =
+/// SqlBulkCopyOption::KeepIdentity | SqlBulkCopyOption::TableLock;
+/// assert!(opts.contains(SqlBulkCopyOption::KeepIdentity));
+/// assert!(SqlBulkCopyOptions::empty().is_empty());
+/// ```
+pub type SqlBulkCopyOptions = BitFlags;
+
+/// The sort order of a column, used as a bulk-insert `ORDER (...)` hint.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SortOrder {
+ /// Ascending order (`ASC`).
+ Ascending,
+ /// Descending order (`DESC`).
+ Descending,
+}
+
+/// An order hint for a bulk insert: the column name and the [`SortOrder`] the
+/// incoming rows are already sorted by. Passed as a slice, e.g.
+/// `&[("id", SortOrder::Ascending)]`, these become the `ORDER (...)` clause of
+/// the `INSERT BULK` statement.
+pub type ColumnOrderHint<'a> = (&'a str, SortOrder);
diff --git a/src/client.rs b/src/client.rs
index 688721d10..3aaf4b0d0 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -1,4 +1,4 @@
-mod auth;
+pub(crate) mod auth;
mod config;
mod connection;
@@ -14,6 +14,8 @@ pub use auth::*;
pub use config::*;
pub(crate) use connection::*;
+use crate::bulk_options::{ColumnOrderHint, SortOrder, SqlBulkCopyOption, SqlBulkCopyOptions};
+use crate::tds::codec::RpcValue;
use crate::tds::stream::ReceivedToken;
use crate::{
result::ExecuteResult,
@@ -21,9 +23,12 @@ use crate::{
codec::{self, IteratorJoin},
stream::{QueryStream, TokenStream},
},
- BulkLoadRequest, ColumnFlag, SqlReadBytes, ToSql,
+ BulkLoadRequest, MetaDataColumn, SqlReadBytes, ToSql,
+};
+use codec::{
+ BatchRequest, ColumnData, IsolationLevel, PacketHeader, RpcParam, RpcProcId, TokenRpcRequest,
+ TransactionManagerRequest,
};
-use codec::{BatchRequest, ColumnData, PacketHeader, RpcParam, RpcProcId, TokenRpcRequest};
use enumflags2::BitFlags;
use futures_util::io::{AsyncRead, AsyncWrite};
use futures_util::stream::TryStreamExt;
@@ -57,6 +62,19 @@ use std::{borrow::Cow, fmt::Debug};
/// # }
/// ```
///
+/// # Cancellation safety
+///
+/// A single [`Client`] drives one connection and one request at a time. If a
+/// `query`/`execute`/`simple_query` future — or the result stream it returns —
+/// is dropped before the request has been sent in full and the response fully
+/// consumed (for example under a `tokio::time::timeout` or a `select!` branch
+/// that loses the race), the connection may be left mid-message and out of sync
+/// with the server. A cancelled *write* is detected and any further use of that
+/// connection fails cleanly; a result stream dropped mid-response cannot be
+/// recovered. In both cases the safe course is to drop the `Client` and open a
+/// new connection (a connection pool should discard the connection on error)
+/// rather than reuse it.
+///
/// [`Config`]: struct.Config.html
#[derive(Debug)]
pub struct Client {
@@ -68,6 +86,11 @@ impl Client {
/// options required to connect to the database using an established
/// tcp connection
///
+ /// Note: `tcp_stream` is a connected stream, so some parts of the `Config`
+ /// (such as multi-subnet failover, which selects between resolved
+ /// addresses) must be handled while establishing that stream, outside of
+ /// this constructor.
+ ///
/// [`Config`]: struct.Config.html
pub async fn connect(config: Config, tcp_stream: S) -> crate::Result> {
Ok(Client {
@@ -89,6 +112,12 @@ impl Client {
/// This API is not quite suitable for dynamic query parameters. In these
/// cases using a [`Query`] object might be easier.
///
+ /// # Errors
+ ///
+ /// Returns an error if the statement cannot be sent, if the server reports
+ /// an error while executing it, or if the connection fails during the
+ /// request.
+ ///
/// # Example
///
/// ```no_run
@@ -148,9 +177,16 @@ impl Client {
/// if fighting too much with the compiler, using a [`Query`] object might be
/// easier.
///
+ /// # Errors
+ ///
+ /// Returns an error if the statement cannot be sent, if the server reports
+ /// an error while executing it, or if the connection fails during the
+ /// request. Note that per-statement server errors may instead surface while
+ /// consuming the returned [`QueryStream`].
+ ///
/// # Example
///
- /// ```
+ /// ```no_run
/// # use tiberius::Config;
/// # use tokio_util::compat::TokioAsyncWriteCompatExt;
/// # use std::env;
@@ -202,9 +238,16 @@ impl Client {
/// Execute multiple queries, delimited with `;` and return multiple result
/// sets; one for each query.
///
+ /// # Errors
+ ///
+ /// Returns an error if the batch cannot be sent, if the server reports an
+ /// error while executing it, or if the connection fails during the request.
+ /// Per-statement server errors may instead surface while consuming the
+ /// returned [`QueryStream`].
+ ///
/// # Example
///
- /// ```
+ /// ```no_run
/// # use tiberius::Config;
/// # use tokio_util::compat::TokioAsyncWriteCompatExt;
/// # use std::env;
@@ -251,13 +294,38 @@ impl Client {
Ok(result)
}
- /// Execute a `BULK INSERT` statement, efficiantly storing a large number of
+ /// Execute a `BULK INSERT` statement, efficiently storing a large number of
/// rows to a specified table. Note: make sure the input row follows the same
/// schema as the table, otherwise calling `send()` will return an error.
///
+ /// This is equivalent to `bulk_insert_columns(table, &["*"])`, inserting into
+ /// all of a table's columns.
+ ///
+ /// # Security
+ ///
+ /// `table` is interpolated **directly** into the SQL batch sent to the
+ /// server. SQL Server does not allow table (or column) identifiers to be
+ /// supplied as bound parameters, so this value cannot be parameterized — it
+ /// becomes part of the SQL text verbatim. The caller MUST therefore pass a
+ /// **trusted, hard-coded or otherwise validated** identifier and MUST NOT
+ /// pass untrusted or user-supplied input, which would open a SQL injection
+ /// vector. As cheap defense-in-depth this method rejects obviously-malformed
+ /// identifiers (NUL/ASCII control characters or an unbalanced `]` bracket),
+ /// but that guard is not a substitute for passing trusted input.
+ ///
+ /// # Errors
+ ///
+ /// Returns an error if `table` is a malformed identifier, if the query for
+ /// the column metadata and collations fails, or if the server rejects the
+ /// `INSERT BULK` statement. Row-level failures surface later from [`send`] and
+ /// [`finalize`] on the returned request.
+ ///
+ /// [`send`]: BulkLoadRequest::send
+ /// [`finalize`]: BulkLoadRequest::finalize
+ ///
/// # Example
///
- /// ```
+ /// ```no_run
/// # use tiberius::{Config, IntoRow};
/// # use tokio_util::compat::TokioAsyncWriteCompatExt;
/// # use std::env;
@@ -300,41 +368,225 @@ impl Client {
&'a mut self,
table: &'a str,
) -> crate::Result> {
- // Start the bulk request
- self.connection.flush_stream().await?;
-
- // retrieve column metadata from server
- let query = format!("SELECT TOP 0 * FROM {}", table);
-
- let req = BatchRequest::new(query, self.connection.context().transaction_descriptor());
+ self.bulk_insert_columns(table, &["*"]).await
+ }
- let id = self.connection.context_mut().next_packet_id();
- self.connection.send(PacketHeader::batch(id), req).await?;
+ /// Execute a `BULK INSERT` statement, efficiently storing a large number of
+ /// rows to a specified table. Note: make sure the input row follows the same
+ /// schema as the column list, otherwise calling `send()` will return an error.
+ ///
+ /// # Security
+ ///
+ /// Both `table` and the entries of `columns` are interpolated **directly**
+ /// into the SQL batches sent to the server (the `SELECT` used to fetch
+ /// column metadata and the `INSERT BULK` statement). SQL Server does not
+ /// allow identifiers to be supplied as bound parameters, so these values
+ /// cannot be parameterized — they become part of the SQL text verbatim. The
+ /// caller MUST therefore pass **trusted, hard-coded or otherwise validated**
+ /// identifiers and MUST NOT pass untrusted or user-supplied input, which
+ /// would open a SQL injection vector. As cheap defense-in-depth this method
+ /// rejects an obviously-malformed `table` (NUL/ASCII control characters or an
+ /// unbalanced `]` bracket), but that guard is not a substitute for passing
+ /// trusted input.
+ ///
+ /// # Errors
+ ///
+ /// Returns an error if `table` is a malformed identifier, if the query for
+ /// the column metadata and collations fails, or if the server rejects the
+ /// `INSERT BULK` statement. Row-level failures surface later from [`send`] and
+ /// [`finalize`] on the returned request.
+ ///
+ /// [`send`]: BulkLoadRequest::send
+ /// [`finalize`]: BulkLoadRequest::finalize
+ ///
+ /// # Example
+ ///
+ /// ```no_run
+ /// # use tiberius::{Config, IntoRow};
+ /// # use tokio_util::compat::TokioAsyncWriteCompatExt;
+ /// # use std::env;
+ /// # #[tokio::main]
+ /// # async fn main() -> Result<(), Box> {
+ /// # let c_str = env::var("TIBERIUS_TEST_CONNECTION_STRING").unwrap_or(
+ /// # "server=tcp:localhost,1433;integratedSecurity=true;TrustServerCertificate=true".to_owned(),
+ /// # );
+ /// # let config = Config::from_ado_string(&c_str)?;
+ /// # let tcp = tokio::net::TcpStream::connect(config.get_addr()).await?;
+ /// # tcp.set_nodelay(true)?;
+ /// # let mut client = tiberius::Client::connect(config, tcp.compat_write()).await?;
+ /// let create_table = r#"
+ /// CREATE TABLE ##bulk_test_columns (
+ /// id INT IDENTITY PRIMARY KEY,
+ /// foo INT NOT NULL,
+ /// bar FLOAT NOT NULL
+ /// )
+ /// "#;
+ ///
+ /// client.simple_query(create_table).await?;
+ ///
+ /// // Start the bulk insert with the client.
+ /// let mut req = client.bulk_insert_columns("##bulk_test_columns", &["foo", "bar"]).await?;
+ ///
+ /// for (i, j) in [(0i32, 0f64), (1i32, 1f64), (2i32, 2f64)] {
+ /// let row = (i, j).into_row();
+ ///
+ /// // The request will handle flushing to the wire in an optimal way,
+ /// // balancing between memory usage and IO performance.
+ /// req.send(row).await?;
+ /// }
+ ///
+ /// // The request must be finalized.
+ /// let res = req.finalize().await?;
+ /// assert_eq!(3, res.total());
+ /// # Ok(())
+ /// # }
+ /// ```
+ pub async fn bulk_insert_columns<'a>(
+ &'a mut self,
+ table: &'a str,
+ columns: &'a [&'a str],
+ ) -> crate::Result> {
+ self.bulk_insert_with_options(table, columns, SqlBulkCopyOptions::empty(), &[])
+ .await
+ }
- let token_stream = TokenStream::new(&mut self.connection).try_unfold();
+ /// Execute a `BULK INSERT` statement like [`bulk_insert_columns`], with
+ /// additional control over the emitted `WITH (...)` clause.
+ ///
+ /// `options` is a set of [`SqlBulkCopyOption`] flags (combine them with `|`,
+ /// or pass [`SqlBulkCopyOptions::empty`] for none), and `order_hints`
+ /// declares the sort order the incoming rows are already in via an
+ /// `ORDER (...)` clause. Pass `&["*"]` as `columns` to target every column,
+ /// exactly like [`bulk_insert`] does internally.
+ ///
+ /// When `options` is empty and `order_hints` is empty this emits the exact
+ /// same statement as [`bulk_insert_columns`] (no `WITH` clause).
+ ///
+ /// # Security
+ ///
+ /// `table`, every entry of `columns`, and every order-hint column name are
+ /// interpolated **directly** into the SQL batches sent to the server (T-SQL
+ /// does not allow identifiers to be parameterized). The caller MUST pass
+ /// **trusted, hard-coded or otherwise validated** identifiers and MUST NOT
+ /// pass untrusted or user-supplied input. As cheap defense-in-depth this
+ /// method rejects obviously-malformed identifiers — NUL/ASCII control
+ /// characters, an unbalanced `]` bracket, a top-level space, statement-
+ /// breaking punctuation (`;`, quotes, `-`, etc.) and tokens spliced onto a
+ /// closing `]`/`)` — for the table, columns *and* order-hint columns, but
+ /// that guard is not a substitute for passing trusted input.
+ ///
+ /// # Errors
+ ///
+ /// Returns an error if `table`, a column, or an order-hint column is a
+ /// malformed identifier, if the query for the column metadata and
+ /// collations fails, if the server reports a collation name that is not a
+ /// plain identifier, or if the server rejects the `INSERT BULK` statement.
+ /// Row-level failures surface later from [`send`] and [`finalize`] on the
+ /// returned request.
+ ///
+ /// # Collations
+ ///
+ /// The `INSERT BULK` statement declares each char, varchar, text, nchar,
+ /// nvarchar and ntext column with its own collation (`COLLATE `), as
+ /// SqlClient's `SqlBulkCopy` does, so the server reads the bulk data in the
+ /// column's code page rather than the database default's. The collation
+ /// names come from `sp_tablecollations_100`, run in the same batch as the
+ /// column metadata query (in `tempdb` for a `#` temp table).
+ ///
+ /// [`bulk_insert`]: #method.bulk_insert
+ /// [`bulk_insert_columns`]: #method.bulk_insert_columns
+ /// [`send`]: BulkLoadRequest::send
+ /// [`finalize`]: BulkLoadRequest::finalize
+ ///
+ /// # Example
+ ///
+ /// ```no_run
+ /// # use tiberius::{Config, IntoRow, SqlBulkCopyOption, SortOrder};
+ /// # use tokio_util::compat::TokioAsyncWriteCompatExt;
+ /// # use std::env;
+ /// # #[tokio::main]
+ /// # async fn main() -> Result<(), Box> {
+ /// # let c_str = env::var("TIBERIUS_TEST_CONNECTION_STRING").unwrap_or(
+ /// # "server=tcp:localhost,1433;integratedSecurity=true;TrustServerCertificate=true".to_owned(),
+ /// # );
+ /// # let config = Config::from_ado_string(&c_str)?;
+ /// # let tcp = tokio::net::TcpStream::connect(config.get_addr()).await?;
+ /// # tcp.set_nodelay(true)?;
+ /// # let mut client = tiberius::Client::connect(config, tcp.compat_write()).await?;
+ /// let mut req = client
+ /// .bulk_insert_with_options(
+ /// "##bulk_test",
+ /// &["id", "val"],
+ /// SqlBulkCopyOption::KeepIdentity | SqlBulkCopyOption::TableLock,
+ /// &[("id", SortOrder::Ascending)],
+ /// )
+ /// .await?;
+ ///
+ /// for i in [0i32, 1i32, 2i32] {
+ /// req.send((i, i).into_row()).await?;
+ /// }
+ ///
+ /// let res = req.finalize().await?;
+ /// # Ok(())
+ /// # }
+ /// ```
+ pub async fn bulk_insert_with_options<'a>(
+ &'a mut self,
+ table: &'a str,
+ columns: &'a [&'a str],
+ options: SqlBulkCopyOptions,
+ order_hints: &'a [ColumnOrderHint<'a>],
+ ) -> crate::Result> {
+ // `table` is interpolated directly into the SQL batch (identifiers cannot
+ // be parameterized in T-SQL). Reject obviously-malformed/dangerous input
+ // as cheap defense-in-depth; see the `# Security` note above.
+ validate_bulk_table_identifier(table)?;
- let columns = token_stream
- .try_fold(None, |mut columns, token| async move {
- if let ReceivedToken::NewResultset(metadata) = token {
- columns = Some(metadata.columns.clone());
- };
+ // Each `columns` entry is likewise interpolated directly into the SQL
+ // (both the metadata `SELECT` and the `INSERT BULK` column list), so it
+ // gets the same cheap defense-in-depth guard as `table`.
+ for column in columns {
+ validate_bulk_column_identifier(column)?;
+ }
- Ok(columns)
- })
- .await?;
+ // Order-hint column names are interpolated into the `ORDER (...)` clause,
+ // so they get the exact same guard (and, below, the same bracket
+ // escaping) as the regular column list.
+ for &(column, _) in order_hints {
+ validate_bulk_column_identifier(column)?;
+ }
- // now start bulk upload
- let columns: Vec<_> = columns
- .ok_or_else(|| {
- crate::Error::Protocol("expecting column metadata from query but not found".into())
- })?
+ // Retrieve column metadata from the server, keeping only the updateable
+ // columns as bulk targets (read-only/computed columns are skipped).
+ //
+ // Identity columns are normally read-only (so filtered out, letting the
+ // server assign values), but `KEEP_IDENTITY` is implemented — exactly as
+ // ADO.NET's `SqlBulkCopy` does — by *including* the identity column in
+ // the bulk column list so the caller supplies explicit values; there is
+ // no `KEEP_IDENTITY` keyword in the `INSERT BULK` `WITH (...)` grammar.
+ // So when the flag is set, identity columns are additionally retained.
+ //
+ // The same batch lists the collation of every column, which the
+ // `INSERT BULK` column list declares for character columns.
+ let keep_identity = options.contains(SqlBulkCopyOption::KeepIdentity);
+ let (columns, collations) = self.fetch_column_metadata(table, columns, true).await?;
+ let mut columns: Vec<_> = columns
.into_iter()
- .filter(|column| column.base.flags.contains(ColumnFlag::Updateable))
+ .filter(|column| bulk_column_is_target(&column.base, keep_identity))
.collect();
+ // `text`/`ntext`/`image` columns must carry the destination TableName in
+ // the COLMETADATA we emit for the bulk load (MS-TDS §2.2.7.4). Record the
+ // target table on every column; the encoder only emits it for those
+ // types, so this is a no-op on the wire for all other columns.
+ for column in columns.iter_mut() {
+ column.base.table_name = Some(table.to_string());
+ }
+
+ // now start bulk upload
self.connection.flush_stream().await?;
- let col_data = columns.iter().map(|c| format!("{}", c)).join(", ");
- let query = format!("INSERT BULK {} ({})", table, col_data);
+ let col_data = bulk_column_list(&columns, &collations)?;
+ let query = build_insert_bulk_sql(table, &col_data, options, order_hints);
let req = BatchRequest::new(query, self.connection.context().transaction_descriptor());
let id = self.connection.context_mut().next_packet_id();
@@ -347,22 +599,293 @@ impl Client {
BulkLoadRequest::new(&mut self.connection, columns)
}
+ /// Retrieve the column metadata for a set of columns of a table, including
+ /// the column names, types (with their size, precision and scale) and flags
+ /// such as nullability and whether a column is an identity column.
+ ///
+ /// Pass `&["*"]` as `columns` to return the metadata for every column of the
+ /// table.
+ ///
+ /// # Security
+ ///
+ /// Both `table` and the entries of `columns` are interpolated **directly**
+ /// into the SQL batch sent to the server (`SELECT TOP 0 {columns} FROM
+ /// {table}`). SQL Server does not allow identifiers to be supplied as bound
+ /// parameters, so these values cannot be parameterized — they become part of
+ /// the SQL text verbatim. The caller MUST therefore pass **trusted,
+ /// hard-coded or otherwise validated** identifiers and MUST NOT pass
+ /// untrusted or user-supplied input, which would open a SQL injection
+ /// vector. As cheap defense-in-depth this method rejects obviously-malformed
+ /// identifiers (NUL/ASCII control characters or an unbalanced `]` bracket),
+ /// but that guard is not a substitute for passing trusted input.
+ ///
+ /// # Errors
+ ///
+ /// Returns an error if `table` is a malformed identifier, if the metadata
+ /// `SELECT` fails, or if the server reports an error while executing it.
+ ///
+ /// ```no_run
+ /// # use tiberius::Config;
+ /// # use tokio_util::compat::TokioAsyncWriteCompatExt;
+ /// # use std::env;
+ /// # #[tokio::main]
+ /// # async fn main() -> Result<(), Box> {
+ /// # let c_str = env::var("TIBERIUS_TEST_CONNECTION_STRING").unwrap_or(
+ /// # "server=tcp:localhost,1433;integratedSecurity=true;TrustServerCertificate=true".to_owned(),
+ /// # );
+ /// # let config = Config::from_ado_string(&c_str)?;
+ /// # let tcp = tokio::net::TcpStream::connect(config.get_addr()).await?;
+ /// # tcp.set_nodelay(true)?;
+ /// # let mut client = tiberius::Client::connect(config, tcp.compat_write()).await?;
+ /// let meta = client.column_metadata("some_table", &["*"]).await?;
+ /// assert!(meta[0].base().is_identity());
+ /// # Ok(())
+ /// # }
+ /// ```
+ pub async fn column_metadata(
+ &mut self,
+ table: &str,
+ columns: &[&str],
+ ) -> crate::Result>> {
+ // `table` and each `column` are interpolated directly into the SQL
+ // batch below (identifiers cannot be parameterized in T-SQL). Reject
+ // obviously-malformed/dangerous input as cheap defense-in-depth; see the
+ // `# Security` note above.
+ validate_bulk_table_identifier(table)?;
+ for column in columns {
+ validate_bulk_column_identifier(column)?;
+ }
+
+ Ok(self.fetch_column_metadata(table, columns, false).await?.0)
+ }
+
+ /// Fetch the metadata of `columns` of `table` like [`column_metadata`],
+ /// and with `collations` also the `(column name, collation name)` of
+ /// every column of the table from `sp_tablecollations_100` (see
+ /// [`table_collations_sql`]), in the same batch. Without `collations` the
+ /// list is empty.
+ ///
+ /// `table` and `columns` must already be validated.
+ ///
+ /// [`column_metadata`]: #method.column_metadata
+ async fn fetch_column_metadata(
+ &mut self,
+ table: &str,
+ columns: &[&str],
+ collations: bool,
+ ) -> crate::Result<(Vec>, Vec<(String, Option)>)> {
+ self.connection.flush_stream().await?;
+
+ // Ask the server for the column layout without returning any rows.
+ let columns = columns.join(", ");
+ let mut query = format!("SELECT TOP 0 {columns} FROM {table}");
+ if collations {
+ let version = self.connection.context().version();
+ query.push_str("; ");
+ query.push_str(&table_collations_sql(table, version));
+ }
+
+ let req = BatchRequest::new(query, self.connection.context().transaction_descriptor());
+ let id = self.connection.context_mut().next_packet_id();
+ self.connection.send(PacketHeader::batch(id), req).await?;
+
+ let token_stream = TokenStream::new(&mut self.connection).try_unfold();
+
+ // The `SELECT TOP 0` result set comes first and has no rows; every
+ // row is one of the collation list.
+ let (columns, collations) = token_stream
+ .try_fold(
+ (None, Vec::new()),
+ |(mut columns, mut collations), token| async move {
+ match token {
+ ReceivedToken::NewResultset(metadata) if columns.is_none() => {
+ columns = Some(metadata.columns.clone());
+ }
+ ReceivedToken::Row(row) => {
+ let string = |i| match row.get(i) {
+ Some(ColumnData::String(s)) => s.as_ref().map(|s| s.to_string()),
+ _ => None,
+ };
+ if let Some(name) = string(1) {
+ collations.push((name, string(3)));
+ }
+ }
+ _ => {}
+ }
+
+ Ok((columns, collations))
+ },
+ )
+ .await?;
+
+ let columns = columns.ok_or_else(|| {
+ crate::Error::Protocol("expecting column metadata from query but not found".into())
+ })?;
+
+ // Own the column names so the returned metadata is not tied to the
+ // lifetime of the token stream.
+ let columns = columns
+ .into_iter()
+ .map(|c| MetaDataColumn {
+ base: c.base,
+ col_name: std::borrow::Cow::Owned(c.col_name.into_owned()),
+ })
+ .collect();
+
+ Ok((columns, collations))
+ }
+
+ /// Sends a TDS Attention signal to the server (packet type `0x06`,
+ /// MS-TDS section 2.2.1.6) to cancel the request that is currently in
+ /// flight on this connection, and drains the acknowledging token stream so
+ /// the connection can be reused for further queries.
+ ///
+ /// The server responds to the Attention signal by aborting the running
+ /// batch or RPC and returning a `DONE` token with the `DONE_ATTN` status
+ /// bit set. This method waits for that acknowledgement before returning,
+ /// discarding any remaining rows or tokens from the cancelled request.
+ ///
+ /// # Query cancellation and futures
+ ///
+ /// Dropping a [`query`], [`execute`] or [`simple_query`] future (for
+ /// example when a `tokio::time::timeout` elapses or a `select!` branch is
+ /// cancelled) stops the client from polling the stream, but it does *not*
+ /// tell the server to stop working on the request. To actually cancel the
+ /// in-flight work on the server, keep the [`Client`] and call
+ /// `cancel_query` on it. Because `cancel_query` borrows the client
+ /// mutably, it can only be issued once the borrowing result stream has
+ /// been dropped — typically from a separate task holding the client, or
+ /// after a cancelled/timed-out future has released its borrow.
+ ///
+ /// [`query`]: #method.query
+ /// [`execute`]: #method.execute
+ /// [`simple_query`]: #method.simple_query
+ pub async fn cancel_query(&mut self) -> crate::Result<()> {
+ self.connection.cancel_request().await?;
+ Ok(())
+ }
+
/// Closes this database connection explicitly.
pub async fn close(self) -> crate::Result<()> {
self.connection.close().await
}
+ /// Begins a new transaction using a Transaction Manager request
+ /// (`TM_BEGIN_XACT`, MS-TDS 2.2.6.8) instead of a `BEGIN TRAN` T-SQL
+ /// batch.
+ ///
+ /// On success the server replies with a `BeginTransaction` environment
+ /// change token whose descriptor is stored in the connection context and
+ /// automatically attached to subsequent requests, scoping them to the
+ /// transaction. Commit the work with [`commit_transaction`] or discard it
+ /// with [`rollback_transaction`].
+ ///
+ /// The transaction uses the server's default isolation level. Use
+ /// [`begin_transaction_with_isolation`] to request a specific one.
+ ///
+ /// [`commit_transaction`]: #method.commit_transaction
+ /// [`rollback_transaction`]: #method.rollback_transaction
+ /// [`begin_transaction_with_isolation`]: #method.begin_transaction_with_isolation
+ pub async fn begin_transaction(&mut self) -> crate::Result<()> {
+ self.begin_transaction_with_isolation(IsolationLevel::Unspecified)
+ .await
+ }
+
+ /// Begins a new transaction with an explicit isolation level using a
+ /// Transaction Manager request (`TM_BEGIN_XACT`, MS-TDS 2.2.6.8).
+ ///
+ /// See [`begin_transaction`] for details on transaction scoping.
+ ///
+ /// [`begin_transaction`]: #method.begin_transaction
+ pub async fn begin_transaction_with_isolation(
+ &mut self,
+ isolation_level: IsolationLevel,
+ ) -> crate::Result<()> {
+ let req = TransactionManagerRequest::begin(
+ self.connection.context().transaction_descriptor(),
+ isolation_level,
+ "",
+ );
+
+ self.send_transaction_manager_request(req).await
+ }
+
+ /// Commits the active transaction using a Transaction Manager request
+ /// (`TM_COMMIT_XACT`, MS-TDS 2.2.6.8).
+ ///
+ /// After a successful commit the connection is no longer scoped to a
+ /// transaction.
+ pub async fn commit_transaction(&mut self) -> crate::Result<()> {
+ let req = TransactionManagerRequest::commit(
+ self.connection.context().transaction_descriptor(),
+ "",
+ );
+
+ self.send_transaction_manager_request(req).await
+ }
+
+ /// Rolls back the active transaction using a Transaction Manager request
+ /// (`TM_ROLLBACK_XACT`, MS-TDS 2.2.6.8).
+ ///
+ /// After a successful rollback the connection is no longer scoped to a
+ /// transaction.
+ pub async fn rollback_transaction(&mut self) -> crate::Result<()> {
+ let req = TransactionManagerRequest::rollback(
+ self.connection.context().transaction_descriptor(),
+ "",
+ );
+
+ self.send_transaction_manager_request(req).await
+ }
+
+ /// Creates a named savepoint in the active transaction using a Transaction
+ /// Manager request (`TM_SAVE_XACT`, MS-TDS 2.2.6.8).
+ ///
+ /// The savepoint can later be targeted by a T-SQL `ROLLBACK TRANSACTION
+ /// ` to undo work performed after it while keeping the surrounding
+ /// transaction open.
+ pub async fn save_transaction<'a>(
+ &mut self,
+ name: impl Into>,
+ ) -> crate::Result<()> {
+ let req = TransactionManagerRequest::save(
+ self.connection.context().transaction_descriptor(),
+ name,
+ );
+
+ self.send_transaction_manager_request(req).await
+ }
+
+ async fn send_transaction_manager_request(
+ &mut self,
+ req: TransactionManagerRequest<'_>,
+ ) -> crate::Result<()> {
+ self.connection.flush_stream().await?;
+
+ let id = self.connection.context_mut().next_packet_id();
+ self.connection
+ .send(PacketHeader::transaction_manager(id), req)
+ .await?;
+
+ // The server responds with a DONE token (plus an ENVCHANGE token that
+ // the token stream applies to the connection context, updating the
+ // active transaction descriptor).
+ TokenStream::new(&mut self.connection).flush_done().await?;
+
+ Ok(())
+ }
+
pub(crate) fn rpc_params<'a>(query: impl Into>) -> Vec> {
vec![
RpcParam {
name: Cow::Borrowed("stmt"),
flags: BitFlags::empty(),
- value: ColumnData::String(Some(query.into())),
+ value: RpcValue::Scalar(ColumnData::String(Some(query.into()))),
},
RpcParam {
name: Cow::Borrowed("params"),
flags: BitFlags::empty(),
- value: ColumnData::I32(Some(0)),
+ value: RpcValue::Scalar(ColumnData::I32(Some(0))),
},
]
}
@@ -388,12 +911,12 @@ impl Client {
rpc_params.push(RpcParam {
name: Cow::Owned(format!("@P{}", i + 1)),
flags: BitFlags::empty(),
- value: param,
+ value: RpcValue::Scalar(param),
});
}
if let Some(params) = rpc_params.iter_mut().find(|x| x.name == "params") {
- params.value = ColumnData::String(Some(param_str.into()));
+ params.value = RpcValue::Scalar(ColumnData::String(Some(param_str.into())));
}
let req = TokenRpcRequest::new(
@@ -407,4 +930,1089 @@ impl Client {
Ok(())
}
+
+ /// Sends a named-procedure RPC request with the given parameters. The caller
+ /// is responsible for flushing the connection beforehand and for consuming
+ /// the resulting token stream.
+ pub(crate) async fn rpc_run_command<'a, 'b>(
+ &'a mut self,
+ command_name: Cow<'b, str>,
+ rpc_params: Vec>,
+ ) -> crate::Result<()>
+ where
+ 'a: 'b,
+ {
+ let req = TokenRpcRequest::new(
+ command_name,
+ rpc_params,
+ self.connection.context().transaction_descriptor(),
+ );
+
+ let id = self.connection.context_mut().next_packet_id();
+ self.connection.send(PacketHeader::rpc(id), req).await?;
+
+ Ok(())
+ }
+
+ /// Runs a batch query solely to retrieve its column metadata. Used to
+ /// resolve the column layout of a table-valued parameter type.
+ pub(crate) async fn query_run_for_metadata<'b>(
+ &mut self,
+ query: String,
+ ) -> crate::Result>>> {
+ self.connection.flush_stream().await?;
+
+ let req = BatchRequest::new(query, self.connection.context().transaction_descriptor());
+
+ let id = self.connection.context_mut().next_packet_id();
+ self.connection.send(PacketHeader::batch(id), req).await?;
+
+ let token_stream = TokenStream::new(&mut self.connection).try_unfold();
+
+ let columns = token_stream
+ .try_fold(None, |mut columns, token| async move {
+ if let ReceivedToken::NewResultset(metadata) = token {
+ columns = Some(metadata.columns.clone());
+ };
+
+ Ok(columns)
+ })
+ .await?;
+
+ Ok(columns)
+ }
+}
+
+/// Build the `INSERT BULK () [WITH (...)]` statement text.
+///
+/// `col_data` is the already-formatted column list (each column bracket-quoted
+/// with its type, joined by `, `). Active [`SqlBulkCopyOptions`] flags and any
+/// `order_hints` are collected into a `WITH (...)` clause; when both are empty
+/// no `WITH` clause is emitted, so this reproduces the plain
+/// `INSERT BULK ()` used by `bulk_insert_columns`.
+///
+/// Order-hint column names are interpolated verbatim as already-valid SQL
+/// identifiers — exactly like `table` and the `columns` entries elsewhere in
+/// this module — so a caller may pass a plain (`id`), bracket-quoted (`[id]`,
+/// `[my]]col]`) or multi-part name and get that same text back. Callers are
+/// expected to have run every identifier through [`validate_bulk_column_identifier`]
+/// first; do NOT re-bracket here, or an already-quoted name like `[id]` would be
+/// double-escaped into the wrong identifier `[[id]]]`.
+///
+/// Note there is deliberately no `KEEP_IDENTITY` keyword: the `INSERT BULK`
+/// `WITH (...)` grammar has no such option (unlike the textual `BULK INSERT`
+/// statement). [`SqlBulkCopyOption::KeepIdentity`] is honoured by the caller
+/// keeping the identity column in `col_data` instead.
+fn build_insert_bulk_sql(
+ table: &str,
+ col_data: &str,
+ options: SqlBulkCopyOptions,
+ order_hints: &[ColumnOrderHint<'_>],
+) -> String {
+ let mut clauses: Vec = Vec::new();
+
+ // NB: `KeepIdentity` intentionally emits no keyword here — it is a
+ // column-inclusion concern handled in `bulk_insert_with_options`.
+ if options.contains(SqlBulkCopyOption::CheckConstraints) {
+ clauses.push("CHECK_CONSTRAINTS".to_owned());
+ }
+ if options.contains(SqlBulkCopyOption::TableLock) {
+ clauses.push("TABLOCK".to_owned());
+ }
+ if options.contains(SqlBulkCopyOption::KeepNulls) {
+ clauses.push("KEEP_NULLS".to_owned());
+ }
+ if options.contains(SqlBulkCopyOption::FireTriggers) {
+ clauses.push("FIRE_TRIGGERS".to_owned());
+ }
+
+ if !order_hints.is_empty() {
+ let hints = order_hints
+ .iter()
+ .map(|(col, order)| {
+ // Interpolate the (already-validated) identifier verbatim, like
+ // `table`/`columns`. Re-bracketing here would double-escape an
+ // already-quoted name (`[id]` -> `[[id]]]`).
+ format!(
+ "{col} {}",
+ match order {
+ SortOrder::Ascending => "ASC",
+ SortOrder::Descending => "DESC",
+ }
+ )
+ })
+ .join(", ");
+
+ clauses.push(format!("ORDER({hints})"));
+ }
+
+ let mut query = format!("INSERT BULK {table} ({col_data})");
+
+ if !clauses.is_empty() {
+ query.push_str(" WITH (");
+ query.push_str(&clauses.join(", "));
+ query.push(')');
+ }
+
+ query
+}
+
+/// Build the `INSERT BULK` column list: each column bracket-quoted with its
+/// type, and every character column followed by ` COLLATE `.
+///
+/// SQL Server reads the bulk data of a column as the type declared here. A
+/// char/varchar/text declaration without `COLLATE` takes the database default
+/// collation, so the server would read the bytes in that code page and convert
+/// them to the column's, corrupting any text whose column collation differs.
+/// Like SqlClient's `SqlBulkCopy`, the column's own collation is declared for
+/// char, varchar, text, nchar, nvarchar and ntext columns.
+///
+/// `collations` holds the `(column name, collation name)` rows of
+/// `sp_tablecollations_100`. A column is matched by exact name, else by a
+/// unique case-insensitive name (a select list may spell a name in another
+/// case than the table does). A character column without a row or with a
+/// `NULL` collation is declared without `COLLATE`.
+///
+/// # Errors
+///
+/// Returns [`Error::Protocol`](crate::Error::Protocol) if a collation name to
+/// be declared is not a plain identifier (see [`validate_collation_name`]).
+fn bulk_column_list(
+ columns: &[MetaDataColumn<'_>],
+ collations: &[(String, Option)],
+) -> crate::Result {
+ let mut list = Vec::with_capacity(columns.len());
+
+ for column in columns {
+ let mut item = format!("{}", column);
+
+ if declares_collation(&column.base.ty) {
+ if let Some(collation) = column_collation(&column.col_name, collations) {
+ validate_collation_name(collation)?;
+ item.push_str(" COLLATE ");
+ item.push_str(collation);
+ }
+ }
+
+ list.push(item);
+ }
+
+ Ok(list.join(", "))
+}
+
+/// Whether the `INSERT BULK` declaration of a column of type `ty` carries a
+/// `COLLATE` clause: the character types SqlClient declares one for.
+fn declares_collation(ty: &crate::tds::codec::TypeInfo) -> bool {
+ use crate::tds::codec::{TypeInfo, VarLenType};
+
+ matches!(
+ ty,
+ TypeInfo::VarLenSized(ctx) if matches!(
+ ctx.r#type(),
+ VarLenType::BigChar
+ | VarLenType::BigVarChar
+ | VarLenType::Text
+ | VarLenType::NChar
+ | VarLenType::NVarchar
+ | VarLenType::NText
+ )
+ )
+}
+
+/// The collation name listed for the column `name`: the row with exactly this
+/// name, else the only row whose name matches ignoring case.
+fn column_collation<'a>(name: &str, collations: &'a [(String, Option)]) -> Option<&'a str> {
+ let row = match collations.iter().find(|(n, _)| n == name) {
+ Some(row) => row,
+ None => {
+ let name = name.to_lowercase();
+ let mut rows = collations.iter().filter(|(n, _)| n.to_lowercase() == name);
+ match (rows.next(), rows.next()) {
+ (Some(row), None) => row,
+ _ => return None,
+ }
+ }
+ };
+
+ row.1.as_deref()
+}
+
+/// Build the batch statement that lists the collation of every column of
+/// `table`, as SqlClient's `SqlBulkCopy` does:
+///
+/// ```text
+/// EXEC ..sp_tablecollations_100 N'.'
+/// ```
+///
+/// Its result set has one row per column, ordered by column id, of `colid`,
+/// `name`, `tds_collation_100` and `collation_100` (the collation name).
+///
+/// The procedure reads the catalog it is called in, so it is called in the
+/// table's database: the catalog part of `table`, else `tempdb` for a temp
+/// table (a name starting with `#`), else the current database (`..`). Schema
+/// and table name are bracket-quoted and put in a string literal. Before SQL
+/// Server 2008 (TDS 7.3) the procedure is `sp_tablecollations_90`.
+///
+/// `table` must have passed [`validate_bulk_table_identifier`].
+fn table_collations_sql(table: &str, version: crate::FeatureLevel) -> String {
+ let parts = split_multipart_identifier(table);
+ let part = |from_end: usize| {
+ parts
+ .len()
+ .checked_sub(from_end + 1)
+ .map_or("", |i| parts[i].as_str())
+ };
+
+ let table_name = part(0);
+ let schema = part(1);
+ let catalog = part(2);
+
+ let catalog = if catalog.is_empty() {
+ if table_name.starts_with('#') {
+ "tempdb".to_owned()
+ } else {
+ String::new()
+ }
+ } else {
+ quote_identifier(catalog)
+ };
+
+ let literal = |part: &str| {
+ if part.is_empty() {
+ String::new()
+ } else {
+ quote_identifier(&part.replace('\'', "''"))
+ }
+ };
+
+ let procedure = if version >= crate::FeatureLevel::SqlServer2008 {
+ "sp_tablecollations_100"
+ } else {
+ "sp_tablecollations_90"
+ };
+
+ format!(
+ "EXEC {catalog}..{procedure} N'{}.{}'",
+ literal(schema),
+ literal(table_name)
+ )
+}
+
+/// Bracket-quote `name`, doubling any `]` in it.
+fn quote_identifier(name: &str) -> String {
+ format!("[{}]", name.replace(']', "]]"))
+}
+
+/// Split a multi-part identifier (`server.catalog.schema.table`, any leading
+/// parts omitted or empty) into its unquoted parts: `[a]]b].c` gives `a]b`
+/// and `c`. `ident` must have passed [`validate_sql_identifier`], so every
+/// bracket-quoted segment is terminated.
+fn split_multipart_identifier(ident: &str) -> Vec {
+ let mut parts = vec![String::new()];
+ let mut chars = ident.chars().peekable();
+ let mut in_bracket = false;
+
+ while let Some(c) = chars.next() {
+ let part = parts.last_mut().expect("parts is never empty");
+
+ if in_bracket {
+ if c == ']' {
+ if chars.peek() == Some(&']') {
+ chars.next();
+ part.push(']');
+ } else {
+ in_bracket = false;
+ }
+ } else {
+ part.push(c);
+ }
+ } else {
+ match c {
+ '[' => in_bracket = true,
+ '.' => parts.push(String::new()),
+ c => part.push(c),
+ }
+ }
+ }
+
+ parts
+}
+
+/// Reject a server-reported collation name that is not a plain identifier of
+/// ASCII letters, digits and `_`, as every SQL Server collation name is. The
+/// name is put into the `INSERT BULK` statement unquoted.
+fn validate_collation_name(name: &str) -> crate::Result<()> {
+ if !name.is_empty() && name.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_') {
+ Ok(())
+ } else {
+ Err(crate::Error::Protocol(
+ format!("invalid collation name {name:?} for a bulk insert column").into(),
+ ))
+ }
+}
+
+/// Decide whether a server-reported column is a bulk-insert target.
+///
+/// Read-only/computed columns are skipped so the server assigns their values.
+/// Identity columns are read-only by default (filtered out, letting the server
+/// assign them), but when [`SqlBulkCopyOption::KeepIdentity`] is set they are
+/// additionally retained so the caller can supply explicit values — matching
+/// ADO.NET's `SqlBulkCopy` (there is no `KEEP_IDENTITY` keyword in the
+/// `INSERT BULK` `WITH (...)` grammar). Factored out of
+/// [`Client::bulk_insert_with_options`] so this selection logic is unit-testable
+/// without a live server.
+fn bulk_column_is_target(
+ base: &crate::tds::codec::BaseMetaDataColumn,
+ keep_identity: bool,
+) -> bool {
+ base.is_updateable() || (keep_identity && base.is_identity())
+}
+
+/// Reject an obviously-malformed or dangerous bulk-insert table identifier.
+///
+/// The `table` argument of [`Client::bulk_insert`] / [`Client::bulk_insert_columns`]
+/// is interpolated directly into the SQL batch because T-SQL does not allow
+/// identifiers to be parameterized. This guard is cheap defense-in-depth — it
+/// does NOT make untrusted input safe. It only rejects input that cannot be a
+/// legitimate identifier (see [`validate_sql_identifier`] for the exact rules).
+///
+/// It deliberately does NOT try to quote or rewrite the identifier, so
+/// multi-part names (`schema.table`), already-bracketed names (`[my table]`) and
+/// temp tables (`##bulk_test`) keep working unchanged.
+fn validate_bulk_table_identifier(table: &str) -> crate::Result<()> {
+ validate_sql_identifier("bulk insert table", table)
+}
+
+/// Reject an obviously-malformed or dangerous bulk-insert `column` identifier.
+///
+/// Column names are interpolated into the metadata `SELECT` and `INSERT BULK`
+/// column list exactly like `table`, so they get the same cheap
+/// defense-in-depth check. See [`validate_bulk_table_identifier`].
+fn validate_bulk_column_identifier(column: &str) -> crate::Result<()> {
+ validate_sql_identifier("bulk insert column", column)
+}
+
+/// Reject an obviously-malformed or dangerous SQL identifier that will be
+/// interpolated directly into a SQL batch because T-SQL does not allow
+/// identifiers or type names to be parameterized. `what` names the kind of
+/// identifier for the error message.
+///
+/// This is cheap defense-in-depth — it does NOT make untrusted input safe. It
+/// rejects input that cannot be a legitimate identifier:
+///
+/// - a NUL byte or any ASCII control character;
+/// - **outside** a `[...]` bracket-quoted segment, any character that is not
+/// identifier-safe. Only alphanumerics and the punctuation needed for real
+/// identifiers/type names are allowed — `_`, `.` (multi-part names like
+/// `dbo.MyType`), `@`/`#` (variable/temp-style names), `*` (a bulk column
+/// list may be `*`), and `(`, `)`, `,` (parameterized types such as
+/// `decimal(10,2)` / `varchar(max)`). Parens must be balanced — an unbalanced
+/// `)` *or* an unclosed `(` is rejected — and both a space and a comma are allowed only *inside*
+/// those parens (e.g. `decimal(18, 4)`); a top-level space or comma is
+/// rejected because it would let one identifier split into several SQL tokens
+/// (a top-level comma would splice a verbatim order hint `a,b` into two
+/// columns). This rejects statement-breaking characters such as `;`, quotes
+/// and `-`, so a value like `1; DROP TABLE Users--` cannot slip through; and
+/// - **inside** a `[...]` bracket-quoted segment anything is allowed except an
+/// unescaped `]` (per the T-SQL bracket-escaping rule a literal `]` must be
+/// doubled as `]]`). The segment must be terminated — an unclosed `[` running
+/// to the end of the string is rejected. A `]` seen outside any bracket is
+/// unbalanced and rejected. A closing `]`, and a top-level closing `)`, are themselves SQL
+/// token boundaries, so a segment may only be followed by `.` (the next part
+/// of a multi-part name) or the end of the string — this stops delimiter-
+/// adjacent splicing such as `[t]UNION(...)` or `foo(1)UNION(...)` that needs
+/// no space.
+///
+/// It deliberately does NOT try to quote or rewrite the identifier, so
+/// multi-part names (`schema.table`), already-bracketed names (`[my table]`,
+/// `[dbo].[my table]`, `[weird]]name]`) and temp tables (`##bulk_test`) keep
+/// working unchanged. This is shared by the bulk-insert guards here and by
+/// `validate_db_type_identifier` in `src/command.rs`.
+pub(crate) fn validate_sql_identifier(what: &str, ident: &str) -> crate::Result<()> {
+ if ident.chars().any(|c| c.is_ascii_control()) {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier must not contain NUL or control characters").into(),
+ ));
+ }
+
+ // Apply the T-SQL bracket rule: inside a `[...]` quoted identifier a literal
+ // `]` must be doubled (`]]`); a single `]` closes the bracket. A `]` seen
+ // outside of any bracket is unbalanced and rejected. Tracking bracket state
+ // keeps legitimate names like `[dbo].[my table]` and `[weird]]name]`
+ // working while catching stray closing brackets such as `Foo]`.
+ let mut chars = ident.chars().peekable();
+ let mut in_bracket = false;
+ let mut paren_depth: u32 = 0;
+ while let Some(c) = chars.next() {
+ if in_bracket {
+ if c == ']' {
+ if chars.peek() == Some(&']') {
+ chars.next(); // consume the doubled `]]` escape
+ } else {
+ in_bracket = false;
+ // A quoted-identifier segment may only be followed by `.`
+ // (introducing the next part of a multi-part name) or the
+ // end of the string. Anything else — e.g. `[t]UNION ...` —
+ // splices a fresh SQL token directly onto the closing `]`
+ // (which is itself a token boundary, needing no space), so
+ // reject it.
+ match chars.peek() {
+ None | Some('.') => {}
+ Some(_) => {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier has trailing characters after a bracket-quoted segment").into(),
+ ));
+ }
+ }
+ }
+ }
+ continue;
+ }
+
+ match c {
+ '[' => in_bracket = true,
+ ']' => {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier contains an unbalanced `]` bracket").into(),
+ ));
+ }
+ '(' => paren_depth += 1,
+ ')' => {
+ // A `)` with no matching `(` is unbalanced. Left unchecked
+ // (`saturating_sub`) it would sail through and, interpolated
+ // verbatim, could close a caller-supplied enclosing paren early
+ // — e.g. an order hint `col)` desyncing `ORDER(col) ...)`. Reject
+ // it exactly like an unbalanced `]`.
+ if paren_depth == 0 {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier contains an unbalanced `)`").into(),
+ ));
+ }
+ paren_depth -= 1;
+ // A parameterized type ends at its closing paren; nothing is a
+ // legitimate continuation after a top-level `)`. Rejecting it
+ // stops `)`-delimited token splicing such as `foo(1)UNION(...)`
+ // (the `)` is a token boundary, so no space is required).
+ if paren_depth == 0 && chars.peek().is_some() {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier has trailing characters after a closing `)`")
+ .into(),
+ ));
+ }
+ }
+ // A space is only legitimate inside a parameterized type's parens
+ // (e.g. `decimal(18, 4)`) or inside a bracket-quoted name (handled
+ // above). A *top-level* space would let a single identifier split
+ // into several SQL tokens (`t UNION SELECT ...`, `t WHERE ...`)
+ // without using any otherwise-blocked character, so reject it.
+ ' ' if paren_depth == 0 => {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier contains a disallowed character").into(),
+ ));
+ }
+ // A comma is only legitimate inside a parameterized type's parens
+ // (`decimal(10,2)`). A *top-level* comma would splice a single
+ // identifier into two — e.g. a verbatim order hint `a,b` becoming
+ // two order columns `a` and `b` — so reject it like a top-level
+ // space.
+ ',' if paren_depth == 0 => {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier contains a disallowed character").into(),
+ ));
+ }
+ // Outside a bracket-quoted segment only identifier-safe characters
+ // are permitted (see the doc comment). Everything else — `;`,
+ // quotes, `-`, etc. — is rejected.
+ c if c.is_alphanumeric() => {}
+ '_' | '.' | '@' | '#' | ',' | ' ' | '*' => {}
+ _ => {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier contains a disallowed character").into(),
+ ));
+ }
+ }
+ }
+
+ // Reject unbalanced *openers* left dangling at end of input, mirroring the
+ // rejection of unbalanced closers above. An unterminated `[` would quote and
+ // swallow whatever follows when interpolated (e.g. an order hint `[abc`
+ // becoming `ORDER([abc ASC))`); an unclosed `(` leaves an enclosing paren
+ // open. A legitimate identifier/type name never ends mid-bracket or with an
+ // open paren.
+ if in_bracket {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier has an unterminated `[` bracket-quoted segment").into(),
+ ));
+ }
+ if paren_depth != 0 {
+ return Err(crate::Error::BulkInput(
+ format!("{what} identifier contains an unbalanced `(`").into(),
+ ));
+ }
+
+ Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::{
+ build_insert_bulk_sql, bulk_column_is_target, validate_bulk_column_identifier,
+ validate_bulk_table_identifier,
+ };
+ use crate::tds::codec::{BaseMetaDataColumn, ColumnFlag, TypeInfo, VarLenContext, VarLenType};
+ use crate::{SortOrder, SqlBulkCopyOption, SqlBulkCopyOptions};
+ use enumflags2::BitFlags;
+
+ // Build a `BaseMetaDataColumn` carrying exactly `flags`, so the bulk-target
+ // selection predicate can be exercised without a live server. The column
+ // type is irrelevant to the predicate; a small fixed-len type stands in.
+ fn base_with_flags(flags: BitFlags) -> BaseMetaDataColumn {
+ BaseMetaDataColumn {
+ flags,
+ ty: TypeInfo::VarLenSized(VarLenContext::new(VarLenType::Intn, 4, None)),
+ table_name: None,
+ }
+ }
+
+ #[test]
+ fn bulk_column_is_target_selects_writeable_and_keep_identity() {
+ let updateable: BitFlags = ColumnFlag::Updateable.into();
+ let unknown: BitFlags = ColumnFlag::UpdateableUnknown.into();
+ let read_only = BitFlags::::empty();
+ let identity_ro: BitFlags = ColumnFlag::Identity.into();
+ // An identity column SQL Server also reports as updateable-unknown.
+ let identity_unknown = ColumnFlag::Identity | ColumnFlag::UpdateableUnknown;
+
+ // Read/write and updateable-unknown columns are always targets,
+ // regardless of the KeepIdentity flag.
+ for keep in [false, true] {
+ assert!(bulk_column_is_target(&base_with_flags(updateable), keep));
+ assert!(bulk_column_is_target(&base_with_flags(unknown), keep));
+ // A plain read-only (non-identity) column is never a target.
+ assert!(!bulk_column_is_target(&base_with_flags(read_only), keep));
+ }
+
+ // A read-only identity column is skipped by default (server assigns the
+ // value) but retained when KeepIdentity is set.
+ assert!(!bulk_column_is_target(&base_with_flags(identity_ro), false));
+ assert!(bulk_column_is_target(&base_with_flags(identity_ro), true));
+
+ // KeepIdentity only *adds* identity columns; it never drops a column that
+ // was already a target on its own merits.
+ assert!(bulk_column_is_target(
+ &base_with_flags(identity_unknown),
+ false
+ ));
+ assert!(bulk_column_is_target(
+ &base_with_flags(identity_unknown),
+ true
+ ));
+
+ // A non-identity read-only column is not resurrected by KeepIdentity.
+ assert!(!bulk_column_is_target(&base_with_flags(read_only), true));
+ }
+
+ // A fixed, hand-written column list stands in for the server-provided
+ // `MetaDataColumn` Display output so the SQL-string builder can be unit
+ // tested without a live connection.
+ const COLS: &str = "[id] int, [val] int";
+
+ #[test]
+ fn build_sql_no_options_no_hints_emits_no_with_clause() {
+ // Empty options + empty hints must reproduce the plain statement that
+ // `bulk_insert_columns` has always emitted.
+ assert_eq!(
+ build_insert_bulk_sql("t", COLS, SqlBulkCopyOptions::empty(), &[]),
+ "INSERT BULK t ([id] int, [val] int)"
+ );
+ }
+
+ #[test]
+ fn build_sql_each_flag_emits_expected_keyword() {
+ // `KeepIdentity` is deliberately absent: the `INSERT BULK` `WITH (...)`
+ // grammar has no `KEEP_IDENTITY` keyword (it is a column-inclusion
+ // concern), so only these four flags map to keywords.
+ for (flag, keyword) in [
+ (SqlBulkCopyOption::CheckConstraints, "CHECK_CONSTRAINTS"),
+ (SqlBulkCopyOption::TableLock, "TABLOCK"),
+ (SqlBulkCopyOption::KeepNulls, "KEEP_NULLS"),
+ (SqlBulkCopyOption::FireTriggers, "FIRE_TRIGGERS"),
+ ] {
+ assert_eq!(
+ build_insert_bulk_sql("t", COLS, flag.into(), &[]),
+ format!("INSERT BULK t ([id] int, [val] int) WITH ({keyword})"),
+ "flag {flag:?} did not emit {keyword}",
+ );
+ }
+ }
+
+ #[test]
+ fn build_sql_keep_identity_emits_no_with_keyword() {
+ // Regression guard: emitting `KEEP_IDENTITY` into the `WITH (...)` clause
+ // is a syntax error against the TDS `INSERT BULK` statement (verified
+ // against ADO.NET's `SqlBulkCopy` and go-mssqldb, neither of which emits
+ // it). `KeepIdentity` alone must therefore produce no `WITH` clause at
+ // all; the flag's effect is entirely in column selection.
+ let sql = build_insert_bulk_sql("t", COLS, SqlBulkCopyOption::KeepIdentity.into(), &[]);
+ assert_eq!(sql, "INSERT BULK t ([id] int, [val] int)", "got: {sql}");
+ assert!(!sql.contains("KEEP_IDENTITY"), "got: {sql}");
+ }
+
+ #[test]
+ fn build_sql_combined_flags_join_in_fixed_order() {
+ // `KeepIdentity` contributes no keyword, so only TABLOCK/FIRE_TRIGGERS
+ // appear even though it is set.
+ let opts = SqlBulkCopyOption::KeepIdentity
+ | SqlBulkCopyOption::TableLock
+ | SqlBulkCopyOption::FireTriggers;
+
+ assert_eq!(
+ build_insert_bulk_sql("t", COLS, opts, &[]),
+ "INSERT BULK t ([id] int, [val] int) WITH (TABLOCK, FIRE_TRIGGERS)"
+ );
+ }
+
+ #[test]
+ fn build_sql_all_flags() {
+ // `all()` includes `KeepIdentity`, which emits nothing, so the keyword
+ // list is the four real `WITH` options.
+ let opts = SqlBulkCopyOptions::all();
+ assert_eq!(
+ build_insert_bulk_sql("t", COLS, opts, &[]),
+ "INSERT BULK t ([id] int, [val] int) WITH (CHECK_CONSTRAINTS, TABLOCK, KEEP_NULLS, FIRE_TRIGGERS)"
+ );
+ }
+
+ #[test]
+ fn build_sql_order_hints_asc_and_desc() {
+ // Plain column names are interpolated verbatim (like `columns`), not
+ // re-bracketed, and the reference `ORDER(` has no space.
+ let hints = [("id", SortOrder::Ascending), ("val", SortOrder::Descending)];
+ assert_eq!(
+ build_insert_bulk_sql("t", COLS, SqlBulkCopyOptions::empty(), &hints),
+ "INSERT BULK t ([id] int, [val] int) WITH (ORDER(id ASC, val DESC))"
+ );
+ }
+
+ #[test]
+ fn build_sql_options_and_order_hints_combine() {
+ let hints = [("id", SortOrder::Ascending)];
+ assert_eq!(
+ build_insert_bulk_sql("t", COLS, SqlBulkCopyOption::TableLock.into(), &hints),
+ "INSERT BULK t ([id] int, [val] int) WITH (TABLOCK, ORDER(id ASC))"
+ );
+ }
+
+ #[test]
+ fn build_sql_order_hint_bracketed_name_not_double_escaped() {
+ // Regression guard: order-hint column names are interpolated verbatim as
+ // already-valid identifiers, exactly like `table`/`columns`. An
+ // already-bracket-quoted name (which the validator accepts) must be
+ // emitted as-is — NOT re-bracketed into `[[id]]]` or `[[my]]]]col]]]`.
+ let hints = [
+ ("[id]", SortOrder::Ascending),
+ ("[my]]col]", SortOrder::Descending),
+ ];
+ assert_eq!(
+ build_insert_bulk_sql("t", COLS, SqlBulkCopyOptions::empty(), &hints),
+ "INSERT BULK t ([id] int, [val] int) WITH (ORDER([id] ASC, [my]]col] DESC))"
+ );
+ }
+
+ #[test]
+ fn build_sql_empty_hints_emits_no_order_clause() {
+ let sql = build_insert_bulk_sql("t", COLS, SqlBulkCopyOption::TableLock.into(), &[]);
+ assert!(!sql.contains("ORDER"), "got: {sql}");
+ assert_eq!(sql, "INSERT BULK t ([id] int, [val] int) WITH (TABLOCK)");
+ }
+
+ #[test]
+ fn build_sql_order_hint_column_names_are_validated_like_columns() {
+ // The public API runs order-hint column names through the same guard as
+ // the column list; confirm that guard rejects a stray `]`.
+ assert!(validate_bulk_column_identifier("my]col").is_err());
+ assert!(validate_bulk_column_identifier("[my]]col]").is_ok());
+ }
+
+ #[test]
+ fn accepts_normal_column_identifiers() {
+ for column in ["foo", "bar", "*", "[my col]", "[weird]]col]"] {
+ assert!(
+ validate_bulk_column_identifier(column).is_ok(),
+ "expected column {column:?} to be accepted",
+ );
+ }
+ }
+
+ #[test]
+ fn rejects_bad_column_identifiers() {
+ // control character
+ assert!(validate_bulk_column_identifier("foo\0bar").is_err());
+ assert!(validate_bulk_column_identifier("foo\nbar").is_err());
+ // lone / unbalanced closing bracket
+ assert!(validate_bulk_column_identifier("foo]").is_err());
+ assert!(validate_bulk_column_identifier("a]b").is_err());
+ }
+
+ #[test]
+ fn accepts_normal_identifiers() {
+ for table in [
+ "Foo",
+ "dbo.Foo",
+ "##bulk_test",
+ "#temp",
+ "[my table]",
+ "[dbo].[my table]",
+ "[weird]]name]", // doubled `]]` escape inside brackets
+ ] {
+ assert!(
+ validate_bulk_table_identifier(table).is_ok(),
+ "expected {table:?} to be accepted",
+ );
+ }
+ }
+
+ #[test]
+ fn rejects_control_characters() {
+ assert!(validate_bulk_table_identifier("Foo\0bar").is_err());
+ assert!(validate_bulk_table_identifier("Foo\nbar").is_err());
+ assert!(validate_bulk_table_identifier("Foo\tbar").is_err());
+ }
+
+ #[test]
+ fn rejects_unbalanced_closing_bracket() {
+ assert!(validate_bulk_table_identifier("Foo]").is_err());
+ assert!(validate_bulk_table_identifier("[my] table]").is_err());
+ assert!(validate_bulk_table_identifier("a]b").is_err());
+ }
+
+ #[test]
+ fn column_metadata_guards_reject_bad_identifiers() {
+ // `column_metadata` interpolates `table`/`columns` into
+ // `SELECT TOP 0 {columns} FROM {table}` and now validates both with the
+ // same guards as `bulk_insert*`. A malformed table or column identifier
+ // must be rejected before any SQL is built.
+ assert!(validate_bulk_table_identifier("Foo]").is_err());
+ assert!(validate_bulk_table_identifier("Foo\nbar").is_err());
+ assert!(validate_bulk_column_identifier("id]").is_err());
+ assert!(validate_bulk_column_identifier("col\0").is_err());
+ }
+
+ #[test]
+ fn rejects_statement_breaking_identifiers() {
+ // The guard must reject statement-breakers (`;`, quotes, `--`, `=`)
+ // that would let an injected column/table escape the interpolated SQL.
+ for bad in [
+ "1; DROP TABLE Users--",
+ "id = 1",
+ "foo'bar",
+ "foo\"bar",
+ "foo--bar",
+ "foo;bar",
+ ] {
+ assert!(
+ validate_bulk_column_identifier(bad).is_err(),
+ "expected column {bad:?} to be rejected",
+ );
+ assert!(
+ validate_bulk_table_identifier(bad).is_err(),
+ "expected table {bad:?} to be rejected",
+ );
+ }
+ }
+
+ #[test]
+ fn accepts_star_and_bracketed_statement_breakers() {
+ // `*` must stay valid as a whole column list (bulk_insert uses `&["*"]`),
+ // and characters that would be statement-breakers outside brackets are
+ // fine when properly bracket-quoted.
+ assert!(validate_bulk_column_identifier("*").is_ok());
+ assert!(validate_bulk_column_identifier("[weird;name]").is_ok());
+ assert!(validate_bulk_table_identifier("[dbo].[my;table]").is_ok());
+ }
+
+ #[test]
+ fn rejects_top_level_space_but_allows_it_inside_parens_and_brackets() {
+ // A top-level space lets a single identifier split into multiple SQL
+ // tokens without any otherwise-blocked character, so it is rejected.
+ assert!(validate_bulk_table_identifier("t UNION SELECT name FROM sysobjects").is_err());
+ assert!(validate_bulk_table_identifier("t WHERE 1=1").is_err());
+ assert!(validate_bulk_column_identifier("a b").is_err());
+
+ // A space is still fine inside a parameterized type's parens...
+ assert!(super::validate_sql_identifier("db_type", "decimal(18, 4)").is_ok());
+ // ...and inside a bracket-quoted name.
+ assert!(validate_bulk_table_identifier("[my table]").is_ok());
+ // The canonical no-space forms keep working.
+ assert!(super::validate_sql_identifier("db_type", "decimal(10,2)").is_ok());
+ assert!(super::validate_sql_identifier("db_type", "varchar(max)").is_ok());
+ }
+
+ #[test]
+ fn rejects_delimiter_adjacent_token_splicing() {
+ // A `]` or `)` is itself a SQL token boundary, so an attacker can splice
+ // a new token onto one without any (now-blocked) top-level space. Both
+ // forms must be rejected.
+ assert!(
+ validate_bulk_table_identifier("[RealTable]UNION(SELECT secret FROM users)").is_err()
+ );
+ assert!(validate_bulk_table_identifier("[t]UNION").is_err());
+ assert!(validate_bulk_table_identifier("[t](1)").is_err());
+ assert!(super::validate_sql_identifier("t", "foo(1)UNION(SELECT x)").is_err());
+ assert!(super::validate_sql_identifier("t", "decimal(10,2)x").is_err());
+
+ // ...while every legitimate multi-part / parameterized form still passes.
+ assert!(validate_bulk_table_identifier("[dbo].[my table]").is_ok());
+ assert!(validate_bulk_table_identifier("[db].[schema].[tbl]").is_ok());
+ assert!(validate_bulk_table_identifier("[weird]]name]").is_ok());
+ assert!(super::validate_sql_identifier("db_type", "decimal(18,4)").is_ok());
+ assert!(super::validate_sql_identifier("db_type", "numeric(38, 38)").is_ok());
+ assert!(super::validate_sql_identifier("db_type", "varchar(max)").is_ok());
+ }
+
+ #[test]
+ fn rejects_unbalanced_closing_paren_and_top_level_comma() {
+ // Order-hint columns are interpolated verbatim into `ORDER( ... )`, so a
+ // value the guard accepts must not be able to close that paren early or
+ // splice a second column: a lone trailing `)` (no matching `(`) and a
+ // top-level comma are both rejected.
+ assert!(validate_bulk_column_identifier("col)").is_err());
+ assert!(validate_bulk_column_identifier(")").is_err());
+ assert!(validate_bulk_column_identifier("a,b").is_err());
+ assert!(validate_bulk_table_identifier("t)").is_err());
+ assert!(super::validate_sql_identifier("db_type", "decimal(10,2))").is_err());
+
+ // The symmetric openers must also be rejected: an unbalanced `(` never
+ // closed, and an unterminated `[` that would swallow trailing SQL when
+ // interpolated verbatim into `ORDER( ... )`.
+ assert!(validate_bulk_column_identifier("a(b").is_err());
+ assert!(validate_bulk_column_identifier("(").is_err());
+ assert!(validate_bulk_column_identifier("[abc").is_err());
+ assert!(validate_bulk_table_identifier("dbo.[my table").is_err());
+ assert!(super::validate_sql_identifier("db_type", "decimal(10,2").is_err());
+
+ // Balanced parens with an interior comma/space are still fine.
+ assert!(super::validate_sql_identifier("db_type", "decimal(10,2)").is_ok());
+ assert!(super::validate_sql_identifier("db_type", "numeric(18, 4)").is_ok());
+ // A bracket-quoted name may still contain `)`/`,` literally.
+ assert!(validate_bulk_column_identifier("[weird,name)]").is_ok());
+ }
+}
+
+// Server-free tests for the column collations declared in `INSERT BULK`.
+#[cfg(test)]
+mod bulk_collation_tests {
+ use super::{bulk_column_list, table_collations_sql, validate_collation_name};
+ use crate::tds::codec::{
+ BaseMetaDataColumn, ColumnFlag, FixedLenType, TypeInfo, VarLenContext, VarLenType,
+ };
+ use crate::tds::Collation;
+ use crate::{FeatureLevel, MetaDataColumn};
+ use std::borrow::Cow;
+
+ fn column(name: &'static str, ty: TypeInfo) -> MetaDataColumn<'static> {
+ MetaDataColumn {
+ base: BaseMetaDataColumn {
+ flags: ColumnFlag::Updateable.into(),
+ ty,
+ table_name: None,
+ },
+ col_name: Cow::Borrowed(name),
+ }
+ }
+
+ fn var(ty: VarLenType, len: usize) -> TypeInfo {
+ // Latin1_General_CI_AS; the declared name comes from the server's
+ // collation list, not from these bytes.
+ let collation = match ty {
+ VarLenType::BigChar
+ | VarLenType::BigVarChar
+ | VarLenType::Text
+ | VarLenType::NChar
+ | VarLenType::NVarchar
+ | VarLenType::NText => Some(Collation::new(0x00d0_0409, 52)),
+ _ => None,
+ };
+ TypeInfo::VarLenSized(VarLenContext::new(ty, len, collation))
+ }
+
+ fn collations(rows: &[(&str, Option<&str>)]) -> Vec<(String, Option)> {
+ rows.iter()
+ .map(|(name, collation)| (name.to_string(), collation.map(str::to_string)))
+ .collect()
+ }
+
+ #[test]
+ fn character_columns_declare_their_collation() {
+ let columns = [
+ column("id", TypeInfo::FixedLen(FixedLenType::Int4)),
+ column("c", var(VarLenType::BigChar, 6)),
+ column("v", var(VarLenType::BigVarChar, 20)),
+ column("vmax", var(VarLenType::BigVarChar, 0xffff)),
+ column("t", var(VarLenType::Text, 0x7fff_ffff)),
+ column("nc", var(VarLenType::NChar, 12)),
+ column("nv", var(VarLenType::NVarchar, 40)),
+ column("nt", var(VarLenType::NText, 0x7fff_ffff)),
+ column("b", var(VarLenType::BigVarBin, 16)),
+ column("img", var(VarLenType::Image, 0x7fff_ffff)),
+ ];
+ let rows = collations(&[
+ ("id", None),
+ ("c", Some("Cyrillic_General_CI_AS")),
+ ("v", Some("Cyrillic_General_CI_AS")),
+ ("vmax", Some("Chinese_PRC_CI_AS")),
+ ("t", Some("Cyrillic_General_CI_AS")),
+ ("nc", Some("Latin1_General_100_CI_AS_SC")),
+ ("nv", Some("Latin1_General_100_CI_AS_SC")),
+ ("nt", Some("Latin1_General_100_CI_AS_SC")),
+ ("b", None),
+ ("img", None),
+ ]);
+
+ assert_eq!(
+ bulk_column_list(&columns, &rows).unwrap(),
+ "[id] int, \
+ [c] char(6) COLLATE Cyrillic_General_CI_AS, \
+ [v] varchar(20) COLLATE Cyrillic_General_CI_AS, \
+ [vmax] varchar(max) COLLATE Chinese_PRC_CI_AS, \
+ [t] text COLLATE Cyrillic_General_CI_AS, \
+ [nc] nchar(12) COLLATE Latin1_General_100_CI_AS_SC, \
+ [nv] nvarchar(40) COLLATE Latin1_General_100_CI_AS_SC, \
+ [nt] ntext COLLATE Latin1_General_100_CI_AS_SC, \
+ [b] varbinary(16), \
+ [img] image"
+ );
+ }
+
+ #[test]
+ fn non_character_columns_never_declare_a_collation() {
+ // Even if the server listed a collation for them.
+ let columns = [
+ column("id", TypeInfo::FixedLen(FixedLenType::Int4)),
+ column("b", var(VarLenType::BigVarBin, 16)),
+ ];
+ let rows = collations(&[
+ ("id", Some("Latin1_General_CI_AS")),
+ ("b", Some("Latin1_General_CI_AS")),
+ ]);
+
+ assert_eq!(
+ bulk_column_list(&columns, &rows).unwrap(),
+ "[id] int, [b] varbinary(16)"
+ );
+ }
+
+ #[test]
+ fn collations_are_matched_by_column_name() {
+ let columns = [
+ column("B", var(VarLenType::BigVarChar, 10)),
+ column("a", var(VarLenType::BigVarChar, 10)),
+ column("missing", var(VarLenType::BigVarChar, 10)),
+ column("no_collation", var(VarLenType::BigVarChar, 10)),
+ ];
+ // Out of order, a case-insensitive match for `B`, an exact match for
+ // `a` that wins over `A`, no row for `missing` and a NULL collation.
+ let rows = collations(&[
+ ("A", Some("Greek_CI_AS")),
+ ("a", Some("Cyrillic_General_CI_AS")),
+ ("b", Some("Hebrew_CI_AS")),
+ ("no_collation", None),
+ ]);
+
+ assert_eq!(
+ bulk_column_list(&columns, &rows).unwrap(),
+ "[B] varchar(10) COLLATE Hebrew_CI_AS, \
+ [a] varchar(10) COLLATE Cyrillic_General_CI_AS, \
+ [missing] varchar(10), \
+ [no_collation] varchar(10)"
+ );
+ }
+
+ #[test]
+ fn bad_collation_names_are_rejected() {
+ for name in [
+ "",
+ "Latin1_General_CI_AS; DROP TABLE t",
+ "Latin1 General",
+ "Latin1_General_CI_AS'",
+ "[Latin1_General_CI_AS]",
+ "Latin1-General",
+ "Latin1_General_CI_AS\0",
+ "Кириллица",
+ ] {
+ assert!(validate_collation_name(name).is_err(), "{name:?}");
+ }
+ for name in [
+ "Latin1_General_CI_AS",
+ "SQL_Latin1_General_CP1_CI_AS",
+ "Latin1_General_100_CI_AS_SC_UTF8",
+ ] {
+ assert!(validate_collation_name(name).is_ok(), "{name:?}");
+ }
+
+ let columns = [column("v", var(VarLenType::BigVarChar, 10))];
+ let rows = collations(&[("v", Some("Latin1_General_CI_AS) --"))]);
+ assert!(matches!(
+ bulk_column_list(&columns, &rows),
+ Err(crate::Error::Protocol(_))
+ ));
+ }
+
+ #[test]
+ fn table_collations_query_matches_sqlclient() {
+ let v = FeatureLevel::SqlServerN;
+ assert_eq!(
+ table_collations_sql("t", v),
+ "EXEC ..sp_tablecollations_100 N'.[t]'"
+ );
+ assert_eq!(
+ table_collations_sql("dbo.t", v),
+ "EXEC ..sp_tablecollations_100 N'[dbo].[t]'"
+ );
+ assert_eq!(
+ table_collations_sql("[my db].[dbo].[it's]]x]", v),
+ "EXEC [my db]..sp_tablecollations_100 N'[dbo].[it''s]]x]'"
+ );
+ assert_eq!(
+ table_collations_sql("srv.db.s.t", v),
+ "EXEC [db]..sp_tablecollations_100 N'[s].[t]'"
+ );
+ assert_eq!(
+ table_collations_sql("db..t", v),
+ "EXEC [db]..sp_tablecollations_100 N'.[t]'"
+ );
+ }
+
+ #[test]
+ fn table_collations_query_reads_temp_tables_from_tempdb() {
+ let v = FeatureLevel::SqlServerN;
+ assert_eq!(
+ table_collations_sql("#t", v),
+ "EXEC tempdb..sp_tablecollations_100 N'.[#t]'"
+ );
+ assert_eq!(
+ table_collations_sql("##t", v),
+ "EXEC tempdb..sp_tablecollations_100 N'.[##t]'"
+ );
+ assert_eq!(
+ table_collations_sql("[#t]", v),
+ "EXEC tempdb..sp_tablecollations_100 N'.[#t]'"
+ );
+ assert_eq!(
+ table_collations_sql("tempdb..#t", v),
+ "EXEC [tempdb]..sp_tablecollations_100 N'.[#t]'"
+ );
+ }
+
+ #[test]
+ fn table_collations_query_uses_the_2005_procedure_before_2008() {
+ assert_eq!(
+ table_collations_sql("t", FeatureLevel::SqlServer2005),
+ "EXEC ..sp_tablecollations_90 N'.[t]'"
+ );
+ assert_eq!(
+ table_collations_sql("t", FeatureLevel::SqlServer2008),
+ "EXEC ..sp_tablecollations_100 N'.[t]'"
+ );
+ }
}
diff --git a/src/client/auth.rs b/src/client/auth.rs
index 2003d99ba..a898eacb2 100644
--- a/src/client/auth.rs
+++ b/src/client/auth.rs
@@ -1,59 +1,81 @@
-use std::fmt::Debug;
+use secrecy::{ExposeSecret, SecretString};
+use zeroize::Zeroize;
-#[derive(Clone, PartialEq, Eq)]
+/// Build a `SecretString` from owned bytes without leaving an un-zeroized copy
+/// in freed heap. `SecretString::from(String)` routes through
+/// `String::into_boxed_str()`, which reallocates and frees the source buffer
+/// *without zeroizing* when the string has spare capacity. Copy the bytes into
+/// an exact-sized `Box` and wipe the original.
+pub(crate) fn secret_from_string(mut s: String) -> SecretString {
+ let boxed: Box = s.as_str().into();
+ s.zeroize();
+ SecretString::new(boxed)
+}
+
+// Credentials are stored as `secrecy::SecretString`, which zeroizes the
+// plaintext on drop and redacts it from `Debug`, so these types can derive
+// `Debug` and still never print a secret. `SecretString` does not implement
+// `PartialEq`/`Eq` (comparing secrets is deliberately opt-in), so the equality
+// impls below are hand-written; they compare the exposed plaintext to preserve
+// the previous derived behaviour (and the public `AuthMethod: Eq` bound).
+#[derive(Clone, Debug)]
pub struct SqlServerAuth {
user: String,
- password: String,
+ password: SecretString,
}
impl SqlServerAuth {
- pub(crate) fn user(&self) -> &str {
- &self.user
- }
-
- pub(crate) fn password(&self) -> &str {
- &self.password
+ pub(crate) fn into_credentials(self) -> (String, SecretString) {
+ (self.user, self.password)
}
}
-impl Debug for SqlServerAuth {
- fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
- f.debug_struct("SqlServerAuth")
- .field("user", &self.user)
- .field("password", &"")
- .finish()
+impl PartialEq for SqlServerAuth {
+ fn eq(&self, other: &Self) -> bool {
+ self.user == other.user && self.password.expose_secret() == other.password.expose_secret()
}
}
-#[derive(Clone, PartialEq, Eq)]
-#[cfg(any(feature = "winauth", doc))]
-#[cfg_attr(feature = "docs", doc(feature = "winauth"))]
+impl Eq for SqlServerAuth {}
+
+#[derive(Clone, Debug)]
+#[cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"), doc))]
+#[cfg_attr(
+ docsrs,
+ doc(cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"))))
+)]
pub struct WindowsAuth {
pub(crate) user: String,
- pub(crate) password: String,
+ pub(crate) password: SecretString,
pub(crate) domain: Option,
}
-#[cfg(any(feature = "winauth", doc))]
-#[cfg_attr(feature = "docs", doc(feature = "winauth"))]
-impl Debug for WindowsAuth {
- fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
- f.debug_struct("WindowsAuth")
- .field("user", &self.user)
- .field("password", &"")
- .field("domain", &self.domain)
- .finish()
+#[cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"), doc))]
+impl PartialEq for WindowsAuth {
+ fn eq(&self, other: &Self) -> bool {
+ self.user == other.user
+ && self.domain == other.domain
+ && self.password.expose_secret() == other.password.expose_secret()
}
}
+#[cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"), doc))]
+impl Eq for WindowsAuth {}
+
/// Defines the method of authentication to the server.
-#[derive(Clone, Debug, PartialEq, Eq)]
+#[derive(Clone, Debug)]
pub enum AuthMethod {
/// Authenticate directly with SQL Server.
SqlServer(SqlServerAuth),
- /// Authenticate with Windows credentials.
- #[cfg(any(feature = "winauth", doc))]
- #[cfg_attr(feature = "docs", doc(cfg(feature = "winauth")))]
+ /// Authenticate with Windows credentials (NTLMv2). The `winauth` feature
+ /// provides it on every platform via its pure-Rust NTLMv2 client; on Unix
+ /// the `sspi-rs` feature provides it via sspi-rs and takes precedence when
+ /// both are enabled.
+ #[cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"), doc))]
+ #[cfg_attr(
+ docsrs,
+ doc(cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"))))
+ )]
Windows(WindowsAuth),
/// Authenticate as the currently logged in user. On Windows uses SSPI and
/// Kerberos on Unix platforms.
@@ -63,29 +85,56 @@ pub enum AuthMethod {
doc
))]
#[cfg_attr(
- feature = "docs",
+ docsrs,
doc(cfg(any(windows, all(unix, feature = "integrated-auth-gssapi"))))
)]
Integrated,
/// Authenticate with an AAD token. The token should encode an AAD user/service principal
/// which has access to SQL Server.
- AADToken(String),
+ AADToken(SecretString),
#[doc(hidden)]
None,
}
+// `SecretString` has no `PartialEq`, so `AuthMethod`'s public equality is
+// hand-written. It mirrors the old derived behaviour: same variant + equal
+// fields (secrets compared via their exposed plaintext).
+impl PartialEq for AuthMethod {
+ fn eq(&self, other: &Self) -> bool {
+ match (self, other) {
+ (Self::SqlServer(a), Self::SqlServer(b)) => a == b,
+ #[cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"), doc))]
+ (Self::Windows(a), Self::Windows(b)) => a == b,
+ #[cfg(any(
+ all(windows, feature = "winauth"),
+ all(unix, feature = "integrated-auth-gssapi"),
+ doc
+ ))]
+ (Self::Integrated, Self::Integrated) => true,
+ (Self::AADToken(a), Self::AADToken(b)) => a.expose_secret() == b.expose_secret(),
+ (Self::None, Self::None) => true,
+ _ => false,
+ }
+ }
+}
+
+impl Eq for AuthMethod {}
+
impl AuthMethod {
/// Construct a new SQL Server authentication configuration.
pub fn sql_server(user: impl ToString, password: impl ToString) -> Self {
Self::SqlServer(SqlServerAuth {
user: user.to_string(),
- password: password.to_string(),
+ password: secret_from_string(password.to_string()),
})
}
/// Construct a new Windows authentication configuration.
- #[cfg(any(feature = "winauth", doc))]
- #[cfg_attr(feature = "docs", doc(cfg(feature = "winauth")))]
+ #[cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"), doc))]
+ #[cfg_attr(
+ docsrs,
+ doc(cfg(any(feature = "winauth", all(unix, feature = "sspi-rs"))))
+ )]
pub fn windows(user: impl AsRef, password: impl ToString) -> Self {
let (domain, user) = match user.as_ref().find('\\') {
Some(idx) => (Some(&user.as_ref()[..idx]), &user.as_ref()[idx + 1..]),
@@ -94,13 +143,108 @@ impl AuthMethod {
Self::Windows(WindowsAuth {
user: user.to_string(),
- password: password.to_string(),
+ password: secret_from_string(password.to_string()),
domain: domain.map(|s| s.to_string()),
})
}
/// Construct a new configuration with AAD auth token.
pub fn aad_token(token: impl ToString) -> Self {
- Self::AADToken(token.to_string())
+ Self::AADToken(secret_from_string(token.to_string()))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::AuthMethod;
+ use secrecy::ExposeSecret;
+
+ // Compile-time proof that the stored credential zeroizes its plaintext on
+ // drop: `secrecy::SecretString` implements `ZeroizeOnDrop`.
+ #[test]
+ fn stored_credentials_are_zeroize_on_drop() {
+ fn assert_zeroize_on_drop() {}
+ assert_zeroize_on_drop::();
+ }
+
+ #[test]
+ fn sql_server_password_can_be_consumed_and_exposed() {
+ let AuthMethod::SqlServer(auth) = AuthMethod::sql_server("sa", "secret") else {
+ unreachable!();
+ };
+
+ let (user, password) = auth.into_credentials();
+
+ assert_eq!("sa", user);
+ // `expose_secret()` yields exactly the plaintext that was provided.
+ assert_eq!("secret", password.expose_secret());
+ // The credential is dropped (and zeroized) at the end of this scope.
+ }
+
+ #[test]
+ fn aad_token_exposes_the_right_value() {
+ let AuthMethod::AADToken(token) = AuthMethod::aad_token("aad-secret-token") else {
+ unreachable!();
+ };
+ assert_eq!("aad-secret-token", token.expose_secret());
+ }
+
+ #[test]
+ fn debug_redacts_credentials() {
+ let sql = format!("{:?}", AuthMethod::sql_server("sa", "sql-secret"));
+ assert!(!sql.contains("sql-secret"), "SQL password leaked: {sql}");
+ // The non-secret user is still visible for diagnostics.
+ assert!(sql.contains("sa"), "user should be shown: {sql}");
+ assert!(sql.contains("REDACTED"), "password not redacted: {sql}");
+
+ let aad = format!("{:?}", AuthMethod::aad_token("aad-secret-token"));
+ assert!(!aad.contains("aad-secret-token"), "AAD token leaked: {aad}");
+ assert!(aad.contains("REDACTED"), "AAD token not redacted: {aad}");
+ }
+
+ #[test]
+ fn secret_from_string_preserves_value_with_spare_capacity() {
+ // A `String` with spare capacity is exactly the input shape that would
+ // trigger the leaky `SecretString::from(String)` reallocation path. This
+ // test verifies the helper preserves the value for that shape. The
+ // zeroization of the freed source is guaranteed by construction
+ // (`s.zeroize()` before drop) and is not directly unit-observable in
+ // safe Rust, so it is not asserted here.
+ let mut s = String::with_capacity(64);
+ s.push_str("pw");
+ assert_eq!(super::secret_from_string(s).expose_secret(), "pw");
+ }
+
+ #[test]
+ fn debug_none_variant() {
+ assert_eq!(format!("{:?}", AuthMethod::None), "None");
+ }
+
+ #[cfg(any(feature = "winauth", all(unix, feature = "sspi-rs")))]
+ #[test]
+ fn windows_auth_parses_domain_and_debug_redacts() {
+ // `DOMAIN\user` form exercises the domain-splitting branch of `windows()`.
+ let auth = AuthMethod::windows("DOMAIN\\user", "win-secret");
+ let dbg = format!("{:?}", auth);
+ assert!(dbg.contains("Windows"), "variant name missing: {dbg}");
+ assert!(dbg.contains("DOMAIN"), "domain not preserved: {dbg}");
+ assert!(dbg.contains("user"), "user not preserved: {dbg}");
+ assert!(!dbg.contains("win-secret"), "password leaked: {dbg}");
+ assert!(dbg.contains("REDACTED"), "password not redacted: {dbg}");
+
+ // No backslash exercises the domain-less branch.
+ let plain = AuthMethod::windows("plainuser", "pw");
+ let dbg = format!("{:?}", plain);
+ assert!(dbg.contains("plainuser"), "user not preserved: {dbg}");
+ assert!(dbg.contains("None"), "domain should be None: {dbg}");
+ }
+
+ #[cfg(any(
+ all(windows, feature = "winauth"),
+ all(unix, feature = "integrated-auth-gssapi")
+ ))]
+ #[test]
+ fn integrated_debug() {
+ assert_eq!(format!("{:?}", AuthMethod::Integrated), "Integrated");
}
}
diff --git a/src/client/config.rs b/src/client/config.rs
index fff68bc15..db2ffd96f 100644
--- a/src/client/config.rs
+++ b/src/client/config.rs
@@ -1,13 +1,30 @@
mod ado_net;
+mod ado_parser;
mod jdbc;
use std::collections::HashMap;
use std::path::PathBuf;
+use std::time::Duration;
+
+/// Default upper bound on how long the connection handshake (TDS prelogin, TLS
+/// negotiation and login) may take before [`Connection::connect`] gives up with
+/// a timeout error. Matches the 15-second `Connect Timeout` default used by
+/// ADO.NET / the Microsoft SQL Server drivers.
+///
+/// [`Connection::connect`]: crate::Client::connect
+const DEFAULT_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(15);
+
+/// Default per-response deadline applied while reading command results (see
+/// [`Config::command_timeout`]). Matches the 30-second `Command Timeout` /
+/// `CommandTimeout` default used by ADO.NET / the Microsoft SQL Server drivers.
+const DEFAULT_COMMAND_TIMEOUT: Duration = Duration::from_secs(30);
use super::AuthMethod;
use crate::EncryptionLevel;
use ado_net::*;
use jdbc::*;
+#[cfg(any(feature = "native-tls", feature = "vendored-openssl"))]
+use secrecy::SecretString;
#[derive(Clone, Debug)]
/// The `Config` struct contains all configuration information
@@ -18,10 +35,17 @@ use jdbc::*;
/// When using an [ADO.NET connection string], it can be
/// constructed using the [`from_ado_string`] function.
///
+/// Alternatively, a [`ConfigBuilder`] can be used for an ergonomic,
+/// chainable construction. Create one via [`builder`], call its
+/// setter methods and finalize it with [`build`].
+///
/// [`Client`]: struct.Client.html
/// [ADO.NET connection string]: https://docs.microsoft.com/en-us/dotnet/framework/data/adonet/connection-strings
/// [`from_ado_string`]: struct.Config.html#method.from_ado_string
/// [`get_addr`]: struct.Config.html#method.get_addr
+/// [`ConfigBuilder`]: struct.ConfigBuilder.html
+/// [`builder`]: struct.Config.html#method.builder
+/// [`build`]: struct.ConfigBuilder.html#method.build
pub struct Config {
pub(crate) host: Option,
pub(crate) port: Option,
@@ -32,14 +56,175 @@ pub struct Config {
pub(crate) trust: TrustConfig,
pub(crate) auth: AuthMethod,
pub(crate) readonly: bool,
+ pub(crate) packet_size: Option,
+ pub(crate) hostname_in_certificate: Option,
+ pub(crate) client_name: Option,
+ pub(crate) multi_subnet_failover: bool,
+ pub(crate) handshake_timeout: Option,
+ pub(crate) command_timeout: Option,
+ pub(crate) lossy_utf16_decoding: bool,
+ pub(crate) lossy_codepage_decoding: bool,
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ pub(crate) client_cert: Option,
+}
+
+/// How the server certificate is trusted.
+///
+/// Two orthogonal axes plus a bypass:
+///
+/// - [`source`](TrustConfig::source): the base set of trust anchors (mutually
+/// exclusive — the OS store or a bundled Mozilla snapshot).
+/// - [`extra_cas`](TrustConfig::extra_cas): additional CA certificates layered
+/// *on top of* the source. This **accumulates**: every `trust_cert_ca` /
+/// `trust_cert_ca_bundle` call appends one entry (composable) rather than
+/// replacing the previous one.
+/// - [`bypass`](TrustConfig::bypass): skip certificate validation entirely
+/// (`trust_cert`). Mutually exclusive with configuring a `source` or
+/// `extra_cas` — mixing them panics (or, from a connection string, errors)
+/// rather than letting the bypass silently win.
+///
+/// `bypass` is deliberately a distinct axis (not folded into `source`) so a
+/// future, narrower "relax hostname verification only" mode can be
+/// added later without a public-API rewrite.
+#[derive(Clone)]
+pub(crate) struct TrustConfig {
+ /// Base trust anchors. Mutually exclusive; defaults to [`RootSource::Native`].
+ pub(crate) source: RootSource,
+ /// Extra CA certificates added on top of `source`. Accumulates in call order.
+ pub(crate) extra_cas: Vec,
+ /// If set, certificate validation (and hostname verification) is skipped
+ /// entirely. See [`Config::trust_cert`].
+ pub(crate) bypass: bool,
+}
+
+impl Default for TrustConfig {
+ fn default() -> Self {
+ Self {
+ source: RootSource::Native,
+ extra_cas: Vec::new(),
+ bypass: false,
+ }
+ }
+}
+
+impl TrustConfig {
+ /// True when nothing has been customised: the OS trust store, no extra CAs,
+ /// no bypass. Used by tests to assert the default trust posture.
+ #[cfg(test)]
+ pub(crate) fn is_default(&self) -> bool {
+ matches!(self.source, RootSource::Native) && self.extra_cas.is_empty() && !self.bypass
+ }
+}
+
+// Manual `Debug` following the crate's curated-Debug convention: never dump raw
+// certificate bytes. `ExtraCa::Bundle` is summarised as `Bundle { len: N }`.
+impl std::fmt::Debug for TrustConfig {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("TrustConfig")
+ .field("source", &self.source)
+ .field("extra_cas", &self.extra_cas)
+ .field("bypass", &self.bypass)
+ .finish()
+ }
+}
+
+/// The base set of trust anchors used to validate the server certificate.
+/// Mutually exclusive.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub(crate) enum RootSource {
+ /// The operating system's trust store (the default).
+ #[default]
+ Native,
+ /// A compiled-in snapshot of Mozilla's root CA store (`webpki-roots`).
+ ///
+ /// rustls-only, and gated on the `rustls-webpki-roots` feature so the
+ /// variant cannot exist without the crate that consumes it. Selected via
+ /// [`Config::trust_webpki_roots`].
+ #[cfg(feature = "rustls-webpki-roots")]
+ WebpkiRoots,
+}
+
+/// An additional CA certificate source layered on top of [`RootSource`].
+#[derive(Clone)]
+#[cfg_attr(
+ not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )),
+ allow(dead_code)
+)]
+pub(crate) enum ExtraCa {
+ /// A certificate file on disk (PEM `.pem`/`.crt`, or DER `.der`). May hold
+ /// multiple certificates when PEM.
+ File(PathBuf),
+ /// In-memory certificate bytes. Multi-certificate: sniffed as PEM (all
+ /// blocks parsed) when the bytes contain a `-----BEGIN` marker at the start
+ /// of a line, otherwise treated as a single DER certificate.
+ Bundle(Vec),
+}
+
+// Manual `Debug`: summarise `Bundle` as `Bundle { len: N }` so raw certificate
+// bytes are never dumped.
+impl std::fmt::Debug for ExtraCa {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self {
+ ExtraCa::File(path) => f.debug_tuple("File").field(path).finish(),
+ ExtraCa::Bundle(bytes) => f.debug_struct("Bundle").field("len", &bytes.len()).finish(),
+ }
+ }
+}
+
+/// A client certificate and its private key, presented to the server during the
+/// TLS handshake to authenticate the *client* (mutual TLS / TDS 8.0
+/// `ENCRYPT_CLIENT_CERT`).
+///
+/// Construct one indirectly via [`Config::client_certificate`] (PEM/DER
+/// certificate + private-key files) or [`Config::client_certificate_pkcs12`]
+/// (a PKCS#12 / PFX bundle, `native-tls` and `vendored-openssl` only).
+#[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+))]
+#[derive(Clone, Debug)]
+pub(crate) struct ClientCertificate {
+ pub(crate) source: ClientCertSource,
}
+#[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+))]
+// `SecretString` redacts the PKCS#12 password from `Debug` (and zeroizes it on
+// drop), so this can derive `Debug` without leaking the password.
#[derive(Clone, Debug)]
-pub(crate) enum TrustConfig {
- #[allow(dead_code)]
- CaCertificateLocation(PathBuf),
- TrustAll,
- Default,
+pub(crate) enum ClientCertSource {
+ /// A certificate file and a separate private-key file. Both may be PEM
+ /// (`.pem`/`.crt` for the certificate, `.pem`/`.key` for the key) or DER
+ /// (`.der`); the concrete format is detected from the file extension by the
+ /// active TLS backend.
+ ///
+ /// The `cert`/`key` fields are read only by the `rustls` and `native-tls`
+ /// backends; the `vendored-openssl` (opentls) backend rejects this variant
+ /// (it supports PKCS#12 only). In a `vendored-openssl`-only build the fields
+ /// are therefore never read, so silence dead-code exactly there rather than
+ /// unconditionally — this keeps the derived `Debug` (which no longer counts
+ /// as a read) while still compiling clean under `-Dwarnings`.
+ #[cfg_attr(not(any(feature = "rustls", feature = "native-tls")), allow(dead_code))]
+ CertAndKey { cert: PathBuf, key: PathBuf },
+ /// A PKCS#12 / PFX bundle path together with its decryption password. Only
+ /// supported by the `native-tls` and `vendored-openssl` backends.
+ #[cfg(any(feature = "native-tls", feature = "vendored-openssl"))]
+ Pkcs12 {
+ path: PathBuf,
+ password: SecretString,
+ },
}
impl Default for Config {
@@ -62,9 +247,23 @@ impl Default for Config {
feature = "vendored-openssl"
)))]
encryption: EncryptionLevel::NotSupported,
- trust: TrustConfig::Default,
+ trust: TrustConfig::default(),
auth: AuthMethod::None,
readonly: false,
+ packet_size: None,
+ hostname_in_certificate: None,
+ client_name: None,
+ multi_subnet_failover: false,
+ handshake_timeout: Some(DEFAULT_HANDSHAKE_TIMEOUT),
+ command_timeout: Some(DEFAULT_COMMAND_TIMEOUT),
+ lossy_utf16_decoding: false,
+ lossy_codepage_decoding: false,
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ client_cert: None,
}
}
}
@@ -75,6 +274,33 @@ impl Config {
Self::default()
}
+ /// Create a new [`ConfigBuilder`] initialized with the default settings.
+ ///
+ /// This provides an ergonomic, chainable alternative to constructing a
+ /// [`Config`] via its individual setter methods.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use tiberius::{Config, AuthMethod};
+ /// let config = Config::builder()
+ /// .host("localhost")
+ /// .port(1433)
+ /// .database("master")
+ /// .authentication(AuthMethod::sql_server("SA", ""))
+ /// .build();
+ ///
+ /// assert_eq!("localhost:1433", config.get_addr());
+ /// ```
+ ///
+ /// [`ConfigBuilder`]: struct.ConfigBuilder.html
+ /// [`Config`]: struct.Config.html
+ pub fn builder() -> ConfigBuilder {
+ ConfigBuilder {
+ inner: Self::default(),
+ }
+ }
+
/// A host or ip address to connect to.
///
/// - Defaults to `localhost`.
@@ -115,10 +341,27 @@ impl Config {
self.application_name = Some(name.to_string());
}
+ /// Sets the TDS packet size for the connection.
+ ///
+ /// Larger packet sizes can improve bulk insert performance by reducing
+ /// the number of network round-trips. Valid values are 512 to 32767.
+ /// The server may negotiate a different size.
+ ///
+ /// - Defaults to 4096 bytes.
+ pub fn packet_size(&mut self, size: u32) {
+ self.packet_size = Some(size);
+ }
+
+ /// Gets the configured packet size, if set.
+ pub fn get_packet_size(&self) -> Option {
+ self.packet_size
+ }
+
/// Set the preferred encryption level.
///
- /// - With `tls` feature, defaults to `Required`.
- /// - Without `tls` feature, defaults to `NotSupported`.
+ /// - With a TLS backend enabled (any of the `rustls`, `native-tls`, or
+ /// `vendored-openssl` features), defaults to `Required`.
+ /// - Without a TLS backend, defaults to `NotSupported`.
pub fn encryption(&mut self, encryption: EncryptionLevel) {
self.encryption = encryption;
}
@@ -129,32 +372,150 @@ impl Config {
/// On production setting, the certificate should be added to the local key
/// storage (or use `trust_cert_ca` instead), using this setting is potentially dangerous.
///
+ /// This also bypasses the rustls backend's certificate *version* checks, so
+ /// it is the escape hatch for the `invalid peer certificate:
+ /// UnsupportedCertVersion` failure some older or self-signed SQL Server
+ /// certificates trigger. Prefer [`trust_cert_ca`] when you
+ /// can point at the server's CA; reach for `trust_cert` only when you cannot.
+ /// Note that SQL Server performs a TLS handshake during login even when
+ /// `Encrypt=false`, so certificate errors can surface regardless of the
+ /// encryption level.
+ ///
+ /// # Security
+ ///
+ /// This accepts **any** certificate: it disables both certificate-chain
+ /// validation *and* hostname verification, so it provides no protection
+ /// against a man-in-the-middle. Only use it on a network you already trust.
+ /// Prefer [`trust_cert_ca`] / [`trust_cert_ca_bundle`] to pin the server's
+ /// CA instead.
+ ///
+ /// [`trust_cert_ca`]: Self::trust_cert_ca
+ /// [`trust_cert_ca_bundle`]: Self::trust_cert_ca_bundle
+ ///
/// # Panics
- /// Will panic in case `trust_cert_ca` was called before.
+ /// Will panic if any of [`trust_cert_ca`], [`trust_cert_ca_bundle`] or
+ /// [`trust_webpki_roots`] was called before — the trust bypass is mutually
+ /// exclusive with configuring trust anchors.
+ ///
+ /// [`trust_webpki_roots`]: Self::trust_webpki_roots
///
/// - Defaults to `default`, meaning server certificate is validated against system-truststore.
pub fn trust_cert(&mut self) {
- if let TrustConfig::CaCertificateLocation(_) = &self.trust {
- panic!("'trust_cert' and 'trust_cert_ca' are mutual exclusive! Only use one.")
+ if !self.trust.extra_cas.is_empty() || !matches!(self.trust.source, RootSource::Native) {
+ panic!(
+ "'trust_cert' and 'trust_cert_ca'/'trust_cert_ca_bundle'/'trust_webpki_roots' \
+ are mutual exclusive! Only use one."
+ )
}
- self.trust = TrustConfig::TrustAll;
+ self.trust.bypass = true;
}
- /// If set, the server certificate will be validated against the given CA certificate in
- /// in addition to the system-truststore.
+ /// Trust an additional CA certificate (from a file) *in addition to* the
+ /// base trust anchors (the system trust store by default).
/// Useful when using self-signed certificates on the server without having to disable the
/// trust-chain.
///
+ /// The file may be PEM (`.pem`/`.crt`) or DER (`.der`); a PEM file may
+ /// contain **multiple** certificates and all of them are trusted.
+ ///
+ /// This **accumulates**: calling it more than once (or alongside
+ /// [`trust_cert_ca_bundle`]) trusts every supplied CA — repeated calls are
+ /// additive, not replace-last-wins.
+ ///
/// # Panics
- /// Will panic in case `trust_cert` was called before.
+ /// Will panic in case [`trust_cert`] was called before.
+ ///
+ /// [`trust_cert`]: Self::trust_cert
+ /// [`trust_cert_ca_bundle`]: Self::trust_cert_ca_bundle
///
/// - Defaults to validating the server certificate is validated against system's certificate storage.
pub fn trust_cert_ca(&mut self, path: impl ToString) {
- if let TrustConfig::TrustAll = &self.trust {
+ if self.trust.bypass {
panic!("'trust_cert' and 'trust_cert_ca' are mutual exclusive! Only use one.")
- } else {
- self.trust = TrustConfig::CaCertificateLocation(PathBuf::from(path.to_string()))
}
+ self.trust
+ .extra_cas
+ .push(ExtraCa::File(PathBuf::from(path.to_string())));
+ }
+
+ /// Trust additional CA certificates supplied as in-memory bytes, *in
+ /// addition to* the base trust anchors. This avoids having to write an
+ /// in-memory certificate out to a temporary file, and accepts a whole
+ /// **bundle** of CA certificates (for example the AWS RDS root bundle).
+ ///
+ /// The byte format is auto-detected: if the bytes contain a `-----BEGIN`
+ /// marker at the start of a line they are parsed as PEM (every certificate
+ /// block is trusted), otherwise they are treated as a single DER
+ /// certificate. A leading UTF-8 byte-order mark is tolerated.
+ ///
+ /// Like [`trust_cert_ca`], this **accumulates**: each call appends to the
+ /// set of trusted CAs.
+ ///
+ /// # Panics
+ /// Will panic in case [`trust_cert`] was called before.
+ ///
+ /// [`trust_cert`]: Self::trust_cert
+ /// [`trust_cert_ca`]: Self::trust_cert_ca
+ pub fn trust_cert_ca_bundle(&mut self, bundle: impl Into>) {
+ if self.trust.bypass {
+ panic!("'trust_cert' and 'trust_cert_ca_bundle' are mutual exclusive! Only use one.")
+ }
+ self.trust.extra_cas.push(ExtraCa::Bundle(bundle.into()));
+ }
+
+ /// Use a compiled-in snapshot of Mozilla's root CA store (via the
+ /// `webpki-roots` crate) as the base trust anchors instead of the operating
+ /// system's trust store. Any CAs added with [`trust_cert_ca`] /
+ /// [`trust_cert_ca_bundle`] are still layered on top.
+ ///
+ /// This is useful on platforms with no usable OS trust store. It is only
+ /// available with the `rustls` backend (via the `rustls-webpki-roots`
+ /// feature); with any other backend the method does not exist, so misuse is
+ /// a compile error.
+ ///
+ /// # Security
+ ///
+ /// The bundled roots are a **pinned snapshot** taken when this crate's
+ /// `webpki-roots` dependency was last updated. Unlike the OS trust store
+ /// they do not receive security updates on their own — they go stale (newly
+ /// distrusted or newly added CAs are missed) unless the dependency is
+ /// updated and the application rebuilt.
+ ///
+ /// # Panics
+ /// Will panic in case [`trust_cert`] was called before.
+ ///
+ /// [`trust_cert`]: Self::trust_cert
+ /// [`trust_cert_ca`]: Self::trust_cert_ca
+ /// [`trust_cert_ca_bundle`]: Self::trust_cert_ca_bundle
+ #[cfg(feature = "rustls-webpki-roots")]
+ #[cfg_attr(docsrs, doc(cfg(feature = "rustls-webpki-roots")))]
+ pub fn trust_webpki_roots(&mut self) {
+ if self.trust.bypass {
+ panic!("'trust_cert' and 'trust_webpki_roots' are mutual exclusive! Only use one.")
+ }
+ self.trust.source = RootSource::WebpkiRoots;
+ }
+
+ /// Sets the hostname that the server certificate is validated against,
+ /// instead of the value given to [`host`].
+ ///
+ /// This is useful when connecting through an IP address, a tunnel, or a
+ /// load balancer whose certificate carries a different subject/SAN than the
+ /// address used to reach it (see issue #340).
+ ///
+ /// - Defaults to the value of [`host`].
+ ///
+ /// [`host`]: Config::host
+ pub fn hostname_in_certificate(&mut self, hostname: impl ToString) {
+ self.hostname_in_certificate = Some(hostname.to_string());
+ }
+
+ /// Sets the client / workstation name reported to the server in the login
+ /// record (queryable with `HOST_NAME()`).
+ ///
+ /// - Defaults to the local workstation id (the machine hostname).
+ pub fn client_name(&mut self, name: impl ToString) {
+ self.client_name = Some(name.to_string());
}
/// Sets the authentication method.
@@ -167,8 +528,302 @@ impl Config {
/// Sets ApplicationIntent readonly.
///
/// - Defaults to `false`.
- pub fn readonly(&mut self, readnoly: bool) {
- self.readonly = readnoly;
+ pub fn readonly(&mut self, readonly: bool) {
+ self.readonly = readonly;
+ }
+
+ /// Enable multi-subnet failover.
+ ///
+ /// When enabled and the server host name resolves to more than one IP
+ /// address (for example, an Always On availability group listener spread
+ /// across subnets), connections are attempted to all resolved addresses in
+ /// parallel and the first one to succeed is used. This mirrors the ADO.NET
+ /// `MultiSubnetFailover` connection-string keyword.
+ ///
+ /// - Defaults to `false`.
+ pub fn multi_subnet_failover(&mut self, multi_subnet_failover: bool) {
+ self.multi_subnet_failover = multi_subnet_failover;
+ }
+
+ /// Returns whether multi-subnet failover is enabled.
+ pub fn get_multi_subnet_failover(&self) -> bool {
+ self.multi_subnet_failover
+ }
+
+ /// Sets an upper bound on how long the connection handshake may take.
+ ///
+ /// The handshake covers everything [`Client::connect`] does after it is
+ /// handed a connected TCP stream: the TDS prelogin exchange, the TLS
+ /// negotiation and the login. If the server accepts the TCP connection but
+ /// then stops responding mid-handshake (for example a TLS handshake that
+ /// stalls indefinitely), the connect future would otherwise hang forever
+ /// with no error. This bound makes such a stall surface as a
+ /// [`Error::Io`] with [`std::io::ErrorKind::TimedOut`] instead.
+ ///
+ /// The timer is runtime-agnostic (it does not depend on tokio or smol), so
+ /// it applies regardless of the async runtime driving the connection. Note
+ /// that it does **not** cover establishing the TCP connection itself, which
+ /// happens before the stream is passed to [`Client::connect`]; bound that
+ /// with your runtime's own connect timeout (e.g. `tokio::time::timeout`).
+ ///
+ /// Enable `tracing` at the `DEBUG` level to see which handshake stage was
+ /// reached, which pinpoints where a stall occurred.
+ ///
+ /// - Defaults to 15 seconds, matching ADO.NET's `Connect Timeout`. Pass
+ /// `None` to wait indefinitely. A zero duration is a degenerate bound
+ /// that fails as soon as the handshake would block.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use tiberius::Config;
+ /// # use std::time::Duration;
+ /// let mut config = Config::new();
+ /// // Fail fast if the handshake stalls.
+ /// config.handshake_timeout(Some(Duration::from_secs(5)));
+ /// ```
+ ///
+ /// [`Client::connect`]: crate::Client::connect
+ /// [`Error::Io`]: crate::error::Error::Io
+ pub fn handshake_timeout(&mut self, timeout: Option) {
+ self.handshake_timeout = timeout;
+ }
+
+ /// Returns the configured connection-handshake timeout, if any.
+ ///
+ /// See [`handshake_timeout`](Config::handshake_timeout).
+ pub fn get_handshake_timeout(&self) -> Option {
+ self.handshake_timeout
+ }
+
+ /// Sets a per-response deadline applied while reading command results
+ /// (`query`, `execute`, `simple_query`, the `bulk_insert` server
+ /// acknowledgement and `column_metadata`).
+ ///
+ /// # Semantics
+ ///
+ /// This bounds **each server round-trip**, not the total time to enumerate a
+ /// result stream. Query results are lazy, caller-driven streams: the timer
+ /// only runs while the client is actively waiting on the server for the next
+ /// chunk of the response, and it is **reset every time a token is
+ /// delivered**. A slow *consumer* (code that pauses between pulling rows)
+ /// therefore never trips it — only a stalled *server* does. Concretely, if
+ /// the gap between the client asking for more data and the server delivering
+ /// the next token exceeds the deadline, the stream yields an [`Error::Io`]
+ /// with [`std::io::ErrorKind::TimedOut`]. This covers both the
+ /// time-to-first-response and any mid-stream stall.
+ ///
+ /// The timer is runtime-agnostic (it does not depend on tokio or smol).
+ ///
+ /// Note: once a command times out, its connection is left mid-response and
+ /// out of sync with the server; drop the [`Client`] and open a new one (a
+ /// pool should discard the connection) rather than reuse it.
+ ///
+ /// - Defaults to 30 seconds, matching ADO.NET's `Command Timeout`. Pass
+ /// `None` to wait indefinitely. A zero duration is a degenerate bound
+ /// that trips on the first server round-trip that is not answered
+ /// immediately.
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use tiberius::Config;
+ /// # use std::time::Duration;
+ /// let mut config = Config::new();
+ /// // Fail a query if the server stops responding for 10s mid-result.
+ /// config.command_timeout(Some(Duration::from_secs(10)));
+ /// // Or wait forever (e.g. for a deliberately long-running batch):
+ /// config.command_timeout(None);
+ /// ```
+ ///
+ /// [`Client`]: crate::Client
+ /// [`Error::Io`]: crate::error::Error::Io
+ pub fn command_timeout(&mut self, timeout: Option) {
+ self.command_timeout = timeout;
+ }
+
+ /// Returns the configured per-response command timeout, if any.
+ ///
+ /// See [`command_timeout`](Config::command_timeout).
+ pub fn get_command_timeout(&self) -> Option {
+ self.command_timeout
+ }
+
+ /// Controls how malformed UTF-16 in NVARCHAR/NTEXT row values is handled.
+ ///
+ /// SQL Server stores `NVARCHAR`/`NCHAR`/`NTEXT` as unchecked UCS-2/UTF-16,
+ /// so a column can legitimately hold lone (unpaired) surrogates or other
+ /// sequences that are not valid Unicode. By default tiberius decodes these
+ /// values *strictly*: a malformed sequence aborts the row stream with an
+ /// error — [`Error::Protocol`] for NVARCHAR/NCHAR and [`Error::Utf16`] for
+ /// NTEXT (an odd, desynced byte length is always [`Error::Protocol`], in
+ /// both modes; see below). Strict decoding
+ /// is the safer default because it also surfaces framing desyncs (a decode
+ /// that silently "succeeds" on garbage can mask a misaligned read).
+ ///
+ /// Enabling this option makes decoding *lossy* for the NVARCHAR/NCHAR and
+ /// NTEXT text arms only: each invalid UTF-16 sequence is replaced with the
+ /// Unicode replacement character (`U+FFFD`, `�`) instead of erroring, so a
+ /// row containing bad Unicode stays readable.
+ ///
+ /// Scope and guarantees:
+ ///
+ /// - Only NVARCHAR/NCHAR (`string`) and NTEXT (`text`) decoding is affected.
+ /// `XML` columns are always decoded strictly. Code-page
+ /// (`VARCHAR`/`CHAR`/`TEXT`) columns are controlled independently by
+ /// [`Config::lossy_codepage_decoding`].
+ /// - Framing/length validation is always enforced: an odd byte length for a
+ /// UTF-16 value is still a protocol error in both modes, because it
+ /// indicates a desynced stream rather than merely bad Unicode.
+ ///
+ /// - Defaults to `false` (strict decoding).
+ ///
+ /// # Example
+ ///
+ /// ```
+ /// # use tiberius::Config;
+ /// let mut config = Config::new();
+ /// // Tolerate legacy rows that hold unchecked UCS-2 with lone surrogates.
+ /// config.lossy_utf16_decoding(true);
+ /// ```
+ ///
+ /// [`Error::Protocol`]: crate::error::Error::Protocol
+ /// [`Error::Utf16`]: crate::error::Error::Utf16
+ pub fn lossy_utf16_decoding(&mut self, lossy: bool) {
+ self.lossy_utf16_decoding = lossy;
+ }
+
+ /// Returns whether lossy UTF-16 decoding is enabled for NVARCHAR/NTEXT
+ /// values.
+ ///
+ /// See [`lossy_utf16_decoding`](Config::lossy_utf16_decoding).
+ pub fn get_lossy_utf16_decoding(&self) -> bool {
+ self.lossy_utf16_decoding
+ }
+
+ /// Enables lossy decoding for code-page character row values.
+ ///
+ /// Defaults to `false`: bytes that are invalid in the column's collation
+ /// cause an [`Error::Encoding`](crate::Error::Encoding) error. Enabling
+ /// this option replaces those sequences with `U+FFFD` so legacy rows
+ /// containing invalid bytes can still be read.
+ ///
+ /// Replacement follows `encoding_rs` / WHATWG decoding, not SQL Server's
+ /// `CONVERT(NVARCHAR)` behavior. For example, under `Chinese_PRC_CI_AS`,
+ /// bytes `61 81 20 62` decode to `"a\u{fffd} b"` and a lone `FF` decodes
+ /// to `"\u{fffd}"`; the server may instead use `?` or a private-use character.
+ /// CP437 and CP850 define every byte, so this option does not change their
+ /// decoded values.
+ ///
+ /// Applies to `CHAR`, `VARCHAR` (including `VARCHAR(MAX)`), `TEXT`, and
+ /// `CHAR`/`VARCHAR` values inside `SQL_VARIANT`. The column's declared
+ /// collation always determines the encoding; BOM-like bytes are not
+ /// stripped or used to select another encoding. Unknown collations and
+ /// malformed protocol lengths still produce errors.
+ ///
+ /// Unicode values are controlled independently by
+ /// [`Config::lossy_utf16_decoding`]. XML, metadata, protocol strings, and
+ /// outgoing character encoding are unaffected.
+ ///
+ /// ```
+ /// let mut config = tiberius::Config::new();
+ /// config.lossy_codepage_decoding(true);
+ /// ```
+ pub fn lossy_codepage_decoding(&mut self, lossy: bool) {
+ self.lossy_codepage_decoding = lossy;
+ }
+
+ /// Returns whether lossy code-page row decoding is enabled.
+ ///
+ /// See [`Config::lossy_codepage_decoding`] for the scope of this option.
+ pub fn get_lossy_codepage_decoding(&self) -> bool {
+ self.lossy_codepage_decoding
+ }
+
+ /// Supplies a client certificate and private key used to authenticate the
+ /// client to the server during the TLS handshake (mutual TLS). This is
+ /// required for TDS 8.0 "strict" connections that use client-certificate
+ /// authentication (`ENCRYPT_CLIENT_CERT`), and may also be used with the
+ /// classic (pre-8.0) TLS handshake when the server requests a client
+ /// certificate.
+ ///
+ /// Both arguments are paths to files:
+ ///
+ /// - `cert`: the client certificate, PEM (`.pem`/`.crt`) or DER (`.der`).
+ /// - `key`: the matching private key, PEM (`.pem`/`.key`) or DER (`.der`,
+ /// PKCS#8).
+ ///
+ /// Backend support:
+ ///
+ /// - `rustls`: PEM and DER certificate/key files.
+ /// - `native-tls`: PEM certificate + PEM PKCS#8 key only (DER files are
+ /// rejected at connect time; use [`client_certificate_pkcs12`] for a
+ /// bundled DER identity).
+ /// - `vendored-openssl` (opentls): does not support separate certificate/key
+ /// files; use [`client_certificate_pkcs12`] instead.
+ ///
+ /// - Defaults to no client certificate.
+ ///
+ /// [`client_certificate_pkcs12`]: Config::client_certificate_pkcs12
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ #[cfg_attr(
+ docsrs,
+ doc(cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))
+ )]
+ pub fn client_certificate(&mut self, cert: impl Into, key: impl Into) {
+ self.client_cert = Some(ClientCertificate {
+ source: ClientCertSource::CertAndKey {
+ cert: cert.into(),
+ key: key.into(),
+ },
+ });
+ }
+
+ /// Supplies a client identity from a PKCS#12 / PFX bundle (certificate,
+ /// private key and any chain, encrypted with `password`) used to
+ /// authenticate the client to the server during the TLS handshake (mutual
+ /// TLS).
+ ///
+ /// Only supported by the `native-tls` and `vendored-openssl` backends; the
+ /// `rustls` backend rejects PKCS#12 identities at connect time (supply
+ /// separate PEM/DER files via [`client_certificate`] instead).
+ ///
+ /// - Defaults to no client certificate.
+ ///
+ /// [`client_certificate`]: Config::client_certificate
+ #[cfg(any(feature = "native-tls", feature = "vendored-openssl"))]
+ #[cfg_attr(
+ docsrs,
+ doc(cfg(any(feature = "native-tls", feature = "vendored-openssl")))
+ )]
+ pub fn client_certificate_pkcs12(
+ &mut self,
+ path: impl Into,
+ password: impl Into,
+ ) {
+ self.client_cert = Some(ClientCertificate {
+ source: ClientCertSource::Pkcs12 {
+ path: path.into(),
+ password: crate::client::auth::secret_from_string(password.into()),
+ },
+ });
+ }
+
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ pub(crate) fn get_client_certificate(&self) -> Option<&ClientCertificate> {
+ self.client_cert.as_ref()
}
pub(crate) fn get_host(&self) -> &str {
@@ -178,6 +833,17 @@ impl Config {
.unwrap_or("localhost")
}
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ pub(crate) fn get_hostname_in_certificate(&self) -> &str {
+ self.hostname_in_certificate
+ .as_deref()
+ .unwrap_or_else(|| self.get_host())
+ }
+
pub(crate) fn get_port(&self) -> u16 {
match (self.port, self.instance_name.as_ref()) {
// A user-defined port, we must use that.
@@ -210,8 +876,60 @@ impl Config {
/// |`database`|``|The name of the database.|
/// |`TrustServerCertificate`|`true`,`false`,`yes`,`no`|Specifies whether the driver trusts the server certificate when connecting using TLS. Cannot be used toghether with `TrustServerCertificateCA`|
/// |`TrustServerCertificateCA`|``|Path to a `pem`, `crt` or `der` certificate file. Cannot be used together with `TrustServerCertificate`|
- /// |`encrypt`|`true`,`false`,`yes`,`no`,`DANGER_PLAINTEXT`|Specifies whether the driver uses TLS to encrypt communication.|
+ /// |`encrypt`|`strict`,`true`,`false`,`yes`,`no`,`DANGER_PLAINTEXT`|Specifies whether the driver uses TLS to encrypt communication. `strict` (TDS 8.0) requires the `tds80` feature.|
/// |`Application Name`, `ApplicationName`|``|Sets the application name for the connection.|
+ /// |`HostNameInCertificate`, `HostName In Certificate`|``|The hostname the server certificate is validated against. Defaults to the value of the `Server` keyword (host).|
+ /// |`WorkstationID`, `Workstation ID`|``|The client / workstation name reported to the server.|
+ /// |`MultiSubnetFailover`|`true`,`false`,`yes`,`no`|When enabled, connections are attempted in parallel to all IP addresses the server resolves to, and the first to succeed is used.|
+ ///
+ /// # Parsing model and special characters
+ ///
+ /// Pairs are separated by `;`, and each pair is split on its **first** `=`,
+ /// so a value may itself contain `=`: a base64 or otherwise generated
+ /// password with `=` padding (for example `password=Zm9vYmFy==`) parses
+ /// without any quoting.
+ ///
+ /// Characters that are still structural inside a *value* — `;`, a leading
+ /// `'`, `"` or `{`, and any leading or trailing spaces you want to keep —
+ /// must be quoted. Wrap the value in single quotes, double quotes, or braces
+ /// (`{...}`), choosing a style the value does not itself contain, and embed
+ /// the enclosing quote by doubling it (`"a""b"` → `a"b`):
+ ///
+ /// - `password='p@ss;word=42'`
+ /// - `password="p@ss;word=42"`
+ /// - `password={p@ss;word=42}`
+ ///
+ /// Do **not** URL-encode the value: `%24` is sent to the server literally,
+ /// not decoded back to `$`, which is a common cause of login failures.
+ /// A bare `}` needs no quoting, but brace quoting cannot hold a literal `}`
+ /// (there is no `}}` doubling), so a value that must be quoted *and*
+ /// contains a `}` has to use single or double quotes. Only ASCII values are
+ /// accepted by the parser.
+ ///
+ /// tiberius parses a **superset** of ADO.NET's documented rules: the ADO.NET
+ /// semantics above, plus `{...}` brace quoting as an extension (braces are
+ /// not part of ADO.NET itself). One consequence of that extension: because a
+ /// value that *begins* with `{` is read as brace-quoted, a value whose
+ /// literal first character is `{` must instead be single- or double-quoted
+ /// (e.g. `password='{literal-braces}'`).
+ ///
+ /// For non-ASCII passwords, or to avoid escaping entirely, build the
+ /// [`Config`] programmatically — the values are passed verbatim:
+ ///
+ /// ```
+ /// # use tiberius::{Config, AuthMethod};
+ /// // Quoted in an ADO.NET string: the `;`, `=` and `{}` are preserved.
+ /// let _config = Config::from_ado_string(
+ /// r#"server=tcp:localhost,1433;user=sa;password='p@ss;w{}rd=42'"#,
+ /// )?;
+ ///
+ /// // The programmatic API needs no escaping and accepts any value.
+ /// let mut config = Config::new();
+ /// config.host("localhost");
+ /// config.port(1433);
+ /// config.authentication(AuthMethod::sql_server("sa", "p@ss;w{}rd=42"));
+ /// # Ok::<(), tiberius::error::Error>(())
+ /// ```
///
/// [ADO.NET connection string]: https://docs.microsoft.com/en-us/dotnet/framework/data/adonet/connection-strings
pub fn from_ado_string(s: &str) -> crate::Result {
@@ -223,6 +941,20 @@ impl Config {
///
/// See [`from_ado_string`] method for supported parameters.
///
+ /// # Special characters in values
+ ///
+ /// The JDBC parser understands only brace quoting: wrap a value that
+ /// contains `;`, `=`, `:`, `{`, `\`, `/`, `[` or `]` in braces, e.g.
+ /// `password={p@ss;word}`.
+ /// Unlike ADO.NET, single and double quotes are **not** escape characters
+ /// here — they are ordinary value characters, and spaces are kept verbatim
+ /// without quoting (JDBC does not trim). Brace quoting cannot hold a literal
+ /// `}` (there is no `}}` doubling), though a bare `}` needs no quoting. Do
+ /// not URL-encode values, and note that only ASCII is accepted.
+ /// For non-ASCII values, or to avoid escaping entirely, build the
+ /// [`Config`] programmatically as shown in [`from_ado_string`]; the values
+ /// are passed verbatim.
+ ///
/// [JDBC connection string]: https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15
/// [`from_ado_string`]: #method.from_ado_string
pub fn from_jdbc_string(s: &str) -> crate::Result {
@@ -257,65 +989,407 @@ impl Config {
builder.application_name(name);
}
- if s.trust_cert()? {
+ let trust_cert = s.trust_cert()?;
+ let trust_cert_ca = s.trust_cert_ca();
+
+ // `TrustServerCertificate` and `TrustServerCertificateCA` are mutually
+ // exclusive. Detect the conflict here and return an error instead of
+ // letting `trust_cert`/`trust_cert_ca` panic on external input.
+ if trust_cert && trust_cert_ca.is_some() {
+ return Err(crate::Error::Conversion(
+ "'TrustServerCertificate' and 'TrustServerCertificateCA' are \
+ mutually exclusive; specify only one"
+ .into(),
+ ));
+ }
+
+ if trust_cert {
builder.trust_cert();
}
- if let Some(ca) = s.trust_cert_ca() {
+ if let Some(ca) = trust_cert_ca {
builder.trust_cert_ca(ca);
}
+ if let Some(hostname_in_cert) = s.hostname_in_certificate() {
+ builder.hostname_in_certificate(hostname_in_cert);
+ }
+
builder.encryption(s.encrypt()?);
builder.readonly(s.readonly());
+ if let Some(client_name) = s.client_name() {
+ builder.client_name(client_name);
+ }
+ builder.multi_subnet_failover(s.multi_subnet_failover()?);
+
Ok(builder)
}
}
-pub(crate) struct ServerDefinition {
- host: Option,
- port: Option,
- instance: Option,
+/// A builder for [`Config`], providing an ergonomic, chainable way to
+/// construct a connection configuration.
+///
+/// Create a builder with [`Config::builder`], set the desired options by
+/// calling its methods (each returns the builder to allow chaining) and
+/// finalize it with [`build`].
+///
+/// # Example
+///
+/// ```
+/// # use tiberius::{Config, AuthMethod, EncryptionLevel};
+/// let config = Config::builder()
+/// .host("localhost")
+/// .port(1433)
+/// .database("master")
+/// .encryption(EncryptionLevel::NotSupported)
+/// .authentication(AuthMethod::sql_server("SA", ""))
+/// .build();
+/// ```
+///
+/// [`Config`]: struct.Config.html
+/// [`Config::builder`]: struct.Config.html#method.builder
+/// [`build`]: struct.ConfigBuilder.html#method.build
+#[derive(Clone, Debug)]
+pub struct ConfigBuilder {
+ inner: Config,
}
-pub(crate) trait ConfigString {
- fn dict(&self) -> &HashMap;
-
- fn server(&self) -> crate::Result;
-
- fn authentication(&self) -> crate::Result {
- let user = self
- .dict()
- .get("uid")
- .or_else(|| self.dict().get("username"))
- .or_else(|| self.dict().get("user"))
- .or_else(|| self.dict().get("user id"))
- .map(|s| s.as_str());
+impl ConfigBuilder {
+ /// A host or ip address to connect to.
+ ///
+ /// - Defaults to `localhost`.
+ pub fn host(mut self, host: impl ToString) -> Self {
+ self.inner.host = Some(host.to_string());
+ self
+ }
- let pw = self
- .dict()
- .get("password")
- .or_else(|| self.dict().get("pwd"))
- .map(|s| s.as_str());
+ /// The server port.
+ ///
+ /// - Defaults to `1433`.
+ pub fn port(mut self, port: u16) -> Self {
+ self.inner.port = Some(port);
+ self
+ }
- match self
- .dict()
- .get("integratedsecurity")
- .or_else(|| self.dict().get("integrated security"))
- {
- #[cfg(all(windows, feature = "winauth"))]
- Some(val) if val.to_lowercase() == "sspi" || Self::parse_bool(val)? => match (user, pw)
- {
- (None, None) => Ok(AuthMethod::Integrated),
- _ => Ok(AuthMethod::windows(user.unwrap_or(""), pw.unwrap_or(""))),
- },
- #[cfg(feature = "integrated-auth-gssapi")]
- Some(val) if val.to_lowercase() == "sspi" || Self::parse_bool(val)? => {
- Ok(AuthMethod::Integrated)
- }
- _ => Ok(AuthMethod::sql_server(user.unwrap_or(""), pw.unwrap_or(""))),
- }
+ /// The database to connect to.
+ ///
+ /// - Defaults to `master`.
+ pub fn database(mut self, database: impl ToString) -> Self {
+ self.inner.database = Some(database.to_string());
+ self
+ }
+
+ /// The instance name as defined in the SQL Browser. Only available on
+ /// Windows platforms.
+ ///
+ /// If specified, the port is replaced with the value returned from the
+ /// browser.
+ ///
+ /// - Defaults to no name specified.
+ pub fn instance_name(mut self, name: impl ToString) -> Self {
+ self.inner.instance_name = Some(name.to_string());
+ self
+ }
+
+ /// Sets the application name to the connection, queryable with the
+ /// `APP_NAME()` command.
+ ///
+ /// - Defaults to no name specified.
+ pub fn application_name(mut self, name: impl ToString) -> Self {
+ self.inner.application_name = Some(name.to_string());
+ self
+ }
+
+ /// Set the preferred encryption level.
+ ///
+ /// - With a TLS backend enabled (any of the `rustls`, `native-tls`, or
+ /// `vendored-openssl` features), defaults to `Required`.
+ /// - Without a TLS backend, defaults to `NotSupported`.
+ pub fn encryption(mut self, encryption: EncryptionLevel) -> Self {
+ self.inner.encryption = encryption;
+ self
+ }
+
+ /// If set, the server certificate will not be validated and it is accepted
+ /// as-is.
+ ///
+ /// On production setting, the certificate should be added to the local key
+ /// storage (or use `trust_cert_ca` instead), using this setting is potentially dangerous.
+ ///
+ /// # Panics
+ /// Will panic in case `trust_cert_ca` was called before.
+ ///
+ /// - Defaults to `default`, meaning server certificate is validated against system-truststore.
+ pub fn trust_cert(mut self) -> Self {
+ self.inner.trust_cert();
+ self
+ }
+
+ /// Trust an additional CA certificate (from a file), in addition to the base
+ /// trust anchors. Accumulates across calls.
+ ///
+ /// See [`Config::trust_cert_ca`] for details.
+ ///
+ /// # Panics
+ /// Will panic in case `trust_cert` was called before.
+ pub fn trust_cert_ca(mut self, path: impl ToString) -> Self {
+ self.inner.trust_cert_ca(path);
+ self
+ }
+
+ /// Trust additional CA certificates supplied as in-memory bytes (a
+ /// PEM/DER bundle), in addition to the base trust anchors. Accumulates
+ /// across calls.
+ ///
+ /// See [`Config::trust_cert_ca_bundle`] for details.
+ ///
+ /// # Panics
+ /// Will panic in case `trust_cert` was called before.
+ pub fn trust_cert_ca_bundle(mut self, bundle: impl Into>) -> Self {
+ self.inner.trust_cert_ca_bundle(bundle);
+ self
+ }
+
+ /// Use the compiled-in Mozilla root CA snapshot as the base trust anchors
+ /// (rustls only).
+ ///
+ /// See [`Config::trust_webpki_roots`] for details and the staleness caveat.
+ ///
+ /// # Panics
+ /// Will panic in case `trust_cert` was called before.
+ #[cfg(feature = "rustls-webpki-roots")]
+ #[cfg_attr(docsrs, doc(cfg(feature = "rustls-webpki-roots")))]
+ pub fn trust_webpki_roots(mut self) -> Self {
+ self.inner.trust_webpki_roots();
+ self
+ }
+
+ /// Sets the authentication method.
+ ///
+ /// - Defaults to `None`.
+ pub fn authentication(mut self, auth: AuthMethod) -> Self {
+ self.inner.auth = auth;
+ self
+ }
+
+ /// Sets ApplicationIntent readonly.
+ ///
+ /// - Defaults to `false`.
+ pub fn readonly(mut self, readonly: bool) -> Self {
+ self.inner.readonly = readonly;
+ self
+ }
+
+ /// Sets an upper bound on how long the connection handshake may take.
+ ///
+ /// See [`Config::handshake_timeout`] for details. Pass `None` to wait
+ /// indefinitely.
+ ///
+ /// - Defaults to 15 seconds.
+ pub fn handshake_timeout(mut self, timeout: Option) -> Self {
+ self.inner.handshake_timeout = timeout;
+ self
+ }
+
+ /// Sets a per-response deadline applied while reading command results.
+ ///
+ /// See [`Config::command_timeout`] for the exact (per-round-trip)
+ /// semantics. Pass `None` to wait indefinitely.
+ ///
+ /// - Defaults to 30 seconds.
+ pub fn command_timeout(mut self, timeout: Option) -> Self {
+ self.inner.command_timeout = timeout;
+ self
+ }
+
+ /// Enables lossy UTF-16 decoding for NVARCHAR/NTEXT row values.
+ ///
+ /// See [`Config::lossy_utf16_decoding`] for the exact semantics (strict is
+ /// the default; enabling replaces invalid UTF-16 with `U+FFFD` for the
+ /// NVARCHAR/NCHAR and NTEXT arms only).
+ ///
+ /// - Defaults to `false`.
+ pub fn lossy_utf16_decoding(mut self, lossy: bool) -> Self {
+ self.inner.lossy_utf16_decoding = lossy;
+ self
+ }
+
+ /// Enables lossy code-page row decoding. Defaults to `false`.
+ ///
+ /// See [`Config::lossy_codepage_decoding`] for the scope of this option.
+ pub fn lossy_codepage_decoding(mut self, lossy: bool) -> Self {
+ self.inner.lossy_codepage_decoding = lossy;
+ self
+ }
+
+ /// Supplies a client certificate and private key for mutual TLS.
+ ///
+ /// See [`Config::client_certificate`] for details and backend support.
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ #[cfg_attr(
+ docsrs,
+ doc(cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))
+ )]
+ pub fn client_certificate(mut self, cert: impl Into, key: impl Into) -> Self {
+ self.inner.client_certificate(cert, key);
+ self
+ }
+
+ /// Supplies a client identity from a PKCS#12 / PFX bundle for mutual TLS.
+ ///
+ /// See [`Config::client_certificate_pkcs12`] for details and backend
+ /// support.
+ #[cfg(any(feature = "native-tls", feature = "vendored-openssl"))]
+ #[cfg_attr(
+ docsrs,
+ doc(cfg(any(feature = "native-tls", feature = "vendored-openssl")))
+ )]
+ pub fn client_certificate_pkcs12(
+ mut self,
+ path: impl Into,
+ password: impl Into,
+ ) -> Self {
+ self.inner.client_certificate_pkcs12(path, password);
+ self
+ }
+
+ /// Produces the finalized [`Config`] from this builder.
+ ///
+ /// [`Config`]: struct.Config.html
+ pub fn build(self) -> Config {
+ self.inner
+ }
+}
+
+impl From for ConfigBuilder {
+ fn from(config: Config) -> Self {
+ ConfigBuilder { inner: config }
+ }
+}
+
+impl From for Config {
+ fn from(builder: ConfigBuilder) -> Self {
+ builder.inner
+ }
+}
+
+pub(crate) struct ServerDefinition {
+ host: Option,
+ port: Option,
+ instance: Option,
+}
+
+/// Wrap a [`connection_string`] parse failure with actionable guidance.
+///
+/// The underlying ADO.NET / JDBC parser fails with a terse, low-level message
+/// (for example "key-value pairs must be joined by a =") when a value contains
+/// an unescaped special character such as `;`, `=` or `{` — a very common
+/// cause of "cannot connect" reports for passwords with special characters.
+/// Append a hint describing how to quote such values so the message is
+/// self-explanatory. `quoting` spells out the escaping styles the specific
+/// parser accepts (they differ between ADO.NET and JDBC) and `docs` names the
+/// constructor whose rustdoc carries the full rules and the programmatic-build
+/// workaround.
+///
+/// The hint is phrased conditionally because `connection_string::Error` is an
+/// opaque string with no error kind, so this wrapper cannot tell a quoting
+/// failure apart from an unrelated one (a bad port, a mistyped sub-protocol,
+/// …); "if a value … contains a special character" keeps the guidance honest
+/// for every failure while still solving the common quoting case.
+fn connection_string_error(
+ err: connection_string::Error,
+ quoting: &str,
+ docs: &str,
+) -> crate::Error {
+ // `connection_string::Error`'s `Display` already prefixes `Conversion
+ // error: `; strip it so wrapping the text in `Error::Conversion` does not
+ // duplicate the prefix.
+ let err = err.to_string();
+ let detail = err.strip_prefix("Conversion error: ").unwrap_or(&err);
+ hinted_conversion_error(detail, quoting, docs)
+}
+
+/// Builds a `Conversion` error from a terse parser reason plus the shared
+/// quoting hint, so every connection-string failure points the caller at the
+/// escaping options and the programmatic `Config` API.
+fn hinted_conversion_error(detail: &str, quoting: &str, docs: &str) -> crate::Error {
+ crate::Error::Conversion(
+ format!(
+ "{detail}. hint: if a value such as a password contains a special \
+ character (for example `;`, `=` or `{{`), it must be quoted — \
+ {quoting}. Do not URL-encode the value (`%24` is sent literally, \
+ not decoded to `$`). Non-ASCII values are not accepted by the \
+ connection-string parser; build the `Config` programmatically \
+ (see `{docs}`) to pass any value without escaping."
+ )
+ .into(),
+ )
+}
+
+pub(crate) trait ConfigString {
+ fn dict(&self) -> &HashMap;
+
+ fn server(&self) -> crate::Result;
+
+ fn authentication(&self) -> crate::Result {
+ let user = self
+ .dict()
+ .get("uid")
+ .or_else(|| self.dict().get("username"))
+ .or_else(|| self.dict().get("user"))
+ .or_else(|| self.dict().get("user id"))
+ .map(|s| s.as_str());
+
+ let pw = self
+ .dict()
+ .get("password")
+ .or_else(|| self.dict().get("pwd"))
+ .map(|s| s.as_str());
+
+ match self
+ .dict()
+ .get("integratedsecurity")
+ .or_else(|| self.dict().get("integrated security"))
+ {
+ #[cfg(all(windows, feature = "winauth"))]
+ Some(val) if Self::is_sspi_or_truthy(val)? => match (user, pw) {
+ (None, None) => Ok(AuthMethod::Integrated),
+ _ => Ok(AuthMethod::windows(user.unwrap_or(""), pw.unwrap_or(""))),
+ },
+ // On Unix with `sspi-rs`, `IntegratedSecurity=SSPI` (or a truthy
+ // value) uses NTLM when a username/password is supplied, and falls
+ // back to Kerberos (`Integrated`) only if `integrated-auth-gssapi`
+ // is also enabled and no credentials are given.
+ #[cfg(all(unix, feature = "sspi-rs"))]
+ Some(val) if Self::is_sspi_or_truthy(val)? => match (user, pw) {
+ (Some(user), Some(pw)) => Ok(AuthMethod::windows(user, pw)),
+ #[cfg(feature = "integrated-auth-gssapi")]
+ (None, None) => Ok(AuthMethod::Integrated),
+ _ => Ok(AuthMethod::windows(user.unwrap_or(""), pw.unwrap_or(""))),
+ },
+ #[cfg(all(
+ feature = "integrated-auth-gssapi",
+ not(all(unix, feature = "sspi-rs"))
+ ))]
+ Some(val) if Self::is_sspi_or_truthy(val)? => Ok(AuthMethod::Integrated),
+ // Default (no integrated security): SQL Server authentication. A
+ // missing user or password is intentionally passed through as an
+ // empty string rather than rejected here — validation of the
+ // credentials is deferred to the server LOGIN response, which
+ // returns a precise authentication error. Failing early would also
+ // break the (unusual but valid) case of an empty SQL login.
+ _ => Ok(AuthMethod::sql_server(user.unwrap_or(""), pw.unwrap_or(""))),
+ }
}
fn database(&self) -> Option {
@@ -346,6 +1420,20 @@ pub(crate) trait ConfigString {
.map(|ca| ca.to_string())
}
+ fn hostname_in_certificate(&self) -> Option {
+ self.dict()
+ .get("hostnameincertificate")
+ .or_else(|| self.dict().get("hostname in certificate"))
+ .map(|host| host.to_string())
+ }
+
+ fn client_name(&self) -> Option {
+ self.dict()
+ .get("workstationid")
+ .or_else(|| self.dict().get("workstation id"))
+ .map(|name| name.to_string())
+ }
+
#[cfg(any(
feature = "rustls",
feature = "native-tls",
@@ -358,9 +1446,20 @@ pub(crate) trait ConfigString {
Ok(true) => Ok(EncryptionLevel::Required),
Ok(false) => Ok(EncryptionLevel::Off),
Err(_) if val == "DANGER_PLAINTEXT" => Ok(EncryptionLevel::NotSupported),
+ Err(_) if val.eq_ignore_ascii_case("strict") && cfg!(feature = "tds80") => {
+ Ok(EncryptionLevel::Strict)
+ }
+ Err(_) if val.eq_ignore_ascii_case("strict") => Err(crate::Error::Conversion(
+ "encrypt=strict requires the crate's `tds80` feature to be enabled".into(),
+ )),
Err(e) => Err(e),
})
- .unwrap_or(Ok(EncryptionLevel::Off))
+ // When the `encrypt` keyword is omitted, default to requiring
+ // encryption — matching `Config::default()` and modern ADO.NET
+ // (`Encrypt=Mandatory`). Callers who want an unencrypted connection
+ // must opt out explicitly with `encrypt=false` (or
+ // `encrypt=DANGER_PLAINTEXT`).
+ .unwrap_or(Ok(EncryptionLevel::Required))
}
#[cfg(not(any(
@@ -369,7 +1468,38 @@ pub(crate) trait ConfigString {
feature = "vendored-openssl"
)))]
fn encrypt(&self) -> crate::Result {
- Ok(EncryptionLevel::NotSupported)
+ // Security (#305): a no-TLS build cannot encrypt, so an explicit request
+ // to do so must fail loudly rather than silently downgrade to plaintext.
+ // Token classification follows the with-TLS `encrypt()`: the values that
+ // mean "encryption on" (`true`/`yes`/`strict`) become the TLS-missing
+ // error, while opting out (`false`/`no`/`DANGER_PLAINTEXT`) and an
+ // omitted keyword still resolve to `NotSupported`. (`strict` reports the
+ // missing backend rather than the with-TLS `tds80`-required hint — a
+ // TLS backend is the more fundamental thing it needs here.)
+ let Some(val) = self.dict().get("encrypt") else {
+ return Ok(EncryptionLevel::NotSupported);
+ };
+
+ match Self::parse_bool(val) {
+ Ok(false) => Ok(EncryptionLevel::NotSupported),
+ Err(_) if val == "DANGER_PLAINTEXT" => Ok(EncryptionLevel::NotSupported),
+ Ok(true) => Err(Self::tls_backend_missing()),
+ Err(_) if val.eq_ignore_ascii_case("strict") => Err(Self::tls_backend_missing()),
+ Err(e) => Err(e),
+ }
+ }
+
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn tls_backend_missing() -> crate::Error {
+ crate::Error::Tls(
+ "encryption was requested (`encrypt=...`) but the crate was compiled without a TLS \
+ backend; enable one of the `native-tls`, `rustls` or `vendored-openssl` features."
+ .to_string(),
+ )
}
fn parse_bool>(v: T) -> crate::Result {
@@ -382,10 +1512,683 @@ pub(crate) trait ConfigString {
}
}
+ /// An `IntegratedSecurity` connection-string value selects Windows/SSPI auth
+ /// when it is the literal `SSPI` (case-insensitive) or a truthy boolean.
+ /// Uses `eq_ignore_ascii_case` so the `SSPI` comparison does not allocate.
+ ///
+ /// Only referenced by the integrated-auth match arms, which are themselves
+ /// feature-gated; gate the helper identically so builds without any
+ /// integrated-auth backend do not warn about it being unused.
+ #[cfg(any(
+ all(windows, feature = "winauth"),
+ all(unix, feature = "sspi-rs"),
+ feature = "integrated-auth-gssapi"
+ ))]
+ fn is_sspi_or_truthy>(v: T) -> crate::Result {
+ let v = v.as_ref();
+ Ok(v.eq_ignore_ascii_case("sspi") || Self::parse_bool(v)?)
+ }
+
fn readonly(&self) -> bool {
self.dict()
.get("applicationintent")
- .filter(|val| *val == "ReadOnly")
+ .filter(|val| val.trim().eq_ignore_ascii_case("ReadOnly"))
.is_some()
}
+
+ fn multi_subnet_failover(&self) -> crate::Result {
+ self.dict()
+ .get("multisubnetfailover")
+ .map(Self::parse_bool)
+ .unwrap_or(Ok(false))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ #[cfg(any(feature = "native-tls", feature = "vendored-openssl"))]
+ use secrecy::ExposeSecret;
+
+ #[test]
+ fn config_debug_redacts_connection_password() {
+ // The connection password lives inside `auth: AuthMethod`; the whole
+ // `Config` Debug must never print it.
+ let config = Config::builder()
+ .authentication(AuthMethod::sql_server("SA", "conn-str-secret"))
+ .build();
+
+ let dbg = format!("{config:?}");
+ assert!(
+ !dbg.contains("conn-str-secret"),
+ "connection password leaked in Config Debug: {dbg}"
+ );
+ assert!(dbg.contains("REDACTED"), "password not redacted: {dbg}");
+ }
+
+ #[test]
+ fn config_builder_constructs_config() {
+ let config = Config::builder()
+ .host("db.example.com")
+ .port(4433)
+ .database("northwind")
+ .application_name("my-app")
+ .authentication(AuthMethod::sql_server("SA", "secret"))
+ .readonly(true)
+ .build();
+
+ assert_eq!("db.example.com", config.get_host());
+ assert_eq!(4433, config.get_port());
+ assert_eq!("db.example.com:4433", config.get_addr());
+ assert_eq!(Some("northwind"), config.database.as_deref());
+ assert_eq!(Some("my-app"), config.application_name.as_deref());
+ assert!(config.readonly);
+ assert!(matches!(config.auth, AuthMethod::SqlServer(_)));
+ assert!(config.trust.is_default());
+ }
+
+ #[test]
+ fn config_builder_roundtrips_via_from() {
+ let config = Config::builder().host("localhost").port(1433).build();
+ let builder: ConfigBuilder = config.into();
+ let config = builder.database("master").build();
+
+ assert_eq!("localhost:1433", config.get_addr());
+ assert_eq!(Some("master"), config.database.as_deref());
+ }
+
+ #[test]
+ fn config_from_builder_carries_builder_settings() {
+ // `From` must return the built inner config, not a default.
+ let config: Config = Config::builder().host("db.internal").port(2020).into();
+ assert_eq!("db.internal", config.get_host());
+ assert_eq!(2020, config.get_port());
+ }
+
+ #[test]
+ fn handshake_timeout_defaults_to_fifteen_seconds() {
+ // A sensible, ADO.NET-matching default so a stalled handshake surfaces
+ // an error instead of hanging forever.
+ let config = Config::new();
+ assert_eq!(
+ config.get_handshake_timeout(),
+ Some(Duration::from_secs(15))
+ );
+ }
+
+ #[test]
+ fn handshake_timeout_setter_roundtrips() {
+ // Table-driven over the values a caller can set, including opting out.
+ let cases = [
+ Some(Duration::from_millis(1)),
+ Some(Duration::from_secs(30)),
+ None,
+ ];
+ for want in cases {
+ let mut config = Config::new();
+ config.handshake_timeout(want);
+ assert_eq!(config.get_handshake_timeout(), want, "for {want:?}");
+ }
+ }
+
+ #[test]
+ fn config_builder_sets_handshake_timeout() {
+ let config = Config::builder()
+ .handshake_timeout(Some(Duration::from_secs(3)))
+ .build();
+ assert_eq!(config.get_handshake_timeout(), Some(Duration::from_secs(3)));
+
+ // And can disable it.
+ let config = Config::builder().handshake_timeout(None).build();
+ assert_eq!(config.get_handshake_timeout(), None);
+ }
+
+ #[test]
+ fn config_builder_defaults_handshake_timeout() {
+ // The builder starts from `Config::default()`, so it inherits the bound.
+ let config = Config::builder().build();
+ assert_eq!(
+ config.get_handshake_timeout(),
+ Some(Duration::from_secs(15))
+ );
+ }
+
+ #[test]
+ fn command_timeout_defaults_to_thirty_seconds() {
+ // ADO.NET-matching default so a mid-result server stall surfaces an
+ // error instead of hanging forever.
+ let config = Config::new();
+ assert_eq!(config.get_command_timeout(), Some(Duration::from_secs(30)));
+ }
+
+ #[test]
+ fn command_timeout_setter_roundtrips() {
+ let cases = [
+ Some(Duration::from_millis(1)),
+ Some(Duration::from_secs(60)),
+ None,
+ ];
+ for want in cases {
+ let mut config = Config::new();
+ config.command_timeout(want);
+ assert_eq!(config.get_command_timeout(), want, "for {want:?}");
+ }
+ }
+
+ #[test]
+ fn config_builder_sets_command_timeout() {
+ let config = Config::builder()
+ .command_timeout(Some(Duration::from_secs(7)))
+ .build();
+ assert_eq!(config.get_command_timeout(), Some(Duration::from_secs(7)));
+
+ let config = Config::builder().command_timeout(None).build();
+ assert_eq!(config.get_command_timeout(), None);
+ }
+
+ #[test]
+ fn config_builder_defaults_command_timeout() {
+ let config = Config::builder().build();
+ assert_eq!(config.get_command_timeout(), Some(Duration::from_secs(30)));
+ }
+
+ #[test]
+ fn lossy_utf16_decoding_defaults_to_false() {
+ let config = Config::new();
+ assert!(!config.get_lossy_utf16_decoding());
+ }
+
+ #[test]
+ fn lossy_codepage_decoding_defaults_and_setter() {
+ let mut config = Config::new();
+ assert!(!config.get_lossy_codepage_decoding());
+ config.lossy_codepage_decoding(true);
+ assert!(config.get_lossy_codepage_decoding());
+ assert!(!config.get_lossy_utf16_decoding());
+ config.lossy_utf16_decoding(true);
+ config.lossy_codepage_decoding(false);
+ assert!(!config.get_lossy_codepage_decoding());
+ assert!(config.get_lossy_utf16_decoding());
+ }
+
+ #[test]
+ fn config_builder_sets_lossy_codepage_decoding() {
+ assert!(!Config::builder().build().get_lossy_codepage_decoding());
+ let config = Config::builder().lossy_codepage_decoding(true).build();
+ assert!(config.get_lossy_codepage_decoding());
+ assert!(!config.get_lossy_utf16_decoding());
+ }
+
+ #[test]
+ fn lossy_utf16_decoding_setter_roundtrips() {
+ let mut config = Config::new();
+ config.lossy_utf16_decoding(true);
+ assert!(config.get_lossy_utf16_decoding());
+ config.lossy_utf16_decoding(false);
+ assert!(!config.get_lossy_utf16_decoding());
+ }
+
+ #[test]
+ fn config_builder_sets_lossy_utf16_decoding() {
+ let config = Config::builder().lossy_utf16_decoding(true).build();
+ assert!(config.get_lossy_utf16_decoding());
+ }
+
+ #[test]
+ fn config_builder_defaults_lossy_utf16_decoding() {
+ let config = Config::builder().build();
+ assert!(!config.get_lossy_utf16_decoding());
+ }
+
+ #[test]
+ fn timeouts_are_independent() {
+ // The two knobs must not alias one another.
+ let mut config = Config::new();
+ config.handshake_timeout(Some(Duration::from_secs(1)));
+ config.command_timeout(Some(Duration::from_secs(2)));
+ assert_eq!(config.get_handshake_timeout(), Some(Duration::from_secs(1)));
+ assert_eq!(config.get_command_timeout(), Some(Duration::from_secs(2)));
+ }
+
+ #[test]
+ fn get_packet_size_reflects_the_set_value() {
+ let mut config = Config::new();
+ assert_eq!(config.get_packet_size(), None);
+ config.packet_size(8192);
+ assert_eq!(config.get_packet_size(), Some(8192));
+ }
+
+ #[test]
+ fn from_jdbc_string_parses_host_and_port() {
+ let config =
+ Config::from_jdbc_string("jdbc:sqlserver://db.example.com:2345").expect("valid jdbc");
+ assert_eq!("db.example.com", config.get_host());
+ assert_eq!(2345, config.get_port());
+ }
+
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ #[test]
+ fn get_hostname_in_certificate_falls_back_to_host() {
+ let mut config = Config::new();
+ config.host("real.host");
+ // Unset: falls back to the connection host.
+ assert_eq!(config.get_hostname_in_certificate(), "real.host");
+ // Set: returns the explicit certificate hostname.
+ config.hostname_in_certificate("cert.host");
+ assert_eq!(config.get_hostname_in_certificate(), "cert.host");
+ }
+
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ #[test]
+ fn client_certificate_sets_cert_and_key_source() {
+ let mut config = Config::new();
+ assert!(config.get_client_certificate().is_none());
+
+ config.client_certificate("/tmp/client.pem", "/tmp/client.key");
+
+ let cert = config
+ .get_client_certificate()
+ .expect("client certificate should be set");
+ match &cert.source {
+ ClientCertSource::CertAndKey { cert, key } => {
+ assert_eq!(cert, &PathBuf::from("/tmp/client.pem"));
+ assert_eq!(key, &PathBuf::from("/tmp/client.key"));
+ }
+ #[allow(unreachable_patterns)]
+ other => panic!("expected CertAndKey source, got {other:?}"),
+ }
+ }
+
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ #[test]
+ fn config_builder_sets_client_certificate() {
+ let config = Config::builder()
+ .host("localhost")
+ .client_certificate("cert.der", "key.der")
+ .build();
+
+ match &config
+ .get_client_certificate()
+ .expect("client certificate should be set")
+ .source
+ {
+ ClientCertSource::CertAndKey { cert, key } => {
+ assert_eq!(cert, &PathBuf::from("cert.der"));
+ assert_eq!(key, &PathBuf::from("key.der"));
+ }
+ #[allow(unreachable_patterns)]
+ other => panic!("expected CertAndKey source, got {other:?}"),
+ }
+ }
+
+ #[cfg(any(feature = "native-tls", feature = "vendored-openssl"))]
+ #[test]
+ fn client_certificate_pkcs12_sets_bundle_source() {
+ let mut config = Config::new();
+ config.client_certificate_pkcs12("/tmp/identity.pfx", "s3cr3t");
+
+ match &config
+ .get_client_certificate()
+ .expect("client certificate should be set")
+ .source
+ {
+ ClientCertSource::Pkcs12 { path, password } => {
+ assert_eq!(path, &PathBuf::from("/tmp/identity.pfx"));
+ assert_eq!(password.expose_secret(), "s3cr3t");
+ }
+ other => panic!("expected Pkcs12 source, got {other:?}"),
+ }
+ }
+
+ #[cfg(any(feature = "native-tls", feature = "vendored-openssl"))]
+ #[test]
+ fn client_certificate_debug_redacts_pkcs12_password() {
+ let mut config = Config::new();
+ config.client_certificate_pkcs12("/tmp/identity.pfx", "topsecret");
+
+ let dbg = format!("{:?}", config.get_client_certificate().unwrap());
+ assert!(dbg.contains("REDACTED"), "password not redacted: {dbg}");
+ assert!(!dbg.contains("topsecret"), "password leaked: {dbg}");
+ }
+
+ #[cfg(all(unix, feature = "sspi-rs"))]
+ #[test]
+ fn ado_integrated_security_sspi_with_credentials_uses_windows_ntlm() {
+ let config = Config::from_ado_string(
+ "server=tcp:localhost,1433;IntegratedSecurity=SSPI;uid=DOMAIN\\user;pwd=secret",
+ )
+ .unwrap();
+
+ match config.auth {
+ AuthMethod::Windows(auth) => {
+ assert_eq!("user", auth.user);
+ assert_eq!(Some("DOMAIN"), auth.domain.as_deref());
+ }
+ other => panic!("expected Windows NTLM auth, got {other:?}"),
+ }
+ }
+
+ #[test]
+ fn config_direct_setters_populate_fields() {
+ let mut config = Config::new();
+ config.database("northwind");
+ config.instance_name("SQLEXPRESS");
+ config.client_name("workstation-7");
+
+ assert_eq!(Some("northwind"), config.database.as_deref());
+ assert_eq!(Some("SQLEXPRESS"), config.instance_name.as_deref());
+ assert_eq!(Some("workstation-7"), config.client_name.as_deref());
+ }
+
+ #[test]
+ fn get_port_defaults_without_port_or_instance() {
+ // No explicit port and no instance -> default SQL Server port.
+ let config = Config::new();
+ assert_eq!(1433, config.get_port());
+ }
+
+ #[test]
+ fn get_port_uses_sql_browser_port_for_named_instance() {
+ // A named instance without an explicit port -> SQL Browser port.
+ let mut config = Config::new();
+ config.instance_name("SQLEXPRESS");
+ assert_eq!(1434, config.get_port());
+ }
+
+ #[test]
+ #[should_panic(expected = "mutual exclusive")]
+ fn trust_cert_after_trust_cert_ca_panics() {
+ let mut config = Config::new();
+ config.trust_cert_ca("/tmp/ca.crt");
+ config.trust_cert();
+ }
+
+ #[test]
+ #[should_panic(expected = "mutual exclusive")]
+ fn trust_cert_ca_after_trust_cert_panics() {
+ let mut config = Config::new();
+ config.trust_cert();
+ config.trust_cert_ca("/tmp/ca.crt");
+ }
+
+ #[test]
+ fn trust_cert_ca_sets_ca_location() {
+ let mut config = Config::new();
+ config.trust_cert_ca("/tmp/ca.crt");
+ assert!(matches!(
+ config.trust.extra_cas.as_slice(),
+ [ExtraCa::File(_)]
+ ));
+ assert!(!config.trust.bypass);
+ assert!(matches!(config.trust.source, RootSource::Native));
+ }
+
+ #[test]
+ fn trust_cert_ca_accumulates_across_calls() {
+ // Repeated calls are additive (not replace-last-wins): both CAs must
+ // be trusted, across file + bundle sources.
+ let mut config = Config::new();
+ config.trust_cert_ca("/tmp/a.crt");
+ config.trust_cert_ca("/tmp/b.crt");
+ config.trust_cert_ca_bundle(b"----- not really a cert -----".to_vec());
+
+ assert_eq!(config.trust.extra_cas.len(), 3);
+ match &config.trust.extra_cas[0] {
+ ExtraCa::File(p) => assert_eq!(p, &PathBuf::from("/tmp/a.crt")),
+ other => panic!("expected File, got {other:?}"),
+ }
+ match &config.trust.extra_cas[1] {
+ ExtraCa::File(p) => assert_eq!(p, &PathBuf::from("/tmp/b.crt")),
+ other => panic!("expected File, got {other:?}"),
+ }
+ assert!(matches!(config.trust.extra_cas[2], ExtraCa::Bundle(_)));
+ }
+
+ #[test]
+ fn trust_cert_ca_bundle_pushes_bundle() {
+ let mut config = Config::new();
+ config.trust_cert_ca_bundle(vec![1u8, 2, 3]);
+ match config.trust.extra_cas.as_slice() {
+ [ExtraCa::Bundle(bytes)] => assert_eq!(bytes, &[1, 2, 3]),
+ other => panic!("expected a single Bundle, got {other:?}"),
+ }
+ }
+
+ #[test]
+ fn trust_config_debug_redacts_bundle_bytes() {
+ // The bundle's raw bytes must never appear in Debug; only a
+ // length summary.
+ let mut config = Config::new();
+ config.trust_cert_ca_bundle(vec![0xDE, 0xAD, 0xBE, 0xEF]);
+ let dbg = format!("{:?}", config.trust);
+ assert!(dbg.contains("Bundle { len: 4 }"), "got: {dbg}");
+ assert!(
+ !dbg.contains("222") && !dbg.contains("0xde"),
+ "bytes leaked: {dbg}"
+ );
+ }
+
+ #[cfg(feature = "rustls-webpki-roots")]
+ #[test]
+ fn trust_webpki_roots_sets_source_and_is_mutually_exclusive_with_extras() {
+ let mut config = Config::new();
+ config.trust_webpki_roots();
+ assert!(matches!(config.trust.source, RootSource::WebpkiRoots));
+ // Extra CAs still layer on top of the webpki source.
+ config.trust_cert_ca("/tmp/extra.crt");
+ assert_eq!(config.trust.extra_cas.len(), 1);
+ }
+
+ #[cfg(feature = "rustls-webpki-roots")]
+ #[test]
+ #[should_panic(expected = "mutual exclusive")]
+ fn trust_cert_after_trust_webpki_roots_panics() {
+ let mut config = Config::new();
+ config.trust_webpki_roots();
+ config.trust_cert();
+ }
+
+ #[cfg(feature = "rustls-webpki-roots")]
+ #[test]
+ #[should_panic(expected = "mutual exclusive")]
+ fn trust_webpki_roots_after_trust_cert_panics() {
+ let mut config = Config::new();
+ config.trust_cert();
+ config.trust_webpki_roots();
+ }
+
+ #[test]
+ #[should_panic(expected = "mutual exclusive")]
+ fn trust_cert_after_trust_cert_ca_bundle_panics() {
+ let mut config = Config::new();
+ config.trust_cert_ca_bundle(vec![1, 2, 3]);
+ config.trust_cert();
+ }
+
+ #[test]
+ #[should_panic(expected = "mutual exclusive")]
+ fn trust_cert_ca_bundle_after_trust_cert_panics() {
+ let mut config = Config::new();
+ config.trust_cert();
+ config.trust_cert_ca_bundle(vec![1, 2, 3]);
+ }
+
+ #[test]
+ fn trust_cert_sets_bypass() {
+ // The default must be a validating config; `trust_cert()` is the explicit
+ // opt-in that switches to bypass validation.
+ let mut config = Config::new();
+ assert!(config.trust.is_default());
+ config.trust_cert();
+ assert!(config.trust.bypass);
+ }
+
+ #[test]
+ fn config_builder_covers_all_setters() {
+ let config = Config::builder()
+ .host("localhost")
+ .instance_name("SQLEXPRESS")
+ .encryption(EncryptionLevel::Off)
+ .trust_cert_ca("/tmp/ca.crt")
+ .build();
+
+ assert_eq!(Some("SQLEXPRESS"), config.instance_name.as_deref());
+ assert!(matches!(config.encryption, EncryptionLevel::Off));
+ assert!(matches!(
+ config.trust.extra_cas.as_slice(),
+ [ExtraCa::File(_)]
+ ));
+ }
+
+ #[test]
+ fn config_builder_trust_cert_sets_bypass() {
+ let config = Config::builder().trust_cert().build();
+ assert!(config.trust.bypass);
+ }
+
+ #[test]
+ fn config_builder_trust_cert_ca_bundle_accumulates() {
+ let config = Config::builder()
+ .trust_cert_ca("/tmp/a.crt")
+ .trust_cert_ca_bundle(vec![1, 2, 3])
+ .build();
+ assert_eq!(config.trust.extra_cas.len(), 2);
+ }
+
+ #[cfg(feature = "rustls-webpki-roots")]
+ #[test]
+ fn config_builder_trust_webpki_roots_sets_source() {
+ let config = Config::builder().trust_webpki_roots().build();
+ assert!(matches!(config.trust.source, RootSource::WebpkiRoots));
+ }
+
+ #[test]
+ #[should_panic(expected = "mutual exclusive")]
+ fn config_builder_trust_cert_after_ca_panics() {
+ Config::builder().trust_cert_ca("/tmp/ca.crt").trust_cert();
+ }
+
+ #[test]
+ #[should_panic(expected = "mutual exclusive")]
+ fn config_builder_trust_cert_ca_after_trust_cert_panics() {
+ Config::builder().trust_cert().trust_cert_ca("/tmp/ca.crt");
+ }
+
+ #[test]
+ fn from_ado_string_populates_optional_fields() {
+ let config = Config::from_ado_string(
+ "server=tcp:my-server.com\\SQLEXPRESS;database=northwind;\
+ HostNameInCertificate=cert.host;WorkstationID=ws-1",
+ )
+ .expect("valid ado string");
+
+ assert_eq!("my-server.com", config.get_host());
+ assert_eq!(Some("SQLEXPRESS"), config.instance_name.as_deref());
+ assert_eq!(Some("northwind"), config.database.as_deref());
+ assert_eq!(Some("cert.host"), config.hostname_in_certificate.as_deref());
+ assert_eq!(Some("ws-1"), config.client_name.as_deref());
+ }
+
+ #[test]
+ fn from_ado_string_trust_cert_ca_populates_extra_cas() {
+ let config = Config::from_ado_string(
+ "server=tcp:localhost,1433;TrustServerCertificateCA=/tmp/ca.crt",
+ )
+ .expect("valid ado string");
+ match config.trust.extra_cas.as_slice() {
+ [ExtraCa::File(p)] => assert_eq!(p, &PathBuf::from("/tmp/ca.crt")),
+ other => panic!("expected a single File CA, got {other:?}"),
+ }
+ assert!(!config.trust.bypass);
+ }
+
+ #[test]
+ fn from_ado_string_trust_cert_populates_bypass() {
+ let config =
+ Config::from_ado_string("server=tcp:localhost,1433;TrustServerCertificate=true")
+ .expect("valid ado string");
+ assert!(config.trust.bypass);
+ }
+
+ #[test]
+ fn from_ado_string_trust_cert_and_ca_conflict_errors() {
+ // The conflict must surface as a hard error, never silently let
+ // the bypass win. From a connection string it is an `Err`, not a panic.
+ let err = Config::from_ado_string(
+ "server=tcp:localhost,1433;TrustServerCertificate=true;\
+ TrustServerCertificateCA=/tmp/ca.crt",
+ )
+ .expect_err("conflicting trust settings must error");
+ match err {
+ crate::Error::Conversion(msg) => {
+ assert!(msg.contains("mutually exclusive"), "got: {msg}")
+ }
+ other => panic!("expected Conversion error, got {other:?}"),
+ }
+ }
+
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ #[test]
+ fn client_cert_source_debug_formats_cert_and_key() {
+ let mut config = Config::new();
+ config.client_certificate("/tmp/client.pem", "/tmp/client.key");
+
+ let dbg = format!("{:?}", config.get_client_certificate().unwrap().source);
+ assert!(dbg.contains("CertAndKey"));
+ assert!(dbg.contains("client.pem"));
+ assert!(dbg.contains("client.key"));
+ }
+
+ #[cfg(any(feature = "native-tls", feature = "vendored-openssl"))]
+ #[test]
+ fn config_builder_sets_pkcs12_client_certificate() {
+ let config = Config::builder()
+ .client_certificate_pkcs12("/tmp/identity.pfx", "s3cr3t")
+ .build();
+
+ match &config
+ .get_client_certificate()
+ .expect("client certificate should be set")
+ .source
+ {
+ ClientCertSource::Pkcs12 { path, password } => {
+ assert_eq!(path, &PathBuf::from("/tmp/identity.pfx"));
+ assert_eq!(password.expose_secret(), "s3cr3t");
+ }
+ other => panic!("expected Pkcs12 source, got {other:?}"),
+ }
+ }
+
+ #[cfg(all(unix, feature = "sspi-rs"))]
+ #[test]
+ fn ado_integrated_security_sspi_with_partial_credentials_uses_windows() {
+ // Only a username (no password) -> falls into the catch-all NTLM arm.
+ let config = Config::from_ado_string(
+ "server=tcp:localhost,1433;IntegratedSecurity=SSPI;uid=onlyuser",
+ )
+ .unwrap();
+
+ match config.auth {
+ AuthMethod::Windows(auth) => {
+ assert_eq!("onlyuser", auth.user);
+ }
+ other => panic!("expected Windows auth, got {other:?}"),
+ }
+ }
}
diff --git a/src/client/config/ado_net.rs b/src/client/config/ado_net.rs
index 94df9ca38..0c878016f 100644
--- a/src/client/config/ado_net.rs
+++ b/src/client/config/ado_net.rs
@@ -2,21 +2,29 @@ use super::{ConfigString, ServerDefinition};
use std::str::FromStr;
pub(crate) struct AdoNetConfig {
- dict: connection_string::AdoNetString,
+ dict: super::ado_parser::AdoNetString,
}
impl FromStr for AdoNetConfig {
type Err = crate::error::Error;
fn from_str(s: &str) -> crate::Result {
- let dict = s.parse()?;
+ let dict = super::ado_parser::parse(s).map_err(|reason| {
+ super::hinted_conversion_error(
+ reason,
+ "wrap the value in single quotes (e.g. `password='p@ss;word'`), \
+ double quotes, or braces (e.g. `password={p@ss;word}`), and \
+ quote leading spaces too",
+ "Config::from_ado_string",
+ )
+ })?;
Ok(Self { dict })
}
}
impl ConfigString for AdoNetConfig {
fn dict(&self) -> &std::collections::HashMap {
- &self.dict
+ self.dict.pairs()
}
fn server(&self) -> crate::Result {
@@ -55,8 +63,9 @@ impl ConfigString for AdoNetConfig {
match self
.dict
+ .pairs()
.get("server")
- .or_else(|| self.dict.get("data source"))
+ .or_else(|| self.dict.pairs().get("data source"))
{
Some(value) if value.starts_with("tcp:") => {
parse_server(value[4..].split(',').collect())
@@ -230,6 +239,39 @@ mod tests {
Ok(())
}
+ #[test]
+ fn server_parsing_too_many_parts_is_error() -> crate::Result<()> {
+ // The Server value must have at most two comma-separated parts
+ // (host[,port]). Three parts is invalid and must error. The guard is
+ // `parts.is_empty() || parts.len() >= 3`; a `&&` mutation would never
+ // trigger (a slice cannot be both empty and have >= 3 parts), so this
+ // three-part value would be wrongly accepted.
+ let ado: AdoNetConfig = "server=tcp:my-server.com,1433,extra".parse()?;
+ assert!(ado.server().is_err());
+
+ let ado: AdoNetConfig = "server=my-server.com,1433,extra".parse()?;
+ assert!(ado.server().is_err());
+
+ Ok(())
+ }
+
+ #[test]
+ fn server_parsing_missing_key() -> crate::Result<()> {
+ // No `server`/`data source` key at all -> an all-`None` definition.
+ let ado: AdoNetConfig = "database=Foo".parse()?;
+ let server = ado.server()?;
+
+ assert_eq!(None, server.host);
+ assert_eq!(None, server.port);
+ assert_eq!(None, server.instance);
+
+ // And the same path through the public constructor.
+ let config = crate::Config::from_ado_string("database=Foo")?;
+ assert_eq!("localhost", config.get_host());
+
+ Ok(())
+ }
+
#[test]
fn database_parsing() -> crate::Result<()> {
let test_str = "database=Foo";
@@ -410,6 +452,262 @@ mod tests {
Ok(())
}
+ #[test]
+ fn parsing_password_special_characters() -> crate::Result<()> {
+ // (value as written in the connection string, exact parsed password).
+ // The user and password must both round-trip exactly.
+ let cases: &[(&str, &str)] = &[
+ // Single quotes: the most general escape; any ASCII char except a
+ // literal single quote can appear verbatim.
+ ("'a;b'", "a;b"),
+ ("'a=b'", "a=b"),
+ ("'a{b'", "a{b"),
+ ("'a}b'", "a}b"),
+ ("'a b'", "a b"),
+ ("'a$b'", "a$b"),
+ ("'a@b'", "a@b"),
+ ("'a!b'", "a!b"),
+ ("'a#b'", "a#b"),
+ ("'a%b'", "a%b"),
+ ("'a&b'", "a&b"),
+ ("'a,b'", "a,b"),
+ ("'a\"b'", "a\"b"), // a double quote inside single quotes
+ ("'p@ss;w{}rd=42'", "p@ss;w{}rd=42"),
+ // Double quotes: same idea, and lets a single quote appear.
+ ("\"a'b\"", "a'b"),
+ ("\"a;b=c\"", "a;b=c"),
+ // Braces (`{...}`): handy for `;` and `=`, but cannot hold a `}`.
+ ("{a;b}", "a;b"),
+ ("{a=b}", "a=b"),
+ ("{a$b}", "a$b"),
+ // Unquoted: non-structural characters pass through untouched.
+ ("a$b", "a$b"),
+ ("a@b", "a@b"),
+ ("a!b", "a!b"),
+ ("a#b", "a#b"),
+ ("a%b", "a%b"),
+ ("a&b", "a&b"),
+ ("a,b", "a,b"),
+ // A bare `}` is not structural: it passes through unquoted.
+ ("a}b", "a}b"),
+ // Percent-encoding is NOT decoded: `%24` stays literal, it does
+ // not become `$`.
+ ("a%24b", "a%24b"),
+ // An empty password is accepted by the ADO parser.
+ ("", ""),
+ ];
+
+ for (value, expected) in cases {
+ let s = format!("User Id=sa;Password={value};");
+ let ado: AdoNetConfig = s.parse()?;
+ assert_eq!(
+ AuthMethod::sql_server("sa", *expected),
+ ado.authentication()?,
+ "value `{value}` should parse to password `{expected}`"
+ );
+ }
+
+ Ok(())
+ }
+
+ #[test]
+ fn parsing_password_whitespace_quirks() -> crate::Result<()> {
+ // Quoting preserves surrounding whitespace (matching ADO.NET): both a
+ // leading and a trailing space inside quotes survive.
+ let ado: AdoNetConfig = "User Id=sa;Password='a '".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", "a "), ado.authentication()?);
+
+ let ado: AdoNetConfig = "User Id=sa;Password=' a'".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", " a"), ado.authentication()?);
+
+ // An unquoted value is trimmed on both sides.
+ let ado: AdoNetConfig = "User Id=sa;Password= a ".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", "a"), ado.authentication()?);
+
+ // Internal tabs survive.
+ let ado: AdoNetConfig = "User Id=sa;Password='a\tb'".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", "a\tb"), ado.authentication()?);
+
+ Ok(())
+ }
+
+ #[test]
+ fn parsing_password_brace_cannot_hold_close_brace() -> crate::Result<()> {
+ // A `{…}` value closes at the first `}` and cannot contain one: any
+ // characters after that `}` are a syntax error rather than being
+ // silently folded into the value.
+ assert!("User Id=sa;Password={a}b}".parse::().is_err());
+
+ // Use single or double quotes for passwords that contain `}`.
+ let ado: AdoNetConfig = "User Id=sa;Password='a}b}'".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", "a}b}"), ado.authentication()?);
+
+ Ok(())
+ }
+
+ #[test]
+ fn parsing_password_non_ascii_is_rejected() {
+ // The ADO parser only accepts ASCII; non-ASCII passwords must use the
+ // programmatic `Config` API instead.
+ assert!("User Id=sa;Password=café".parse::().is_err());
+ assert!("User Id=sa;Password='café'"
+ .parse::()
+ .is_err());
+ }
+
+ // Every printable-ASCII special character must be usable in a password
+ // through single quotes and through double quotes, round-tripping exactly.
+ // The enclosing quote is embedded by doubling it.
+ #[test]
+ fn parsing_password_every_special_char_via_quotes() -> crate::Result<()> {
+ const SPECIALS: &str = "!@#$%^&*()-_+=[]{}|\\:;\"'<>,.?/~` ";
+ for c in SPECIALS.chars() {
+ let expected = format!("Pa{c}ss1");
+
+ // Single quotes: a literal `'` is written as `''`.
+ let inner = if c == '\'' {
+ "Pa''ss1".to_string()
+ } else {
+ format!("Pa{c}ss1")
+ };
+ let s = format!("User Id=sa;Password='{inner}'");
+ let ado: AdoNetConfig = s
+ .parse()
+ .unwrap_or_else(|e| panic!("char {c:?} single-quoted failed: {e}"));
+ assert_eq!(
+ AuthMethod::sql_server("sa", expected.as_str()),
+ ado.authentication()?,
+ "char {c:?} single-quoted"
+ );
+
+ // Double quotes: a literal `"` is written as `""`.
+ let inner = if c == '"' {
+ "Pa\"\"ss1".to_string()
+ } else {
+ format!("Pa{c}ss1")
+ };
+ let s = format!("User Id=sa;Password=\"{inner}\"");
+ let ado: AdoNetConfig = s
+ .parse()
+ .unwrap_or_else(|e| panic!("char {c:?} double-quoted failed: {e}"));
+ assert_eq!(
+ AuthMethod::sql_server("sa", expected.as_str()),
+ ado.authentication()?,
+ "char {c:?} double-quoted"
+ );
+ }
+
+ Ok(())
+ }
+
+ // A doubled enclosing quote embeds that quote character.
+ #[test]
+ fn parsing_password_doubled_quotes_embed_the_quote() -> crate::Result<()> {
+ let ado: AdoNetConfig = "User Id=sa;Password='a''b'".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", "a'b"), ado.authentication()?);
+
+ let ado: AdoNetConfig = "User Id=sa;Password=\"a\"\"b\"".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", "a\"b"), ado.authentication()?);
+
+ Ok(())
+ }
+
+ // An unquoted value may contain `=` — each pair splits on the first `=` —
+ // so a base64/generated password with `=` padding parses (issue #313).
+ #[test]
+ fn issue_313_unquoted_equals_in_password_parses() -> crate::Result<()> {
+ let cases: &[(&str, &str)] = &[
+ ("Zm9vYmFy==", "Zm9vYmFy=="), // base64 with `==` padding (the report)
+ ("aGVsbG8=", "aGVsbG8="), // base64 with a single `=` pad
+ ("Pa=ss1", "Pa=ss1"),
+ ("a=b=c", "a=b=c"),
+ ];
+ for (raw, expected) in cases {
+ let s =
+ format!("Server=tcp:host.example.com,1433;Database=DB;User Id=sa;Password={raw}");
+ let ado: AdoNetConfig = s
+ .parse()
+ .unwrap_or_else(|e| panic!("unquoted `{raw}` should parse: {e}"));
+ assert_eq!(
+ AuthMethod::sql_server("sa", *expected),
+ ado.authentication()?,
+ "unquoted `{raw}`"
+ );
+ }
+
+ Ok(())
+ }
+
+ // `==` in the key position is a literal `=`; the pair still splits on the
+ // first *single* `=`.
+ #[test]
+ fn parsing_key_double_equals_is_literal() -> crate::Result<()> {
+ let ado: AdoNetConfig = "User Id=sa;Password=p".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", "p"), ado.authentication()?);
+ // A hypothetical key containing `=` round-trips via `==`.
+ let cfg: AdoNetConfig = "a==b=c".parse()?;
+ assert_eq!(cfg.dict.pairs().get("a=b").map(String::as_str), Some("c"));
+
+ Ok(())
+ }
+
+ // Characters that remain genuinely ambiguous unquoted must still error and
+ // point the caller at quoting — never silently mis-parse.
+ #[test]
+ fn parsing_password_ambiguous_unquoted_chars_error() {
+ // `;` is the separator; `Password=a;b` is read as a pair `a` then a
+ // second pair `b` with no `=`.
+ assert!("User Id=sa;Password=a;b".parse::().is_err());
+ // A value that *starts* with a quote/brace but is not closed is an error.
+ assert!("User Id=sa;Password='ab".parse::().is_err());
+ assert!("User Id=sa;Password=\"ab".parse::().is_err());
+ assert!("User Id=sa;Password={ab".parse::().is_err());
+ }
+
+ #[test]
+ fn unquoted_special_char_password_error_has_hint() {
+ // An unquoted `;` in a password breaks parsing. The error must guide
+ // the user toward quoting or the programmatic API while preserving the
+ // underlying parser message.
+ let err = "User Id=sa;Password=a;b"
+ .parse::()
+ .err()
+ .unwrap();
+ let msg = err.to_string();
+ // Underlying terse parser message is preserved (not replaced).
+ assert!(msg.contains("must be joined"), "message was: {msg}");
+ // Hint mentions the ADO quoting styles and the programmatic API.
+ assert!(msg.contains("single quotes"), "message was: {msg}");
+ assert!(msg.contains("braces"), "message was: {msg}");
+ assert!(
+ msg.contains("Config::from_ado_string"),
+ "message was: {msg}"
+ );
+ // The `Conversion error:` prefix must not be doubled.
+ assert!(
+ !msg.contains("Conversion error: Conversion error:"),
+ "message was: {msg}"
+ );
+ }
+
+ #[test]
+ fn unclosed_quote_and_brace_errors_have_hint() {
+ // Unclosed quote/brace are quoting mistakes; the hint should attach.
+ for input in [
+ "User Id=sa;Password='abc", // unclosed single quote
+ "User Id=sa;Password=\"abc", // unclosed double quote
+ "User Id=sa;Password={abc", // unclosed brace
+ ] {
+ let err = input.parse::().err().unwrap();
+ let msg = err.to_string();
+ assert!(msg.contains("must be quoted"), "message was: {msg}");
+ assert!(
+ !msg.contains("Conversion error: Conversion error:"),
+ "message was: {msg}"
+ );
+ }
+ }
+
#[test]
#[cfg(any(
feature = "rustls",
@@ -465,7 +763,149 @@ mod tests {
let test_str = "";
let ado: AdoNetConfig = test_str.parse()?;
- assert_eq!(EncryptionLevel::Off, ado.encrypt()?);
+ assert_eq!(EncryptionLevel::Required, ado.encrypt()?);
+
+ Ok(())
+ }
+
+ #[test]
+ #[cfg(feature = "tds80")]
+ fn encryption_parsing_strict() -> crate::Result<()> {
+ let test_str = "encrypt=strict";
+ let ado: AdoNetConfig = test_str.parse()?;
+
+ assert_eq!(EncryptionLevel::Strict, ado.encrypt()?);
+
+ Ok(())
+ }
+
+ // No-TLS build: an explicit encryption request must error (not silently
+ // downgrade to plaintext, #305); opting out and an omitted keyword stay
+ // `NotSupported`.
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_on_errors_without_tls_backend() -> crate::Result<()> {
+ for test_str in ["encrypt=true", "encrypt=yes"] {
+ let ado: AdoNetConfig = test_str.parse()?;
+ let err = ado.encrypt().unwrap_err();
+ assert!(
+ matches!(err, crate::Error::Tls(_)),
+ "expected Error::Tls for {test_str}, got {err:?}"
+ );
+ let msg = err.to_string();
+ assert!(msg.contains("without a TLS backend"), "message was: {msg}");
+ }
+
+ Ok(())
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_strict_errors_without_tls_backend() {
+ let ado: AdoNetConfig = "encrypt=strict".parse().unwrap();
+ let err = ado.encrypt().unwrap_err();
+ assert!(
+ matches!(err, crate::Error::Tls(_)),
+ "expected Error::Tls, got {err:?}"
+ );
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_mandatory_errors_without_tls_backend() {
+ // `mandatory` is not an accepted token in either build; the with-TLS
+ // parser rejects it as a bad boolean, so the no-TLS branch mirrors that
+ // (still an error, just not the TLS-missing one).
+ let ado: AdoNetConfig = "encrypt=mandatory".parse().unwrap();
+ assert!(ado.encrypt().is_err());
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_off_ok_without_tls_backend() -> crate::Result<()> {
+ for test_str in ["encrypt=false", "encrypt=no"] {
+ let ado: AdoNetConfig = test_str.parse()?;
+ assert_eq!(crate::EncryptionLevel::NotSupported, ado.encrypt()?);
+ }
+
+ Ok(())
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_plaintext_ok_without_tls_backend() -> crate::Result<()> {
+ let ado: AdoNetConfig = "encrypt=DANGER_PLAINTEXT".parse()?;
+ assert_eq!(crate::EncryptionLevel::NotSupported, ado.encrypt()?);
+
+ Ok(())
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_missing_ok_without_tls_backend() -> crate::Result<()> {
+ let ado: AdoNetConfig = "".parse()?;
+ assert_eq!(crate::EncryptionLevel::NotSupported, ado.encrypt()?);
+
+ Ok(())
+ }
+
+ #[test]
+ fn client_name_parsing() -> crate::Result<()> {
+ let test_str = "workstationid=meow";
+ let ado: AdoNetConfig = test_str.parse()?;
+
+ assert_eq!(Some("meow".into()), ado.client_name());
+
+ let test_str = "Workstation ID=meow";
+ let ado: AdoNetConfig = test_str.parse()?;
+
+ assert_eq!(Some("meow".into()), ado.client_name());
+
+ Ok(())
+ }
+
+ #[test]
+ fn hostname_in_certificate_parsing() -> crate::Result<()> {
+ let test_str = "HostNameInCertificate=foo.example.com";
+ let ado: AdoNetConfig = test_str.parse()?;
+
+ assert_eq!(
+ Some("foo.example.com".into()),
+ ado.hostname_in_certificate()
+ );
+
+ let test_str = "HostName In Certificate=foo.example.com";
+ let ado: AdoNetConfig = test_str.parse()?;
+
+ assert_eq!(
+ Some("foo.example.com".into()),
+ ado.hostname_in_certificate()
+ );
Ok(())
}
@@ -484,4 +924,64 @@ mod tests {
Ok(())
}
+
+ #[test]
+ fn application_intent_readonly_parsing() -> crate::Result<()> {
+ // Exact spelling from the ADO.NET connection string.
+ let ado: AdoNetConfig = "ApplicationIntent=ReadOnly".parse()?;
+ assert!(ado.readonly());
+
+ // ADO.NET treats the value case-insensitively.
+ let ado: AdoNetConfig = "applicationintent=readonly".parse()?;
+ assert!(ado.readonly());
+
+ // ReadWrite (the default) must not request read-only intent.
+ let ado: AdoNetConfig = "ApplicationIntent=ReadWrite".parse()?;
+ assert!(!ado.readonly());
+
+ // Absent altogether.
+ let ado: AdoNetConfig = "server=tcp:localhost,1433".parse()?;
+ assert!(!ado.readonly());
+
+ Ok(())
+ }
+
+ #[test]
+ fn multi_subnet_failover_parsing() -> crate::Result<()> {
+ let test_str = "MultiSubnetFailover=true";
+ let ado: AdoNetConfig = test_str.parse()?;
+ assert!(ado.multi_subnet_failover()?);
+
+ let test_str = "MultiSubnetFailover=yes";
+ let ado: AdoNetConfig = test_str.parse()?;
+ assert!(ado.multi_subnet_failover()?);
+
+ let test_str = "MultiSubnetFailover=false";
+ let ado: AdoNetConfig = test_str.parse()?;
+ assert!(!ado.multi_subnet_failover()?);
+
+ Ok(())
+ }
+
+ #[test]
+ fn multi_subnet_failover_parsing_missing() -> crate::Result<()> {
+ let test_str = "";
+ let ado: AdoNetConfig = test_str.parse()?;
+ assert!(!ado.multi_subnet_failover()?);
+
+ Ok(())
+ }
+
+ #[test]
+ fn multi_subnet_failover_from_ado_string() -> crate::Result<()> {
+ let config = crate::Config::from_ado_string(
+ "server=tcp:my-server.com,1433;MultiSubnetFailover=true",
+ )?;
+ assert!(config.get_multi_subnet_failover());
+
+ let config = crate::Config::from_ado_string("server=tcp:my-server.com,1433")?;
+ assert!(!config.get_multi_subnet_failover());
+
+ Ok(())
+ }
}
diff --git a/src/client/config/ado_parser.rs b/src/client/config/ado_parser.rs
new file mode 100644
index 000000000..ae3e7841f
--- /dev/null
+++ b/src/client/config/ado_parser.rs
@@ -0,0 +1,426 @@
+//! In-house ADO.NET-style connection-string tokenizer.
+//!
+//! Tiberius parses ADO.NET connection strings as a **superset** of the rules
+//! documented for .NET's `DbConnectionStringBuilder`:
+//!
+//! - pairs are separated by `;`; empty pairs (a stray `;`, trailing `;`) are
+//! ignored;
+//! - each pair is split on the **first** `=`, so a value may contain further
+//! `=` characters (for example the `=` padding on a base64 password); a `==`
+//! in the key position is a literal `=`;
+//! - keys are trimmed and matched case-insensitively;
+//! - an unquoted value is trimmed of surrounding whitespace; to keep `;`, a
+//! quote, or leading/trailing spaces, quote the value with `'…'` or `"…"` and
+//! double the enclosing quote to embed it (`"a""b"` → `a"b`);
+//! - **extension (not ADO.NET):** `{…}` brace quoting is also accepted; the
+//! value runs to the first `}` and therefore cannot itself contain `}`.
+//!
+//! Only ASCII input is accepted; build [`Config`] programmatically for anything
+//! else.
+//!
+//! The returned error is a terse reason; the caller wraps it with the escaping
+//! hint (see `hinted_conversion_error`), so the messages here stay short.
+//!
+//! [`Config`]: crate::Config
+
+use std::collections::HashMap;
+
+/// A parsed ADO.NET connection string: a map of lower-cased keys to their
+/// unescaped values.
+#[derive(Debug)]
+pub(crate) struct AdoNetString {
+ pairs: HashMap,
+}
+
+impl AdoNetString {
+ /// The parsed key/value pairs (keys lower-cased).
+ pub(crate) fn pairs(&self) -> &HashMap {
+ &self.pairs
+ }
+}
+
+/// Parses an ADO.NET connection string. On failure returns a terse reason the
+/// caller turns into a hinted [`crate::Error`].
+pub(crate) fn parse(input: &str) -> Result {
+ // The parser is byte-oriented for a single reason: every character it
+ // treats specially (`;`, `=`, `'`, `"`, `{`, `}`, whitespace) is ASCII, and
+ // rejecting non-ASCII up front lets the byte index and the char index stay
+ // identical without any multi-byte bookkeeping.
+ if !input.is_ascii() {
+ return Err("the connection string contains non-ASCII characters");
+ }
+
+ let b = input.as_bytes();
+ let n = b.len();
+ let mut i = 0;
+ let mut pairs = HashMap::new();
+
+ while i < n {
+ // Between pairs, skip separators and surrounding whitespace.
+ while i < n && (b[i] == b';' || b[i].is_ascii_whitespace()) {
+ i += 1;
+ }
+ if i >= n {
+ break;
+ }
+
+ // Key: everything up to the first single `=`. A `==` is a literal `=`.
+ let mut key = String::new();
+ loop {
+ if i >= n || b[i] == b';' {
+ return Err("key-value pairs must be joined by a `=`");
+ }
+ if b[i] == b'=' {
+ if i + 1 < n && b[i + 1] == b'=' {
+ key.push('=');
+ i += 2;
+ continue;
+ }
+ i += 1; // consume the separating `=`
+ break;
+ }
+ key.push(b[i] as char);
+ i += 1;
+ }
+ let key = key
+ .trim_matches(|c: char| c.is_ascii_whitespace())
+ .to_ascii_lowercase();
+ if key.is_empty() {
+ return Err("a key in the connection string is empty");
+ }
+
+ // Value: leading whitespace before the value is not significant.
+ while i < n && b[i].is_ascii_whitespace() {
+ i += 1;
+ }
+
+ let value = if i < n && (b[i] == b'\'' || b[i] == b'"') {
+ let quote = b[i];
+ i += 1;
+ let mut v = String::new();
+ loop {
+ if i >= n {
+ return Err(if quote == b'\'' {
+ "the connection string has an unclosed single quote"
+ } else {
+ "the connection string has an unclosed double quote"
+ });
+ }
+ if b[i] == quote {
+ // A doubled quote is a literal quote; a lone quote closes.
+ if i + 1 < n && b[i + 1] == quote {
+ v.push(quote as char);
+ i += 2;
+ continue;
+ }
+ i += 1;
+ break;
+ }
+ v.push(b[i] as char);
+ i += 1;
+ }
+ skip_trailing(b, &mut i, "unexpected characters after a quoted value")?;
+ v
+ } else if i < n && b[i] == b'{' {
+ i += 1;
+ let mut v = String::new();
+ loop {
+ if i >= n {
+ return Err("the connection string has an unclosed brace `{`");
+ }
+ if b[i] == b'}' {
+ i += 1;
+ break;
+ }
+ v.push(b[i] as char);
+ i += 1;
+ }
+ skip_trailing(
+ b,
+ &mut i,
+ "unexpected characters after a `{…}` value; quote with '' or \"\" if the value contains `}`",
+ )?;
+ v
+ } else {
+ // Unquoted: runs to the next `;`, with surrounding whitespace
+ // trimmed (leading was already skipped above). Trimming uses the
+ // same ASCII-whitespace definition as the leading skip so a value
+ // is not truncated differently at its two ends.
+ let start = i;
+ while i < n && b[i] != b';' {
+ i += 1;
+ }
+ input[start..i]
+ .trim_end_matches(|c: char| c.is_ascii_whitespace())
+ .to_string()
+ };
+
+ // Duplicate keys: last one wins, matching ADO.NET.
+ pairs.insert(key, value);
+
+ if i < n && b[i] == b';' {
+ i += 1;
+ }
+ }
+
+ Ok(AdoNetString { pairs })
+}
+
+/// After a closing quote or brace, only whitespace may precede the next `;` or
+/// the end of the string; anything else is reported with `err`.
+fn skip_trailing(b: &[u8], i: &mut usize, err: &'static str) -> Result<(), &'static str> {
+ while *i < b.len() && b[*i] != b';' {
+ if !b[*i].is_ascii_whitespace() {
+ return Err(err);
+ }
+ *i += 1;
+ }
+ Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::parse;
+
+ /// Parse and return the single value stored under `key`, panicking with the
+ /// parser error if parsing failed.
+ fn value(s: &str, key: &str) -> Option {
+ parse(s)
+ .unwrap_or_else(|e| panic!("`{s}` failed to parse: {e}"))
+ .pairs()
+ .get(key)
+ .cloned()
+ }
+
+ #[test]
+ fn basic_pairs() {
+ let p = parse("Server=host;Database=db;User Id=sa;Password=pw").unwrap();
+ assert_eq!(p.pairs().get("server").map(String::as_str), Some("host"));
+ assert_eq!(p.pairs().get("database").map(String::as_str), Some("db"));
+ assert_eq!(p.pairs().get("user id").map(String::as_str), Some("sa"));
+ assert_eq!(p.pairs().get("password").map(String::as_str), Some("pw"));
+ }
+
+ #[test]
+ fn keys_are_lowercased_and_trimmed() {
+ assert_eq!(value(" SeRVeR =host", "server").as_deref(), Some("host"));
+ assert_eq!(value("USER ID=sa", "user id").as_deref(), Some("sa"));
+ }
+
+ #[test]
+ fn splits_each_pair_on_the_first_equals() {
+ // A value may contain further `=` (base64 padding etc.); see #313.
+ assert_eq!(
+ value("Password=ab=cd", "password").as_deref(),
+ Some("ab=cd")
+ );
+ assert_eq!(
+ value("Password=Zm9vYmFy==", "password").as_deref(),
+ Some("Zm9vYmFy==")
+ );
+ assert_eq!(value("k=a=b=c=", "k").as_deref(), Some("a=b=c="));
+ }
+
+ #[test]
+ fn double_equals_in_key_is_a_literal_equals() {
+ // `k==v` reads as the key `k=v` with no separator, hence an error; a
+ // value that must *start* with `=` has to be quoted instead.
+ assert!(parse("k==v").is_err());
+ assert_eq!(value("k='=v'", "k").as_deref(), Some("=v"));
+ assert_eq!(value("a==b=c", "a=b").as_deref(), Some("c"));
+ }
+
+ #[test]
+ fn empty_pairs_are_ignored() {
+ assert_eq!(value(";;Server=host;;", "server").as_deref(), Some("host"));
+ assert_eq!(value("Server=host;", "server").as_deref(), Some("host"));
+ assert_eq!(value(";Server=host", "server").as_deref(), Some("host"));
+ assert!(parse("").unwrap().pairs().is_empty());
+ assert!(parse(" ").unwrap().pairs().is_empty());
+ assert!(parse(";;;").unwrap().pairs().is_empty());
+ }
+
+ #[test]
+ fn whitespace_between_pairs_is_ignored() {
+ let p = parse("Server=host ; Database=db").unwrap();
+ assert_eq!(p.pairs().get("server").map(String::as_str), Some("host"));
+ assert_eq!(p.pairs().get("database").map(String::as_str), Some("db"));
+ }
+
+ #[test]
+ fn unquoted_values_are_trimmed_both_sides() {
+ assert_eq!(value("k= a b ", "k").as_deref(), Some("a b"));
+ assert_eq!(value("k=", "k").as_deref(), Some(""));
+ assert_eq!(value("k= ", "k").as_deref(), Some(""));
+ }
+
+ #[test]
+ fn quotes_preserve_surrounding_whitespace() {
+ assert_eq!(value("k=' a '", "k").as_deref(), Some(" a "));
+ assert_eq!(value("k=\" a \"", "k").as_deref(), Some(" a "));
+ assert_eq!(value("k=' '", "k").as_deref(), Some(" "));
+ }
+
+ #[test]
+ fn quotes_hold_structural_characters() {
+ assert_eq!(value("k='a;b=c{d'", "k").as_deref(), Some("a;b=c{d"));
+ assert_eq!(value("k=\"a;b=c{d\"", "k").as_deref(), Some("a;b=c{d"));
+ // The other quote character is a literal inside.
+ assert_eq!(value("k='a\"b'", "k").as_deref(), Some("a\"b"));
+ assert_eq!(value("k=\"a'b\"", "k").as_deref(), Some("a'b"));
+ }
+
+ #[test]
+ fn doubled_quote_embeds_the_quote() {
+ assert_eq!(value("k='a''b'", "k").as_deref(), Some("a'b"));
+ assert_eq!(value("k=\"a\"\"b\"", "k").as_deref(), Some("a\"b"));
+ assert_eq!(value("k=''''", "k").as_deref(), Some("'")); // '' '' -> one '
+ }
+
+ #[test]
+ fn braces_hold_structural_characters() {
+ assert_eq!(value("k={a;b=c}", "k").as_deref(), Some("a;b=c"));
+ assert_eq!(value("k={a'b\"c}", "k").as_deref(), Some("a'b\"c"));
+ }
+
+ #[test]
+ fn brace_cannot_contain_close_brace() {
+ // Closes at the first `}`; trailing content is an error, not folded in.
+ assert_eq!(
+ parse("k={a}b}").unwrap_err(),
+ "unexpected characters after a `{…}` value; quote with '' or \"\" if the value contains `}`"
+ );
+ assert_eq!(value("k={a}", "k").as_deref(), Some("a"));
+ }
+
+ #[test]
+ fn trailing_junk_after_quote_is_rejected() {
+ assert_eq!(
+ parse("k='ab'x").unwrap_err(),
+ "unexpected characters after a quoted value"
+ );
+ assert_eq!(
+ parse("k=\"ab\"x").unwrap_err(),
+ "unexpected characters after a quoted value"
+ );
+ // Trailing whitespace after a closing quote is fine.
+ assert_eq!(value("k='ab' ;n=1", "k").as_deref(), Some("ab"));
+ }
+
+ #[test]
+ fn empty_quoted_value() {
+ assert_eq!(value("k=''", "k").as_deref(), Some(""));
+ assert_eq!(value("k=\"\"", "k").as_deref(), Some(""));
+ assert_eq!(value("k={}", "k").as_deref(), Some(""));
+ }
+
+ #[test]
+ fn ascii_control_bytes_are_not_treated_as_trim_whitespace() {
+ // A trailing vertical tab (0x0B) is content, not whitespace: it must be
+ // preserved, consistently with the leading-whitespace skip which also
+ // ignores 0x0B. (str::trim_end would wrongly strip it.)
+ assert_eq!(
+ value("k=secret\u{000B}", "k").as_deref(),
+ Some("secret\u{000B}")
+ );
+ // Ordinary ASCII whitespace is still trimmed when unquoted.
+ assert_eq!(value("k=secret\t ", "k").as_deref(), Some("secret"));
+ // Keys use the same ASCII-whitespace definition: ASCII spaces are
+ // trimmed, but a 0x0B is content (kept), consistent with values.
+ assert_eq!(value(" k =v", "k").as_deref(), Some("v"));
+ assert_eq!(value("k\u{000B}=v", "k\u{000B}").as_deref(), Some("v"));
+ }
+
+ #[test]
+ fn duplicate_keys_last_wins() {
+ assert_eq!(value("k=a;k=b;k=c", "k").as_deref(), Some("c"));
+ }
+
+ #[test]
+ fn server_value_passes_through_raw() {
+ assert_eq!(
+ value("Server=tcp:host.example.com,1433", "server").as_deref(),
+ Some("tcp:host.example.com,1433")
+ );
+ assert_eq!(
+ value("Server=host\\instance", "server").as_deref(),
+ Some("host\\instance")
+ );
+ }
+
+ #[test]
+ fn error_reasons() {
+ assert_eq!(
+ parse("=value").unwrap_err(),
+ "a key in the connection string is empty"
+ );
+ assert_eq!(
+ parse("k=a;b").unwrap_err(),
+ "key-value pairs must be joined by a `=`"
+ );
+ assert_eq!(
+ parse("k='ab").unwrap_err(),
+ "the connection string has an unclosed single quote"
+ );
+ assert_eq!(
+ parse("k=\"ab").unwrap_err(),
+ "the connection string has an unclosed double quote"
+ );
+ assert_eq!(
+ parse("k={ab").unwrap_err(),
+ "the connection string has an unclosed brace `{`"
+ );
+ assert!(parse("k=café").is_err());
+ }
+
+ // Every printable-ASCII character must round-trip verbatim inside single
+ // quotes (with `'` doubled) and inside double quotes (with `"` doubled).
+ #[test]
+ fn exhaustive_ascii_roundtrip_in_quotes() {
+ for byte in 0x20u8..=0x7e {
+ let c = byte as char;
+
+ let inner = if c == '\'' {
+ "a''b".to_string()
+ } else {
+ format!("a{c}b")
+ };
+ let expected = format!("a{c}b");
+ assert_eq!(
+ value(&format!("k='{inner}'"), "k").as_deref(),
+ Some(expected.as_str()),
+ "char {c:?} (0x{byte:02x}) via single quotes"
+ );
+
+ let inner = if c == '"' {
+ "a\"\"b".to_string()
+ } else {
+ format!("a{c}b")
+ };
+ assert_eq!(
+ value(&format!("k=\"{inner}\""), "k").as_deref(),
+ Some(expected.as_str()),
+ "char {c:?} (0x{byte:02x}) via double quotes"
+ );
+ }
+ }
+
+ // Unquoted values round-trip verbatim for every printable-ASCII character
+ // that is not structural in that position (`;`, and a leading `'`/`"`/`{`).
+ #[test]
+ fn exhaustive_ascii_roundtrip_unquoted_where_legal() {
+ for byte in 0x21u8..=0x7e {
+ let c = byte as char;
+ if c == ';' {
+ continue; // separator: cannot appear unquoted
+ }
+ // Placed after a leading letter so `'`/`"`/`{` are not value-leading.
+ let raw = format!("a{c}b");
+ assert_eq!(
+ value(&format!("k={raw}"), "k").as_deref(),
+ Some(raw.as_str()),
+ "char {c:?} (0x{byte:02x}) unquoted"
+ );
+ }
+ }
+}
diff --git a/src/client/config/jdbc.rs b/src/client/config/jdbc.rs
index 4168cf975..d9577ee72 100644
--- a/src/client/config/jdbc.rs
+++ b/src/client/config/jdbc.rs
@@ -11,7 +11,14 @@ impl FromStr for JdbcConfig {
type Err = Error;
fn from_str(s: &str) -> crate::Result {
- let config = s.parse()?;
+ let config = s.parse().map_err(|e| {
+ super::connection_string_error(
+ e,
+ "wrap the value in braces (e.g. `password={p@ss;word}`); single \
+ and double quotes are ordinary characters in JDBC, not escapes",
+ "Config::from_jdbc_string",
+ )
+ })?;
Ok(Self { config })
}
}
@@ -259,6 +266,141 @@ mod tests {
Ok(())
}
+ #[test]
+ fn parsing_password_special_characters() -> crate::Result<()> {
+ // (value as written after `Password=`, exact parsed password). Unlike
+ // ADO.NET, the JDBC parser only supports brace (`{...}`) quoting — not
+ // single or double quotes — so `'` and `"` are ordinary characters.
+ let cases: &[(&str, &str)] = &[
+ // Braces are required for structural characters.
+ ("{a;b}", "a;b"),
+ ("{a=b}", "a=b"),
+ ("{a:b}", "a:b"),
+ ("{a b}", "a b"),
+ ("{a$b}", "a$b"),
+ ("{a'b}", "a'b"),
+ ("{a\"b}", "a\"b"),
+ // `\`, `/`, `[` and `]` are structural in JDBC values and need
+ // braces (they would otherwise terminate the value).
+ ("{a\\b}", "a\\b"),
+ ("{a/b}", "a/b"),
+ ("{a[b]}", "a[b]"),
+ // Non-structural characters pass through unquoted, including `}`,
+ // `'` and `"` (which are not special to the JDBC parser).
+ ("a$b", "a$b"),
+ ("a@b", "a@b"),
+ ("a!b", "a!b"),
+ ("a#b", "a#b"),
+ ("a%b", "a%b"),
+ ("a&b", "a&b"),
+ ("a,b", "a,b"),
+ ("a'b", "a'b"),
+ ("a\"b", "a\"b"),
+ ("a}b", "a}b"),
+ ("a b", "a b"),
+ // Percent-encoding is NOT decoded: `%24` stays literal.
+ ("a%24b", "a%24b"),
+ ];
+
+ for (value, expected) in cases {
+ let s = format!("jdbc:sqlserver://host.com:1433;User ID=sa;Password={value}");
+ let jdbc: JdbcConfig = s.parse()?;
+ assert_eq!(
+ AuthMethod::sql_server("sa", *expected),
+ jdbc.authentication()?,
+ "value `{value}` should parse to password `{expected}`"
+ );
+ }
+
+ Ok(())
+ }
+
+ #[test]
+ fn parsing_password_preserves_surrounding_whitespace() -> crate::Result<()> {
+ // Unlike the ADO parser, JDBC does not trim; braced whitespace is kept.
+ let jdbc: JdbcConfig =
+ "jdbc:sqlserver://host.com:1433;User ID=sa;Password={ a }".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", " a "), jdbc.authentication()?);
+
+ Ok(())
+ }
+
+ #[test]
+ fn parsing_password_brace_cannot_hold_close_brace() -> crate::Result<()> {
+ // Like ADO.NET, JDBC brace quoting has no `}}` doubling: the brace
+ // closes at the first `}`, so the inner `}` is consumed as the
+ // terminator. Since JDBC has no quote escaping, a value needing braces
+ // that also contains `}` cannot be represented — document the limit.
+ let jdbc: JdbcConfig =
+ "jdbc:sqlserver://host.com:1433;User ID=sa;Password={a}b}".parse()?;
+ assert_eq!(AuthMethod::sql_server("sa", "ab}"), jdbc.authentication()?);
+
+ Ok(())
+ }
+
+ #[test]
+ fn parsing_password_non_ascii_is_rejected() {
+ // The JDBC parser only accepts ASCII, in every position; non-ASCII
+ // passwords must use the programmatic `Config` API instead.
+ assert!("jdbc:sqlserver://host.com:1433;User ID=sa;Password=café"
+ .parse::()
+ .is_err());
+ // Braces are JDBC's only quoting mechanism; non-ASCII is rejected there
+ // too (mirrors the ADO quoted-value test).
+ assert!("jdbc:sqlserver://host.com:1433;User ID=sa;Password={café}"
+ .parse::()
+ .is_err());
+ }
+
+ #[test]
+ fn empty_password_is_rejected() {
+ // Unlike the ADO parser (which accepts an empty value), the JDBC parser
+ // requires a non-empty property value, so `Password=` fails to parse.
+ assert!("jdbc:sqlserver://host.com:1433;User ID=sa;Password="
+ .parse::()
+ .is_err());
+ }
+
+ #[test]
+ fn unquoted_special_char_password_error_has_hint() {
+ // An unquoted `;` in a password breaks parsing. The error must guide
+ // the user toward brace quoting (JDBC's only escape) or the programmatic
+ // API, while preserving the underlying parser message.
+ let err = "jdbc:sqlserver://host.com:1433;User ID=sa;Password=a;b"
+ .parse::()
+ .err()
+ .unwrap();
+ let msg = err.to_string();
+ // Underlying terse parser message is preserved (not replaced).
+ assert!(msg.contains("must be joined"), "message was: {msg}");
+ // JDBC guidance must steer toward braces and its own constructor docs.
+ assert!(msg.contains("braces"), "message was: {msg}");
+ assert!(
+ msg.contains("Config::from_jdbc_string"),
+ "message was: {msg}"
+ );
+ // The `Conversion error:` prefix must not be doubled.
+ assert!(
+ !msg.contains("Conversion error: Conversion error:"),
+ "message was: {msg}"
+ );
+ }
+
+ #[test]
+ fn unclosed_brace_error_has_hint() {
+ // An unclosed brace is a quoting mistake; the hint should attach.
+ let err = "jdbc:sqlserver://host.com:1433;User ID=sa;Password={abc"
+ .parse::()
+ .err()
+ .unwrap();
+ let msg = err.to_string();
+ assert!(msg.contains("must be quoted"), "message was: {msg}");
+ assert!(
+ !msg.contains("Conversion error: Conversion error:"),
+ "message was: {msg}"
+ );
+ }
+
#[test]
#[cfg(any(
feature = "rustls",
@@ -314,7 +456,109 @@ mod tests {
let test_str = "jdbc:sqlserver://my-server.com:4200;";
let jdbc: JdbcConfig = test_str.parse()?;
- assert_eq!(EncryptionLevel::Off, jdbc.encrypt()?);
+ assert_eq!(EncryptionLevel::Required, jdbc.encrypt()?);
+
+ Ok(())
+ }
+
+ // No-TLS build: an explicit encryption request must error (not silently
+ // downgrade to plaintext, #305); opting out and an omitted keyword stay
+ // `NotSupported`.
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_on_errors_without_tls_backend() -> crate::Result<()> {
+ for enc in ["true", "yes"] {
+ let test_str = format!("jdbc:sqlserver://my-server.com:4200;encrypt={enc};");
+ let jdbc: JdbcConfig = test_str.parse()?;
+ let err = jdbc.encrypt().unwrap_err();
+ assert!(
+ matches!(err, crate::Error::Tls(_)),
+ "expected Error::Tls for {test_str}, got {err:?}"
+ );
+ let msg = err.to_string();
+ assert!(msg.contains("without a TLS backend"), "message was: {msg}");
+ }
+
+ Ok(())
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_strict_errors_without_tls_backend() {
+ let jdbc: JdbcConfig = "jdbc:sqlserver://my-server.com:4200;encrypt=strict;"
+ .parse()
+ .unwrap();
+ let err = jdbc.encrypt().unwrap_err();
+ assert!(
+ matches!(err, crate::Error::Tls(_)),
+ "expected Error::Tls, got {err:?}"
+ );
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_mandatory_errors_without_tls_backend() {
+ // `mandatory` is not an accepted token in either build; the with-TLS
+ // parser rejects it as a bad boolean, so the no-TLS branch mirrors that
+ // (still an error, just not the TLS-missing one).
+ let jdbc: JdbcConfig = "jdbc:sqlserver://my-server.com:4200;encrypt=mandatory;"
+ .parse()
+ .unwrap();
+ assert!(jdbc.encrypt().is_err());
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_off_ok_without_tls_backend() -> crate::Result<()> {
+ for enc in ["false", "no"] {
+ let test_str = format!("jdbc:sqlserver://my-server.com:4200;encrypt={enc};");
+ let jdbc: JdbcConfig = test_str.parse()?;
+ assert_eq!(crate::EncryptionLevel::NotSupported, jdbc.encrypt()?);
+ }
+
+ Ok(())
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_plaintext_ok_without_tls_backend() -> crate::Result<()> {
+ let jdbc: JdbcConfig =
+ "jdbc:sqlserver://my-server.com:4200;encrypt=DANGER_PLAINTEXT;".parse()?;
+ assert_eq!(crate::EncryptionLevel::NotSupported, jdbc.encrypt()?);
+
+ Ok(())
+ }
+
+ #[test]
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
+ fn encryption_parsing_missing_ok_without_tls_backend() -> crate::Result<()> {
+ let jdbc: JdbcConfig = "jdbc:sqlserver://my-server.com:4200;".parse()?;
+ assert_eq!(crate::EncryptionLevel::NotSupported, jdbc.encrypt()?);
Ok(())
}
diff --git a/src/client/connection.rs b/src/client/connection.rs
index 6467a8eec..707f94f34 100644
--- a/src/client/connection.rs
+++ b/src/client/connection.rs
@@ -18,9 +18,14 @@ use crate::{
};
use asynchronous_codec::Framed;
use bytes::BytesMut;
-#[cfg(any(windows, feature = "integrated-auth-gssapi", feature = "winauth"))]
+#[cfg(any(
+ windows,
+ feature = "winauth",
+ feature = "integrated-auth-gssapi",
+ feature = "sspi-rs"
+))]
use codec::TokenSspi;
-use futures_util::io::{AsyncRead, AsyncWrite};
+use futures_util::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
use futures_util::ready;
use futures_util::sink::SinkExt;
use futures_util::stream::{Stream, TryStream, TryStreamExt};
@@ -32,15 +37,24 @@ use libgssapi::{
oid::{OidSet, GSS_MECH_KRB5, GSS_NT_KRB5_PRINCIPAL},
};
use pretty_hex::*;
+use secrecy::ExposeSecret;
+#[cfg(all(unix, feature = "sspi-rs"))]
+use sspi::{
+ AuthIdentity, BufferType, ClientRequestFlags, CredentialUse, DataRepresentation, Ntlm,
+ SecurityBuffer, Sspi, SspiImpl, Username,
+};
#[cfg(all(unix, feature = "integrated-auth-gssapi"))]
use std::ops::Deref;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
use std::{cmp, fmt::Debug, io, pin::Pin, task};
use task::Poll;
use tracing::{event, Level};
#[cfg(all(windows, feature = "winauth"))]
use winauth::windows::NtlmSspiBuilder;
-#[cfg(feature = "winauth")]
+#[cfg(all(feature = "winauth", not(all(unix, feature = "sspi-rs"))))]
use winauth::NextBytes;
+use zeroize::{Zeroize, Zeroizing};
/// A `Connection` is an abstraction between the [`Client`] and the server. It
/// can be used as a `Stream` to fetch [`Packet`]s from and to `send` packets
@@ -59,6 +73,23 @@ where
flushed: bool,
context: Context,
buf: BytesMut,
+ /// Set for the duration of a multi-packet write. A message is only partly
+ /// on the wire while this is `true`; if the writing future is dropped
+ /// (a cancelled `query`/`execute`, a `select!` losing the race, a
+ /// `tokio::time::timeout` firing) the flag stays set, so the next write on
+ /// the same connection fails cleanly instead of appending a second message
+ /// after a half-sent one and silently desyncing the server.
+ poisoned: bool,
+ /// Set when a `command_timeout` fires mid-response. The tail of the
+ /// timed-out response is then still unread on the wire, so the connection is
+ /// out of sync with the server and must not be reused. This handle is shared
+ /// with the token stream's `RoundTripTimeout`, which flips it when its
+ /// deadline elapses; [`ensure_not_poisoned`] rejects every subsequent use so
+ /// a pool discards the connection instead of hanging in `flush_stream` on
+ /// the still-pending previous response.
+ ///
+ /// [`ensure_not_poisoned`]: Self::ensure_not_poisoned
+ command_desync: Arc,
}
impl Debug for Connection {
@@ -73,14 +104,76 @@ impl Debug for Connection {
}
impl Connection {
- /// Creates a new connection
+ /// Creates a new connection.
+ ///
+ /// Note: `tcp_stream` is a connected stream, so some parts of the
+ /// [`Config`] need to be handled outside of this method.
+ ///
+ /// The handshake performed here (prelogin, TLS negotiation and login) is
+ /// bounded by [`Config::handshake_timeout`]: if the server accepts the TCP
+ /// connection but then stalls mid-handshake (for example a TLS handshake
+ /// that never completes), the connect future fails with a
+ /// [`std::io::ErrorKind::TimedOut`] error instead of hanging forever. Enable
+ /// `tracing` at `DEBUG` to see which stage was last reached.
pub(crate) async fn connect(config: Config, tcp_stream: S) -> crate::Result> {
+ let handshake_timeout = config.handshake_timeout;
+ with_optional_timeout(handshake_timeout, Self::establish(config, tcp_stream)).await
+ }
+
+ /// Performs the full connection handshake (prelogin, TLS negotiation and
+ /// login) over an already-connected `tcp_stream`.
+ ///
+ /// Split out from [`connect`](Self::connect) so the whole handshake can be
+ /// wrapped in a single [`Config::handshake_timeout`] bound; on its own it
+ /// runs unbounded and would block forever if the server stalls.
+ async fn establish(config: Config, tcp_stream: S) -> crate::Result> {
+ // Captured before `config` is consumed below and applied to the
+ // `Context` only *after* the handshake completes (see the end of this
+ // method). Arming it up front would also bound the login-ack/SSPI drain
+ // that runs through the same token stream (`flush_done`/`flush_sspi`)
+ // during connect, which is wrong: that whole handshake is governed by
+ // `handshake_timeout` alone, so `handshake_timeout(None)` must genuinely
+ // wait indefinitely regardless of `command_timeout`.
+ let command_timeout = config.command_timeout;
+
let context = {
let mut context = Context::new();
context.set_spn(config.get_host(), config.get_port());
+ // Row-decode preference; unrelated to handshake timing, so set it up
+ // front alongside the SPN.
+ context.set_lossy_utf16(config.lossy_utf16_decoding);
+ context.set_lossy_codepage(config.lossy_codepage_decoding);
context
};
+ // In TDS 8.0 "strict" mode the TLS handshake happens *before* the
+ // prelogin, so we wrap the stream in TLS up front. In every other mode
+ // the connection starts in the clear and TLS (if any) is negotiated
+ // during the prelogin.
+ #[cfg(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ ))]
+ let transport = match config.encryption {
+ EncryptionLevel::Strict => {
+ event!(Level::DEBUG, "Performing a TLS handshake (TDS 8.0 strict)");
+ let mut pre_login_stream = TlsPreloginWrapper::new(tcp_stream);
+ // No prelogin framing is used for the strict handshake; pass the
+ // raw TLS bytes straight through.
+ pre_login_stream.handshake_complete();
+ let stream = create_tls_stream(&config, pre_login_stream).await?;
+ event!(Level::DEBUG, "TLS handshake successful");
+ Framed::new(MaybeTlsStream::Tls(stream), PacketCodec)
+ }
+ _ => Framed::new(MaybeTlsStream::Raw(tcp_stream), PacketCodec),
+ };
+
+ #[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+ )))]
let transport = Framed::new(MaybeTlsStream::Raw(tcp_stream), PacketCodec);
let mut connection = Self {
@@ -88,18 +181,31 @@ impl Connection {
context,
flushed: false,
buf: BytesMut::new(),
+ poisoned: false,
+ command_desync: Arc::new(AtomicBool::new(false)),
};
let fed_auth_required = matches!(config.auth, AuthMethod::AADToken(_));
+ event!(Level::DEBUG, "Handshake stage: sending TDS prelogin");
let prelogin = connection
- .prelogin(config.encryption, fed_auth_required)
+ .prelogin(
+ config.encryption,
+ fed_auth_required,
+ config.instance_name.clone(),
+ )
.await?;
- let encryption = prelogin.negotiated_encryption(config.encryption);
+ let encryption = prelogin.negotiated_encryption(config.encryption)?;
+ event!(
+ Level::DEBUG,
+ "Handshake stage: prelogin complete, negotiated encryption = {:?}",
+ encryption
+ );
let connection = connection.tls_handshake(&config, encryption).await?;
+ event!(Level::DEBUG, "Handshake stage: sending login");
let mut connection = connection
.login(
config.auth,
@@ -107,12 +213,21 @@ impl Connection {
config.database,
config.host,
config.application_name,
+ config.client_name,
config.readonly,
+ config.packet_size,
prelogin,
)
.await?;
connection.flush_done().await?;
+ event!(Level::DEBUG, "Handshake stage: login complete");
+
+ // The handshake is done; arm the per-response command timeout now so it
+ // only ever bounds command result reads, never the handshake above.
+ connection
+ .context_mut()
+ .set_command_timeout(command_timeout);
Ok(connection)
}
@@ -122,7 +237,12 @@ impl Connection {
TokenStream::new(self).flush_done().await
}
- #[cfg(any(windows, feature = "integrated-auth-gssapi", feature = "winauth"))]
+ #[cfg(any(
+ windows,
+ feature = "winauth",
+ feature = "integrated-auth-gssapi",
+ feature = "sspi-rs"
+ ))]
/// Flush the incoming token stream until receiving `SSPI` token.
async fn flush_sspi(&mut self) -> crate::Result {
TokenStream::new(self).flush_sspi().await
@@ -168,12 +288,17 @@ impl Connection {
where
E: Sized + Encode,
{
+ self.ensure_not_poisoned()?;
self.flushed = false;
let packet_size = (self.context.packet_size() as usize) - HEADER_BYTES;
let mut payload = BytesMut::new();
item.encode(&mut payload)?;
+ // Mark the connection poisoned across the multi-packet write; a clean
+ // completion clears it below. A future dropped mid-loop leaves it set.
+ self.poisoned = true;
+
while !payload.is_empty() {
let writable = cmp::min(payload.len(), packet_size);
let split_payload = payload.split_to(writable);
@@ -194,6 +319,95 @@ impl Connection {
}
self.flush_sink().await?;
+ self.poisoned = false;
+
+ Ok(())
+ }
+
+ /// Returns an error if a previous multi-packet write on this connection was
+ /// interrupted (e.g. the query/execute future was cancelled), which would
+ /// have left a partial message on the wire. The connection cannot be safely
+ /// reused in that state and should be dropped.
+ pub(crate) fn ensure_not_poisoned(&self) -> crate::Result<()> {
+ if self.poisoned {
+ return Err(crate::Error::Protocol(
+ "connection was left in an inconsistent state by a cancelled write and can no longer be used; open a new connection"
+ .into(),
+ ));
+ }
+ if self.command_desync.load(Ordering::Acquire) {
+ return Err(crate::Error::Protocol(
+ "connection was left out of sync with the server by a command timeout (the previous response is only partly read) and can no longer be used; open a new connection"
+ .into(),
+ ));
+ }
+ Ok(())
+ }
+
+ /// A handle to the command-timeout desync flag, shared with the token stream
+ /// so it can mark the connection unusable when a `command_timeout` fires
+ /// mid-response. See the `command_desync` field.
+ pub(crate) fn command_desync_flag(&self) -> Arc {
+ Arc::clone(&self.command_desync)
+ }
+
+ /// Marks the connection poisoned for the duration of a multi-packet write.
+ ///
+ /// Exposed to the bulk-load write path (`BulkLoadRequest`), which writes its
+ /// messages by calling [`write_to_wire`] directly rather than through
+ /// [`send`]. It must bracket those write loops with `poison`/[`unpoison`] so
+ /// that a dropped future (cancelled bulk insert, `select!`, `timeout`) leaves
+ /// the connection unusable instead of silently reused after a half-sent
+ /// message — the same guarantee `send`/`cancel_request` get from their inline
+ /// bracketing. This is deliberately *not* folded into `write_to_wire`: that
+ /// method is called once per packet inside `send`'s loop, so clearing the
+ /// flag there would drop the poison between packets of a multi-packet send
+ /// and destroy the very protection `send` relies on.
+ ///
+ /// [`write_to_wire`]: Self::write_to_wire
+ /// [`send`]: Self::send
+ /// [`unpoison`]: Self::unpoison
+ pub(crate) fn poison(&mut self) {
+ self.poisoned = true;
+ }
+
+ /// Clears the poisoned flag after a multi-packet write completes cleanly.
+ /// The counterpart to [`poison`](Self::poison); see its docs.
+ pub(crate) fn unpoison(&mut self) {
+ self.poisoned = false;
+ }
+
+ async fn send_sensitive_login(
+ &mut self,
+ header: PacketHeader,
+ mut payload: Zeroizing>,
+ ) -> crate::Result<()> {
+ self.ensure_not_poisoned()?;
+ self.flushed = false;
+ let packet_size = (self.context.packet_size() as usize) - HEADER_BYTES;
+
+ // Frame the login into zeroizable packets off the shared `BytesMut`
+ // path. Each frame is a `Zeroizing` wiped on drop at the end of its
+ // loop iteration, so no explicit call is needed there; `payload` is
+ // zeroized right after framing to drop the plaintext copy before the
+ // network-write loop's awaits.
+ let frames = frame_sensitive_login(header, &payload[..], packet_size)?;
+ payload.zeroize();
+
+ // Mark the connection poisoned across the multi-frame write, exactly
+ // like `send`/`cancel_request`: if the writing future is dropped
+ // mid-loop the login is only partly on the wire and the connection must
+ // not be silently reused. A clean flush clears it below.
+ self.poisoned = true;
+
+ for frame in frames {
+ event!(Level::TRACE, "Sending a packet ({} bytes)", frame.len(),);
+
+ self.transport.write_all(&frame[..]).await?;
+ }
+
+ (&mut *self.transport).flush().await?;
+ self.poisoned = false;
Ok(())
}
@@ -222,6 +436,43 @@ impl Connection {
self.transport.flush().await
}
+ /// Sends a TDS Attention signal (packet type `0x06`, MS-TDS section
+ /// 2.2.1.6) to request cancellation of the request currently in flight on
+ /// this connection, then drains the token stream until the acknowledging
+ /// DONE token (with the `DONE_ATTN` status bit set) is received.
+ ///
+ /// The Attention message carries no payload, so it is written to the wire
+ /// as a single end-of-message packet. Draining the acknowledgement leaves
+ /// the connection clean and ready to be reused for further queries.
+ pub(crate) async fn cancel_request(&mut self) -> crate::Result {
+ // Consistency with the other write paths (`send`,
+ // `send_sensitive_login`, `flush_stream`): if a previous multi-packet
+ // write was interrupted, the connection is already desynced with a
+ // partial message sitting on the wire. Appending an Attention packet
+ // after that half-sent message would corrupt the stream further and the
+ // acknowledging DONE could never be matched, so fail fast instead. A
+ // legitimate cancel targets an in-flight request, which means the prior
+ // `send` completed and cleared the flag, so this guard never rejects a
+ // valid cancellation.
+ self.ensure_not_poisoned()?;
+
+ let id = self.context.next_packet_id();
+ let header = PacketHeader::attention(id);
+
+ // Mark the connection poisoned across the write, exactly like `send`:
+ // the Attention is a single end-of-message packet, but if the writing
+ // future is dropped mid-flight the header is only partly on the wire and
+ // the connection must not be silently reused. A clean flush clears it.
+ self.poisoned = true;
+
+ // Attention has an empty payload; send just the 8-byte header.
+ self.write_to_wire(header, BytesMut::new()).await?;
+ self.flush_sink().await?;
+ self.poisoned = false;
+
+ TokenStream::new(self).flush_done_attention().await
+ }
+
/// Cleans the packet stream from previous use. It is important to use the
/// whole stream before using the connection again. Flushing the stream
/// makes sure we don't have any old data causing undefined behaviour after
@@ -230,22 +481,42 @@ impl Connection {
/// Calling this will slow down the queries if stream is still dirty if all
/// results are not handled.
pub async fn flush_stream(&mut self) -> crate::Result<()> {
+ // If a previous write was cancelled mid-message the connection is
+ // already known-bad; fail fast rather than layering a new request on
+ // top of it.
+ self.ensure_not_poisoned()?;
+
+ // Discard any partially-consumed packet payload, then drain whole
+ // packets up to the end-of-message marker. Truncating `buf` and
+ // re-reading on packet boundaries resynchronises the token stream even
+ // if a previous result stream was dropped part-way through a value
+ // (the lost bytes belonged to a packet we are discarding anyway).
self.buf.truncate(0);
if self.flushed {
return Ok(());
}
- while let Some(packet) = self.try_next().await? {
- event!(
- Level::WARN,
- "Flushing unhandled packet from the wire. Please consume your streams!",
- );
+ loop {
+ match self.try_next().await {
+ Ok(Some(packet)) => {
+ event!(
+ Level::WARN,
+ "Flushing unhandled packet from the wire. Please consume your streams!",
+ );
- let is_last = packet.is_last();
-
- if is_last {
- break;
+ if packet.is_last() {
+ break;
+ }
+ }
+ Ok(None) => break,
+ // The stream could not be drained cleanly (e.g. it was
+ // abandoned at an unrecoverable offset). Poison the connection
+ // so it is not silently reused in an inconsistent state.
+ Err(e) => {
+ self.poisoned = true;
+ return Err(e);
+ }
}
}
@@ -270,10 +541,12 @@ impl Connection {
&mut self,
encryption: EncryptionLevel,
fed_auth_required: bool,
+ instance_name: Option,
) -> crate::Result {
let mut msg = PreloginMessage::new();
msg.encryption = encryption;
msg.fed_auth_required = fed_auth_required;
+ msg.instance_name = instance_name.clone();
let id = self.context.next_packet_id();
self.send(PacketHeader::pre_login(id), msg).await?;
@@ -281,20 +554,24 @@ impl Connection {
let response: PreloginMessage = codec::collect_from(self).await?;
// threadid (should be empty when sent from server to client)
debug_assert_eq!(response.thread_id, 0);
+ // ensure the server accepted the instance we asked it to validate
+ response.validate_instance(instance_name.as_deref())?;
Ok(response)
}
/// Defines the login record rules with SQL Server. Authentication with
/// connection options.
#[allow(clippy::too_many_arguments)]
- async fn login<'a>(
+ async fn login(
mut self,
auth: AuthMethod,
encryption: EncryptionLevel,
db: Option,
server_name: Option,
application_name: Option,
+ client_name: Option,
readonly: bool,
+ packet_size: Option,
prelogin: PreloginMessage,
) -> crate::Result {
let mut login_message = LoginMessage::new();
@@ -311,8 +588,16 @@ impl Connection {
login_message.app_name(app_name);
}
+ if let Some(client_name) = client_name {
+ login_message.hostname(client_name);
+ }
+
login_message.readonly(readonly);
+ if let Some(size) = packet_size {
+ login_message.packet_size(size);
+ }
+
match auth {
#[cfg(all(windows, feature = "winauth"))]
AuthMethod::Integrated => {
@@ -334,31 +619,37 @@ impl Connection {
event!(Level::TRACE, sspi_response_len = sspi_response.len());
let id = self.context.next_packet_id();
- let header = PacketHeader::login(id);
+ let header = PacketHeader::sspi(id);
let token = TokenSspi::new(sspi_response);
self.send(header, token).await?;
}
- None => unreachable!(),
+ None => {
+ return Err(crate::Error::Protocol(
+ "NTLM handshake produced no response to the server challenge".into(),
+ ))
+ }
}
}
#[cfg(all(unix, feature = "integrated-auth-gssapi"))]
AuthMethod::Integrated => {
- let mut s = OidSet::new()?;
- s.add(&GSS_MECH_KRB5)?;
+ let mut s = OidSet::new();
+ s.add(GSS_MECH_KRB5)?;
let client_cred = Cred::acquire(None, None, CredUsage::Initiate, Some(&s))?;
let mut ctx = ClientCtx::new(
Some(client_cred),
- Name::new(self.context.spn().as_bytes(), Some(&GSS_NT_KRB5_PRINCIPAL))?,
+ Name::new(self.context.spn().as_bytes(), Some(GSS_NT_KRB5_PRINCIPAL))?,
CtxFlags::GSS_C_MUTUAL_FLAG | CtxFlags::GSS_C_SEQUENCE_FLAG,
None,
);
- let init_token = ctx.step(None, None)?;
+ let init_token = ctx.step(None, None)?.ok_or_else(|| {
+ crate::Error::Protocol("GSSAPI produced no initial token".into())
+ })?;
- login_message.integrated_security(Some(Vec::from(init_token.unwrap().deref())));
+ login_message.integrated_security(Some(Vec::from(init_token.deref())));
let id = self.context.next_packet_id();
self.send(PacketHeader::login(id), login_message).await?;
@@ -383,11 +674,114 @@ impl Connection {
self.send(header, next_token).await?;
}
- #[cfg(feature = "winauth")]
+ #[cfg(all(unix, feature = "sspi-rs"))]
+ AuthMethod::Windows(auth) => {
+ let mut ntlm = Ntlm::new();
+
+ let username =
+ Username::new(&auth.user, auth.domain.as_deref()).map_err(sspi::Error::from)?;
+
+ // `auth.password` is a `SecretString`; sspi requires a
+ // plaintext `String`, but that single copy is *moved* (not
+ // cloned again) into `AuthIdentity.password`, which is
+ // `sspi::Secret` — a `#[derive(ZeroizeOnDrop)]` wrapper.
+ // The plaintext is therefore wiped when `identity` (and the
+ // credentials handle derived from it) is dropped; no
+ // un-zeroized copy is left behind. Expose the secret once, for
+ // this single `to_string()`, so no extra plaintext lingers
+ // here (`auth.password` zeroizes when this arm's `auth`
+ // drops).
+ let identity = AuthIdentity {
+ username,
+ password: auth.password.expose_secret().to_string().into(),
+ };
+
+ let mut creds = ntlm
+ .acquire_credentials_handle()
+ .with_credential_use(CredentialUse::Outbound)
+ .with_auth_data(&identity)
+ .execute(&mut ntlm)?;
+
+ let spn = self.context.spn().to_string();
+
+ // First leg of the NTLM handshake: produce the NEGOTIATE token
+ // and ship it in the login packet as integrated security data.
+ let mut input = vec![SecurityBuffer::new(Vec::new(), BufferType::Token)];
+ let mut output = vec![SecurityBuffer::new(Vec::new(), BufferType::Token)];
+
+ let mut builder = ntlm
+ .initialize_security_context()
+ .with_credentials_handle(&mut creds.credentials_handle)
+ .with_context_requirements(
+ ClientRequestFlags::CONFIDENTIALITY | ClientRequestFlags::ALLOCATE_MEMORY,
+ )
+ .with_target_data_representation(DataRepresentation::Native)
+ .with_target_name(&spn)
+ .with_input(&mut input)
+ .with_output(&mut output);
+
+ ntlm.initialize_security_context_impl(&mut builder)?
+ .resolve_to_result()?;
+
+ login_message.integrated_security(Some(output[0].buffer.clone()));
+
+ let id = self.context.next_packet_id();
+ self.send(PacketHeader::login(id), login_message).await?;
+ self = self.post_login_encryption(encryption);
+
+ // Second leg: consume the server's CHALLENGE token and reply
+ // with the AUTHENTICATE token.
+ let sspi_bytes = self.flush_sspi().await?;
+
+ let mut input = vec![SecurityBuffer::new(
+ sspi_bytes.as_ref().to_vec(),
+ BufferType::Token,
+ )];
+ let mut output = vec![SecurityBuffer::new(Vec::new(), BufferType::Token)];
+
+ let mut builder = ntlm
+ .initialize_security_context()
+ .with_credentials_handle(&mut creds.credentials_handle)
+ .with_context_requirements(
+ ClientRequestFlags::CONFIDENTIALITY | ClientRequestFlags::ALLOCATE_MEMORY,
+ )
+ .with_target_data_representation(DataRepresentation::Native)
+ .with_target_name(&spn)
+ .with_input(&mut input)
+ .with_output(&mut output);
+
+ ntlm.initialize_security_context_impl(&mut builder)?
+ .resolve_to_result()?;
+
+ event!(Level::TRACE, authenticate_len = output[0].buffer.len());
+
+ let id = self.context.next_packet_id();
+ self.send(
+ PacketHeader::login(id),
+ TokenSspi::new(output[0].buffer.clone()),
+ )
+ .await?;
+ }
+ // winauth's NTLMv2 client is pure Rust, so this arm serves every
+ // platform; on Unix the sspi-rs arm above wins when both are on.
+ #[cfg(all(feature = "winauth", not(all(unix, feature = "sspi-rs"))))]
AuthMethod::Windows(auth) => {
let spn = self.context.spn().to_string();
let builder = winauth::NtlmV2ClientBuilder::new().target_spn(spn);
- let mut client = builder.build(auth.domain, auth.user, auth.password);
+ // `auth.password` is a `SecretString`, but `winauth`
+ // 0.0.5's `build` takes the password by value as a plain
+ // `String` and neither zeroizes it nor exposes it afterwards, so
+ // it cannot be wiped once handed over. Expose it once for a
+ // single `to_string()` copy (no additional retained plaintext
+ // here) and accept a residual: the plaintext lives inside
+ // the `NtlmV2Client` until that value is dropped, un-zeroized.
+ // Closing this fully requires zeroize support upstream in
+ // `winauth`.
+ let mut client = builder.build(
+ auth.domain,
+ auth.user,
+ auth.password.expose_secret().to_string(),
+ );
login_message.integrated_security(client.next_bytes(None)?);
@@ -408,7 +802,11 @@ impl Connection {
let token = TokenSspi::new(sspi_response);
self.send(header, token).await?;
}
- None => unreachable!(),
+ None => {
+ return Err(crate::Error::Protocol(
+ "NTLM handshake produced no response to the server challenge".into(),
+ ))
+ }
}
}
AuthMethod::None => {
@@ -417,17 +815,38 @@ impl Connection {
self = self.post_login_encryption(encryption);
}
AuthMethod::SqlServer(auth) => {
- login_message.user_name(auth.user());
- login_message.password(auth.password());
+ let (user, mut password) = auth.into_credentials();
+
+ login_message.user_name(user);
+ // Expose the password only to hand it to the login message,
+ // which stores its own `SecretString` copy.
+ login_message.password(password.expose_secret());
+ let payload = login_message.encode_to_boxed_slice()?;
+ // Wipe the local copy immediately; `login_message` was consumed by
+ // `encode_to_boxed_slice` and its `SecretString` password was
+ // zeroized on drop there.
+ password.zeroize();
let id = self.context.next_packet_id();
- self.send(PacketHeader::login(id), login_message).await?;
+ self.send_sensitive_login(PacketHeader::login(id), payload)
+ .await?;
self = self.post_login_encryption(encryption);
}
AuthMethod::AADToken(token) => {
- login_message.aad_token(token, prelogin.fed_auth_required, prelogin.nonce);
+ // Expose the token only to hand it to the login message; the
+ // `SecretString` here is wiped on drop at the end of this arm,
+ // and the login message stores its own `SecretString` copy.
+ login_message.aad_token(
+ token.expose_secret(),
+ prelogin.fed_auth_required,
+ prelogin.nonce,
+ );
+ // Encode into a zeroizing buffer and use the sensitive-login
+ // path so the bearer token does not linger in freed heap memory.
+ let payload = login_message.encode_to_boxed_slice()?;
let id = self.context.next_packet_id();
- self.send(PacketHeader::login(id), login_message).await?;
+ self.send_sensitive_login(PacketHeader::login(id), payload)
+ .await?;
self = self.post_login_encryption(encryption);
}
}
@@ -446,37 +865,55 @@ impl Connection {
config: &Config,
encryption: EncryptionLevel,
) -> crate::Result {
- if encryption != EncryptionLevel::NotSupported {
- event!(Level::INFO, "Performing a TLS handshake");
-
- let Self {
- transport, context, ..
- } = self;
- let mut stream = match transport.into_inner() {
- MaybeTlsStream::Raw(tcp) => {
- create_tls_stream(config, TlsPreloginWrapper::new(tcp)).await?
- }
- _ => unreachable!(),
- };
+ match encryption {
+ EncryptionLevel::NotSupported => {
+ event!(
+ Level::WARN,
+ "TLS encryption is not enabled. All traffic including the login credentials are not encrypted."
+ );
- stream.get_mut().handshake_complete();
- event!(Level::INFO, "TLS handshake successful");
+ Ok(self)
+ }
+ // In strict mode the handshake already happened before the prelogin,
+ // so the transport is already a TLS stream. Nothing to do here.
+ EncryptionLevel::Strict => {
+ event!(
+ Level::TRACE,
+ "Already in a TLS stream (TDS 8.0 strict), skipping handshake."
+ );
- let transport = Framed::new(MaybeTlsStream::Tls(stream), PacketCodec);
+ Ok(self)
+ }
+ EncryptionLevel::Off | EncryptionLevel::On | EncryptionLevel::Required => {
+ event!(Level::DEBUG, "Performing a TLS handshake");
+
+ let Self {
+ transport,
+ context,
+ command_desync,
+ ..
+ } = self;
+ let mut stream = match transport.into_inner() {
+ MaybeTlsStream::Raw(tcp) => {
+ create_tls_stream(config, TlsPreloginWrapper::new(tcp)).await?
+ }
+ _ => unreachable!(),
+ };
- Ok(Self {
- transport,
- context,
- flushed: false,
- buf: BytesMut::new(),
- })
- } else {
- event!(
- Level::WARN,
- "TLS encryption is not enabled. All traffic including the login credentials are not encrypted."
- );
+ stream.get_mut().handshake_complete();
+ event!(Level::DEBUG, "TLS handshake successful");
+
+ let transport = Framed::new(MaybeTlsStream::Tls(stream), PacketCodec);
- Ok(self)
+ Ok(Self {
+ transport,
+ context,
+ flushed: false,
+ buf: BytesMut::new(),
+ poisoned: false,
+ command_desync,
+ })
+ }
}
}
@@ -486,7 +923,9 @@ impl Connection {
feature = "native-tls",
feature = "vendored-openssl"
)))]
- async fn tls_handshake(self, _: &Config, _: EncryptionLevel) -> crate::Result {
+ async fn tls_handshake(self, config: &Config, _: EncryptionLevel) -> crate::Result {
+ check_tls_backend_available(config.encryption)?;
+
event!(
Level::WARN,
"TLS encryption is not enabled. All traffic including the login credentials are not encrypted."
@@ -500,6 +939,284 @@ impl Connection {
}
}
+#[cfg(test)]
+impl Connection {
+ /// Builds a `Connection` over a caller-supplied mock `AsyncRead + AsyncWrite`
+ /// stream for server-free unit tests, bypassing the prelogin/login handshake.
+ ///
+ /// The buffer starts empty and `flushed` starts `false`, so the first read
+ /// pulls a packet from the mock transport; a default [`Context`] is used and
+ /// the `poisoned` flag is caller-controlled. This mirrors the real field
+ /// initialization in [`Connection::connect`] and is `#[cfg(test)]` only, so
+ /// it never ships. Shared by the poison-guard tests and the `TokenStream`
+ /// state-machine tests, which feed it canned TDS-framed bytes.
+ pub(crate) fn test_over(io: S, poisoned: bool) -> Connection {
+ Connection {
+ transport: Framed::new(MaybeTlsStream::Raw(io), PacketCodec),
+ flushed: false,
+ context: Context::new(),
+ buf: BytesMut::new(),
+ poisoned,
+ command_desync: Arc::new(AtomicBool::new(false)),
+ }
+ }
+}
+
+/// Returns an error when the user requested encryption but no TLS backend was
+/// compiled in. Without this check, a `Required`/`On` encryption request would
+/// silently fall back to an unencrypted connection.
+#[cfg(not(any(
+ feature = "rustls",
+ feature = "native-tls",
+ feature = "vendored-openssl"
+)))]
+fn check_tls_backend_available(encryption: EncryptionLevel) -> crate::Result<()> {
+ if let EncryptionLevel::On | EncryptionLevel::Required | EncryptionLevel::Strict = encryption {
+ return Err(crate::Error::Tls(
+ "TLS encryption was requested but the crate was compiled without a TLS backend. \
+ Enable one of the `native-tls`, `rustls` or `vendored-openssl` features."
+ .to_string(),
+ ));
+ }
+
+ Ok(())
+}
+
+/// Runs `fut` to completion, but fails with a clear [`crate::Error::Io`] of
+/// kind [`io::ErrorKind::TimedOut`] if it does not finish within `timeout`.
+///
+/// A `None` timeout runs the future unbounded (the pre-0.13 behaviour). The
+/// timer comes from `futures-timer`, whose `Delay` is runtime-agnostic, so this
+/// works under any executor driving the generic [`Connection::connect`] path —
+/// it does not assume tokio or smol. Used to bound the connection handshake so
+/// a server that accepts the TCP connection and then stalls yields
+/// a diagnosable error instead of an indefinite hang.
+async fn with_optional_timeout(
+ timeout: Option,
+ fut: F,
+) -> crate::Result
+where
+ F: std::future::Future