Python API Reference

**Example**

```
>>> cursor.execute("SELECT id, name FROM users LIMIT 3")
>>> row = cursor.fetchone()
>>> print(row)  # (1, 'Alice')
>>> row = cursor.fetchone()
>>> print(row)  # (2, 'Bob')
```

---

#### `max_stmt_length = 1024000`[​](#max-stmt-length "Direct link to max-stmt-length")

Max statement size which [`executemany()`](#chdb-dbapi-cursors-cursor-executemany) generates.

Default value is 1024000.

---

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

Return the exact query string that would be sent to the database.

This method shows the final SQL query after parameter substitution,
which is useful for debugging and logging purposes.

**Syntax**

```
mogrify(query, args=None)
```

**Parameters**

|  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `query` str *required* SQL query with parameter placeholders|  |  |  |  | | --- | --- | --- | --- | | `args` tuple/list/dict `None` Parameters to substitute | | | | | | | | | | | |

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `str` The final SQL query string with parameters substituted | | | |

**Example**

```
>>> cur.mogrify("SELECT * FROM users WHERE id = ?", (123,))
"SELECT * FROM users WHERE id = 123"
```

Note

This method follows the extension to DB-API 2.0 used by Psycopg.

---

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

Move to the next result set (not supported).

**Syntax**

```
nextset()
```

**Returns**

|  |  |  |  |
| --- | --- | --- | --- |
| Return Type Description|  |  | | --- | --- | | `None` Always returns None as multiple result sets aren't supported | | | |

Note

chDB/ClickHouse doesn't support multiple result sets from a single query.
This method is provided for DB-API 2.0 compliance but always returns None.

---

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

Set input sizes for parameters (no-op implementation).

**Syntax**

```
setinputsizes(*args)
```

**Parameters**

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  | | --- | --- | --- | | `*args` - Parameter size specifications (ignored) | | | | | |

Note

This method does nothing but is required by DB-API 2.0 specification.
chDB automatically handles parameter sizing internally.

---

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

Set output column sizes (no-op implementation).

**Syntax**

```
setoutputsizes(*args)
```

**Parameters**

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Parameter Type Description|  |  |  | | --- | --- | --- | | `*args` - Column size specifications (ignored) | | | | | |

Note

This method does nothing but is required by DB-API 2.0 specification.
chDB automatically handles output sizing internally.

---

### Error Classes[​](#error-classes "Direct link to Error Classes")

Exception classes for chdb database operations.

This module provides a complete hierarchy of exception classes for handling
database-related errors in chdb, following the Python Database API Specification v2.0.

The exception hierarchy is structured as follows:

```
StandardError
├── Warning
└── Error
    ├── InterfaceError
    └── DatabaseError
        ├── DataError
        ├── OperationalError
        ├── IntegrityError
        ├── InternalError
        ├── ProgrammingError
        └── NotSupportedError
```

Each exception class represents a specific category of database errors:

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Exception Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `Warning` Non-fatal warnings during database operations|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `InterfaceError` Problems with the database interface itself|  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `DatabaseError` Base class for all database-related errors|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `DataError` Problems with data processing (invalid values, type errors)|  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `OperationalError` Database operational issues (connectivity, resources)|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `IntegrityError` Constraint violations (foreign keys, uniqueness)|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `InternalError` Database internal errors and corruption|  |  |  |  | | --- | --- | --- | --- | | `ProgrammingError` SQL syntax errors and API misuse|  |  | | --- | --- | | `NotSupportedError` Unsupported features or operations | | | | | | | | | | | | | | | | | | | |

Note

These exception classes are compliant with Python DB API 2.0 specification
and provide consistent error handling across different database operations.

**See also**

- [Python Database API Specification v2.0](https://peps.python.org/pep-0249/)
- `chdb.dbapi.connections` - Database connection management
- `chdb.dbapi.cursors` - Database cursor operations

**Examples**

```
>>> try:
...     cursor.execute("SELECT * FROM nonexistent_table")
... except ProgrammingError as e:
...     print(f"SQL Error: {e}")
...
SQL Error: Table 'nonexistent_table' doesn't exist
```

```
>>> try:
...     cursor.execute("INSERT INTO users (id) VALUES (1), (1)")
... except IntegrityError as e:
...     print(f"Constraint violation: {e}")
...
Constraint violation: Duplicate entry '1' for key 'PRIMARY'
```

---

#### **exception** `chdb.dbapi.err.DataError`[​](#chdb-dbapi-err-dataerror "Direct link to chdb-dbapi-err-dataerror")

Bases: [`DatabaseError`](#chdb-dbapi-err-databaseerror)

Exception raised for errors that are due to problems with the processed data.

This exception is raised when database operations fail due to issues with
the data being processed, such as:

- Division by zero operations
- Numeric values out of range
- Invalid date/time values
- String truncation errors
- Type conversion failures
- Invalid data format for column type

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`DataError`](#chdb-dbapi-err-dataerror) When data validation or processing fails | | | |

**Examples**

```
>>> # Division by zero in SQL
>>> cursor.execute("SELECT 1/0")
DataError: Division by zero
```

```
>>> # Invalid date format
>>> cursor.execute("INSERT INTO table VALUES ('invalid-date')")
DataError: Invalid date format
```

---

#### **exception** `chdb.dbapi.err.DatabaseError`[​](#chdb-dbapi-err-databaseerror "Direct link to chdb-dbapi-err-databaseerror")

Bases: [`Error`](#chdb-dbapi-err-error)

Exception raised for errors that are related to the database.

This is the base class for all database-related errors. It encompasses
all errors that occur during database operations and are related to the
database itself rather than the interface.

Common scenarios include:

- SQL execution errors
- Database connectivity issues
- Transaction-related problems
- Database-specific constraints violations

Note

This serves as the parent class for more specific database error types
such as [`DataError`](#chdb-dbapi-err-dataerror), [`OperationalError`](#chdb-dbapi-err-operationalerror), etc.

---

#### **exception** `chdb.dbapi.err.Error`[​](#chdb-dbapi-err-error "Direct link to chdb-dbapi-err-error")

Bases: [`StandardError`](#chdb-dbapi-err-standarderror)

Exception that is the base class of all other error exceptions (not Warning).