Skip to content

ClickHouse Managed Postgres

Connect Hyperdrive to ClickHouse Managed Postgres.

Last updated View as MarkdownAgent setup

This example connects Hyperdrive to a ClickHouse Managed Postgres ↗︎ database in ClickHouse Cloud. ClickHouse Managed Postgres is a managed PostgreSQL service with local NVMe storage and built-in ClickHouse integration for analytics.

Prerequisites

Before you begin, you need:

  • An existing ClickHouse Managed Postgres instance.
  • A Workers project. Refer to Get started to create one.
  • Wrangler version 4.9.0 or later, authenticated with your Cloudflare account.

1. Get your connection details

  1. In the ClickHouse Cloud console ↗︎, select your Postgres instance and open the Connect menu.
  2. Select Directly to use the direct PostgreSQL endpoint. Hyperdrive provides connection pooling.
  3. Copy the hostname, port, database name, username, and password. Use a database role with the permissions your application needs.
  4. In Settings, download the certificate authority (CA) certificate for this instance. Save it locally as postgres-ca.pem.

For more information, refer to ClickHouse Managed Postgres connection details ↗︎.

Your database must accept connections from Hyperdrive. If you restrict inbound connections by IP address, allow the Cloudflare IP address ranges.

2. Create a database configuration

Use the instance CA to verify the database server with Transport Layer Security (TLS). The CA certificate is specific to your Postgres instance.

  1. Upload the CA certificate to your Cloudflare account:

    npx wrangler cert upload certificate-authority --ca-cert postgres-ca.pem --name clickhouse-postgres-ca

  2. Copy the certificate ID from the command output. Create a Hyperdrive configuration using that ID and your database connection details:

    npx wrangler hyperdrive create clickhouse-postgres --origin-host '<HOSTNAME>' --origin-port '<PORT>' --database '<DATABASE_NAME>' --origin-scheme postgres --origin-user '<USERNAME>' --origin-password '<PASSWORD>' --ca-certificate-id '<CA_CERTIFICATE_ID>' --sslmode verify-full --caching-disabled

    Replace each placeholder with your values. Use the direct endpoint port, which defaults to 5432. Keep the password and command output private.

  3. Copy the Hyperdrive configuration ID from the output. Use this ID for the Worker binding in the next section.

The verify-full mode validates the certificate and database hostname. Hyperdrive checks the connection when you create the configuration. For certificate configuration details, refer to SSL/TLS certificates.

This example turns off query caching so reads reach Postgres. Connection pooling still applies. For workloads that can tolerate cached results, refer to Query caching.

3. Use Hyperdrive from your Worker

Install the node-postgres driver:

npm i pg@>8.16.3

If using TypeScript, install the types package:

npm i -D @types/pg

Add the required Node.js compatibility flags and Hyperdrive binding to your wrangler.jsonc file:

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-10-29",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}
compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-10-29"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

Create a new Client instance and pass the Hyperdrive connectionString:

// filepath: src/index.ts
import { Client } from "pg";

export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		// Create a new client instance for each request. Hyperdrive maintains the
		// underlying database connection pool, so creating a new client is fast.
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});

		try {
			// Connect to the database
			await client.connect();

			// Perform a simple query
			const result = await client.query("SELECT * FROM pg_tables");

			return Response.json({
				success: true,
				result: result.rows,
			});
		} catch (error: any) {
			console.error("Database error:", error.message);

			return new Response("Internal error occurred", { status: 500 });
		}
	},
};

To test the connection through Hyperdrive, deploy your Worker and request its URL. A successful response contains success: true and the query results.

Next steps

Was this helpful?