Skip to main content

Connection

Struct Connection 

Source
pub struct Connection { /* private fields */ }
Expand description

A connection to a chDB database.

A Connection represents an active connection to a chDB database instance. Connections can be created for in-memory databases or persistent databases stored on disk.

§Thread Safety

Connection implements Send, meaning it can be safely transferred between threads. However, the underlying chDB library may have limitations on concurrent access. It’s recommended to use one connection per thread or implement proper synchronization.

§Examples

use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;

// Create an in-memory connection
let conn = Connection::open_in_memory()?;

// Execute a query
let result = conn.query("SELECT 1", OutputFormat::JSONEachRow)?;
println!("{}", result.data_utf8_lossy());

Implementations§

Source§

impl Connection

Source

pub fn open(args: &[&str]) -> Result<Self>

Connect to chDB with the given command-line arguments.

Use crate::session::SessionBuilder for a higher-level API that supports sessions and persistent storage.

§Arguments
  • args - Array of command-line arguments (e.g., ["--path=/tmp/db"])
§Examples
use chdb_rust::connection::Connection;

// Connect with custom arguments
let conn = Connection::open(&["--path=/tmp/mydb"])?;
§Errors

Returns Error::ConnectionFailed if the connection cannot be established.

Source

pub fn open_in_memory() -> Result<Self>

Connect to an in-memory database.

Creates a connection to a temporary in-memory database. Data stored in this database will be lost when the connection is closed.

§Examples
use chdb_rust::connection::Connection;

let conn = Connection::open_in_memory()?;
§Errors

Returns Error::ConnectionFailed if the connection cannot be established.

Source

pub fn query(&self, sql: &str, format: OutputFormat) -> Result<QueryResult>

Execute a query and return the result.

Executes a SQL query against the database and returns the result in the specified output format.

§Arguments
  • sql - The SQL query string to execute
  • format - The desired output format for the result
§Returns

Returns a QueryResult containing the query output, or an Error if the query fails.

§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;

let conn = Connection::open_in_memory()?;
let result = conn.query("SELECT 1 + 1 AS sum", OutputFormat::JSONEachRow)?;
println!("{}", result.data_utf8_lossy());
§Errors

Returns an error if:

  • The query syntax is invalid
  • The query references non-existent tables or columns
  • The query execution fails for any other reason
Source

pub fn query_stream<'a>( &'a mut self, sql: &str, format: OutputFormat, ) -> Result<QueryStream<'a>>

Execute a query and return a streaming result.

Unlike query, this returns a QueryStream that yields result data in chunks. This is useful for large result sets that should not be fully materialized in memory.

§Arguments
  • sql - The SQL query string to execute
  • format - The desired output format for each chunk
§Returns

Returns a QueryStream tied to this connection, or an Error if the query cannot be started.

§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;

let mut conn = Connection::open_in_memory()?;
let mut stream = conn.query_stream(
    "SELECT number FROM numbers(100_000)",
    OutputFormat::JSONEachRow,
)?;

while let Some(chunk) = stream.next_chunk()? {
    print!("{}", chunk.data_utf8_lossy());
}
§Errors

Returns an error if:

  • The query syntax is invalid
  • The query references non-existent tables or columns
  • The query execution fails for any other reason
Source

pub fn query_stream_with_params<'a>( &'a mut self, sql: &str, format: OutputFormat, params: impl Into<QueryParams>, ) -> Result<QueryStream<'a>>

Execute a query with ClickHouse {name:Type} parameter binding and stream text chunks.

Like Self::query_stream, but SQL placeholders are bound from params before streaming begins. The connection is exclusively borrowed for the stream’s lifetime. Syntax errors fail when the stream is created. A missing placeholder binding is reported on the first QueryStream::next_chunk, not at start.

§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;

let mut conn = Connection::open_in_memory()?;
let mut stream = conn.query_stream_with_params(
    "SELECT {x:UInt64} AS v",
    OutputFormat::CSV,
    [("x", 11_u64)],
)?;
while let Some(chunk) = stream.next_chunk()? {
    print!("{}", chunk.data_utf8_lossy());
}
§Errors

Returns an error if:

  • The query syntax is invalid
  • The query cannot be started
Source

pub fn query_stream_arrow<'a>( &'a mut self, sql: &str, ) -> Result<ArrowQueryStream<'a>>

Execute a query and stream the result as Arrow record batches.

Each call to Iterator::next or ArrowQueryStream::next_batch on the returned stream pulls a single arrow::record_batch::RecordBatch via the Arrow C Data Interface.

Available when the crate is built with the arrow feature.

§Examples
use chdb_rust::connection::Connection;

let mut conn = Connection::open_in_memory()?;
let mut stream = conn.query_stream_arrow("SELECT number FROM numbers(100_000)")?;
while let Some(batch) = stream.next_batch()? {
    println!("rows: {}", batch.num_rows());
}
Source

pub fn query_arrow(&self, sql: &str) -> Result<ArrowReader>

Execute a query and take the whole result as one Arrow stream.

No Arrow IPC serialization or compression round-trip; conversion of ClickHouse columns into Arrow buffers may still copy data. Prefer query_stream_arrow when the result is too large to hold at once.

The returned reader owns the Arrow stream. The C ABI transfers out_stream->release to the caller, so the reader can be drained after this connection is dropped.

Available when the crate is built with the arrow feature.

§Examples
use chdb_rust::connection::Connection;

let conn = Connection::open_in_memory()?;
let reader = conn.query_arrow("SELECT number FROM numbers(1000)")?;
for batch in reader {
    println!("rows: {}", batch?.num_rows());
}
Source

pub fn query_arrow_with_opts( &self, sql: &str, opts: &ArrowOptions, ) -> Result<ArrowReader>

query_arrow with explicit type-mapping options.

Source

pub fn query_stream_arrow_with_opts<'a>( &'a mut self, sql: &str, opts: &ArrowOptions, ) -> Result<ArrowQueryStream<'a>>

Stream a query’s result as Arrow record batches with explicit type-mapping options.

Source

pub fn insert_stream<'a>( &'a mut self, sql: &str, format: InputFormat, ) -> Result<InsertStream<'a>>

Open a streaming INSERT.

The write-side counterpart of query_stream: send the INSERT statement here, then push the rows in chunks. The statement must carry no FORMAT clause and no inline data — the format is the format argument, and the data goes through InsertStream::append.

The connection is exclusively borrowed until the stream is finished, cancelled or dropped, because it accepts no other statement meanwhile.

§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::InputFormat;

let mut conn = Connection::open_in_memory()?;
let mut ins = conn.insert_stream("INSERT INTO t (a, b)", InputFormat::CSV)?;
ins.append(b"1,\"one\"\n")?;
let stats = ins.finish()?;
§Errors

Returns Error::QueryError if the statement is invalid — a missing table, say — which is reported when the stream is opened.

Source

pub fn insert_stream_with_params<'a>( &'a mut self, sql: &str, format: InputFormat, params: impl Into<QueryParams>, ) -> Result<InsertStream<'a>>

Open a streaming INSERT whose statement carries {name:Type} placeholders.

The motivating case is INSERT INTO FUNCTION file({path:String}, ...), where the destination itself is a bound value. See query_with_params for binding rules.

Source

pub fn query_with_params( &self, sql: &str, format: OutputFormat, params: impl Into<QueryParams>, ) -> Result<QueryResult>

Execute a query with ClickHouse {name:Type} parameter binding.

Parameter values are encoded here and bound in the chDB library; they are never interpolated into the SQL text. Names in params need not match placeholder order in the query. An empty params list is a plain query.

§Examples
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;

let conn = Connection::open_in_memory()?;
let result = conn.query_with_params(
    "SELECT {x:UInt64} + {y:UInt64} AS total",
    OutputFormat::CSV,
    [("y", 5_u64), ("x", 7_u64)],
)?;
§Errors

Returns an error if:

  • The query syntax is invalid
  • A {name:Type} placeholder has no matching param
  • A value cannot be parsed as the type declared in the placeholder
  • The query execution fails for any other reason
Source

pub fn query_stream_arrow_with_params<'a>( &'a mut self, sql: &str, params: impl Into<QueryParams>, opts: Option<&ArrowOptions>, ) -> Result<ArrowQueryStream<'a>>

Execute a query with ClickHouse {name:Type} parameter binding and stream Arrow batches.

Like Self::query_stream_arrow, but SQL placeholders are bound from params in the chDB library before streaming begins. The connection is exclusively borrowed for the stream’s lifetime. Syntax errors fail when the stream is created. A missing placeholder binding is reported on the first ArrowQueryStream::next_batch, not at start.

§Examples
use chdb_rust::connection::Connection;

let mut conn = Connection::open_in_memory()?;
let mut stream = conn.query_stream_arrow_with_params(
    "SELECT {x:UInt64} AS v",
    [("x", 11_u64)],
    None,
)?;
while let Some(batch) = stream.next_batch()? {
    println!("rows: {}", batch.num_rows());
}
§Errors

Returns an error if:

  • The query syntax is invalid
  • The query cannot be started

Pass opts to control Arrow type mapping alongside the bindings; None selects the engine’s default contract.

Source

pub fn register_arrow_reader( &mut self, reader: Box<dyn RecordBatchReader + Send>, ) -> Result<ArrowRegistration<'_>>

Register an owned Arrow reader for queries within a scoped lifetime.

The returned handle generates a process-unique name and unregisters on close or drop. Use its sql_expr() in SQL and run the query through the handle so lazy results cannot outlive the input reader.

Source

pub fn register_arrow_stream( &self, table_name: &str, arrow_stream: &ArrowStream, ) -> Result<()>

Register an Arrow C Data Interface stream for use with ArrowStream('name').

Pass a raw ArrowArrayStream* (see ArrowStream). Registered names are not ordinary tables; query them with the arrow_stream_table_sql helper, e.g. SELECT * FROM ArrowStream('my_data').

The stream pointer must stay valid until unregister_arrow_table is called or the connection is dropped.

§Examples
use chdb_rust::arrow_stream::{arrow_stream_table_sql, ArrowStream};
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;

let conn = Connection::open_in_memory()?;
// let stream_ptr: *mut arrow::ffi::FFI_ArrowArrayStream = ...;
// let arrow_stream = unsafe { ArrowStream::from_raw(stream_ptr) };
// conn.register_arrow_stream("my_data", &arrow_stream)?;
// let sql = format!("SELECT * FROM {}", arrow_stream_table_sql("my_data"));
// let _ = conn.query(&sql, OutputFormat::JSONEachRow)?;
§Errors

Returns an error if:

  • The table name contains invalid characters
  • The Arrow stream handle is invalid
  • Registration fails for any other reason
Source

pub fn register_arrow_array( &self, table_name: &str, arrow_schema: &ArrowSchema, arrow_array: &ArrowArray, ) -> Result<()>

Register Arrow C Data Interface schema + array for use with ArrowStream('name').

libchdb wraps the pair in a one-shot stream. Query via arrow_stream_table_sql.

§Arguments
  • table_name - The name to register for the Arrow stream table function
  • arrow_schema - The Arrow schema handle describing the array structure
  • arrow_array - The Arrow array handle containing the data
§Returns

Returns Ok(()) on success, or an Error if registration fails.

§Examples
use chdb_rust::arrow_stream::{arrow_stream_table_sql, ArrowArray, ArrowSchema};
use chdb_rust::connection::Connection;
use chdb_rust::format::OutputFormat;

let conn = Connection::open_in_memory()?;

// Assuming you have Arrow C Data Interface schema and array handles
// let arrow_schema = unsafe { ArrowSchema::from_raw(schema_ptr) };
// let arrow_array = unsafe { ArrowArray::from_raw(array_ptr) };
// conn.register_arrow_array("my_data", &arrow_schema, &arrow_array)?;

// Query via the ArrowStream table function
// let sql = format!("SELECT * FROM {}", arrow_stream_table_sql("my_data"));
// let result = conn.query(&sql, OutputFormat::JSONEachRow)?;
§Errors

Returns an error if:

  • The table name contains invalid characters
  • The Arrow schema or array handles are invalid
  • Registration fails for any other reason
Source

pub fn unregister_arrow_table(&self, table_name: &str) -> Result<()>

Unregister an Arrow stream table function that was previously registered.

This function removes a previously registered Arrow stream table function, making it no longer available for queries.

§Arguments
  • table_name - The name of the Arrow stream table function to unregister
§Returns

Returns Ok(()) on success, or an Error if unregistration fails.

§Examples
use chdb_rust::connection::Connection;
use chdb_rust::arrow_stream::ArrowStream;

let conn = Connection::open_in_memory()?;

// Register a table
// let arrow_stream = ArrowStream::from_raw(stream_ptr);
// conn.register_arrow_stream("my_data", &arrow_stream)?;

// Use it...

// Unregister when done
// conn.unregister_arrow_table("my_data")?;
§Errors

Returns an error if:

  • The table name contains invalid characters
  • The table was not previously registered
  • Unregistration fails for any other reason

Trait Implementations§

Source§

impl Debug for Connection

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Drop for Connection

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more
Source§

impl Send for Connection

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.