Add support for querying parameter names in prepared statements (#609)

Fixes #605

Author: mlafeldt

crates/duckdb/src/error.rs

@@ -80,11 +80,16 @@ pub enum Error {
 
     /// Error when the SQL contains multiple statements.
     MultipleStatement,
+
     /// Error when the number of bound parameters does not match the number of
     /// parameters in the query. The first `usize` is how many parameters were
     /// given, the 2nd is how many were expected.
     InvalidParameterCount(usize, usize),
 
+    /// Error when a parameter is requested, but the index is out of range
+    /// for the statement.
+    InvalidParameterIndex(usize),
+
     /// Append Error
     AppendError,
 }
@@ -108,6 +113,7 @@ impl PartialEq for Error {
             }
             (Self::StatementChangedRows(n1), Self::StatementChangedRows(n2)) => n1 == n2,
             (Self::InvalidParameterCount(i1, n1), Self::InvalidParameterCount(i2, n2)) => i1 == i2 && n1 == n2,
+            (Self::InvalidParameterIndex(i1), Self::InvalidParameterIndex(i2)) => i1 == i2,
             (..) => false,
         }
     }
@@ -187,6 +193,7 @@ impl fmt::Display for Error {
             Self::InvalidParameterCount(i1, n1) => {
                 write!(f, "Wrong number of parameters passed to query. Got {i1}, needed {n1}")
             }
+            Self::InvalidParameterIndex(i) => write!(f, "Invalid parameter index: {i}"),
             Self::StatementChangedRows(i) => write!(f, "Query changed {i} rows"),
             Self::ToSqlConversionFailure(ref err) => err.fmt(f),
             Self::InvalidQuery => write!(f, "Query is not read-only"),
@@ -213,6 +220,7 @@ impl error::Error for Error {
             | Self::InvalidColumnType(..)
             | Self::InvalidPath(_)
             | Self::InvalidParameterCount(..)
+            | Self::InvalidParameterIndex(_)
             | Self::StatementChangedRows(_)
             | Self::InvalidQuery
             | Self::AppendError

crates/duckdb/src/raw_statement.rs

@@ -316,6 +316,30 @@ impl RawStatement {
         unsafe { ffi::duckdb_nparams(self.ptr) as usize }
     }
 
+    pub fn parameter_name(&self, idx: usize) -> Result<String> {
+        let count = self.bind_parameter_count();
+        if idx == 0 || idx > count {
+            return Err(Error::InvalidParameterIndex(idx));
+        }
+
+        unsafe {
+            let name_ptr = ffi::duckdb_parameter_name(self.ptr, idx as u64);
+            // Range check above ensures this shouldn't be null, but check defensively
+            if name_ptr.is_null() {
+                return Err(Error::DuckDBFailure(
+                    ffi::Error::new(ffi::DuckDBError),
+                    Some(format!("Could not retrieve parameter name for index {idx}")),
+                ));
+            }
+
+            let name = CStr::from_ptr(name_ptr).to_string_lossy().to_string();
+
+            ffi::duckdb_free(name_ptr as *mut std::ffi::c_void);
+
+            Ok(name)
+        }
+    }
+
     #[inline]
     pub fn sql(&self) -> Option<&CStr> {
         panic!("not supported")

crates/duckdb/src/statement.rs

@@ -437,6 +437,39 @@ impl Statement<'_> {
         self.stmt.bind_parameter_count()
     }
 
+    /// Returns the name of the parameter at the given index.
+    ///
+    /// This can be used to query the names of named parameters (e.g., `$param_name`)
+    /// in a prepared statement.
+    ///
+    /// # Arguments
+    ///
+    /// * `one_based_col_index` - One-based parameter index (1 to [`Statement::parameter_count`])
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(String)` - The parameter name (without the `$` prefix for named params, or the numeric index for positional params)
+    /// * `Err(InvalidParameterIndex)` - If the index is out of range
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # use duckdb::{Connection, Result};
+    /// fn query_parameter_names(conn: &Connection) -> Result<()> {
+    ///     let stmt = conn.prepare("SELECT $foo, $bar")?;
+    ///
+    ///     assert_eq!(stmt.parameter_count(), 2);
+    ///     assert_eq!(stmt.parameter_name(1)?, "foo");
+    ///     assert_eq!(stmt.parameter_name(2)?, "bar");
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    #[inline]
+    pub fn parameter_name(&self, idx: usize) -> Result<String> {
+        self.stmt.parameter_name(idx)
+    }
+
     /// Low level API to directly bind a parameter to a given index.
     ///
     /// Note that the index is one-based, that is, the first parameter index is
@@ -1120,4 +1153,69 @@ mod test {
         assert_eq!(expected, actual);
         Ok(())
     }
+
+    #[test]
+    fn test_parameter_name() -> Result<()> {
+        let db = Connection::open_in_memory()?;
+
+        {
+            let stmt = db.prepare("SELECT $foo, $bar")?;
+
+            assert_eq!(stmt.parameter_count(), 2);
+            assert_eq!(stmt.parameter_name(1)?, "foo");
+            assert_eq!(stmt.parameter_name(2)?, "bar");
+
+            assert!(matches!(stmt.parameter_name(0), Err(Error::InvalidParameterIndex(0))));
+            assert!(matches!(
+                stmt.parameter_name(100),
+                Err(Error::InvalidParameterIndex(100))
+            ));
+        }
+
+        // Positional parameters return their index number as the name
+        {
+            let stmt = db.prepare("SELECT ?, ?")?;
+            assert_eq!(stmt.parameter_count(), 2);
+            assert_eq!(stmt.parameter_name(1)?, "1");
+            assert_eq!(stmt.parameter_name(2)?, "2");
+        }
+
+        // Numbered positional parameters also return their number
+        {
+            let stmt = db.prepare("SELECT ?1, ?2")?;
+            assert_eq!(stmt.parameter_count(), 2);
+            assert_eq!(stmt.parameter_name(1)?, "1");
+            assert_eq!(stmt.parameter_name(2)?, "2");
+        }
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_bind_named_parameters_manually() -> Result<()> {
+        use std::collections::HashMap;
+
+        let db = Connection::open_in_memory()?;
+        let mut stmt = db.prepare("SELECT $foo > $bar")?;
+
+        let mut params: HashMap<String, i32> = HashMap::new();
+        params.insert("foo".to_string(), 42);
+        params.insert("bar".to_string(), 23);
+
+        for idx in 1..=stmt.parameter_count() {
+            let name = stmt.parameter_name(idx)?;
+            if let Some(value) = params.get(&name) {
+                stmt.raw_bind_parameter(idx, value)?;
+            }
+        }
+
+        stmt.raw_execute()?;
+
+        let mut rows = stmt.raw_query();
+        let row = rows.next()?.unwrap();
+        let result: bool = row.get(0)?;
+        assert!(result);
+
+        Ok(())
+    }
 }