Struct Connection 

pub struct Connection { /* private fields */ }

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

impl Connection

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

Connect to chDB with the given command-line arguments.

This is a low-level function that allows you to pass arbitrary arguments to the chDB connection. For most use cases, prefer open_in_memory or open_with_path.

Arguments

• args - Array of command-line arguments (e.g., ["clickhouse", "--path=/tmp/db"])

Examples

use chdb_rust::connection::Connection;

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

Errors

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

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.

pub fn open_with_path(path: &str) -> Result<Self>

Connect to a database at the given path.

Creates a connection to a persistent database stored at the specified path. The directory will be created if it doesn’t exist.

Arguments

• path - The filesystem path where the database should be stored

Examples

use chdb_rust::connection::Connection;

let conn = Connection::open_with_path("/tmp/mydb")?;

Errors

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

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

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

Register an Arrow stream as a table function with the given name.

This function registers an Arrow stream as a virtual table that can be queried using SQL. The table will be available for queries until it is unregistered.

Arguments

• table_name - The name to register for the Arrow stream table function
• arrow_stream - The Arrow stream handle to register

Returns

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

Examples

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

let conn = Connection::open_in_memory()?;

// Assuming you have an Arrow stream handle
// let arrow_stream = ArrowStream::from_raw(stream_ptr);
// conn.register_arrow_stream("my_data", &arrow_stream)?;

// Now you can query it
// let result = conn.query("SELECT * FROM my_data", 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

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

Register an Arrow array as a table function with the given name.

This function registers an Arrow array (with its schema) as a virtual table that can be queried using SQL. The table will be available for queries until it is unregistered.

Arguments

• table_name - The name to register for the Arrow array 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::connection::Connection;
use chdb_rust::arrow_stream::{ArrowSchema, ArrowArray};

let conn = Connection::open_in_memory()?;

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

// Now you can query it
// let result = conn.query("SELECT * FROM my_data", 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

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

impl Debug for Connection

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

Formats the value using the given formatter.

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Connection