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}