# DB API 2.0

This part of the documentation covers driver DB API.

exception clickhouse_driver.dbapi.DataError
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.DatabaseError
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.Error
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.IntegrityError
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.InterfaceError
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.InternalError
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.NotSupportedError
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.OperationalError
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.ProgrammingError
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception clickhouse_driver.dbapi.Warning
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

clickhouse_driver.dbapi.connect(dsn=None, host=None, user='default', password='', port=9000, database='default', **kwargs)

  Create a new database connection.

  The connection can be specified via DSN:

  > `conn = connect("clickhouse://localhost/test?param1=value1&...")`

  or using database and credentials arguments:

  > `conn = connect(database="test", user="default", password="default", host="localhost", **kwargs)`

  The basic connection parameters are:

  - host: host with running ClickHouse server.

  - port: port ClickHouse server is bound to.

  - database: database connect to.

  - user: database user.

  - password: user’s password.

  See defaults in `Connection` constructor.

  DSN or host is required.

  Any other keyword parameter will be passed to the underlying Connection class.

  Returns

    a new connection.

## Connection

class clickhouse_driver.dbapi.connection.Connection(dsn=None, host=None, user='default', password='', port=9000, database='default', **kwargs)

  Creates new Connection for accessing ClickHouse database.

  Connection is just wrapper for handling multiple cursors (clients) and do not initiate actual connections to the ClickHouse server.

  See parameters description in `Connection`.

  close()

    Close the connection now. The connection will be unusable from this point forward; an `Error` (or subclass) exception will be raised if any operation is attempted with the connection. The same applies to all cursor objects trying to use the connection.

  commit()

    Do nothing since ClickHouse has no transactions.

  cursor()
    Returns

      a new Cursor Object using the connection.

  rollback()

    Do nothing since ClickHouse has no transactions.

## Cursor

class clickhouse_driver.dbapi.cursor.Cursor(client, connection)
  close()

    Close the cursor now. The cursor will be unusable from this point forward; an `Error` (or subclass) exception will be raised if any operation is attempted with the cursor.

  property columns_with_types
    Returns

      list of column names with corresponding types of the last .execute*(). E.g. [(‘x’, ‘UInt64’)].

  execute(operation, parameters=None)

    Prepare and execute a database operation (query or command).

    Parameters

      - operation – query or command to execute.

      - parameters – sequence or mapping that will be bound to variables in the operation.

    Returns

      None

  executemany(operation, seq_of_parameters)

    Prepare a database operation (query or command) and then execute it against all parameter sequences found in the sequence seq_of_parameters.

    Parameters

      - operation – query or command to execute.

      - seq_of_parameters – sequences or mappings for execution.

    Returns

      None

  fetchall()

    Fetch all (remaining) rows of a query result, returning them as a sequence of sequences (e.g. a list of tuples).

    Returns

      list of fetched rows.

  fetchmany(size=None)

    Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples). An empty sequence is returned when no more rows are available.

    Parameters

      size – amount of rows to return.

    Returns

      list of fetched rows or empty list.

  fetchone()

    Fetch the next row of a query result set, returning a single sequence, or None when no more data is available.

    Returns

      the next row of a query result set or None.

  property rowcount
    Returns

      the number of rows that the last .execute*() produced.

  set_external_table(name, structure, data)

    Adds external table to cursor context.

    If the same table is specified more than once the last one is used.

    Parameters

      - name – name of external table

      - structure – list of tuples (name, type) that defines table structure. Example [(x, ‘Int32’)].

      - data – sequence of rows of tuples or dicts for transmission.

    Returns

      None

  set_query_id(query_id)

    Specifies the query identifier for cursor.

    Parameters

      query_id – the query identifier.

    Returns

      None

  set_settings(settings)

    Specifies settings for cursor.

    Parameters

      settings – dictionary of query settings

    Returns

      None

  set_stream_results(stream_results, max_row_buffer)

    Toggles results streaming from server. Driver will consume block-by-block of max_row_buffer size and yield row-by-row from each block.

    Parameters

      - stream_results – enable or disable results streaming.

      - max_row_buffer – specifies the maximum number of rows to buffer at a time.

    Returns

      None

  set_types_check(types_check)

    Toggles type checking for sequence of INSERT parameters. Disabled by default.

    Parameters

      types_check – new types check value.

    Returns

      None