{"id":34497343,"url":"https://github.com/ClickHouse/pg_clickhouse","last_synced_at":"2025-12-24T09:04:45.840Z","repository":{"id":328399812,"uuid":"1062909598","full_name":"ClickHouse/pg_clickhouse","owner":"ClickHouse","description":"Interfaces to query ClickHouse databases from PostgreSQL","archived":false,"fork":false,"pushed_at":"2025-12-18T23:53:30.000Z","size":441,"stargazers_count":96,"open_issues_count":26,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T22:51:23.055Z","etag":null,"topics":["clickhouse","fdw","postgresql","sql"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClickHouse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-23T22:50:39.000Z","updated_at":"2025-12-21T08:46:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ClickHouse/pg_clickhouse","commit_stats":null,"previous_names":["clickhouse/pg_clickhouse"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ClickHouse/pg_clickhouse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fpg_clickhouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fpg_clickhouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fpg_clickhouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fpg_clickhouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClickHouse","download_url":"https://codeload.github.com/ClickHouse/pg_clickhouse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fpg_clickhouse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27999336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","fdw","postgresql","sql"],"created_at":"2025-12-24T01:00:50.266Z","updated_at":"2025-12-24T09:04:45.834Z","avatar_url":"https://github.com/ClickHouse.png","language":"C","readme":"pg_clickhouse Postgres Extension\n================================\n\n[![PGXN]][⚙️] [![Docker]][🐳] [![GitHub]][🐙] [![Postgres]][🐘] [![ClickHouse]][🏠]\n\nThis library contains `pg_clickhouse`, a PostgreSQL extension that runs\nanalytics queries on ClickHouse right from PostgreSQL without rewriting any\nSQL. It supports PostgreSQL 13 and later and ClickHouse v23 and later.\n\n## Getting Started\n\nThe simplest way to try pg_clickhouse is the [Docker image][🐳], which\ncontains the standard PostgreSQL Docker image with the pg_clickhouse\nextension:\n\n```sh\ndocker run --name pg_clickhouse -e POSTGRES_PASSWORD=my_pass \\\n       -d ghcr.io/clickhouse/pg_clickhouse:18\ndocker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhouse'\n```\n\nSee the [tutorial](doc/tutorial.md) to get started importing ClickHouse tables\nand pushing down queries.\n\n## Documentation\n\n*   [Reference](doc/pg_clickhouse.md)\n*   [Tutorial](doc/tutorial.md)\n\n## Test Case: TPC-H\n\nThis table compares [TPC-H] query performance between regular PostgreSQL\ntables and pg_clickhouse connected to ClickHouse, both loaded at scaling\nfactor 1; ✅ indicates full pushdown, while a dash indicates a query\ncancellation after 1m. All tests run on a MacBook Pro M4 Max with 36 GB of\nmemory.\n\n| Query      | Pushdown | pg_clickhouse | PostgreSQL |\n| ---------: | :------: | ------------: | ---------: |\n|  [Query 1] |     ✅    |         73ms  |     4478ms |\n|  [Query 2] |          |             - |      560ms |\n|  [Query 3] |     ✅    |          74ms |     1454ms |\n|  [Query 4] |     ✅    |          67ms |      650ms |\n|  [Query 5] |     ✅    |         104ms |      452ms |\n|  [Query 6] |     ✅    |          42ms |      740ms |\n|  [Query 7] |     ✅    |          83ms |      633ms |\n|  [Query 8] |     ✅    |         114ms |      320ms |\n|  [Query 9] |     ✅    |         136ms |     3028ms |\n| [Query 10] |     ✅    |          10ms |        6ms |\n| [Query 11] |     ✅    |          78ms |      213ms |\n| [Query 12] |     ✅    |          37ms |     1101ms |\n| [Query 13] |          |        1242ms |      967ms |\n| [Query 14] |     ✅    |          51ms |      193ms |\n| [Query 15] |          |         522ms |     1095ms |\n| [Query 16] |          |        1797ms |      492ms |\n| [Query 17] |          |           9ms |     1802ms |\n| [Query 18] |          |          10ms |     6185ms |\n| [Query 19] |          |         532ms |       64ms |\n| [Query 20] |          |        4595ms |      473ms |\n| [Query 21] |          |        1702ms |     1334ms |\n| [Query 22] |          |         268ms |      257ms |\n\n### Compile From Source\n\n#### General Unix\n\nThe PostgreSQL and curl development packages include `pg_config` and\n`curl-config` in the path, so you should be able to just run `make` (or\n`gmake`), then `make install`, then in your database `CREATE EXTENSION http`.\n\n#### Debian / Ubuntu / APT\n\nSee [PostgreSQL Apt] for details on pulling from the PostgreSQL Apt repository.\n\n```sh\nsudo apt install \\\n  postgresql-server-18 \\\n  libcurl4-openssl-dev \\\n  uuid-dev \\\n  libssl-dev \\\n  make \\\n  cmake \\\n  g++\n```\n\n#### RedHat / CentOS / Yum\n\n```sh\nsudo yum install \\\n  postgresql-server \\\n  libcurl-devel \\\n  libuuid-devel \\\n  openssl-libs \\\n  automake \\\n  cmake \\\n  gcc\n```\n\nSee [PostgreSQL Yum] for details on pulling from the PostgreSQL Yum repository.\n\n#### Install From PGXN\n\nWith the above dependencies satisfied use the [PGXN client] (available as\n[Homebrew], [Apt] and Yum packages named `pgxnclient`) to download, compile,\nand install `pg_clickhouse`:\n\n\n```sh\npgxn install pg_clickhouse\n```\n\n#### Compile and Install\n\nTo build and install the ClickHouse library and `pg_clickhouse`, run:\n\n```sh\nmake\nsudo make install\n```\n\n\u003c!-- XXX DSO currently disabled.\nBy default `make` dynamically links the `clickhouse-cpp` library (except on\nmacOS, where a dynamic `clickhouse-cpp` library is not yet supported). To\nstatically compile the ClickHouse library into `pg_clickhouse`, pass\n`CH_BUILD=static`:\n\n```sh\nmake CH_BUILD=static\nsudo make install CH_BUILD=static\n```\n --\u003e\n\nIf your host has several PostgreSQL installations, you might need to specify\nthe appropriate version of `pg_config`:\n\n```sh\nexport PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config\nmake\nsudo make install\n```\n\nIf `curl-config` is not in the path on you host, you can specify the path\nexplicitly:\n\n```sh\nexport CURL_CONFIG=/opt/homebrew/opt/curl/bin/curl-config\nmake\nsudo make install\n```\n\nIf you encounter an error such as:\n\n``` text\n\"Makefile\", line 8: Need an operator\n```\n\nYou need to use GNU make, which may well be installed on your system as\n`gmake`:\n\n``` sh\ngmake\ngmake install\ngmake installcheck\n```\n\nIf you encounter an error such as:\n\n``` text\nmake: pg_config: Command not found\n```\n\nBe sure that you have `pg_config` installed and in your path. If you used a\npackage management system such as RPM to install PostgreSQL, be sure that the\n`-devel` package is also installed. If necessary tell the build process where\nto find it:\n\n``` sh\nexport PG_CONFIG=/path/to/pg_config\nmake\nsudo make install\n```\n\nTo install the extension in a custom prefix on PostgreSQL 18 or later, pass\nthe `prefix` argument to `install` (but no other `make` targets):\n\n```sh\nsudo make install prefix=/usr/local/extras\n```\n\nThen ensure that the prefix is included in the following [`postgresql.conf`\nparameters]:\n\n```ini\nextension_control_path = '/usr/local/extras/postgresql/share:$system'\ndynamic_library_path   = '/usr/local/extras/postgresql/lib:$libdir'\n```\n\n#### Testing\n\nTo run the test suite, once the extension has been installed, run\n\n```sh\nmake installcheck\n```\n\nIf you encounter an error such as:\n\n``` text\nERROR:  must be owner of database regression\n```\n\nYou need to run the test suite using a super user, such as the default\n\"postgres\" super user:\n\n``` sh\nmake installcheck PGUSER=postgres\n```\n\n### Loading\n\nOnce `pg_clickhouse` is installed, you can add it to a database by connecting\nas a super user and running:\n\n``` sql\nCREATE EXTENSION pg_clickhouse;\n```\n\nIf you want to install `pg_clickhouse` and all of its supporting objects into\na specific schema, use the `SCHEMA` clause to specify the schema, like so:\n\n``` sql\nCREATE SCHEMA env;\nCREATE EXTENSION pg_clickhouse SCHEMA env;\n```\n\n## Dependencies\n\nThe `pg_clickhouse` extension requires [PostgreSQL] 13 or higher, [libcurl],\n[libuuid]. Building the extension requires a C and C++ compiler, [libSSL], [GNU\nmake], and [CMake].\n\n## Road Map\n\nOur top focus is finishing pushdown coverage for analytic workloads before\nadding DML features. Our road map:\n\n*   Get the remaining 10 un-pushed-down TPC-H queries optimally planned\n*   Test and fix pushdown for the ClickBench queries\n*   Support transparent pushdown of all PostgreSQL aggregate functions\n*   Support transparent pushdown of all PostgreSQL functions\n*   Allow server-level and session-level ClickHouse settings via CREATE SERVER\n    and GUCs\n*   Support all ClickHouse data types\n*   Support lightweight DELETEs and UPDATEs\n*   Support batch insertion via COPY\n*   Add a function to execute an arbitrary ClickHouse query and return its\n    results as a tables\n*   Add support for pushdown of UNION queries when they all query the remote\n    database\n\n## Authors\n\n*   [David E. Wheeler](https://justatheory.com/)\n*   [Ildus Kurbangaliev](https://github.com/ildus)\n*   [Ibrar Ahmed](https://github.com/ibrarahmad)\n\n## Copyright\n\n*   Copyright (c) 2025, ClickHouse\n*   Portions Copyright (c) 2023-2025, Ildus Kurbangaliev\n*   Portions Copyright (c) 2019-2023, Adjust GmbH\n*   Portions Copyright (c) 2012-2019, PostgreSQL Global Development Group\n\n  [PGXN]:       https://badge.fury.io/pg/pg_clickhouse.svg\n  [⚙️]:         https://pgxn.org/dist/pg_clickhouse \"Latest version on PGXN\"\n  [Postgres]:   https://github.com/clickhouse/pg_clickhouse/actions/workflows/postgres.yml/badge.svg\n  [🐘]:         https://github.com/clickhouse/pg_clickhouse/actions/workflows/postgres.yml \"Tested with PostgreSQL 13-18\"\n  [ClickHouse]: https://github.com/clickhouse/pg_clickhouse/actions/workflows/clickhouse.yml/badge.svg\n  [🏠]:          https://github.com/clickhouse/pg_clickhouse/actions/workflows/clickhouse.yml \"Tested with ClickHouse v23–25\"\n  [Docker]:     https://img.shields.io/github/v/release/ClickHouse/pg_clickhouse?label=%F0%9F%90%B3%20Docker\u0026color=44cc11\n  [🐳]:          https://github.com/ClickHouse/pg_clickhouse/pkgs/container/pg_clickhouse \"Latest Docker release\"\n  [GitHub]:     https://img.shields.io/github/v/release/ClickHouse/pg_clickhouse?label=%F0%9F%90%99%20GitHub\u0026color=44cc11\n  [🐙]:          https://github.com/ClickHouse/pg_clickhouse/releases \"Latest release on GitHub\"\n\n  [PostgreSQL Apt]: https://wiki.postgresql.org/wiki/Apt\n  [PostgreSQL Yum]: https://yum.postgresql.org\n  [PGXN client]: https://pgxn.github.io/pgxnclient/ \"PGXN Client’s documentation\"\n  [Homebrew]: https://formulae.brew.sh/formula/pgxnclient#default \"PGXN client on Homebrew\"\n  [Apt]: https://tracker.debian.org/pkg/pgxnclient \"PGXN client on Debian Apt\"\n  [`postgresql.conf` parameters]: https://www.postgresql.org/docs/devel/runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER\n  [PostgreSQL]: https://www.postgresql.org \"PostgreSQL: The World's Most Advanced Open Source Relational Database\"\n  [libcurl]: https://curl.se/libcurl/ \"libcurl — your network transfer library\"\n  [libuuid]: https://linux.die.net/man/3/libuuid \"libuuid - DCE compatible Universally Unique Identifier library\"\n  [GNU make]: https://www.gnu.org/software/make \"GNU Make\"\n  [CMake]: https://cmake.org/ \"CMake: A Powerful Software Build System\"\n  [LibSSL]: https://openssl-library.org \"OpenSSL Library\"\n  [TPC-H]: https://www.tpc.org/tpch/\n\n  [Query 1]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/1.sql\n  [Query 2]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/2.sql\n  [Query 3]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/3.sql\n  [Query 4]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/4.sql\n  [Query 5]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/5.sql\n  [Query 6]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/6.sql\n  [Query 7]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/7.sql\n  [Query 8]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/8.sql\n  [Query 9]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/9.sql\n  [Query 10]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/10.sql\n  [Query 11]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/11.sql\n  [Query 12]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/12.sql\n  [Query 13]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/13.sql\n  [Query 14]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/14.sql\n  [Query 15]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/15.sql\n  [Query 16]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/16.sql\n  [Query 17]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/17.sql\n  [Query 18]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/18.sql\n  [Query 19]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/19.sql\n  [Query 20]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/20.sql\n  [Query 21]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/21.sql\n  [Query 22]: https://github.com/Vonng/pgtpc/blob/master/tpch/queries/22.sql\n","funding_links":[],"categories":["Language bindings","C"],"sub_categories":["C/C++"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FClickHouse%2Fpg_clickhouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FClickHouse%2Fpg_clickhouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FClickHouse%2Fpg_clickhouse/lists"}