ClickHouse Managed Postgres FAQ

모니터링 및 메트릭

ClickHouse Managed Postgres 인스턴스의 메트릭은 어떻게 확인하나요?

ClickHouse Cloud Console에서 ClickHouse Managed Postgres 인스턴스의 모니터링 탭으로 이동하면 CPU, 메모리, IOPS 및 스토리지 사용량을 직접 모니터링할 수 있습니다. 또한 Query Insights 탭에서 쿼리를 자세히 분석할 수 있도록 Query Performance Insights를 살펴볼 수 있습니다.

백업 및 복구

사용 가능한 백업 옵션은 무엇입니까?

ClickHouse Managed Postgres에는 지속적인 WAL 아카이빙과 함께 매일 자동 백업이 포함되어 있어 7일 보관 기간 내의 임의 시점으로 시점 복구를 수행할 수 있습니다. 백업은 객체 스토리지에 저장됩니다. 백업 주기, 보관 기간, 시점 복구 수행 방법에 대한 자세한 내용은 백업 및 복원 문서를 참조하십시오.

인프라 및 자동화

어떤 클라우드 제공업체가 지원됩니까?

ClickHouse Managed Postgres는 AWS에서 퍼블릭 베타로 제공됩니다. GCP는 비공개 프리뷰 단계입니다. GCP 비공개 프리뷰 대기 명단은 여기에서 신청할 수 있으며, 더 자세한 내용은 공지를 참고하십시오. 세부 사항은 지원되는 클라우드 제공업체를 참고하십시오.

ClickHouse Managed Postgres에서 Terraform을 지원하나요?

예. ClickHouse Terraform 프로바이더의 clickhouse_postgres_service 리소스를 사용해 ClickHouse Managed Postgres 서비스를 생성하고 관리할 수 있습니다. 자세한 내용은 Terraform 참고를 확인하십시오. 또한 ClickHouse Cloud 콘솔이나 OpenAPI를 사용해 인스턴스를 생성하고 관리할 수도 있습니다.

확장 기능 및 구성

어떤 확장 기능을 지원하나요?

ClickHouse Managed Postgres에는 PostGIS, pgvector, pg_cron 등 널리 사용되는 PostgreSQL 확장 기능을 포함해 90개 이상의 PostgreSQL 확장 기능이 제공됩니다. 사용 가능한 확장 기능의 전체 목록과 설치 방법은 확장 기능 문서를 참조하십시오.

PostgreSQL 구성 매개변수를 사용자 지정할 수 있나요?

예, Console의 설정 탭에서 PostgreSQL 및 PgBouncer의 구성 매개변수를 수정할 수 있습니다. 사용 가능한 매개변수와 변경 방법에 대한 자세한 내용은 설정 문서를 참조하십시오.

현재 제공되지 않는 매개변수가 필요하면 support에 문의하여 요청하십시오.

연결 풀링

PgBouncer를 통해 `prepared statement does not exist` 오류가 발생하는 이유는 무엇입니까?

ClickHouse Managed Postgres는 PgBouncer를 트랜잭션 풀링(transaction pooling) 모드로 실행합니다. 이 모드에서는 백엔드 Postgres 연결이 단일 트랜잭션 동안에만 클라이언트에 할당되었다가 풀로 반환됩니다. 따라서 같은 클라이언트에서 보낸 다음 트랜잭션이 다른 백엔드에서 실행될 수 있습니다. PgBouncer는 프로토콜 수준 prepared statement를 추적합니다. 대부분의 드라이버는 확장 쿼리 프로토콜(Parse, Bind, Execute 메시지)을 사용해 이를 전송합니다. 아직 해당 SQL 문을 받은 적이 없는 백엔드에서 SQL 문이 실행되면 PgBouncer가 먼저 그 백엔드에서 SQL 문을 준비합니다. 각 백엔드 연결은 prepared statement를 최대 max_prepared_statements개(기본값 200)까지 유지합니다. 따라서 대부분의 드라이버는 기본 설정 그대로 PgBouncer를 통해 정상적으로 동작합니다. 다음 항목은 PgBouncer를 통해 동작하지 않습니다.

SQL 수준 prepared statement. PgBouncer는 SQL로 전송된 PREPARE와 EXECUTE를 추적하지 않으므로, PREPARE를 실행한 적이 없는 백엔드에서 EXECUTE가 실행될 수 있습니다.
SQL DEALLOCATE를 사용한 SQL 문 해제. PgBouncer는 백엔드에서 SQL 문의 이름을 바꾸므로, 클라이언트 측 SQL 문 이름으로 DEALLOCATE를 실행하면 실패합니다. 트랜잭션 안에서 이 오류가 발생하면 트랜잭션이 중단되고, 이후 SQL 문은 current transaction is aborted 오류와 함께 실패합니다. libpq 17 이상을 기반으로 하는 드라이버는 대신 프로토콜 수준 Close 메시지로 SQL 문을 해제하며, PgBouncer는 이 메시지를 처리할 수 있습니다.
여러 왕복에 나뉘어 전송되는 이름 없는 SQL 문. 일부 드라이버 모드는 이름 없는 SQL 문의 Parse를 한 번의 왕복으로 보내고 Bind는 다음 왕복으로 보냅니다. 이때 PgBouncer가 두 번째 왕복을 다른 백엔드에서 실행할 수 있으며, 그러면 unnamed prepared statement does not exist 오류와 함께 실패하거나, 아무런 오류 없이 다른 클라이언트의 SQL 문을 실행하고 그 결과를 반환합니다.

이러한 경우 다음과 같은 오류가 발생합니다.

ERROR:  prepared statement "..." does not exist
ERROR:  unnamed prepared statement does not exist
ERROR:  prepared statement did not exist

다음은 흔히 동일한 근본 원인에서 비롯되는 증상입니다.

특히 백필이나 동시성이 높은 쓰기 작업 중에 prepared statement does not exist 오류가 집중적으로 발생합니다
삽입이 “조용히 실패”하는 것처럼 보입니다. SQL 문에서 오류가 발생하고 드라이버가 재시도하는 과정에서 배치가 일부만 적용되거나 누락될 수 있습니다
SQL 문이 해제된 후 트랜잭션이 current transaction is aborted 오류와 함께 실패합니다
다른 쿼리에 속한 행이 반환됩니다

해결 방법: 아래에서 사용 중인 드라이버에 해당하는 설정을 적용하십시오. 드라이버가 목록에 없다면 libpq 17 이상을 사용하는 릴리스로 업그레이드하거나, 드라이버에서 서버 측 prepared statement를 비활성화하십시오.

드라이버	PgBouncer 경유 시
node-postgres / pg (Node.js)	변경할 필요가 없습니다.
Bun.sql (Bun)	변경할 필요가 없습니다. `prepared statement does not exist` 오류가 발생하면 `prepare: false`를 설정하십시오.
Prisma (`@prisma/adapter-pg` 사용)	변경할 필요가 없습니다. Prisma 7에서는 `pgbouncer=true` URL 매개변수가 적용되지 않습니다.
psycopg 3 (Python, Django)	`psycopg[binary]` 또는 libpq 17 이상을 사용하면 변경할 필요가 없습니다. 이전 버전의 libpq를 사용한다면 `prepare_threshold=None`을 설정하십시오. Django는 기본적으로 클라이언트 측 바인딩을 사용하므로 변경할 필요가 없습니다.
asyncpg (Python, SQLAlchemy)	변경할 필요가 없습니다. SQLAlchemy에서 `statement_cache_size=0`으로 SQL 문 캐시를 비활성화한다면 URL에 `prepared_statement_cache_size=0`도 함께 설정하십시오.
pgjdbc (Java)	변경할 필요가 없습니다. pgjdbc 42.7.5 이상을 사용하십시오. 이전 버전은 PgBouncer를 통해 연결할 수 없습니다. `unsupported startup parameter`를 참조하십시오.
Npgsql (.NET)	자동 준비(automatic preparation)가 기본적으로 꺼져 있으므로 변경할 필요가 없습니다. PgBouncer를 통해 연결할 때는 `Max Auto Prepare`를 활성화하거나 `Prepare`를 호출하지 마십시오. 꼭 사용해야 한다면 `No Reset On Close=true`도 함께 설정하십시오.
pgx (Go)	`default_query_exec_mode=cache_describe`(또는 `exec`)를 설정하십시오. `describe_exec`는 이름 없는 SQL 문을 여러 번의 왕복(round trip)에 나누어 처리하므로 절대 사용하지 마십시오.
Postgrex / Ecto (Elixir)	repo 구성에서 `prepare: :unnamed`를 설정하십시오. 이름 있는 SQL 문을 사용하면 약 4 KB 크기의 쿼리가 PgBouncer를 거치면서 멈출 수 있습니다.
sqlx (Rust)	prepared statement 관련 설정은 필요하지 않습니다. `.persistent(false)` 또는 `statement_cache_capacity(0)`는 사용하지 마십시오. 다만 연결하려면 반드시 `extra_float_digits(None)`을 설정해야 합니다. `unsupported startup parameter`를 참조하십시오.
Active Record (Ruby on Rails)	`pg` gem 1.6 이상과 libpq 17 이상을 사용하면 변경할 필요가 없습니다. 그 외에는 `config/database.yml`에서 `prepared_statements: false`를 설정하십시오.
PDO (PHP, Laravel)	`pdo_pgsql`이 libpq 17 이상으로 컴파일되었다면 변경할 필요가 없습니다. 그 외에는 `PDO::ATTR_EMULATE_PREPARES => true`를 설정하십시오.

워크로드가 SQL 수준의 PREPARE에 의존한다면 PgBouncer 풀러 대신 PostgreSQL에 직접(포트 5432) 연결하십시오. 풀링 엔드포인트와 직접 엔드포인트 중 무엇을 선택할지에 대한 자세한 내용은 연결을 참조하십시오.

마이그레이션 후 쿼리가 `cached plan must not change result type` 오류로 실패하는 이유는 무엇입니까?

PgBouncer는 Postgres 연결에 prepared statement를 유지하며, 동일한 SQL 텍스트에 대해 이를 재사용합니다. 스키마 변경으로 쿼리가 반환하는 컬럼의 타입이 바뀌면(예: integer에서 bigint로 변경) 해당 쿼리는 PgBouncer를 거칠 때 cached plan must not change result type 오류와 함께 계속 실패합니다. 이 현상은 새 클라이언트 연결에서도 발생하며, PgBouncer가 Postgres 연결을 교체할 때까지 지속됩니다. 일부 드라이버는 오류를 내는 대신 오래된 결과 타입으로 디코딩하여 오류 없이 잘못된 값을 반환합니다. 직접 연결을 사용하면 각 연결은 최대 한 번만 실패한 후 복구됩니다. 복구하려면 해당 데이터베이스에 대한 PgBouncer의 Postgres 연결을 종료하십시오. 그러면 PgBouncer가 새 연결을 엽니다. PgBouncer는 Postgres에 로컬로 연결하므로 해당 연결에는 client_addr가 없습니다. 다음 명령은 직접 연결(포트 5432)을 통해, 애플리케이션이 연결할 때 사용하는 것과 동일한 사용자로 실행하십시오. 이 명령은 애플리케이션 사용자의 PgBouncer 연결만 종료하므로, 그 시점에 PgBouncer를 통해 실행 중인 트랜잭션은 실패하지만 직접 연결에는 영향을 주지 않습니다.

SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE datname = '<your_database>' AND usename = current_user
  AND client_addr IS NULL AND backend_type = 'client backend'
  AND pid <> pg_backend_pid();

기본 설정의 Npgsql, prepare: :unnamed를 사용하는 Postgrex, cache_describe를 사용하는 pgx처럼 이름 없는 SQL 문(unnamed statement)을 사용하는 드라이버는 영향을 받지 않습니다.

PgBouncer를 통해 연결할 때 `unsupported startup parameter` 오류가 발생하는 이유는 무엇입니까?

PgBouncer는 풀링된 Postgres 연결 전반에 일관되게 적용할 수 없는 연결 시점 설정을 거부하며, 이때 FATAL: unsupported startup parameter: ... 또는 unsupported startup parameter in options: ... 오류가 발생합니다. 주로 다음과 같은 경우에 해당합니다.

extra_float_digits: pgjdbc 42.7.4 이하 버전(예: Spring Boot 3 사용 시)과 sqlx는 연결할 때마다 이 설정을 전송합니다. pgjdbc를 42.7.5 이상으로 업그레이드하십시오. sqlx에서는 PgConnectOptions에 extra_float_digits(None)을 설정하십시오.
연결 문자열(connection string)에 포함된 search_path 및 기타 설정: JDBC URL의 currentSchema, Npgsql 연결 문자열의 Search Path, options=-c ..., Django의 OPTIONS["options"] 등이 여기에 해당합니다. 이러한 경우에는 ALTER ROLE ... SET 또는 ALTER DATABASE ... SET으로 기본값을 설정하거나, 트랜잭션 안에서 SET LOCAL을 사용하거나, PgBouncer를 거치지 않고 직접 연결하십시오.

application_name과 TimeZone은 지원됩니다.

PgBouncer를 거치면 `SET` 명령어가 유지되지 않는 이유는 무엇입니까?

트랜잭션 풀링 모드(transaction pooling mode)에서는 세션 수준의 SET이 클라이언트가 아니라 해당 명령을 실행한 Postgres 연결에 적용됩니다. 따라서 같은 클라이언트의 이후 트랜잭션은 해당 설정이 없는 다른 연결에서 실행될 수 있고, 반대로 다른 클라이언트가 해당 설정이 적용된 연결을 사용하게 될 수도 있습니다. SET ROLE도 마찬가지이므로, 사용자가 전환한 역할이 다른 클라이언트의 쿼리에 적용될 수 있습니다. 트랜잭션 내부에서 SET LOCAL을 사용하거나, ALTER ROLE ... SET 또는 ALTER DATABASE ... SET으로 기본값을 설정하십시오. 세션 상태(session state)에 의존하는 워크로드는 PgBouncer를 거치지 않고 직접 연결하십시오.

PgBouncer를 통해 마이그레이션을 실행하면 왜 멈추거나 advisory lock 해제에 실패합니까?

많은 마이그레이션 도구는 한 번에 하나의 마이그레이션만 실행되도록 세션 수준의 advisory lock을 획득한 뒤, 별도의 SQL 문으로 이를 해제합니다. PgBouncer를 거치면 해제 SQL 문이 다른 Postgres 연결에서 실행될 수 있으며, 이 경우 잠금은 풀링된 연결에 그대로 남습니다. 그 결과 이후의 마이그레이션은 직접 연결을 사용하더라도 계속 대기하거나 failed to release advisory lock과 같은 오류를 내며 실패합니다. 세션 advisory lock을 사용하는 도구로는 golang-migrate, sqlx, Kysely의 Migrator, Rails, transactional-lock=false가 설정된 Flyway, migration_lock: :pg_advisory_lock이 설정된 Ecto 등이 있습니다. 마이그레이션은 직접 연결(포트 5432)을 통해 실행하십시오. 누수된 잠금은 유휴 세션이 보유하는 반면, 아직 실행 중인 마이그레이션의 잠금은 활성 세션이 보유합니다. 누수된 잠금을 해제하려면 마찬가지로 직접 연결을 통해 데이터베이스에서 advisory lock을 보유한 유휴 세션만 종료하십시오.

SELECT pg_terminate_backend(l.pid) FROM pg_locks l
JOIN pg_stat_activity a ON a.pid = l.pid
WHERE l.locktype = 'advisory' AND a.state = 'idle'
  AND l.database = (SELECT oid FROM pg_database WHERE datname = current_database());

PgBouncer의 `max_client_conn` 설정은 무엇을 의미하며, Postgres의 `max_connections`와는 어떤 관련이 있습니까?

두 설정은 서로 다른 대상을 제어합니다.

**Postgres max_connections**는 PostgreSQL 자체의 백엔드(backend) 연결 수 상한을 정합니다. 이 값은 비용이 큰 편입니다. 각 백엔드는 메모리와 프로세스 슬롯을 사용합니다.
**PgBouncer max_client_conn**는 풀러에 동시에 열 수 있는 클라이언트(client) 연결 수 상한을 정합니다. PgBouncer는 이렇게 많은 클라이언트 연결을 훨씬 더 적은 수의 백엔드 연결에 다중화합니다.

PgBouncer는 Postgres 백엔드 수보다 몇 배 많은 클라이언트 연결을 허용합니다. 예를 들어 max_connections가 500으로 설정된 인스턴스는 풀러에서 클라이언트 연결을 2500개까지 허용합니다. 풀러에서 연결 오류가 발생한다면, 겉으로 드러나는 클라이언트 제한에 도달했다기보다 풀별 백엔드 제한(default_pool_size 또는 데이터베이스별 max_db_connections)에 걸렸을 가능성이 훨씬 높습니다. 인스턴스에 설정된 값을 확인하려면 PgBouncer(포트 6432)를 통해 특수 데이터베이스인 pgbouncer에 연결한 후 SHOW CONFIG를 실행하십시오.

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:6432/pgbouncer?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "SHOW CONFIG;"

데이터베이스 기능

여러 데이터베이스와 스키마를 생성할 수 있습니까?

예. ClickHouse Managed Postgres는 단일 인스턴스 내에서 여러 데이터베이스와 스키마를 지원하는 등 PostgreSQL의 모든 네이티브 기능을 제공합니다. 표준 PostgreSQL 명령으로 데이터베이스와 스키마를 생성하고 관리할 수 있습니다.

역할 기반 접근 제어(RBAC)를 지원하나요?

ClickHouse Managed Postgres 인스턴스에서는 전체 슈퍼유저 액세스 권한이 제공되며, 표준 PostgreSQL 명령을 사용해 역할을 생성하고 권한을 관리할 수 있습니다.

Console 통합이 포함된 향상된 RBAC 기능은 올해 중 제공될 예정입니다.

업그레이드

PostgreSQL 버전 업그레이드는 어떻게 처리되나요?

마이너 버전 업그레이드와 메이저 버전 업그레이드는 모두 페일오버를 통해 수행되며, 일반적으로 다운타임은 몇 초에 불과합니다. 업그레이드가 적용되는 요일과 UTC 기준 2시간의 기간을 제어할 수 있도록 예약된 업그레이드를 구성할 수 있습니다. 자세한 내용은 업그레이드 문서를 참조하십시오.

마이그레이션

ClickHouse Managed Postgres로 마이그레이션할 때 사용할 수 있는 도구는 무엇인가요?

ClickHouse Managed Postgres는 여러 가지 마이그레이션 방식을 지원합니다.

pg_dump and pg_restore: 소규모 데이터베이스 또는 일회성 마이그레이션에 적합합니다. pg_dump and pg_restore 가이드를 참조하세요.
Logical replication: 다운타임을 최소화해야 하는 대규모 데이터베이스에 적합합니다. 논리적 복제 가이드를 참조하세요.
PeerDB: 다른 Postgres 소스의 CDC 기반 복제에 적합합니다. PeerDB migration 가이드를 참조하세요.

완전 관리형 마이그레이션 환경이 곧 제공될 예정입니다.

시작하기

기능

가이드

요금

ClickHouse 통합

마이그레이션

모니터링

자주 묻는 질문

모니터링 및 메트릭

ClickHouse Managed Postgres 인스턴스의 메트릭은 어떻게 확인하나요?

백업 및 복구

사용 가능한 백업 옵션은 무엇입니까?

인프라 및 자동화

어떤 클라우드 제공업체가 지원됩니까?

ClickHouse Managed Postgres에서 Terraform을 지원하나요?

확장 기능 및 구성

어떤 확장 기능을 지원하나요?

PostgreSQL 구성 매개변수를 사용자 지정할 수 있나요?

연결 풀링

PgBouncer를 통해 `prepared statement does not exist` 오류가 발생하는 이유는 무엇입니까?

마이그레이션 후 쿼리가 `cached plan must not change result type` 오류로 실패하는 이유는 무엇입니까?

PgBouncer를 통해 연결할 때 `unsupported startup parameter` 오류가 발생하는 이유는 무엇입니까?

PgBouncer를 거치면 `SET` 명령어가 유지되지 않는 이유는 무엇입니까?

PgBouncer를 통해 마이그레이션을 실행하면 왜 멈추거나 advisory lock 해제에 실패합니까?

PgBouncer의 `max_client_conn` 설정은 무엇을 의미하며, Postgres의 `max_connections`와는 어떤 관련이 있습니까?

데이터베이스 기능

여러 데이터베이스와 스키마를 생성할 수 있습니까?

역할 기반 접근 제어(RBAC)를 지원하나요?

업그레이드

PostgreSQL 버전 업그레이드는 어떻게 처리되나요?

마이그레이션

ClickHouse Managed Postgres로 마이그레이션할 때 사용할 수 있는 도구는 무엇인가요?

​모니터링 및 메트릭

​ClickHouse Managed Postgres 인스턴스의 메트릭은 어떻게 확인하나요?

​백업 및 복구

​사용 가능한 백업 옵션은 무엇입니까?

​인프라 및 자동화

​어떤 클라우드 제공업체가 지원됩니까?

​ClickHouse Managed Postgres에서 Terraform을 지원하나요?

​확장 기능 및 구성

​어떤 확장 기능을 지원하나요?

​PostgreSQL 구성 매개변수를 사용자 지정할 수 있나요?

​연결 풀링

​PgBouncer를 통해 prepared statement does not exist 오류가 발생하는 이유는 무엇입니까?

​마이그레이션 후 쿼리가 cached plan must not change result type 오류로 실패하는 이유는 무엇입니까?

​PgBouncer를 통해 연결할 때 unsupported startup parameter 오류가 발생하는 이유는 무엇입니까?

​PgBouncer를 거치면 SET 명령어가 유지되지 않는 이유는 무엇입니까?

​PgBouncer를 통해 마이그레이션을 실행하면 왜 멈추거나 advisory lock 해제에 실패합니까?

​PgBouncer의 max_client_conn 설정은 무엇을 의미하며, Postgres의 max_connections와는 어떤 관련이 있습니까?

​데이터베이스 기능

​여러 데이터베이스와 스키마를 생성할 수 있습니까?

​역할 기반 접근 제어(RBAC)를 지원하나요?

​업그레이드

​PostgreSQL 버전 업그레이드는 어떻게 처리되나요?

​마이그레이션

​ClickHouse Managed Postgres로 마이그레이션할 때 사용할 수 있는 도구는 무엇인가요?

모니터링 및 메트릭

ClickHouse Managed Postgres 인스턴스의 메트릭은 어떻게 확인하나요?

백업 및 복구

사용 가능한 백업 옵션은 무엇입니까?

인프라 및 자동화

어떤 클라우드 제공업체가 지원됩니까?

ClickHouse Managed Postgres에서 Terraform을 지원하나요?

확장 기능 및 구성

어떤 확장 기능을 지원하나요?

PostgreSQL 구성 매개변수를 사용자 지정할 수 있나요?

연결 풀링

PgBouncer를 통해 `prepared statement does not exist` 오류가 발생하는 이유는 무엇입니까?

마이그레이션 후 쿼리가 `cached plan must not change result type` 오류로 실패하는 이유는 무엇입니까?

PgBouncer를 통해 연결할 때 `unsupported startup parameter` 오류가 발생하는 이유는 무엇입니까?

PgBouncer를 거치면 `SET` 명령어가 유지되지 않는 이유는 무엇입니까?

PgBouncer를 통해 마이그레이션을 실행하면 왜 멈추거나 advisory lock 해제에 실패합니까?

PgBouncer의 `max_client_conn` 설정은 무엇을 의미하며, Postgres의 `max_connections`와는 어떤 관련이 있습니까?

데이터베이스 기능

여러 데이터베이스와 스키마를 생성할 수 있습니까?

역할 기반 접근 제어(RBAC)를 지원하나요?

업그레이드

PostgreSQL 버전 업그레이드는 어떻게 처리되나요?

마이그레이션

ClickHouse Managed Postgres로 마이그레이션할 때 사용할 수 있는 도구는 무엇인가요?