Addition: DataValue::VarChar, a string sent as varchar

A &str or String parameter goes as nvarchar, which against an indexed
varchar column under a SQL_* collation makes the server scan rather
than seek. DataValue::VarChar is sent as varchar in the server's
collation, as varchar(max) past 8000 bytes; a character the code page
lacks is an error before anything is sent. It reads and compares as
text. A varchar column still reads as Text.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: CommonwealthPasta

docs/types.md

@@ -129,13 +129,30 @@ implement `ToSql::null_type`.
 
 ## Parameter types and query plans
 
-A string parameter is always `nvarchar`. Compared with an indexed `varchar`
-column under one of the `SQL_*` collations, which is SQL Server's default on
-many installations, that makes the server convert the column rather than the
-parameter, and the index is scanned instead of sought. On 300,000 rows that
-was 20 ms a query instead of 0.4 ms. Cast the parameter in the SQL to get the
-seek back: `WHERE code = CAST(@P1 AS varchar(20))`. Windows collations such as
-`Latin1_General_CI_AS` are not affected.
+A `&str` or `String` parameter is sent as `nvarchar`. Compared with an indexed
+`varchar` column under one of the `SQL_*` collations, which is SQL Server's
+default on many installations, that makes the server convert the column rather
+than the parameter, and the index is scanned instead of sought. On 300,000
+rows that was 20 ms a query instead of 0.4 ms. Bind such a parameter as
+`DataValue::VarChar` and it is sent as `varchar` in the server's collation, so
+the index is sought:
+
+```rust,no_run
+# use tdsql::{Client, DataValue};
+# async fn f(client: &mut Client, code: &str) -> tdsql::Result<()> {
+let rows = client
+    .query(
+        "SELECT id FROM items WHERE code = @P1",
+        &[&DataValue::VarChar(code.into())],
+    )
+    .await?;
+# Ok(())
+# }
+```
+
+A character the server's code page cannot hold is an error at bind time, so
+keep `VarChar` for columns that are `varchar` themselves. Windows collations
+such as `Latin1_General_CI_AS` are not affected.
 
 A `Decimal` parameter is declared as `numeric(38, s)` with the value's own
 scale, so each distinct scale compiles its own plan for the same SQL, and the

src/client.rs

@@ -48,6 +48,7 @@ impl tds_driver::ToSql for DataValue {
             DataValue::Decimal(v) => v.to_sql(),
             DataValue::Bool(v) => C::Bit(Some(*v)),
             DataValue::Text(v) => C::String(Some(Cow::Borrowed(v.as_str()))),
+            DataValue::VarChar(v) => C::VarChar(Some(Cow::Borrowed(v.as_str()))),
             DataValue::Binary(v) => C::Binary(Some(Cow::Borrowed(v.as_slice()))),
             DataValue::Guid(v) => C::Guid(Some(*v)),
             DataValue::Date(v) => v.to_sql(),
@@ -104,6 +105,7 @@ impl<'a> tds_driver::IntoSql<'a> for DataValue {
         use tds_driver::ColumnData as C;
         match self {
             DataValue::Text(v) => C::String(Some(Cow::Owned(v))),
+            DataValue::VarChar(v) => C::VarChar(Some(Cow::Owned(v))),
             DataValue::Binary(v) => C::Binary(Some(Cow::Owned(v))),
             // Every other variant borrows nothing.
             other => match tds_driver::ToSql::to_sql(&other) {

src/value.rs

@@ -30,6 +30,15 @@ pub enum DataValue {
     Bool(bool),
     /// Any character or XML type.
     Text(String),
+    /// A string sent as `varchar`, in the server's collation, where
+    /// [`Text`](DataValue::Text) goes as `nvarchar`.
+    ///
+    /// Against an indexed `varchar` column under a `SQL_*` collation an
+    /// `nvarchar` parameter makes the server convert the column and scan the
+    /// index; a `varchar` parameter seeks. A character the collation's code
+    /// page lacks is an error at bind time. Only sent: a `varchar` column
+    /// still reads as `Text`.
+    VarChar(String),
     /// Any binary type.
     Binary(Vec<u8>),
     /// `uniqueidentifier`
@@ -69,6 +78,7 @@ impl DataValue {
             DataValue::Decimal(_) => "Decimal",
             DataValue::Bool(_) => "Bool",
             DataValue::Text(_) => "Text",
+            DataValue::VarChar(_) => "VarChar",
             DataValue::Binary(_) => "Binary",
             DataValue::Guid(_) => "Guid",
             DataValue::Date(_) => "Date",
@@ -490,7 +500,7 @@ impl_from_sql!(Decimal, "Decimal", |v| match v {
 });
 
 impl_from_sql!(String, "String", |v| match v {
-    DataValue::Text(s) => Some(s.clone()),
+    DataValue::Text(s) | DataValue::VarChar(s) => Some(s.clone()),
     _ => None,
 });
 
@@ -581,13 +591,16 @@ impl_partial_eq!(f64, |s, o| matches!(s, DataValue::Float(v) if v == o));
 impl_partial_eq!(Decimal, |s, o| matches!(s, DataValue::Decimal(v) if v == o));
 impl_partial_eq!(
     str,
-    |s, o| matches!(s, DataValue::Text(v) if v.as_str() == o)
+    |s, o| matches!(s, DataValue::Text(v) | DataValue::VarChar(v) if v.as_str() == o)
 );
 impl_partial_eq!(
     &str,
-    |s, o| matches!(s, DataValue::Text(v) if v.as_str() == *o)
+    |s, o| matches!(s, DataValue::Text(v) | DataValue::VarChar(v) if v.as_str() == *o)
+);
+impl_partial_eq!(
+    String,
+    |s, o| matches!(s, DataValue::Text(v) | DataValue::VarChar(v) if v == o)
 );
-impl_partial_eq!(String, |s, o| matches!(s, DataValue::Text(v) if v == o));
 impl_partial_eq!(Uuid, |s, o| matches!(s, DataValue::Guid(v) if v == o));
 impl_partial_eq!(NaiveDate, |s, o| matches!(s, DataValue::Date(v) if v == o));
 impl_partial_eq!(NaiveTime, |s, o| matches!(s, DataValue::Time(v) if v == o));

src/value/tests.rs

@@ -274,3 +274,14 @@ fn compares_equal_across_zones() {
     assert_ne!(value, utc + chrono::Duration::hours(1));
     assert_ne!(DataValue::Null, utc);
 }
+
+#[test]
+fn varchar_reads_and_compares_as_text() {
+    let v = DataValue::VarChar("abc".into());
+    assert_eq!(v.type_name(), "VarChar");
+    assert_eq!(get::<String>(v.clone()).unwrap(), "abc");
+    assert!(v == "abc");
+    let owned = String::from("abc");
+    assert!(v == owned);
+    assert!(v != "abd");
+}

tests/integration_test.rs

@@ -847,3 +847,54 @@ async fn datetime_parameters_can_be_sent_as_datetime_for_datetime_columns() {
 
     ddl(&mut client, "DROP TABLE dbo.tdsql_dt_legacy").await;
 }
+
+/// The wire type the server saw for a parameter, as `sql_variant` reports it.
+async fn param_type(client: &mut Client, value: &dyn ToSql) -> String {
+    client
+        .query_scalar(
+            "SELECT CAST(SQL_VARIANT_PROPERTY(ISNULL(@P1, ''), 'BaseType') AS nvarchar(30))",
+            &[value],
+        )
+        .await
+        .unwrap()
+}
+
+#[tokio::test]
+#[ignore]
+async fn varchar_values_are_sent_as_varchar() {
+    let mut client = connect().await;
+
+    assert_eq!(param_type(&mut client, &"abc").await, "nvarchar");
+    assert_eq!(
+        param_type(&mut client, &DataValue::VarChar("abc".into())).await,
+        "varchar"
+    );
+
+    // Round trip, by position and by name.
+    let name = DataValue::VarChar("Väinämöinen".into());
+    let back: String = client.query_scalar("SELECT @P1", &[&name]).await.unwrap();
+    assert_eq!(back, "Väinämöinen");
+    let cmd = Command::query("SELECT @name AS name").param("name", name);
+    let ds = client.query_dataset(&cmd).await.unwrap();
+    assert_eq!(ds[0][0].get::<String, _>("name"), "Väinämöinen");
+
+    // Over 8000 bytes it goes as varchar(max), whole.
+    let long = DataValue::VarChar("x".repeat(8001));
+    let len: i64 = client
+        .query_scalar("SELECT DATALENGTH(@P1)", &[&long])
+        .await
+        .unwrap();
+    assert_eq!(len, 8001);
+
+    // A character the server's code page lacks is an error before anything
+    // is sent, and the connection is still usable. (The test server's
+    // collation is SQL_Latin1_General_CP1_CI_AS, code page 1252.)
+    let err = client
+        .query_scalar::<String>("SELECT @P1", &[&DataValue::VarChar("日本".into())])
+        .await
+        .unwrap_err();
+    assert!(!err.is_connection_lost(), "{err:?}");
+    assert!(err.to_string().contains("SELECT @P1"), "{err}");
+    let one: i32 = client.query_scalar("SELECT 1", &[]).await.unwrap();
+    assert_eq!(one, 1);
+}