Mark RawStatement as Send and document thread safety constraints (#606)

Fixes #366

Author: mlafeldt

crates/duckdb/src/appender/mod.rs

@@ -8,6 +8,19 @@ use crate::{
 };
 
 /// Appender for fast import data
+///
+/// # Thread Safety
+///
+/// `Appender` is neither `Send` nor `Sync`:
+/// - Not `Send` because it holds a reference to `Connection`, which is `!Sync`
+/// - Not `Sync` because DuckDB appenders don't support concurrent access
+///
+/// To use an appender in another thread, move the `Connection` to that thread
+/// and create the appender there.
+///
+/// If you need to share an `Appender` across threads, wrap it in a `Mutex`.
+///
+/// See [DuckDB concurrency documentation](https://duckdb.org/docs/stable/connect/concurrency.html) for more details.
 pub struct Appender<'conn> {
     conn: &'conn Connection,
     app: ffi::duckdb_appender,

crates/duckdb/src/raw_statement.rs

@@ -11,8 +11,13 @@ use super::{ffi, Result};
 use crate::arrow2;
 use crate::{error::result_from_duckdb_arrow, Error};
 
-// Private newtype for raw sqlite3_stmts that finalize themselves when dropped.
-// TODO: destroy statement and result
+/// Private newtype for DuckDB prepared statements that finalize themselves when dropped.
+///
+/// # Thread Safety
+///
+/// `RawStatement` is `Send` but not `Sync`:
+/// - `Send` because it owns all its data and can be safely moved between threads
+/// - Not `Sync` because DuckDB prepared statements don't support concurrent access
 #[derive(Debug)]
 pub struct RawStatement {
     ptr: ffi::duckdb_prepared_statement,
@@ -325,3 +330,5 @@ impl Drop for RawStatement {
         }
     }
 }
+
+unsafe impl Send for RawStatement {}

crates/duckdb/src/statement.rs

@@ -12,6 +12,14 @@ use crate::{
 };
 
 /// A prepared statement.
+///
+/// # Thread Safety
+///
+/// `Statement` is neither `Send` nor `Sync`:
+/// - Not `Send` because it holds a reference to `Connection`, which is `!Sync`
+/// - Not `Sync` because DuckDB prepared statements don't support concurrent access
+///
+/// See the [DuckDB concurrency documentation](https://duckdb.org/docs/stable/connect/concurrency.html) for more details.
 pub struct Statement<'conn> {
     conn: &'conn Connection,
     pub(crate) stmt: RawStatement,