> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > SQL을 다시 작성할 필요 없이 PostgreSQL에서 바로 ClickHouse 분석 쿼리를 실행하세요 # pg_clickhouse 참조 문서
## 소개
오픈소스 PostgreSQL 확장인 \[pg\_clickhouse]는 SQL을 다시 작성할 필요 없이 PostgreSQL에서 바로 ClickHouse에 분석 쿼리를 실행할 수 있게 해줍니다. PostgreSQL 13 이상과 ClickHouse v23 이상을 지원합니다. [ClickPipes](/ko/integrations/clickpipes/home)가 데이터를 ClickHouse로 동기화하기 시작하면 pg\_clickhouse를 사용해 PostgreSQL 스키마로 \[외부 테이블 가져오기]를 빠르고 쉽게 수행할 수 있습니다. 그러면 해당 테이블에 대해 기존 PostgreSQL 쿼리를 그대로 실행하면서도 기존 코드베이스는 유지하고, 실행은 ClickHouse로 푸시다운할 수 있습니다.
## 시작하기
pg\_clickhouse를 가장 간단하게 사용해 보는 방법은 \[Docker 이미지]를 이용하는 것으로, 여기에는 pg\_clickhouse와 [re2] 확장이 포함된 표준 PostgreSQL Docker 이미지가 들어 있습니다: ```sh theme={null} docker run --name pg_clickhouse -e POSTGRES_PASSWORD=my_pass \ -d ghcr.io/clickhouse/pg_clickhouse:18 docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhouse' ``` ClickHouse 테이블 가져오기와 쿼리 푸시다운을 시작하려면 [tutorial]을 참고하세요.
## 테스트 케이스: TPC-H
이 표는 일반 PostgreSQL 테이블과 ClickHouse에 연결된 pg\_clickhouse의 [TPC-H] 쿼리 성능을 비교한 것입니다. 두 환경 모두 스케일링 팩터 1로 로드되었으며, ✔︎는 완전한 푸시다운을, 대시는 쿼리가 1분 후 취소되었음을 뜻합니다. 모든 테스트는 36 GB 메모리가 탑재된 MacBook Pro M4 Max에서 실행되었습니다. | 쿼리 | PostgreSQL | pg\_clickhouse | 푸시다운 | | ----------: | ---------: | -------------: | :--: | | \[Query 1] | 4693 ms | 268 ms | ✔︎ | | \[Query 2] | 458 ms | 3446 ms | | | \[Query 3] | 742 ms | 111 ms | ✔︎ | | \[Query 4] | 270 ms | 130 ms | ✔︎ | | \[Query 5] | 337 ms | 1460 ms | ✔︎ | | \[Query 6] | 764 ms | 53 ms | ✔︎ | | \[Query 7] | 619 ms | 96 ms | ✔︎ | | \[Query 8] | 342 ms | 156 ms | ✔︎ | | \[Query 9] | 3094 ms | 298 ms | ✔︎ | | \[Query 10] | 581 ms | 197 ms | ✔︎ | | \[Query 11] | 212 ms | 24 ms | | | \[Query 12] | 1116 ms | 84 ms | ✔︎ | | \[Query 13] | 958 ms | 1368 ms | | | \[Query 14] | 181 ms | 73 ms | ✔︎ | | \[Query 15] | 1118 ms | 557 ms | | | \[Query 16] | 497 ms | 1714 ms | | | \[Query 17] | 1846 ms | 32709 ms | | | \[Query 18] | 5823 ms | 10649 ms | | | \[Query 19] | 53 ms | 206 ms | ✔︎ | | \[Query 20] | 421 ms | - | | | \[Query 21] | 1349 ms | 4434 ms | | | \[Query 22] | 258 ms | 1415 ms | |
### 소스에서 컴파일하기
#### 일반 Unix
PostgreSQL 및 curl 개발 패키지에는 `pg_config`와 `curl-config`가 경로에 포함되어 있으므로, `make`(또는 `gmake`)를 실행한 다음 `make install`을 실행하고, 데이터베이스에서 `CREATE EXTENSION pg_clickhouse`를 실행하면 됩니다.
#### Debian / Ubuntu / APT
PostgreSQL Apt 저장소에서 패키지를 가져오는 방법에 대한 자세한 내용은 [PostgreSQL Apt]를 참조하세요. ```sh theme={null} sudo apt install \ postgresql-server-18 \ libcurl4-openssl-dev \ uuid-dev \ libssl-dev \ make \ cmake \ g++ ```
#### RedHat / CentOS / Yum
```sh theme={null} sudo yum install \ postgresql-server \ libcurl-devel \ libuuid-devel \ openssl-libs \ automake \ cmake \ gcc ``` [PostgreSQL Yum] 저장소에서 가져오는 방법에 대한 자세한 내용은 [PostgreSQL Yum]을 참조하세요.
#### PGXN에서 설치
위의 의존성을 충족했다면 \[PGXN 클라이언트]\([Homebrew], [Apt], 그리고 `pgxnclient`라는 이름의 Yum 패키지로 제공됨)를 사용해 `pg_clickhouse`를 다운로드하고, 컴파일한 뒤 설치하세요: ```sh theme={null} pgxn install pg_clickhouse ```
#### 컴파일 및 설치
ClickHouse 라이브러리와 `pg_clickhouse`를 빌드하고 설치하려면 다음 명령을 실행하세요: ```sh theme={null} make sudo make install ``` 호스트에 PostgreSQL이 여러 버전 설치되어 있다면, 알맞은 버전의 `pg_config`를 지정해야 할 수 있습니다: ```sh theme={null} export PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config make sudo make install ``` 호스트의 PATH에 `curl-config`가 없으면, 해당 경로를 명시적으로 지정할 수 있습니다: ```sh theme={null} export CURL_CONFIG=/opt/homebrew/opt/curl/bin/curl-config make sudo make install ``` 다음과 같은 오류가 발생했다면: ```text theme={null} "Makefile", line 8: Need an operator ``` GNU make를 사용해야 하며, 시스템에 `gmake`라는 이름으로 설치되어 있을 수 있습니다: ```sh theme={null} gmake gmake install gmake installcheck ``` 다음과 같은 오류가 발생했다면: ```text theme={null} make: pg_config: Command not found ``` `pg_config`가 설치되어 있고 경로에 포함되어 있는지 확인하세요. RPM과 같은 패키지 관리 시스템을 사용해 PostgreSQL을 설치했다면 `-devel` 패키지도 설치되어 있는지 확인하세요. 필요한 경우 빌드 프로세스에 해당 파일의 위치를 알려주세요: ```sh theme={null} export PG_CONFIG=/path/to/pg_config make sudo make install ``` PostgreSQL 18 이상에서 사용자 지정 prefix에 확장을 설치하려면, `install`에 `prefix` 인수를 전달하세요(`make`의 다른 대상에는 전달하지 마세요): ```sh theme={null} sudo make install prefix=/usr/local/extras ``` 그런 다음 다음 \[`postgresql.conf` 매개변수]에 접두사가 포함되어 있는지 확인하세요: ```ini theme={null} extension_control_path = '/usr/local/extras/postgresql/share:$system' dynamic_library_path = '/usr/local/extras/postgresql/lib:$libdir' ```
#### 테스트
테스트 스위트를 실행하려면 확장을 설치한 후 다음을 실행하세요 ```sh theme={null} make installcheck ``` 다음과 같은 오류가 발생하는 경우: ```text theme={null} ERROR: must be owner of database regression ``` 기본 "postgres" 슈퍼유저와 같은 슈퍼유저 계정을 사용해 테스트 스위트를 실행해야 합니다: ```sh theme={null} make installcheck PGUSER=postgres ```
### 불러오기
`pg_clickhouse`를 설치한 후에는 슈퍼유저로 접속한 다음 아래를 실행해 데이터베이스에 추가할 수 있습니다: ```sql theme={null} CREATE EXTENSION pg_clickhouse; ``` `pg_clickhouse`와 관련 지원 객체를 모두 특정 스키마에 설치하려면 다음과 같이 `SCHEMA` 절을 사용해 해당 스키마를 지정하세요: ```sql theme={null} CREATE SCHEMA env; CREATE EXTENSION pg_clickhouse SCHEMA env; ```
## 의존성
`pg_clickhouse` 확장을 사용하려면 [PostgreSQL] 13 이상, [libcurl], [libuuid]가 필요합니다. 확장을 빌드하려면 C 및 C++ 컴파일러, [libSSL], [GNU make], [CMake]가 필요합니다.
## 로드맵
가장 우선순위가 높은 과제는 DML 기능을 추가하기에 앞서 분석 워크로드에 대한 푸시다운 커버리지를 완성하는 것입니다. 로드맵은 다음과 같습니다. * 아직 푸시다운되지 않은 나머지 TPC-H 쿼리 10개를 최적으로 계획하기 * ClickBench 쿼리에 대한 푸시다운을 테스트하고 수정하기 * 모든 PostgreSQL 집계 함수의 투명한 푸시다운 지원 * 모든 PostgreSQL 함수의 투명한 푸시다운 지원 * CREATE SERVER와 GUC를 통해 서버 수준 및 세션 수준의 ClickHouse 설정 허용 * 모든 ClickHouse 데이터 타입 지원 * 경량 DELETE 및 UPDATE 지원 * COPY를 통한 배치 삽입 지원 * 임의의 ClickHouse 쿼리를 실행하고 그 결과를 테이블로 반환하는 함수 추가 * 모두 원격 데이터베이스를 조회하는 경우 UNION 쿼리의 푸시다운 지원 추가
## 저자
* [David E. Wheeler](https://justatheory.com/) * [Ildus Kurbangaliev](https://github.com/ildus) * [Ibrar Ahmed](https://github.com/ibrarahmad) * 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 [pg_clickhouse]: https://github.com/clickHouse/pg_clickhouse "GitHub의 pg_clickhouse" [import foreign tables]: /integrations/connectors/tools/pg_clickhouse/reference#import-foreign-schema [Docker image]: https://github.com/ClickHouse/pg_clickhouse/pkgs/container/pg_clickhouse "최신 Docker 릴리스" [tutorial]: /integrations/connectors/tools/pg_clickhouse/tutorial "pg_clickhouse 튜토리얼" [PostgreSQL Apt]: https://wiki.postgresql.org/wiki/Apt [PostgreSQL Yum]: https://yum.postgresql.org [PGXN client]: https://pgxn.github.io/pgxnclient/ "PGXN 클라이언트 문서" [Homebrew]: https://formulae.brew.sh/formula/pgxnclient#default "Homebrew의 PGXN 클라이언트" [Apt]: https://tracker.debian.org/pkg/pgxnclient "Debian Apt의 PGXN 클라이언트" [`postgresql.conf` parameters]: https://www.postgresql.org/docs/devel/runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER [PostgreSQL]: https://www.postgresql.org "PostgreSQL: 세계에서 가장 진보한 오픈 소스 관계형 데이터베이스" [libcurl]: https://curl.se/libcurl/ "libcurl — 네트워크 전송 라이브러리" [libuuid]: https://linux.die.net/man/3/libuuid "libuuid - DCE 호환 범용 고유 식별자 라이브러리" [GNU make]: https://www.gnu.org/software/make "GNU Make" [CMake]: https://cmake.org/ "CMake: 강력한 소프트웨어 빌드 시스템" [LibSSL]: https://openssl-library.org "OpenSSL 라이브러리" [TPC-H]: https://www.tpc.org/tpch/ [re2]: https://github.com/ClickHouse/pg_re2 "pg_re2: RE2를 사용하는 ClickHouse 호환 정규식 함수" \[쿼리 1] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/1.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/1.sql) \[쿼리 2] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/2.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/2.sql) \[쿼리 3] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/3.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/3.sql) \[쿼리 4] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/4.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/4.sql) \[쿼리 5] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/5.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/5.sql) \[쿼리 6] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/6.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/6.sql) \[쿼리 7] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/7.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/7.sql) \[쿼리 8] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/8.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/8.sql) \[쿼리 9] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/9.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/9.sql) \[쿼리 10] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/10.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/10.sql) \[쿼리 11] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/11.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/11.sql) \[쿼리 12] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/12.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/12.sql) \[쿼리 13] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/13.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/13.sql) \[쿼리 14] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/14.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/14.sql) \[쿼리 15] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/15.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/15.sql) \[쿼리 16] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/16.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/16.sql) \[쿼리 17] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/17.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/17.sql) \[쿼리 18] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/18.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/18.sql) \[쿼리 19] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/19.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/19.sql) \[쿼리 20] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/20.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/20.sql) \[쿼리 21] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/21.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/21.sql) \[쿼리 22] [https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/22.sql](https://github.com/ClickHouse/pg\_clickhouse/blob/main/dev/tpch/queries/22.sql)