Improve documentation

Author: ozgurcancal

src/lib.rs

@@ -314,6 +314,19 @@ impl Client {
     }
 
     /// Starts a new SELECT/DDL query that will be used as-is without any processing.
+    ///
+    /// # Key Differences from `query()`
+    ///
+    /// - **No parameter binding**: Question marks are treated as literal characters
+    /// - **Raw SQL execution**: The query is sent to ClickHouse exactly as written
+    /// - **No SQL injection protection**: Since no parameter binding occurs, ensure
+    ///   your SQL is safe and doesn't contain user input
+    ///
+    /// # Parameters
+    ///
+    /// - **Input**: `&str` - the raw SQL query to be executed
+    /// - **Output**: [`Query`] - the query builder that executes the query
+    /// 
     pub fn query_raw(&self, query: &str) -> query::Query {
         query::Query::raw(self, query)
     }

src/query.rs

@@ -97,6 +97,7 @@ impl Query {
     /// # Ok(()) }
     /// ```
     pub fn fetch<T: Row>(mut self) -> Result<RowCursor<T>> {
+        // skip binding if raw query
         if !self.raw {
             self.sql.bind_fields::<T>();
         }

tests/it/query_raw.rs

@@ -17,7 +17,6 @@ async fn verify_raw_query_basic_functionality() {
     let client = prepare_database!();
 
     // The key test: verify that ? characters don't cause binding errors
-    // Use fetch_bytes to avoid the RowBinary format issue
     let result = client
         .query_raw("SELECT 1 WHERE 'test?' = 'test?'")
         .fetch_bytes("TSV")
@@ -50,21 +49,19 @@ async fn verify_raw_query_basic_functionality() {
 async fn fetch_with_single_field_struct() {
     let client = prepare_database!();
 
-    // Create a test table
     client
         .query("CREATE TABLE test_users(name String) ENGINE = Memory")
         .execute()
         .await
         .unwrap();
 
-    // Insert test data
     client
         .query_raw("INSERT INTO test_users VALUES ('Alice?'), ('Bob??'), ('Charlie???')")
         .execute()
         .await
         .unwrap();
 
-    // Test raw query with struct fetching (FORMAT is RowBinary by default)
+    // Test raw query with struct fetching 
     let sql = "SELECT name FROM test_users ORDER BY name";
 
     let mut cursor = client.query_raw(sql).fetch::<PersonName<'_>>().unwrap();
@@ -95,7 +92,7 @@ async fn fetch_with_multi_field_struct() {
         .await
         .unwrap();
 
-    // Test raw query with multi-field struct (FORMAT is RowBinary by default)
+    // Test raw query with multi-field struct 
     let sql = "SELECT name, age FROM test_persons ORDER BY age";
 
     let mut cursor = client.query_raw(sql).fetch::<PersonInfo>().unwrap();
@@ -119,14 +116,12 @@ async fn fetch_with_multi_field_struct() {
 async fn compare_raw_vs_regular_query_with_structs() {
     let client = prepare_database!();
 
-    // Create a test table
     client
         .query("CREATE TABLE test_comparison(name String) ENGINE = Memory")
         .execute()
         .await
         .unwrap();
 
-    // Insert test data
     client
         .query_raw("INSERT INTO test_comparison VALUES ('Alice?')")
         .execute()
@@ -144,7 +139,7 @@ async fn compare_raw_vs_regular_query_with_structs() {
         assert!(error_msg.contains("unbound"));
     }
 
-    // Raw query with ? should succeed (FORMAT will be added automatically)
+    // Raw query with ? should succeed )
     let raw_result = client
         .query_raw("SELECT name FROM test_comparison WHERE name = 'Alice?'")
         .fetch::<PersonName<'_>>()
@@ -286,6 +281,7 @@ async fn complex_sql_with_question_marks() {
 #[tokio::test]
 async fn query_raw_preserves_exact_sql() {
     let client = prepare_database!();
+//check client
 
     // Test that raw query preserves the exact SQL including whitespace and formatting
     let sql = "SELECT   1   WHERE   'test?'   =   'test?'   ";