Add support for raw queries without going through query builder (#234)

examples/README.md

@@ -8,7 +8,8 @@ If something is missing, or you found a mistake in one of these examples, please
 
 ### General usage
 
-- [usage.rs](usage.rs) - creating tables, executing other DDLs, inserting the data, and selecting it back. Optional cargo features: `inserter`.
+- [usage.rs](usage.rs) - creating tables, executing other DDLs, inserting the data, and selecting it back. Additionally, it covers `WATCH` queries. Optional cargo features: `inserter`, `watch`.
+- [query_raw.rs](query_raw.rs) - raw queries executes SQL queries exactly as written, without parameter binding or preprocessing. This allows queries containing literal question marks that would otherwise be treated as bind parameters. FORMAT is the RowBinary by default
 - [mock.rs](mock.rs) - writing tests with `mock` feature. Cargo features: requires `test-util`.
 - [inserter.rs](inserter.rs) - using the client-side batching via the `inserter` feature. Cargo features: requires `inserter`.
 - [async_insert.rs](async_insert.rs) - using the server-side batching via the [asynchronous inserts](https://clickhouse.com/docs/en/optimize/asynchronous-inserts) ClickHouse feature

src/lib.rs

@@ -319,6 +319,24 @@ impl Client {
         query::Query::new(self, query)
     }
 
+    /// 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::Query`] - the query builder that executes the query
+    ///
+    pub fn query_raw(&self, query: &str) -> query::Query {
+        query::Query::raw(self, query)
+    }
+
     /// Enables or disables [`Row`] data types validation against the database schema
     /// at the cost of performance. Validation is enabled by default, and in this mode,
     /// the client will use `RowBinaryWithNamesAndTypes` format.

src/query.rs

@@ -23,13 +23,23 @@ use crate::headers::with_authentication;
 pub struct Query {
     client: Client,
     sql: SqlBuilder,
+    raw: bool,
 }
 
 impl Query {
     pub(crate) fn new(client: &Client, template: &str) -> Self {
         Self {
             client: client.clone(),
             sql: SqlBuilder::new(template),
+            raw: false,
+        }
+    }
+    /// Creates a new query that will be used as-is without any processing.
+    pub(crate) fn raw(client: &Client, query: &str) -> Self {
+        Self {
+            client: client.clone(),
+            sql: SqlBuilder::raw(query),
+            raw: true,
         }
     }
 
@@ -53,6 +63,9 @@ impl Query {
     /// [`Identifier`]: crate::sql::Identifier
     #[track_caller]
     pub fn bind(mut self, value: impl Bind) -> Self {
+        if self.raw {
+            panic!("bind() cannot be used with raw queries");
+        }
         self.sql.bind_arg(value);
         self
     }
@@ -84,7 +97,10 @@ impl Query {
     /// # Ok(()) }
     /// ```
     pub fn fetch<T: Row>(mut self) -> Result<RowCursor<T>> {
-        self.sql.bind_fields::<T>();
+        // skip binding if raw query
+        if !self.raw {
+            self.sql.bind_fields::<T>();
+        }
 
         let validation = self.client.get_validation();
         if validation {

src/sql/mod.rs

@@ -74,6 +74,9 @@ impl SqlBuilder {
 
         SqlBuilder::InProgress(parts, None)
     }
+    pub(crate) fn raw(query: &str) -> Self {
+        Self::InProgress(vec![Part::Text(query.to_string())], None)
+    }
 
     pub(crate) fn set_output_format(&mut self, format: impl Into<String>) {
         if let Self::InProgress(_, format_opt) = self {

tests/it/main.rs

@@ -177,6 +177,7 @@ mod ip;
 mod mock;
 mod nested;
 mod query;
+mod query_raw;
 mod rbwnat;
 mod time;
 mod user_agent;