> ## 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 | 푸시다운 | | -------: | ---------: | -------------: | :--: | | \[쿼리 1] | 4693 ms | 268 ms | ✔︎ | | \[쿼리 2] | 458 ms | 3446 ms | | | \[쿼리 3] | 742 ms | 111 ms | ✔︎ | | \[쿼리 4] | 270 ms | 130 ms | ✔︎ | | \[쿼리 5] | 337 ms | 1460 ms | ✔︎ | | \[쿼리 6] | 764 ms | 53 ms | ✔︎ | | \[쿼리 7] | 619 ms | 96 ms | ✔︎ | | \[쿼리 8] | 342 ms | 156 ms | ✔︎ | | \[쿼리 9] | 3094 ms | 298 ms | ✔︎ | | \[쿼리 10] | 581 ms | 197 ms | ✔︎ | | \[쿼리 11] | 212 ms | 24 ms | | | \[쿼리 12] | 1116 ms | 84 ms | ✔︎ | | \[쿼리 13] | 958 ms | 1368 ms | | | \[쿼리 14] | 181 ms | 73 ms | ✔︎ | | \[쿼리 15] | 1118 ms | 557 ms | | | \[쿼리 16] | 497 ms | 1714 ms | | | \[쿼리 17] | 1846 ms | 32709 ms | | | \[쿼리 18] | 5823 ms | 10649 ms | | | \[쿼리 19] | 53 ms | 206 ms | ✔︎ | | \[쿼리 20] | 421 ms | - | | | \[쿼리 21] | 1349 ms | 4434 ms | | | \[쿼리 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 ``` `curl-config`가 호스트의 PATH에 없으면, 경로를 명시적으로 지정할 수 있습니다: ```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`가 설치되어 있고 경로에 포함되어 있는지 확인하십시오. PostgreSQL을 설치할 때 RPM과 같은 패키지 관리 시스템을 사용했다면 `-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 기능을 추가하기 전에 분석 워크로드에 대한 푸시다운 적용 범위를 마무리하는 것입니다. 로드맵은 다음과 같습니다: * 아직 푸시다운되지 않은 나머지 10개의 TPC-H 쿼리에 대해 최적의 실행 계획 수립 * ClickBench 쿼리에 대한 푸시다운을 테스트하고 수정 * 모든 PostgreSQL 집계 함수에 대한 투명한 푸시다운 지원 * 모든 PostgreSQL 함수에 대한 투명한 푸시다운 지원 * CREATE SERVER 및 GUCs를 통해 서버 수준과 세션 수준의 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) * 저작권 (c) 2025-2026, ClickHouse * 일부 저작권 (c) 2023-2025, Ildus Kurbangaliev * 일부 저작권 (c) 2019-2023, Adjust GmbH * 일부 저작권 (c) 2012-2019, PostgreSQL Global Development Group [pg_clickhouse]: https://github.com/clickHouse/pg_clickhouse "GitHub의 pg_clickhouse" [import foreign tables]: /products/managed-postgres/extensions/pg_clickhouse/reference#import-foreign-schema [Docker image]: https://github.com/ClickHouse/pg_clickhouse/pkgs/container/pg_clickhouse "최신 Docker 릴리스" [tutorial]: /products/managed-postgres/extensions/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)