Skip to main content

chdb_rust/
connection.rs

1//! Connection management for chDB.
2//!
3//! This module provides the [`Connection`] type for managing connections to chDB databases.
4
5use std::ffi::{c_char, CString};
6
7#[cfg(feature = "arrow")]
8use crate::arrow_options::ArrowOptions;
9#[cfg(all(feature = "arrow", direct_arrow_insert))]
10use crate::arrow_options::InsertOptions;
11#[cfg(feature = "arrow")]
12use crate::arrow_query_stream::ArrowQueryStream;
13#[cfg(feature = "arrow")]
14use crate::arrow_stream::ArrowRegistration;
15#[cfg(feature = "arrow")]
16use crate::arrow_stream::{ArrowArray, ArrowSchema, ArrowStream};
17use crate::error::{Error, Result};
18use crate::format::{InputFormat, OutputFormat};
19use crate::query_param::{EncodedParams, QueryParams};
20use crate::query_result::QueryResult;
21use crate::query_stream::QueryStream;
22use crate::{bindings, registry, CHDB_PROGRAM_NAME};
23
24/// A connection to a chDB database.
25///
26/// A `Connection` represents an active connection to a chDB database instance.
27/// Connections can be created for in-memory databases or persistent databases
28/// stored on disk.
29///
30/// # Thread Safety
31///
32/// `Connection` implements `Send`, meaning it can be safely transferred between threads.
33/// However, the underlying chDB library may have limitations on concurrent access.
34/// It's recommended to use one connection per thread or implement proper synchronization.
35///
36/// # Examples
37///
38/// ```no_run
39/// use chdb_rust::connection::Connection;
40/// use chdb_rust::format::OutputFormat;
41///
42/// // Create an in-memory connection
43/// let conn = Connection::open_in_memory()?;
44///
45/// // Execute a query
46/// let result = conn.query("SELECT 1", OutputFormat::JSONEachRow)?;
47/// println!("{}", result.data_utf8_lossy());
48/// # Ok::<(), chdb_rust::error::Error>(())
49/// ```
50#[derive(Debug)]
51pub struct Connection {
52    // Pointer to chdb_connection (which is *mut chdb_connection_)
53    inner: *mut bindings::chdb_connection,
54    /// Holds this connection's claim on the process-wide engine. Dropping it
55    /// lets a later connection bind a different data path.
56    slot: registry::Slot,
57}
58
59// Safety: Connection is safe to send between threads
60// The underlying chDB library is thread-safe for query execution
61unsafe impl Send for Connection {}
62
63impl Connection {
64    /// Connect to chDB with the given command-line arguments.
65    ///
66    /// Use [crate::session::SessionBuilder] for a higher-level API that supports
67    /// sessions and persistent storage.
68    ///
69    /// # Arguments
70    ///
71    /// * `args` - Array of command-line arguments (e.g., `["--path=/tmp/db"]`)
72    ///
73    /// # Examples
74    ///
75    /// ```no_run
76    /// use chdb_rust::connection::Connection;
77    ///
78    /// // Connect with custom arguments
79    /// let conn = Connection::open(&["--path=/tmp/mydb"])?;
80    /// # Ok::<(), chdb_rust::error::Error>(())
81    /// ```
82    ///
83    /// # Errors
84    ///
85    /// Returns [`Error::ConnectionFailed`] if the
86    /// connection cannot be established.
87    pub fn open(args: &[&str]) -> Result<Self> {
88        crate::version::verify_loaded_engine()?;
89        // A post-shutdown connect fails inside the engine as a null connection
90        // and nothing else, so it is caught here where the reason is known.
91        crate::runtime::ensure_running()?;
92
93        let c_args: Vec<CString> = std::iter::once(CHDB_PROGRAM_NAME)
94            .chain(args.iter().copied())
95            .map(CString::new)
96            .collect::<std::result::Result<_, _>>()?;
97
98        // Claimed before connecting, so that a second data path is refused with
99        // the reason rather than by the engine, which reports a refusal as a
100        // null connection and nothing else.
101        let slot = registry::acquire(registry::key_from_args(args))?;
102
103        let argv: Vec<*const c_char> = c_args.iter().map(|s| s.as_ptr()).collect();
104        let conn_ptr =
105            unsafe { bindings::chdb_connect(argv.len() as i32, argv.as_ptr() as *mut *mut c_char) };
106
107        if conn_ptr.is_null() {
108            return Err(Error::ConnectionFailed);
109        }
110
111        // Check if the connection itself is null
112        let conn = unsafe { *conn_ptr };
113        if conn.is_null() {
114            return Err(Error::ConnectionFailed);
115        }
116
117        Ok(Self {
118            inner: conn_ptr,
119            slot,
120        })
121    }
122
123    /// Connect to an in-memory database.
124    ///
125    /// Creates a connection to a temporary in-memory database. Data stored in this
126    /// database will be lost when the connection is closed.
127    ///
128    /// # Examples
129    ///
130    /// ```no_run
131    /// use chdb_rust::connection::Connection;
132    ///
133    /// let conn = Connection::open_in_memory()?;
134    /// # Ok::<(), chdb_rust::error::Error>(())
135    /// ```
136    ///
137    /// # Errors
138    ///
139    /// Returns [`Error::ConnectionFailed`] if the
140    /// connection cannot be established.
141    pub fn open_in_memory() -> Result<Self> {
142        Self::open(&[])
143    }
144
145    /// Get the underlying chDB connection handle.
146    ///
147    /// Returns the `chdb_connection` value passed to chDB C API functions. This is
148    /// used by crate-internal code such as [`QueryStream`](crate::query_stream::QueryStream).
149    ///
150    /// # Returns
151    ///
152    /// Returns the raw `chdb_connection` handle.
153    pub(crate) fn handle(&self) -> bindings::chdb_connection {
154        unsafe { *self.inner }
155    }
156
157    /// Execute a query and return the result.
158    ///
159    /// Executes a SQL query against the database and returns the result in the
160    /// specified output format.
161    ///
162    /// # Arguments
163    ///
164    /// * `sql` - The SQL query string to execute
165    /// * `format` - The desired output format for the result
166    ///
167    /// # Returns
168    ///
169    /// Returns a [`QueryResult`] containing the query output, or an [`Error`]
170    /// if the query fails.
171    ///
172    /// # Examples
173    ///
174    /// ```no_run
175    /// use chdb_rust::connection::Connection;
176    /// use chdb_rust::format::OutputFormat;
177    ///
178    /// let conn = Connection::open_in_memory()?;
179    /// let result = conn.query("SELECT 1 + 1 AS sum", OutputFormat::JSONEachRow)?;
180    /// println!("{}", result.data_utf8_lossy());
181    /// # Ok::<(), chdb_rust::error::Error>(())
182    /// ```
183    ///
184    /// # Errors
185    ///
186    /// Returns an error if:
187    /// - The query syntax is invalid
188    /// - The query references non-existent tables or columns
189    /// - The query execution fails for any other reason
190    pub fn query(&self, sql: &str, format: OutputFormat) -> Result<QueryResult> {
191        let conn = unsafe { *self.inner };
192        let format = format.as_str();
193
194        // chdb_query_n takes pointer + length for both strings, so neither has
195        // to be NUL-terminated and neither is copied. It returns an owned
196        // chdb_result handle (or null on failure): QueryResult::new below takes
197        // ownership of that pointer, and QueryResult's Drop impl frees it via
198        // chdb_destroy_query_result.
199        let result_ptr = unsafe {
200            bindings::chdb_query_n(
201                conn,
202                sql.as_ptr() as *const c_char,
203                sql.len(),
204                format.as_ptr() as *const c_char,
205                format.len(),
206            )
207        };
208
209        if result_ptr.is_null() {
210            return Err(Error::NoResult);
211        }
212
213        let result = QueryResult::new(result_ptr);
214        result.check_error()
215    }
216
217    /// Execute a query and return a streaming result.
218    ///
219    /// Unlike [`query`](Self::query), this returns a [`QueryStream`] that yields
220    /// result data in chunks. This is useful for large result sets that should not
221    /// be fully materialized in memory.
222    ///
223    /// # Arguments
224    ///
225    /// * `sql` - The SQL query string to execute
226    /// * `format` - The desired output format for each chunk
227    ///
228    /// # Returns
229    ///
230    /// Returns a [`QueryStream`] tied to this connection, or an [`Error`] if the query
231    /// cannot be started.
232    ///
233    /// # Examples
234    ///
235    /// ```no_run
236    /// use chdb_rust::connection::Connection;
237    /// use chdb_rust::format::OutputFormat;
238    ///
239    /// let mut conn = Connection::open_in_memory()?;
240    /// let mut stream = conn.query_stream(
241    ///     "SELECT number FROM numbers(100_000)",
242    ///     OutputFormat::JSONEachRow,
243    /// )?;
244    ///
245    /// while let Some(chunk) = stream.next_chunk()? {
246    ///     print!("{}", chunk.data_utf8_lossy());
247    /// }
248    /// # Ok::<(), chdb_rust::error::Error>(())
249    /// ```
250    ///
251    /// # Errors
252    ///
253    /// Returns an error if:
254    /// - The query syntax is invalid
255    /// - The query references non-existent tables or columns
256    /// - The query execution fails for any other reason
257    pub fn query_stream<'a>(
258        &'a mut self,
259        sql: &str,
260        format: OutputFormat,
261    ) -> Result<QueryStream<'a>> {
262        QueryStream::start_borrowed(self, sql, format)
263    }
264
265    /// Execute a query with ClickHouse `{name:Type}` parameter binding and stream text chunks.
266    ///
267    /// Like [`Self::query_stream`], but SQL placeholders are bound from `params`
268    /// before streaming begins. The connection is exclusively borrowed for the
269    /// stream's lifetime. Syntax errors fail when the stream is created. A
270    /// missing placeholder binding is reported on the first
271    /// [`QueryStream::next_chunk`], not at start.
272    ///
273    /// # Examples
274    ///
275    /// ```no_run
276    /// use chdb_rust::connection::Connection;
277    /// use chdb_rust::format::OutputFormat;
278    ///
279    /// let mut conn = Connection::open_in_memory()?;
280    /// let mut stream = conn.query_stream_with_params(
281    ///     "SELECT {x:UInt64} AS v",
282    ///     OutputFormat::CSV,
283    ///     [("x", 11_u64)],
284    /// )?;
285    /// while let Some(chunk) = stream.next_chunk()? {
286    ///     print!("{}", chunk.data_utf8_lossy());
287    /// }
288    /// # Ok::<(), chdb_rust::error::Error>(())
289    /// ```
290    ///
291    /// # Errors
292    ///
293    /// Returns an error if:
294    /// - The query syntax is invalid
295    /// - The query cannot be started
296    pub fn query_stream_with_params<'a>(
297        &'a mut self,
298        sql: &str,
299        format: OutputFormat,
300        params: impl Into<QueryParams>,
301    ) -> Result<QueryStream<'a>> {
302        QueryStream::start_borrowed_with_params(self, sql, format, params)
303    }
304
305    /// Execute a query and stream the result as Arrow record batches.
306    ///
307    /// Each call to [`Iterator::next`] or [`ArrowQueryStream::next_batch`] on the
308    /// returned stream pulls a single [`arrow::record_batch::RecordBatch`] via the
309    /// Arrow C Data Interface.
310    ///
311    /// Available when the crate is built with the `arrow` feature.
312    ///
313    /// # Examples
314    ///
315    /// ```no_run
316    /// use chdb_rust::connection::Connection;
317    ///
318    /// let mut conn = Connection::open_in_memory()?;
319    /// let mut stream = conn.query_stream_arrow("SELECT number FROM numbers(100_000)")?;
320    /// while let Some(batch) = stream.next_batch()? {
321    ///     println!("rows: {}", batch.num_rows());
322    /// }
323    /// # Ok::<(), chdb_rust::error::Error>(())
324    /// ```
325    #[cfg(feature = "arrow")]
326    pub fn query_stream_arrow<'a>(
327        &'a mut self,
328        sql: &str,
329    ) -> Result<crate::arrow_query_stream::ArrowQueryStream<'a>> {
330        crate::arrow_query_stream::ArrowQueryStream::start_borrowed(self, sql, None)
331    }
332
333    /// Execute a query and take the whole result as one Arrow stream.
334    ///
335    /// No Arrow IPC serialization or compression round-trip; conversion of
336    /// ClickHouse columns into Arrow buffers may still copy data. Prefer
337    /// [`query_stream_arrow`](Self::query_stream_arrow) when the result is too
338    /// large to hold at once.
339    ///
340    /// The returned reader owns the Arrow stream. The C ABI transfers
341    /// `out_stream->release` to the caller, so the reader can be drained after
342    /// this connection is dropped.
343    ///
344    /// Available when the crate is built with the `arrow` feature.
345    ///
346    /// # Examples
347    ///
348    /// ```no_run
349    /// use chdb_rust::connection::Connection;
350    ///
351    /// let conn = Connection::open_in_memory()?;
352    /// let reader = conn.query_arrow("SELECT number FROM numbers(1000)")?;
353    /// for batch in reader {
354    ///     println!("rows: {}", batch?.num_rows());
355    /// }
356    /// # Ok::<(), Box<dyn std::error::Error>>(())
357    /// ```
358    #[cfg(feature = "arrow")]
359    pub fn query_arrow(&self, sql: &str) -> Result<crate::arrow_query_stream::ArrowReader> {
360        self.query_arrow_inner(sql, None)
361    }
362
363    /// [`query_arrow`](Self::query_arrow) with explicit type-mapping options.
364    #[cfg(feature = "arrow")]
365    pub fn query_arrow_with_opts(
366        &self,
367        sql: &str,
368        opts: &ArrowOptions,
369    ) -> Result<crate::arrow_query_stream::ArrowReader> {
370        self.query_arrow_inner(sql, Some(opts))
371    }
372
373    #[cfg(feature = "arrow")]
374    fn query_arrow_inner(
375        &self,
376        sql: &str,
377        opts: Option<&ArrowOptions>,
378    ) -> Result<crate::arrow_query_stream::ArrowReader> {
379        use arrow::ffi_stream::{ArrowArrayStreamReader, FFI_ArrowArrayStream};
380
381        let conn = unsafe { *self.inner };
382        let c_opts = opts.map(|o| o.to_c());
383        let opts_ptr = c_opts.as_ref().map_or(std::ptr::null(), |o| {
384            o as *const bindings::chdb_arrow_options
385        });
386
387        let mut ffi_stream = FFI_ArrowArrayStream::empty();
388
389        // Wraps chdb_query_arrow_n. The engine fills `ffi_stream` and transfers
390        // ownership of its release callback; the returned chdb_result carries
391        // only metrics and an error slot, and is destroyed here.
392        let result_ptr = unsafe {
393            bindings::chdb_query_arrow_n(
394                conn,
395                sql.as_ptr() as *const c_char,
396                sql.len(),
397                (&mut ffi_stream as *mut FFI_ArrowArrayStream).cast(),
398                opts_ptr,
399            )
400        };
401
402        if result_ptr.is_null() {
403            return Err(Error::NoResult);
404        }
405        // Freed when it drops; the data lives in `ffi_stream`, not in it.
406        QueryResult::new(result_ptr).check_error()?;
407
408        let reader = ArrowArrayStreamReader::try_new(ffi_stream)
409            .map_err(|e| Error::InvalidData(e.to_string()))?;
410        Ok(crate::arrow_query_stream::ArrowReader::new(reader))
411    }
412
413    /// Stream a query's result as Arrow record batches with explicit
414    /// type-mapping options.
415    #[cfg(feature = "arrow")]
416    pub fn query_stream_arrow_with_opts<'a>(
417        &'a mut self,
418        sql: &str,
419        opts: &ArrowOptions,
420    ) -> Result<crate::arrow_query_stream::ArrowQueryStream<'a>> {
421        crate::arrow_query_stream::ArrowQueryStream::start_borrowed(self, sql, Some(opts))
422    }
423
424    /// Open a streaming INSERT.
425    ///
426    /// The write-side counterpart of [`query_stream`](Self::query_stream): send
427    /// the INSERT statement here, then push the rows in chunks. The statement
428    /// must carry no `FORMAT` clause and no inline data — the format is the
429    /// `format` argument, and the data goes through
430    /// [`InsertStream::append`](crate::insert_stream::InsertStream::append).
431    ///
432    /// The connection is exclusively borrowed until the stream is finished,
433    /// cancelled or dropped, because it accepts no other statement meanwhile.
434    ///
435    /// # Examples
436    ///
437    /// ```no_run
438    /// use chdb_rust::connection::Connection;
439    /// use chdb_rust::format::InputFormat;
440    ///
441    /// let mut conn = Connection::open_in_memory()?;
442    /// let mut ins = conn.insert_stream("INSERT INTO t (a, b)", InputFormat::CSV)?;
443    /// ins.append(b"1,\"one\"\n")?;
444    /// let stats = ins.finish()?;
445    /// # Ok::<(), chdb_rust::error::Error>(())
446    /// ```
447    ///
448    /// # Errors
449    ///
450    /// Returns [`Error::QueryError`] if the statement is invalid — a missing
451    /// table, say — which is reported when the stream is opened.
452    pub fn insert_stream<'a>(
453        &'a mut self,
454        sql: &str,
455        format: InputFormat,
456    ) -> Result<crate::insert_stream::InsertStream<'a>> {
457        crate::insert_stream::InsertStream::start(self, sql, format)
458    }
459
460    /// Open a streaming INSERT whose statement carries `{name:Type}`
461    /// placeholders.
462    ///
463    /// The motivating case is `INSERT INTO FUNCTION file({path:String}, ...)`,
464    /// where the destination itself is a bound value. See
465    /// [`query_with_params`](Self::query_with_params) for binding rules.
466    pub fn insert_stream_with_params<'a>(
467        &'a mut self,
468        sql: &str,
469        format: InputFormat,
470        params: impl Into<QueryParams>,
471    ) -> Result<crate::insert_stream::InsertStream<'a>> {
472        crate::insert_stream::InsertStream::start_with_params(self, sql, format, params)
473    }
474
475    /// Execute a query with ClickHouse `{name:Type}` parameter binding.
476    ///
477    /// Parameter values are encoded here and bound in the chDB library; they
478    /// are never interpolated into the SQL text. Names in `params` need not match placeholder
479    /// order in the query. An empty `params` list is a plain query.
480    ///
481    /// # Examples
482    ///
483    /// ```no_run
484    /// use chdb_rust::connection::Connection;
485    /// use chdb_rust::format::OutputFormat;
486    ///
487    /// let conn = Connection::open_in_memory()?;
488    /// let result = conn.query_with_params(
489    ///     "SELECT {x:UInt64} + {y:UInt64} AS total",
490    ///     OutputFormat::CSV,
491    ///     [("y", 5_u64), ("x", 7_u64)],
492    /// )?;
493    /// # Ok::<(), chdb_rust::error::Error>(())
494    /// ```
495    ///
496    /// # Errors
497    ///
498    /// Returns an error if:
499    /// - The query syntax is invalid
500    /// - A `{name:Type}` placeholder has no matching param
501    /// - A value cannot be parsed as the type declared in the placeholder
502    /// - The query execution fails for any other reason
503    pub fn query_with_params(
504        &self,
505        sql: &str,
506        format: OutputFormat,
507        params: impl Into<QueryParams>,
508    ) -> Result<QueryResult> {
509        let format = format.as_str();
510        let encoded = EncodedParams::encode(params)?;
511
512        // chdb_query_with_params_n takes pointer + length for query, format, and
513        // each bound value, so none of them need to be NUL-terminated. It returns
514        // an owned chdb_result handle (or null on failure): QueryResult::new below
515        // takes ownership, and QueryResult's Drop impl frees it via
516        // chdb_destroy_query_result.
517        let conn = unsafe { *self.inner };
518        let result_ptr = unsafe {
519            bindings::chdb_query_with_params_n(
520                conn,
521                sql.as_ptr() as *const c_char,
522                sql.len(),
523                format.as_ptr() as *const c_char,
524                format.len(),
525                encoded.names_ptr(),
526                encoded.name_lens_ptr(),
527                encoded.values_ptr(),
528                encoded.value_lens_ptr(),
529                encoded.len(),
530            )
531        };
532
533        if result_ptr.is_null() {
534            return Err(Error::NoResult);
535        }
536
537        let result = QueryResult::new(result_ptr);
538        result.check_error()
539    }
540
541    #[cfg(feature = "arrow")]
542    /// Execute a query with ClickHouse `{name:Type}` parameter binding and stream Arrow batches.
543    ///
544    /// Like [`Self::query_stream_arrow`], but SQL placeholders are bound from `params`
545    /// in the chDB library before streaming begins. The connection is exclusively borrowed
546    /// for the stream's lifetime. Syntax errors fail when the stream is created.
547    /// A missing placeholder binding is reported on the first
548    /// [`ArrowQueryStream::next_batch`], not at start.
549    ///
550    /// # Examples
551    ///
552    /// ```no_run
553    /// use chdb_rust::connection::Connection;
554    ///
555    /// let mut conn = Connection::open_in_memory()?;
556    /// let mut stream = conn.query_stream_arrow_with_params(
557    ///     "SELECT {x:UInt64} AS v",
558    ///     [("x", 11_u64)],
559    ///     None,
560    /// )?;
561    /// while let Some(batch) = stream.next_batch()? {
562    ///     println!("rows: {}", batch.num_rows());
563    /// }
564    /// # Ok::<(), chdb_rust::error::Error>(())
565    /// ```
566    ///
567    /// # Errors
568    ///
569    /// Returns an error if:
570    /// - The query syntax is invalid
571    /// - The query cannot be started
572    ///
573    /// Pass `opts` to control Arrow type mapping alongside the bindings; `None`
574    /// selects the engine's default contract.
575    pub fn query_stream_arrow_with_params<'a>(
576        &'a mut self,
577        sql: &str,
578        params: impl Into<QueryParams>,
579        opts: Option<&ArrowOptions>,
580    ) -> Result<ArrowQueryStream<'a>> {
581        ArrowQueryStream::start_borrowed_with_params(self, sql, params, opts)
582    }
583
584    /// Register an owned Arrow reader for queries within a scoped lifetime.
585    ///
586    /// The returned handle generates a process-unique name and unregisters on
587    /// close or drop. Use its `sql_expr()` in SQL and run the query through the
588    /// handle so lazy results cannot outlive the input reader.
589    #[cfg(feature = "arrow")]
590    pub fn register_arrow_reader(
591        &mut self,
592        reader: Box<dyn arrow::array::RecordBatchReader + Send>,
593    ) -> Result<ArrowRegistration<'_>> {
594        ArrowRegistration::new(self, reader)
595    }
596
597    #[cfg(feature = "arrow")]
598    /// Register an Arrow C Data Interface stream for use with `ArrowStream('name')`.
599    ///
600    /// Pass a raw `ArrowArrayStream*` (see [`ArrowStream`]).
601    /// Registered names are **not** ordinary tables; query them with the
602    /// [`arrow_stream_table_sql`](crate::arrow_stream::arrow_stream_table_sql) helper, e.g.
603    /// `SELECT * FROM ArrowStream('my_data')`.
604    ///
605    /// The stream pointer must stay valid until [`unregister_arrow_table`](Self::unregister_arrow_table)
606    /// is called or the connection is dropped.
607    ///
608    /// # Examples
609    ///
610    /// ```no_run
611    /// use chdb_rust::arrow_stream::{arrow_stream_table_sql, ArrowStream};
612    /// use chdb_rust::connection::Connection;
613    /// use chdb_rust::format::OutputFormat;
614    ///
615    /// let conn = Connection::open_in_memory()?;
616    /// // let stream_ptr: *mut arrow::ffi::FFI_ArrowArrayStream = ...;
617    /// // let arrow_stream = unsafe { ArrowStream::from_raw(stream_ptr) };
618    /// // conn.register_arrow_stream("my_data", &arrow_stream)?;
619    /// // let sql = format!("SELECT * FROM {}", arrow_stream_table_sql("my_data"));
620    /// // let _ = conn.query(&sql, OutputFormat::JSONEachRow)?;
621    /// # Ok::<(), chdb_rust::error::Error>(())
622    /// ```
623    ///
624    /// # Errors
625    ///
626    /// Returns an error if:
627    /// - The table name contains invalid characters
628    /// - The Arrow stream handle is invalid
629    /// - Registration fails for any other reason
630    pub fn register_arrow_stream(
631        &self,
632        table_name: &str,
633        arrow_stream: &ArrowStream,
634    ) -> Result<()> {
635        let table_name_cstr = CString::new(table_name)?;
636        let conn = unsafe { *self.inner };
637
638        let state = unsafe {
639            bindings::chdb_arrow_scan(conn, table_name_cstr.as_ptr(), arrow_stream.as_c())
640        };
641
642        if state == bindings::chdb_state_CHDBSuccess {
643            Ok(())
644        } else {
645            Err(Error::QueryError(format!(
646                "Failed to register Arrow stream as table '{}'",
647                table_name
648            )))
649        }
650    }
651
652    #[cfg(feature = "arrow")]
653    /// Register Arrow C Data Interface schema + array for use with `ArrowStream('name')`.
654    ///
655    /// libchdb wraps the pair in a one-shot stream. Query via
656    /// [`arrow_stream_table_sql`](crate::arrow_stream::arrow_stream_table_sql).
657    ///
658    /// # Arguments
659    ///
660    /// * `table_name` - The name to register for the Arrow stream table function
661    /// * `arrow_schema` - The Arrow schema handle describing the array structure
662    /// * `arrow_array` - The Arrow array handle containing the data
663    ///
664    /// # Returns
665    ///
666    /// Returns `Ok(())` on success, or an [`Error`] if registration fails.
667    ///
668    /// # Examples
669    ///
670    /// ```no_run
671    /// use chdb_rust::arrow_stream::{arrow_stream_table_sql, ArrowArray, ArrowSchema};
672    /// use chdb_rust::connection::Connection;
673    /// use chdb_rust::format::OutputFormat;
674    ///
675    /// let conn = Connection::open_in_memory()?;
676    ///
677    /// // Assuming you have Arrow C Data Interface schema and array handles
678    /// // let arrow_schema = unsafe { ArrowSchema::from_raw(schema_ptr) };
679    /// // let arrow_array = unsafe { ArrowArray::from_raw(array_ptr) };
680    /// // conn.register_arrow_array("my_data", &arrow_schema, &arrow_array)?;
681    ///
682    /// // Query via the ArrowStream table function
683    /// // let sql = format!("SELECT * FROM {}", arrow_stream_table_sql("my_data"));
684    /// // let result = conn.query(&sql, OutputFormat::JSONEachRow)?;
685    /// # Ok::<(), chdb_rust::error::Error>(())
686    /// ```
687    ///
688    /// # Errors
689    ///
690    /// Returns an error if:
691    /// - The table name contains invalid characters
692    /// - The Arrow schema or array handles are invalid
693    /// - Registration fails for any other reason
694    pub fn register_arrow_array(
695        &self,
696        table_name: &str,
697        arrow_schema: &ArrowSchema,
698        arrow_array: &ArrowArray,
699    ) -> Result<()> {
700        let table_name_cstr = CString::new(table_name)?;
701        let conn = unsafe { *self.inner };
702
703        let state = unsafe {
704            bindings::chdb_arrow_array_scan(
705                conn,
706                table_name_cstr.as_ptr(),
707                arrow_schema.as_c(),
708                arrow_array.as_c(),
709            )
710        };
711
712        if state == bindings::chdb_state_CHDBSuccess {
713            Ok(())
714        } else {
715            Err(Error::QueryError(format!(
716                "Failed to register Arrow array as table '{}'",
717                table_name
718            )))
719        }
720    }
721
722    #[cfg(feature = "arrow")]
723    /// Unregister an Arrow stream table function that was previously registered.
724    ///
725    /// This function removes a previously registered Arrow stream table function,
726    /// making it no longer available for queries.
727    ///
728    /// # Arguments
729    ///
730    /// * `table_name` - The name of the Arrow stream table function to unregister
731    ///
732    /// # Returns
733    ///
734    /// Returns `Ok(())` on success, or an [`Error`] if unregistration fails.
735    ///
736    /// # Examples
737    ///
738    /// ```no_run
739    /// use chdb_rust::connection::Connection;
740    /// use chdb_rust::arrow_stream::ArrowStream;
741    ///
742    /// let conn = Connection::open_in_memory()?;
743    ///
744    /// // Register a table
745    /// // let arrow_stream = ArrowStream::from_raw(stream_ptr);
746    /// // conn.register_arrow_stream("my_data", &arrow_stream)?;
747    ///
748    /// // Use it...
749    ///
750    /// // Unregister when done
751    /// // conn.unregister_arrow_table("my_data")?;
752    /// # Ok::<(), chdb_rust::error::Error>(())
753    /// ```
754    ///
755    /// # Errors
756    ///
757    /// Returns an error if:
758    /// - The table name contains invalid characters
759    /// - The table was not previously registered
760    /// - Unregistration fails for any other reason
761    pub fn unregister_arrow_table(&self, table_name: &str) -> Result<()> {
762        let table_name_cstr = CString::new(table_name)?;
763        let conn = unsafe { *self.inner };
764
765        let state =
766            unsafe { bindings::chdb_arrow_unregister_table(conn, table_name_cstr.as_ptr()) };
767
768        if state == bindings::chdb_state_CHDBSuccess {
769            Ok(())
770        } else {
771            Err(Error::QueryError(format!(
772                "Failed to unregister Arrow table '{}'",
773                table_name
774            )))
775        }
776    }
777
778    /// Insert rows from a registered Arrow schema+array directly into `dest_table`.
779    ///
780    /// Requires libchdb built with `chdb_insert_arrow_array` (see `direct_arrow_insert` cfg).
781    #[cfg(all(feature = "arrow", direct_arrow_insert))]
782    pub fn insert_arrow_array(
783        &self,
784        dest_table: &str,
785        arrow_schema: &ArrowSchema,
786        arrow_array: &ArrowArray,
787        options: &InsertOptions,
788    ) -> Result<()> {
789        let dest_cstr = CString::new(dest_table)?;
790        let conn = unsafe { *self.inner };
791        let result_ptr = with_insert_options(options, |options_ptr| unsafe {
792            bindings::chdb_insert_arrow_array(
793                conn,
794                dest_cstr.as_ptr(),
795                arrow_schema.as_c(),
796                arrow_array.as_c(),
797                options_ptr,
798            )
799        })?;
800
801        check_insert_result(result_ptr)
802    }
803
804    /// Insert rows from a registered Arrow stream directly into `dest_table`.
805    ///
806    /// Requires libchdb built with `chdb_insert_arrow_stream` (see `direct_arrow_insert` cfg).
807    #[cfg(all(feature = "arrow", direct_arrow_insert))]
808    pub fn insert_arrow_stream(
809        &self,
810        dest_table: &str,
811        arrow_stream: &ArrowStream,
812        options: &InsertOptions,
813    ) -> Result<()> {
814        let dest_cstr = CString::new(dest_table)?;
815        let conn = unsafe { *self.inner };
816        let result_ptr = with_insert_options(options, |options_ptr| unsafe {
817            bindings::chdb_insert_arrow_stream(
818                conn,
819                dest_cstr.as_ptr(),
820                arrow_stream.as_c(),
821                options_ptr,
822            )
823        })?;
824
825        check_insert_result(result_ptr)
826    }
827}
828
829#[cfg(all(feature = "arrow", direct_arrow_insert))]
830fn with_insert_options<T>(
831    options: &InsertOptions,
832    call: impl FnOnce(*const bindings::chdb_arrow_insert_options) -> T,
833) -> Result<T> {
834    let settings_cstr = options.settings_clause().map(CString::new).transpose()?;
835    let c_options = settings_cstr
836        .as_ref()
837        .map(|settings| bindings::chdb_arrow_insert_options {
838            settings: settings.as_ptr(),
839        });
840    let options_ptr = c_options
841        .as_ref()
842        .map(|opts| opts as *const bindings::chdb_arrow_insert_options)
843        .unwrap_or(std::ptr::null());
844    // Both the C struct and the string it points to remain alive until the
845    // synchronous FFI call returns. Returning options_ptr would dangle.
846    Ok(call(options_ptr))
847}
848
849#[cfg(all(feature = "arrow", direct_arrow_insert))]
850fn check_insert_result(result_ptr: *mut bindings::chdb_result) -> Result<()> {
851    if result_ptr.is_null() {
852        return Err(Error::NoResult);
853    }
854
855    let result = QueryResult::new(result_ptr);
856    result.check_error().map(|_| ())
857}
858
859impl Connection {
860    /// The engine handle behind this connection, for the FFI calls in sibling
861    /// modules. `chdb_connect` hands back a pointer to the handle, and every
862    /// entry point takes the handle itself.
863    pub(crate) fn raw(&self) -> bindings::chdb_connection {
864        // SAFETY: `inner` is non-null for the lifetime of a Connection —
865        // `open` returns an error rather than a handle when either the outer
866        // or the inner pointer is null.
867        unsafe { *self.inner }
868    }
869
870    /// Removes `dir` once this is the last connection on its data path.
871    ///
872    /// The removal happens while the engine record is locked, so a connection
873    /// cannot attach to the path in between and lose its data.
874    pub(crate) fn remove_dir_on_last(&mut self, dir: std::path::PathBuf) {
875        self.slot.remove_on_last(dir);
876    }
877}
878
879impl Drop for Connection {
880    fn drop(&mut self) {
881        if !self.inner.is_null() {
882            unsafe { bindings::chdb_close_conn(self.inner) };
883        }
884    }
885}
886
887#[cfg(test)]
888mod test {
889    use super::*;
890    use crate::{error::Result, test_utils::tempdir};
891
892    #[cfg(all(feature = "arrow", direct_arrow_insert))]
893    #[test]
894    fn direct_insert_options_live_through_the_call() -> Result<()> {
895        let settings = with_insert_options(&InsertOptions::default_bulk(), |options| {
896            assert!(!options.is_null());
897            // The callback models the synchronous C call reading both pointers.
898            unsafe { std::ffi::CStr::from_ptr((*options).settings) }
899                .to_str()
900                .unwrap()
901                .to_owned()
902        })?;
903        assert_eq!(settings, "max_threads = 4");
904
905        with_insert_options(&InsertOptions::default(), |options| {
906            assert!(options.is_null());
907        })?;
908        Ok(())
909    }
910
911    #[test]
912    fn test_connection_open_with_explicit_data_path() -> Result<()> {
913        let tmp = tempdir();
914        let path_arg = format!(
915            "--path={}",
916            tmp.path().to_str().expect("temp path is not valid UTF-8")
917        );
918        Connection::open(&[&path_arg])?;
919
920        assert!(
921            tmp.path().read_dir()?.next().is_some(),
922            "expected chDB to create files in the data dir"
923        );
924
925        Ok(())
926    }
927}