Python API Reference

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `pd.DataFrame` pandas DataFrame containing the query results | | | |

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | `ImportError` If pyarrow or pandas aren't installed | | | |

**Example**

```
>>> result = chdb.query("SELECT 1 as id, 'hello' as msg", "Arrow")
>>> df = chdb.to_df(result)
>>> print(df)
   id    msg
0   1  hello
```

## Connection and Session Management[​](#connection-session-management "Direct link to Connection and Session Management")

The following Session Functions are available:

### `chdb.connect`[​](#chdb-connect "Direct link to chdb-connect")

Create a connection to chDB background server.

This function establishes a [Connection](#chdb-state-sqlitelike-connection) to the chDB (ClickHouse) database engine.
Only one open connection is allowed per process.
Multiple calls with the same connection string will return the same connection object.

```
chdb.connect(connection_string: str = ':memory:') → Connection
```

**Parameters:**

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  | | --- | --- | --- | --- | | `connection_string` str `":memory:"` Database connection string. See formats below. | | | | | | | |

**Basic formats**

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Format Description|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `":memory:"` In-memory database (default)|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `"test.db"` Relative path database file|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `"file:test.db"` Same as relative path|  |  |  |  | | --- | --- | --- | --- | | `"/path/to/test.db"` Absolute path database file|  |  | | --- | --- | | `"file:/path/to/test.db"` Same as absolute path | | | | | | | | | | | |

**With query parameters**

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Format Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `"file:test.db?param1=value1&param2=value2"` Relative path with params|  |  |  |  | | --- | --- | --- | --- | | `"file::memory:?verbose&log-level=test"` In-memory with params|  |  | | --- | --- | | `"///path/to/test.db?param1=value1&param2=value2"` Absolute path with params | | | | | | | |

**Query parameter handling**

Query parameters are passed to ClickHouse engine as startup arguments.
Special parameter handling:

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Special Parameter Becomes Description|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `mode=ro` `--readonly=1` Read-only mode|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `verbose` (flag) Enables verbose logging|  |  |  | | --- | --- | --- | | `log-level=test` (setting) Sets logging level | | | | | | | | | | | |

For a complete parameter list, see `clickhouse local --help --verbose`

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `Connection` Database connection object that supports: • Creating cursors with `Connection.cursor()` • Direct queries with `Connection.query()` • Streaming queries with `Connection.send_query()` • Context manager protocol for automatic cleanup | | | |

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | `RuntimeError` If connection to database fails | | | |

Note

Only one connection per process is supported.
Creating a new connection will close any existing connection.

**Examples**

```
>>> # In-memory database
>>> conn = connect()
>>> conn = connect(":memory:")
>>>
>>> # File-based database
>>> conn = connect("my_data.db")
>>> conn = connect("/path/to/data.db")
>>>
>>> # With parameters
>>> conn = connect("data.db?mode=ro")  # Read-only mode
>>> conn = connect(":memory:?verbose&log-level=debug")  # Debug logging
>>>
>>> # Using context manager for automatic cleanup
>>> with connect("data.db") as conn:
...     result = conn.query("SELECT 1")
...     print(result)
>>> # Connection automatically closed
```

**See also**

- [`Connection`](#chdb-state-sqlitelike-connection) - Database connection class
- [`Cursor`](#chdb-state-sqlitelike-cursor) - Database cursor for DB-API 2.0 operations

## Exception Handling[​](#chdb-exceptions "Direct link to Exception Handling")

### **class** `chdb.ChdbError`[​](#chdb_chdbError "Direct link to chdb_chdbError")

Bases: `Exception`

Base exception class for chDB-related errors.

This exception is raised when chDB query execution fails or encounters
an error. It inherits from the standard Python Exception class and
provides error information from the underlying ClickHouse engine.

---

### **class** `chdb.session.Session`[​](#chdb_session_session "Direct link to chdb_session_session")

Bases: `object`

Session will keep the state of query.
If path is None, it will create a temporary directory and use it as the database path
and the temporary directory will be removed when the session is closed.
You can also pass in a path to create a database at that path where will keep your data.

You can also use a connection string to pass in the path and other parameters.

```
class chdb.session.Session(path=None)
```

**Examples**

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Connection String Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `":memory:"` In-memory database|  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `"test.db"` Relative path|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `"file:test.db"` Same as above|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `"/path/to/test.db"` Absolute path|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `"file:/path/to/test.db"` Same as above|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `"file:test.db?param1=value1&param2=value2"` Relative path with query params|  |  |  |  | | --- | --- | --- | --- | | `"file::memory:?verbose&log-level=test"` In-memory database with query params|  |  | | --- | --- | | `"///path/to/test.db?param1=value1&param2=value2"` Absolute path with query params | | | | | | | | | | | | | | | | | |

Connection string args handling

Connection strings containing query params like “<file:test.db?param1=value1&param2=value2>”
“param1=value1” will be passed to ClickHouse engine as start up args.

For more details, see `clickhouse local –help –verbose`

Some special args handling:

- “mode=ro” would be “–readonly=1” for clickhouse (read-only mode)

Important

- There can be only one session at a time. If you want to create a new session, you need to close the existing one.
- Creating a new session will close the existing one.

---

#### `cleanup`[​](#cleanup "Direct link to cleanup")

Cleanup session resources with exception handling.

This method attempts to close the session while suppressing any exceptions
that might occur during the cleanup process. It’s particularly useful in
error handling scenarios or when you need to ensure cleanup happens regardless
of the session state.

**Syntax**

```
cleanup()
```

Note

This method will never raise an exception, making it safe to call in
finally blocks or destructors.

**Examples**

```
>>> session = Session("test.db")
>>> try:
...     session.query("INVALID SQL")
... finally:
...     session.cleanup()  # Safe cleanup regardless of errors
```

**See also**