# Changelog

All notable changes to this project will be documented in this file. It uses the
[Keep a Changelog] format, and this project adheres to [Semantic Versioning].

  [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
  [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
    "Semantic Versioning 2.0.0"

## [v0.1.2] — 2026-09-30

This release makes binary-only changes. Once installed and loaded, any
existing use of chdb and chdb_hook v0.1 will get the v0.1.2 benefits without
needing to `ALTER EXTENSION UPDATE`.

### ⚡ Improvements

*   Added mappings for additional chDB data types:
    *   The [Interval] family maps to Postgres interval or bigint
    *   A [Map] maps to a two-dimensional array of key/value pairs or a custom
        two-field [composite type]
    *   A [Tuple] maps to an array of its values or [composite type]
    *   An unflattened [Nested] column maps to a two-dimensional array or
        [composite type] array
    *   All [LowCardinality] types now map to their Postgres equivalents, not
        just `LowCardinality(String)`
    *   Parameterized [JSON] (`JSON(...)`) now maps to jsonb or json
*   Added the `encoding_check` option to `COPY`. Valid values are `fail`,
    `replace`, `remove`, and `truncate`. See the [COPY docs] for details
    ([#96]).
*   Linking to libchdb v26.9.0 fixes the CVS format with NULL geometric types.

### 🐞 Bug Fixes

*   Reject `COPY FROM` a URL with a `WHERE` clause, preventing imports from
    silently ignoring row filters ([#86]).
*   Fix `CREATE TABLE` inference to use `text[]` for `Tuple` and `text[][]`
    for `Map` and `Nested` instead of `text`. Reuse source types from
    `DESCRIBE` when loading rows, keeping `Nested` fields in one column ([#89]).
*   The `install` target no longer installs `libchdb.a` when using
    `LIBCHDB_BUILD=static`. Since we statically link it, we do not need to
    install it.

### 🏗️ Build Setup

*   Added the `NO_FILE_SCHEME` option to `make`. When set, chd_hook will be
    built without support for the `file://` scheme, which may be useful for
    Postgres hosting providers ([#85]).
*   The `install` target no longer installs `libchdb.a` when using
    `LIBCHDB_BUILD=static`. Since we statically link it, we do not need to
    install it ([#87]).
*   Added the `MAX_CONCURRENT_TESTS` variable to minimize the number of
    concurrent tests in resource-constrained environments, such as CI runners
    ([#91]).
*   Added macOS testing to the CI workflow and adopted the PGXN actions for
    the CI and release workflows.

### ⬆️ Dependencies

*   Added testing for chDB v26.7.3 and v26.9.0.
*   Updated to support PostgreSQL 19 beta 4.

### 📚 Documentation

*   Added missing links to the README and docs and simplified the list of
    files to load in a single command.
*   Document [manual enum and composite type mappings](doc/chdb_hook.md#manual-type-mappings)
    for `Enum`, `Tuple`, `Map`, and `Nested` columns ([#89]).

  [v0.1.2]: https://github.com/clickhouse/pg_chdb/compare/v0.1.1...v0.1.2
  [#85]: https://github.com/ClickHouse/pg_chdb/pull/85
    "ClickHouse/pg_chdb#85 Add `NO_FILE_SCHEME` option to make"
  [#86]: https://github.com/ClickHouse/pg_chdb/pull/86
    "ClickHouse/pg_chdb#96 Reject COPY FROM WHERE"
  [#87]: https://github.com/ClickHouse/pg_chdb/pull/87
    "ClickHouse/pg_chdb#87 Don't install libchdb.a"
  [#89]: https://github.com/ClickHouse/pg_chdb/pull/89
    "ClickHouse/pg_chdb#89 Fix CREATE TABLE inference for Tuple, Map, and Nested"
  [#91]: https://github.com/ClickHouse/pg_chdb/pull/91
    "ClickHouse/pg_chdb#91 Restore `MAX_CONCURRENT_TESTS`, fix macOS"
  [#96]: https://github.com/ClickHouse/pg_chdb/pull/96
    "ClickHouse/pg_chdb#96 Update pg-clickhouse-c & add encoding_check option"
  [COPY docs](doc/chdb_hook.md#copy-overloading) "chdb_hook docs: COPY Overloading"
  [Interval]: https://clickhouse.com/docs/reference/data-types/special-data-types/interval
    "ClickHouse Docs: Interval"
  [composite type]: https://www.postgresql.org/docs/current/rowtypes.html
  [Map]: https://clickhouse.com/docs/reference/data-types/map
    "ClickHouse Docs: Map"
  [Tuple]: https://clickhouse.com/docs/reference/data-types/tuple
    "ClickHouse Docs: Tuple"
  [Nested]: https://clickhouse.com/docs/reference/data-types/nested-data-structures
    "ClickHouse Docs: Nested"
  [LowCardinality]: https://clickhouse.com/docs/reference/data-types/lowcardinality
    "ClickHouse Docs: LowCardinality"
  [JSON]: https://clickhouse.com/docs/reference/formats/JSON/JSON
  [LowCardinality]: https://clickhouse.com/docs/reference/data-types/lowcardinality
    "ClickHouse Docs: JSON"

## [v0.1.1] — 2026-09-06

This release makes binary-only changes. Once installed and loaded, any
existing use of chdb and chdb_hook v0.1 will get the v0.1.1 benefits without
needing to `ALTER EXTENSION UPDATE`.

### ⚡ Improvements

*   Support mapping `BFloat16` to `real`, and `Interval` types to `interval`.
    `Interval` types also map to `bigint` transparently ([#76], [#92]).
*   Added PostgreSQL 15 support.
*   Map `UInt64`, `Int128`, `Int256`, `UInt128`, and `UInt256` to Postgres
    `numeric`, so values above the `bigint` range no longer raise an error.
    A derived column carries the precision spanning its chDB type ([#78]).

### 🐞 Bug Fixes

*   `DateTime64` or `Time64` now defaults to millisecond precision ([#76]).
*   Reading a ClickHouse string into a text column validates its bytes against
    database encoding, raising an error instead of returning unreadable text.
    Use `bytea` to preserve raw bytes ([#80]).
*   Added the `date_time_output_format='iso'` setting to each chDB query to
    always format `timestamp` and `timestamptz` values in plain text formats
    with the ISO-8601 format in UTC, converting `timestamp` values from the
    current `timezone` setting.

### 💅🏻 Quality

*   Added comprehensive tests for timestamp and timestamptz `COPY` output and
    round-tripping, including the impact of the `timezone` setting on
    `timestamp` values.

### 📚 Documentation

*   Added the "Timestamp Conversion" section to the [chdb_hook docs] to
    document the ISO-8601 format of plain text exports of `timestamp` and
    `timestamptz` values, as well as the impact of the `timezone` setting on
    exported and imported values.
*   Added a [benchmark](dev/benchmark/) and documented its results in the
    README.

  [v0.1.1]: https://github.com/clickhouse/pg_chdb/compare/v0.1.0...v0.1.1
  [#76]: https://github.com/clickhouse/pg_chdb/issues/76
  [#78]: https://github.com/clickhouse/pg_chdb/pulls/78
  [#80]: https://github.com/clickhouse/pg_chdb/pulls/80
  [#92]: https://github.com/ClickHouse/pg_chdb/pull/92
  [chdb_hook docs]: ./doc/chdb_hook.md
  [structure]: ./doc/chdb_hook.md#structure "chdb_hook Docs: structure"

## [v0.1.0] — 2026-08-25

The theme of this release is *Shakedown.*

### ⚡ Improvements

*   New extension, everything fresh!
*   Relies on a helper app, `chdb_helper`, to encapsulate all interaction with
    [chDB]
*   chdb extension provides `chdb_query()` to execute a single, stateless
    query.
*   chdb_hooks module hooks into the `COPY` command to copy data from a remote
    URL in any of the [formats] supported by chDB
*   chdb_hooks also hooks into the `CREATE TABLE` command to copy and or
    define the column structure for the table from a remote URL in any of the
    [formats] supported by chDB
*   The `COPY` and `CREATE TABLE` hooks support a variety of URL schemes,
    including:
    *   `file`
    *   `http` and `https`
    *   `s3` for [AWS S3]
    *   `gs` for [Google Cloud Storage]
    *   `az` for [Azure Blob Storage]
    *   `abfs` for [Azure ABFS]
*   Data type mapping provided by the [pg-clickhouse-c] header-only library

### 🏗️ Build Setup

*   Requires [chDB] v26.7.0
*   PGXS build pipeline
*   PGXN and GitHub release workflows
*   Limited to macOS and Linux (only platforms supported by [chDB])
*   Dynamic linking to [chDB] by default
*   Statically link [chDB] with `LIBCHDB_BUILD=static`
*   Automatically download [chDB] with `BUNDLE_LIBCHDB=1`

### 📚 Documentation

*   chdb extension reference documentation in [doc/chdb.md](doc/chdb.md)
*   chdb_hook module reference documentation in [doc/chdb_hook.md](doc/chdb_hook.md)

  [v0.1.0]: https://github.com/clickhouse/pg_chdb/compare/fca4dc1...v0.1.0
  [chDB]: https://clickhouse.com/chdb "chDB - fast, reliable, and scalable in-process database"
  [formats]: https://github.com/chdb-io/chdb/blob/main/refs/clickhouse-formats-settings.md#complete-format-names-table
    "chDB Docs: Complete Format Names Table"
  [AWS S3]: https://aws.amazon.com/s3/ "Cloud Object Storage - Amazon S3 - Amazon Web Services"
  [Google Cloud Storage]: https://cloud.google.com/storage "Cloud Storage - Google Cloud"
  [Azure Blob Storage]: https://azure.microsoft.com/en-us/products/storage/blobs/
  [Azure ABFS]: https://learn.microsoft.com/en-us/azure/storage/blobs/data-lake-storage-introduction-abfs-uri
    "Use the Azure Data Lake Storage URI (ABFS) - Azure Storage"
  [pg-clickhouse-c]: https://github.com/ClickHouse/pg-clickhouse-c/
    "Turn a ClickHouse Native block into PostgreSQL `Datum`s and back."