Python API Reference

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).

This is the base class for all error exceptions in chdb, excluding warnings.
It serves as the parent class for all database error conditions that prevent
successful completion of operations.

Note

This exception hierarchy follows the Python DB API 2.0 specification.

**See also**

- [`Warning`](#chdb-dbapi-err-warning) - For non-fatal warnings that don’t prevent operation completion

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

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

Exception raised when the relational integrity of the database is affected.

This exception is raised when database operations violate integrity constraints,
including:

- Foreign key constraint violations
- Primary key or unique constraint violations (duplicate keys)
- Check constraint violations
- NOT NULL constraint violations
- Referential integrity violations

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`IntegrityError`](#chdb-dbapi-err-integrityerror) When database integrity constraints are violated | | | |

**Examples**

```
>>> # Duplicate primary key
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'John')")
>>> cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Jane')")
IntegrityError: Duplicate entry '1' for key 'PRIMARY'
```

```
>>> # Foreign key violation
>>> cursor.execute("INSERT INTO orders (user_id) VALUES (999)")
IntegrityError: Cannot add or update a child row: foreign key constraint fails
```

---

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

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

Exception raised for errors that are related to the database interface rather than the database itself.

This exception is raised when there are problems with the database interface
implementation, such as:

- Invalid connection parameters
- API misuse (calling methods on closed connections)
- Interface-level protocol errors
- Module import or initialization failures

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`InterfaceError`](#chdb-dbapi-err-interfaceerror) When database interface encounters errors unrelated to database operations | | | |

Note

These errors are typically programming errors or configuration issues
that can be resolved by fixing the client code or configuration.

---

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

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

Exception raised when the database encounters an internal error.

This exception is raised when the database system encounters internal
errors that aren't caused by the application, such as:

- Invalid cursor state (cursor isn't valid anymore)
- Transaction state inconsistencies (transaction is out of sync)
- Database corruption issues
- Internal data structure corruption
- System-level database errors

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`InternalError`](#chdb-dbapi-err-internalerror) When database encounters internal inconsistencies | | | |

Warning

Internal errors may indicate serious database problems that require
database administrator attention. These errors are typically not
recoverable through application-level retry logic.

Note

These errors are generally outside the control of the application
and may require database restart or repair operations.

---

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

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

Exception raised when a method or database API isn't supported.

This exception is raised when the application attempts to use database
features or API methods that aren't supported by the current database
configuration or version, such as:

- Requesting `rollback()` on connections without transaction support
- Using advanced SQL features not supported by the database version
- Calling methods not implemented by the current driver
- Attempting to use disabled database features

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`NotSupportedError`](#chdb-dbapi-err-notsupportederror) When unsupported database features are accessed | | | |

**Examples**

```
>>> # Transaction rollback on non-transactional connection
>>> connection.rollback()
NotSupportedError: Transactions are not supported
```

```
>>> # Using unsupported SQL syntax
>>> cursor.execute("SELECT * FROM table WITH (NOLOCK)")
NotSupportedError: WITH clause not supported in this database version
```

Note

Check database documentation and driver capabilities to avoid
these errors. Consider graceful fallbacks where possible.

---

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

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

Exception raised for errors that are related to the database’s operation.

This exception is raised for errors that occur during database operation
and aren't necessarily under the control of the programmer, including:

- Unexpected disconnection from database
- Database server not found or unreachable
- Transaction processing failures
- Memory allocation errors during processing
- Disk space or resource exhaustion
- Database server internal errors
- Authentication or authorization failures

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`OperationalError`](#chdb-dbapi-err-operationalerror) When database operations fail due to operational issues | | | |

Note

These errors are typically transient and may be resolved by retrying
the operation or addressing system-level issues.

Warning

Some operational errors may indicate serious system problems that
require administrative intervention.

---

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

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

Exception raised for programming errors in database operations.

This exception is raised when there are programming errors in the
application’s database usage, including:

- Table or column not found
- Table or index already exists when creating
- SQL syntax errors in statements
- Wrong number of parameters specified in prepared statements
- Invalid SQL operations (e.g., DROP on non-existent objects)
- Incorrect usage of database API methods

**Raises**

|  |  |  |  |
| --- | --- | --- | --- |
| Exception Condition|  |  | | --- | --- | | [`ProgrammingError`](#chdb-dbapi-err-programmingerror) When SQL statements or API usage contains errors | | | |

**Examples**

```
>>> # Table not found
>>> cursor.execute("SELECT * FROM nonexistent_table")
ProgrammingError: Table 'nonexistent_table' doesn't exist
```

```
>>> # SQL syntax error
>>> cursor.execute("SELCT * FROM users")
ProgrammingError: You have an error in your SQL syntax
```