pg_clickhouse

### Compile From Source[​](#compile-from-source "Direct link to Compile From Source")

#### General Unix[​](#general-unix "Direct link to General Unix")

The PostgreSQL and curl development packages include `pg_config` and
`curl-config` in the path, so you should be able to just run `make` (or
`gmake`), then `make install`, then in your database
`CREATE EXTENSION pg_clickhouse`.

#### Debian / Ubuntu / APT[​](#debian--ubuntu--apt "Direct link to Debian / Ubuntu / APT")

See [PostgreSQL Apt](https://wiki.postgresql.org/wiki/Apt) for details on pulling from the PostgreSQL Apt repository.

```
sudo apt install \
  postgresql-server-18 \
  libcurl4-openssl-dev \
  uuid-dev \
  libssl-dev \
  make \
  cmake \
  g++
```

#### RedHat / CentOS / Yum[​](#redhat--centos--yum "Direct link to RedHat / CentOS / Yum")

```
sudo yum install \
  postgresql-server \
  libcurl-devel \
  libuuid-devel \
  openssl-libs \
  automake \
  cmake \
  gcc
```

See [PostgreSQL Yum](https://yum.postgresql.org) for details on pulling from the PostgreSQL Yum repository.

#### Install From PGXN[​](#install-from-pgxn "Direct link to Install From PGXN")

With the above dependencies satisfied use the [PGXN client](https://pgxn.github.io/pgxnclient/ "PGXN Client’s documentation") (available as
[Homebrew](https://formulae.brew.sh/formula/pgxnclient#default "PGXN client on Homebrew"), [Apt](https://tracker.debian.org/pkg/pgxnclient "PGXN client on Debian Apt") and Yum packages named `pgxnclient`) to download, compile,
and install `pg_clickhouse`:

```
pgxn install pg_clickhouse
```

#### Compile and Install[​](#compile-and-install "Direct link to Compile and Install")

To build and install the ClickHouse library and `pg_clickhouse`, run:

```
make
sudo make install
```

If your host has several PostgreSQL installations, you might need to specify
the appropriate version of `pg_config`:

```
export PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config
make
sudo make install
```

If `curl-config` isn't in the path on you host, you can specify the path
explicitly:

```
export CURL_CONFIG=/opt/homebrew/opt/curl/bin/curl-config
make
sudo make install
```

If you encounter an error such as:

```
"Makefile", line 8: Need an operator
```

You need to use GNU make, which may well be installed on your system as
`gmake`:

```
gmake
gmake install
gmake installcheck
```

If you encounter an error such as:

```
make: pg_config: Command not found
```

Be sure that you have `pg_config` installed and in your path. If you used a
package management system such as RPM to install PostgreSQL, be sure that the
`-devel` package is also installed. If necessary tell the build process where
to find it:

```
export PG_CONFIG=/path/to/pg_config
make
sudo make install
```

To install the extension in a custom prefix on PostgreSQL 18 or later, pass
the `prefix` argument to `install` (but no other `make` targets):

```
sudo make install prefix=/usr/local/extras
```

Then ensure that the prefix is included in the following [`postgresql.conf`
parameters](https://www.postgresql.org/docs/devel/runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER):

```
extension_control_path = '/usr/local/extras/postgresql/share:$system'
dynamic_library_path   = '/usr/local/extras/postgresql/lib:$libdir'
```

#### Testing[​](#testing "Direct link to Testing")

To run the test suite, once the extension has been installed, run

```
make installcheck
```

If you encounter an error such as:

```
ERROR:  must be owner of database regression
```

You need to run the test suite using a super user, such as the default
"postgres" super user:

```
make installcheck PGUSER=postgres
```

### Loading[​](#loading "Direct link to Loading")

Once `pg_clickhouse` is installed, you can add it to a database by connecting
as a super user and running:

```
CREATE EXTENSION pg_clickhouse;
```

If you want to install `pg_clickhouse` and all of its supporting objects into
a specific schema, use the `SCHEMA` clause to specify the schema, like so:

```
CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;
```

## Dependencies[​](#dependencies "Direct link to Dependencies")

The `pg_clickhouse` extension requires [PostgreSQL](https://www.postgresql.org "PostgreSQL: The World's Most Advanced Open Source Relational Database") 13 or higher, [libcurl](https://curl.se/libcurl/ "libcurl — your network transfer library"),
[libuuid](https://linux.die.net/man/3/libuuid "libuuid - DCE compatible Universally Unique Identifier library"). Building the extension requires a C and C++ compiler, [libSSL](https://openssl-library.org "OpenSSL Library"), [GNU
make](https://www.gnu.org/software/make "GNU Make"), and [CMake](https://cmake.org/ "CMake: A Powerful Software Build System").

## Road Map[​](#road-map "Direct link to Road Map")

Our top focus is finishing pushdown coverage for analytic workloads before
adding DML features. Our road map:

- Get the remaining 10 un-pushed-down TPC-H queries optimally planned
- Test and fix pushdown for the ClickBench queries
- Support transparent pushdown of all PostgreSQL aggregate functions
- Support transparent pushdown of all PostgreSQL functions
- Allow server-level and session-level ClickHouse settings via CREATE SERVER
  and GUCs
- Support all ClickHouse data types
- Support lightweight DELETEs and UPDATEs
- Support batch insertion via COPY
- Add a function to execute an arbitrary ClickHouse query and return its
  results as a tables
- Add support for pushdown of UNION queries when they all query the remote
  database

## Authors[​](#authors "Direct link to Authors")

- [David E. Wheeler](https://justatheory.com/)
- [Ildus Kurbangaliev](https://github.com/ildus)
- [Ibrar Ahmed](https://github.com/ibrarahmad)

## Copyright[​](#copyright "Direct link to Copyright")

- Copyright (c) 2025-2026, ClickHouse
- Portions Copyright (c) 2023-2025, Ildus Kurbangaliev
- Portions Copyright (c) 2019-2023, Adjust GmbH
- Portions Copyright (c) 2012-2019, PostgreSQL Global Development Group

[Query 1] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/1.sql>
[Query 2] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/2.sql>
[Query 3] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/3.sql>
[Query 4] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/4.sql>
[Query 5] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/5.sql>
[Query 6] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/6.sql>
[Query 7] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/7.sql>
[Query 8] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/8.sql>
[Query 9] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/9.sql>
[Query 10] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/10.sql>
[Query 11] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/11.sql>
[Query 12] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/12.sql>
[Query 13] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/13.sql>
[Query 14] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/14.sql>
[Query 15] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/15.sql>
[Query 16] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/16.sql>
[Query 17] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/17.sql>
[Query 18] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/18.sql>
[Query 19] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/19.sql>
[Query 20] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/20.sql>
[Query 21] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/21.sql>
[Query 22] <https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/22.sql>