Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
feat(pam): clickhouse native protocol
bernie-g3576fd1b7c6b
diff --git a/backend/src/ee/routes/v2/gateway-router.ts b/backend/src/ee/routes/v2/gateway-router.tsindex d273b2d140..60593c6019 100644--- a/backend/src/ee/routes/v2/gateway-router.ts+++ b/backend/src/ee/routes/v2/gateway-router.ts@@ -138,6 +138,7 @@ export const registerGatewayV2Router = async (server: FastifyZodProvider) => {.object({pkcs11: z.boolean().optional(),sessionLogMaskingBuiltInDetection: z.boolean().optional(),+ clickhouseNativeProtocol: z.boolean().optional(),supported_account_types: z.array(z.string().trim().max(64)).max(64).optional()}).optional()diff --git a/backend/src/ee/services/gateway-v2/gateway-v2-fns.ts b/backend/src/ee/services/gateway-v2/gateway-v2-fns.tsindex e1c5750abd..43630ffab1 100644--- a/backend/src/ee/services/gateway-v2/gateway-v2-fns.ts+++ b/backend/src/ee/services/gateway-v2/gateway-v2-fns.ts@@ -17,7 +17,9 @@ export const testConnectionWithGateway = async (gatewayV2Service: TGatewayDep,request: Record<string, unknown>,timeoutMs: number,- signal?: AbortSignal+ signal?: AbortSignal,+ // Ports beyond the primary one that this test is allowed to probe, signed into the client certificate.+ additionalTargetPorts?: number[]): Promise<TestConnectionResponse | null> => {const [host] = await verifyHostInputValidity({ host: targetHost, isGateway: true, isDynamicSecret: false });@@ -25,7 +27,8 @@ export const testConnectionWithGateway = async (const platform = await gatewayV2Service.getPlatformConnectionDetailsByGatewayId({gatewayId,targetHost: host,- targetPort+ targetPort,+ additionalTargetPorts});if (!platform) return null;diff --git a/backend/src/ee/services/gateway-v2/gateway-v2-service.ts b/backend/src/ee/services/gateway-v2/gateway-v2-service.tsindex 86ee99e44e..25f33e78b8 100644--- a/backend/src/ee/services/gateway-v2/gateway-v2-service.ts+++ b/backend/src/ee/services/gateway-v2/gateway-v2-service.ts@@ -351,11 +351,15 @@ export const gatewayV2ServiceFactory = ({gatewayId,targetHost,targetPort,+ // Some account types reach one host on more than one port. Naming them all in the signed cert keeps the+ // gateway from having to trust a port out of the request body.+ additionalTargetPorts,transport}: {gatewayId: string;targetHost: string;targetPort: number;+ additionalTargetPorts?: number[];transport?: GatewayTransport;}): Promise<TGatewayV2ConnectionDetails | undefined> => {const gateway = await gatewayV2DAL.findById(gatewayId);@@ -424,9 +428,14 @@ export const gatewayV2ServiceFactory = ({const clientKeys = await crypto.nativeCrypto.subtle.generateKey(alg, true, ["sign", "verify"]);const clientCertSerialNumber = createSerialNumber();+ const allowedPorts = [targetPort, ...(additionalTargetPorts ?? [])].filter(+ (port, index, ports) => port > 0 && ports.indexOf(port) === index+ );const routingInfo = {targetHost,- targetPort+ targetPort,+ // A gateway too old to read this ignores it and keeps using targetPort, so adding it is additive.+ ...(allowedPorts.length > 1 ? { targetPorts: allowedPorts } : {})};const routingExtension = new x509.Extension(diff --git a/backend/src/ee/services/pam-account/pam-account-connection-test.test.ts b/backend/src/ee/services/pam-account/pam-account-connection-test.test.tsindex b1836ee6ea..bb30811e72 100644--- a/backend/src/ee/services/pam-account/pam-account-connection-test.test.ts+++ b/backend/src/ee/services/pam-account/pam-account-connection-test.test.ts@@ -9,6 +9,10 @@ import {const ORG_ID = "11111111-1111-1111-1111-111111111111";+// The keys that survive serialization, which is what the gateway actually decodes. An `undefined` property+// is still a present key in JS, so checking the object directly would not prove the field was omitted.+const wireKeys = (request: unknown): string[] => Object.keys(JSON.parse(JSON.stringify(request)) as object);+describe("buildGatewayConnectionTest: MSSQL Windows authentication", () => {const connectionDetails = {host: "sql.corp.example.com",@@ -242,3 +246,66 @@ describe("buildGatewayConnectionTest: Oracle", () => {expect(result?.request).toMatchObject({ mode: TestConnectionMode.SQL, dialect: "postgres" });});});++describe("buildGatewayConnectionTest: ClickHouse", () => {+ const connectionDetails = {+ host: "clickhouse.example.com",+ port: 8123,+ database: "analytics",+ sslEnabled: false,+ sslRejectUnauthorized: true+ };++ test("carries the native port so both interfaces are checked before the account saves", async () => {+ const result = await buildGatewayConnectionTest(+ PamAccountType.ClickHouse,+ { ...connectionDetails, nativePort: 9000 },+ { username: "default", password: "pw" },+ ORG_ID+ );++ expect(result?.request.mode).toBe(TestConnectionMode.ClickHouse);+ expect(result?.request).toMatchObject({+ httpPort: 8123,+ nativePort: 9000,+ username: "default",+ database: "analytics",+ sslEnabled: false+ });+ expect(result?.port).toBe(8123);+ });++ test("a native-only account targets the native port and sends no HTTP port", async () => {+ const result = await buildGatewayConnectionTest(+ PamAccountType.ClickHouse,+ {+ host: "clickhouse.example.com",+ nativePort: 9440,+ database: "analytics",+ sslEnabled: true,+ sslRejectUnauthorized: true+ },+ { username: "default", password: "pw" },+ ORG_ID+ );++ expect(result?.request.mode).toBe(TestConnectionMode.ClickHouse);+ expect(result?.port).toBe(9440);+ expect(result?.request).toMatchObject({ nativePort: 9440, sslEnabled: true });+ // toMatchObject treats an absent key as undefined, so the wire form is what gets asserted.+ expect(wireKeys(result!.request)).not.toContain("httpPort");+ });++ test("omits the native port when the server only serves HTTP", async () => {+ const result = await buildGatewayConnectionTest(+ PamAccountType.ClickHouse,+ connectionDetails,+ { username: "default", password: "pw" },+ ORG_ID+ );++ expect(result?.request.mode).toBe(TestConnectionMode.ClickHouse);+ expect(result?.request).toMatchObject({ httpPort: 8123 });+ expect(wireKeys(result!.request)).not.toContain("nativePort");+ });+});diff --git a/backend/src/ee/services/pam-account/pam-account-connection-test.ts b/backend/src/ee/services/pam-account/pam-account-connection-test.tsindex d4e561015e..0f115fbcfb 100644--- a/backend/src/ee/services/pam-account/pam-account-connection-test.ts+++ b/backend/src/ee/services/pam-account/pam-account-connection-test.ts@@ -109,6 +109,9 @@ export type TestConnectionRequest =username: string;password?: string;database: string;+ // Either interface can be absent, so each is named rather than inferred from the gateway target.+ httpPort?: number;+ nativePort?: number;sslEnabled?: boolean;sslRejectUnauthorized?: boolean;sslCertificate?: string;@@ -140,7 +143,13 @@ export const buildGatewayConnectionTest = async (orgId: string,// Off for account create and update, which must not fail against a gateway predating the test they need.opts?: { allowNewerGatewayTests?: boolean }-): Promise<{ host: string; port: number; request: TestConnectionRequest } | null> => {+): Promise<{+ host: string;+ port: number;+ request: TestConnectionRequest;+ // Ports the gateway may probe beyond the primary one, so they can be signed into its certificate.+ additionalPorts?: number[];+} | null> => {const creds = credentials && isCredentialConfigured(accountType, credentials) ? credentials : null;const target =@@ -384,6 +393,8 @@ export const buildGatewayConnectionTest = async (case PamAccountType.ClickHouse: {const cd = connectionDetails as {database: string;+ port?: number;+ nativePort?: number;sslEnabled?: boolean;sslRejectUnauthorized?: boolean;sslCertificate?: string;@@ -393,11 +404,14 @@ export const buildGatewayConnectionTest = async (return {host,port,+ additionalPorts: [cd.port, cd.nativePort].filter((p): p is number => typeof p === "number"),request: {mode: TestConnectionMode.ClickHouse,username: c.username,password: c.password,database: cd.database,+ httpPort: cd.port,+ nativePort: cd.nativePort,sslEnabled: cd.sslEnabled,sslRejectUnauthorized: cd.sslRejectUnauthorized,sslCertificate: cd.sslCertificatediff --git a/backend/src/ee/services/pam-account/pam-account-schemas.test.ts b/backend/src/ee/services/pam-account/pam-account-schemas.test.tsindex 5d5a91002f..99f9afa02f 100644--- a/backend/src/ee/services/pam-account/pam-account-schemas.test.ts+++ b/backend/src/ee/services/pam-account/pam-account-schemas.test.ts@@ -7,11 +7,13 @@ import {buildPamAccountTypeMetadata,collectCredentialSecrets,gatewaySupportsAccountType,+ gatewaySupportsClickHouseNative,getAccountAccessibilityIssues,isCredentialConfigured,PamAccountAccessibilityIssue,PamAccountTypeMetadataSchema,PamFieldDescriptorSchema,+ requiresClickHouseNative,sanitizeCredentials,suppliesCredentialSecret,validateConnectionDetails,@@ -182,6 +184,7 @@ describe("buildPamAccountTypeMetadata", () => {expect(clickhouse?.connectionFields.map((f) => f.key)).toEqual(["host","port",+ "nativePort","database","sslEnabled","sslRejectUnauthorized",@@ -189,10 +192,24 @@ describe("buildPamAccountTypeMetadata", () => {]);expect(fieldByKey(clickhouse!.connectionFields, "port")).toMatchObject({+ label: "HTTP Port",widget: "number",- required: true,+ required: false,defaultValue: 8123});+ // The native port must NOT carry a default: the edit form spreads defaults under the stored details,+ // so a default would add a native port to every existing HTTP-only account on the next save.+ expect(fieldByKey(clickhouse!.connectionFields, "nativePort")?.defaultValue).toBeUndefined();+ // A native port is offered by default so clickhouse-client works without anyone choosing a protocol,+ // and stays optional for a server that only serves HTTP.+ expect(fieldByKey(clickhouse!.connectionFields, "nativePort")).toMatchObject({+ label: "Native Port",+ widget: "number",+ required: false+ });+ // Both ports are plain always-visible fields: neither is hidden behind a condition on the other.+ expect(fieldByKey(clickhouse!.connectionFields, "port")?.showWhen).toBeUndefined();+ expect(fieldByKey(clickhouse!.connectionFields, "nativePort")?.showWhen).toBeUndefined();expect(fieldByKey(clickhouse!.connectionFields, "database")).toMatchObject({required: true,defaultValue: "default"@@ -211,6 +228,64 @@ describe("buildPamAccountTypeMetadata", () => {});});+ test("accepts a ClickHouse server that serves only one of its two interfaces", () => {+ const base = {+ host: "clickhouse.example.com",+ database: "analytics",+ sslEnabled: false,+ sslRejectUnauthorized: true+ };++ // HTTP disabled on the server: clickhouse-client works, and Web Access is bridged by the gateway.+ expect(validateConnectionDetails(PamAccountType.ClickHouse, { ...base, nativePort: 9000 })).toMatchObject({+ nativePort: 9000+ });++ // Native disabled: JDBC and Web Access work, native drivers are turned away.+ expect(validateConnectionDetails(PamAccountType.ClickHouse, { ...base, port: 8123 })).toMatchObject({+ port: 8123+ });++ expect(() => validateConnectionDetails(PamAccountType.ClickHouse, base)).toThrow();+ expect(() => validateConnectionDetails(PamAccountType.ClickHouse, { ...base, port: "", nativePort: "" })).toThrow();+ });++ test("accepts a ClickHouse account with the native port cleared", () => {+ const base = {+ host: "clickhouse.example.com",+ port: 8123,+ database: "analytics",+ sslEnabled: false,+ sslRejectUnauthorized: true+ };++ expect(validateConnectionDetails(PamAccountType.ClickHouse, { ...base, nativePort: 9000 })).toMatchObject({+ nativePort: 9000+ });++ // Clearing a number input submits an empty string, so an HTTP-only account has to save through it.+ for (const cleared of ["", " ", null, undefined]) {+ const result = validateConnectionDetails(PamAccountType.ClickHouse, { ...base, nativePort: cleared });+ expect((result as { nativePort?: number }).nativePort).toBeUndefined();+ }+ });++ test("a native port needs a gateway that reports the native protocol", () => {+ const httpOnly = { host: "h", port: 8123, database: "d", sslEnabled: false, sslRejectUnauthorized: true };+ const withNative = { ...httpOnly, nativePort: 9000 };++ expect(requiresClickHouseNative(PamAccountType.ClickHouse, withNative)).toBe(true);+ expect(requiresClickHouseNative(PamAccountType.ClickHouse, httpOnly)).toBe(false);+ // Only ClickHouse has two interfaces; no other type should be gated on this.+ expect(requiresClickHouseNative(PamAccountType.Postgres, withNative)).toBe(false);++ // An absent flag means a gateway too old to report it, which is exactly what must be refused.+ expect(gatewaySupportsClickHouseNative(null)).toBe(false);+ expect(gatewaySupportsClickHouseNative({})).toBe(false);+ expect(gatewaySupportsClickHouseNative({ clickhouseNativeProtocol: false })).toBe(false);+ expect(gatewaySupportsClickHouseNative({ clickhouseNativeProtocol: true })).toBe(true);+ });+test("derives Redis connection and credential fields from the schema", () => {const redis = byType.get(PamAccountType.Redis);expect(redis).toBeDefined();diff --git a/backend/src/ee/services/pam-account/pam-account-schemas.ts b/backend/src/ee/services/pam-account/pam-account-schemas.tsindex b6775b55d0..e7b9a649d0 100644--- a/backend/src/ee/services/pam-account/pam-account-schemas.ts+++ b/backend/src/ee/services/pam-account/pam-account-schemas.ts@@ -47,6 +47,14 @@ const boundedOptionalString = (max: number) =>.transform((v) => v || undefined).optional();+// Clearing a number input submits an empty string rather than undefined, which a bare .optional() rejects+// and coercion would read as port 0.+const optionalPort = () =>+ z.preprocess(+ (v) => (v === null || (typeof v === "string" && v.trim() === "") ? undefined : v),+ z.coerce.number().int().min(1).max(65535).optional()+ );+const normalizeDelimitedStringList = (value: unknown): unknown => {if (Array.isArray(value)) return value;if (typeof value !== "string") return value;@@ -596,14 +604,21 @@ export const ACCOUNT_TYPE_CONFIGS = {[PamAccountType.ClickHouse]: {name: "ClickHouse",icon: "ClickHouse.png",- connectionDetails: z.object({- host: z.string().trim().min(1).max(255),- port: z.coerce.number().int().min(1).max(65535),- database: z.string().trim().min(1).max(255),- sslEnabled: z.boolean(),- sslRejectUnauthorized: z.boolean(),- sslCertificate: boundedOptionalString(16384)- }),+ connectionDetails: z+ .object({+ host: z.string().trim().min(1).max(255),+ port: optionalPort(),+ nativePort: optionalPort(),+ database: z.string().trim().min(1).max(255),+ sslEnabled: z.boolean(),+ sslRejectUnauthorized: z.boolean(),+ sslCertificate: boundedOptionalString(16384)+ })+ // Either interface can be turned off on the server, but a session needs at least one of them.+ .refine((v) => v.port !== undefined || v.nativePort !== undefined, {+ message: "Set the HTTP port, the native port, or both",+ path: ["port"]+ }),credentials: z.object({username: z.string().trim().min(1).max(255),password: boundedOptionalString(256)@@ -611,9 +626,17 @@ export const ACCOUNT_TYPE_CONFIGS = {sanitizedCredentials: z.object({ username: z.string() }),ui: {port: {+ label: "HTTP Port",defaultValue: 8123,tooltip:- "The HTTP interface port: 8123 for plain HTTP, 8443 for HTTPS. Sessions never use the native protocol on 9000."+ "The HTTP interface port: 8123 for plain HTTP, 8443 for HTTPS. Leave it empty if the server only serves the native protocol."+ },+ nativePort: {+ label: "Native Port",+ // Deliberately no default: the edit form seeds defaults over stored details, so an existing+ // HTTP-only account would silently gain a native port the next time anyone edited it.+ tooltip:+ "The native TCP port, usually 9000 for plain TCP or 9440 with SSL. clickhouse-client and other native drivers need it. Leave it empty if the server only serves HTTP."},database: {defaultValue: "default",@@ -1053,12 +1076,16 @@ export const extractGatewayTarget = async (case PamAccountType.MsSQL:case PamAccountType.OracleDB:case PamAccountType.Redis:- case PamAccountType.ClickHouse:case PamAccountType.Windows:return {host: (validated as { host: string; port: number }).host,port: (validated as { host: string; port: number }).port};+ case PamAccountType.ClickHouse: {+ // Either interface can be absent, so the target is whichever one the account actually has.+ const { host, port, nativePort } = validated as { host: string; port?: number; nativePort?: number };+ return { host, port: port ?? nativePort };+ }case PamAccountType.Kubernetes: {const { url } = validated as { url: string };const parsed = new URL(url);@@ -1140,6 +1167,19 @@ export const gatewaySupportsAccountType = (supportedTypes: string[] | undefined): boolean => !supportedTypes || supportedTypes.includes(resolveGatewayAccountType(accountType));+// A gateway can support ClickHouse accounts and still predate the native protocol, so the account type on+// its own does not say whether a native port can be served. An absent flag means a gateway too old to+// report it, which is exactly the case this guards.+export const gatewaySupportsClickHouseNative = (capabilities: { clickhouseNativeProtocol?: boolean } | null) =>+ Boolean(capabilities?.clickhouseNativeProtocol);++// The connection details name a native port the gateway would have to speak.+export const requiresClickHouseNative = (+ accountType: PamAccountType,+ connectionDetails: Record<string, unknown>+): boolean =>+ accountType === PamAccountType.ClickHouse && (connectionDetails as { nativePort?: number }).nativePort !== undefined;+export const buildSessionGatewayConnectionDetails = (accountType: PamAccountType,rawConnectionDetails: Record<string, unknown>,diff --git a/backend/src/ee/services/pam-account/pam-account-service.ts b/backend/src/ee/services/pam-account/pam-account-service.tsindex b5a6af9b90..4cb823c2e2 100644--- a/backend/src/ee/services/pam-account/pam-account-service.ts+++ b/backend/src/ee/services/pam-account/pam-account-service.ts@@ -78,6 +78,7 @@ import {ACCOUNT_TYPE_CONFIGS,applyForcedFields,gatewaySupportsAccountType,+ gatewaySupportsClickHouseNative,getAccountAccessibilityIssues,hasRevealableCredential,isCredentialConfigured,@@ -86,6 +87,7 @@ import {ORACLE_MAX_PASSWORD_LENGTH,PamAccountAccessibilityIssue,parseInternalMetadata,+ requiresClickHouseNative,sanitizeCredentials,suppliesCredentialSecret,type TSshInternalMetadata,@@ -628,13 +630,24 @@ export const pamAccountServiceFactory = (deps: TPamAccountServiceFactoryDep) =>}const attachedGateway = await gatewayV2DAL.findOne({ id: gatewayId });- const capabilities = attachedGateway?.capabilities as { supported_account_types?: string[] } | null;+ const capabilities = attachedGateway?.capabilities as {+ supported_account_types?: string[];+ clickhouseNativeProtocol?: boolean;+ } | null;if (!gatewaySupportsAccountType(accountType, capabilities?.supported_account_types)) {throw new BadRequestError({message: `Gateway '${attachedGateway?.name ?? gatewayId}' does not support ${ACCOUNT_TYPE_CONFIGS[accountType as TSupportedAccountType].name} accounts. Update the gateway, then try again.`});}+ // Saving a native port against a gateway that cannot speak it would pass this test over HTTP and then+ // fail every native client at session time, with nothing to point at.+ if (requiresClickHouseNative(accountType, connectionDetails) && !gatewaySupportsClickHouseNative(capabilities)) {+ throw new BadRequestError({+ message: `Gateway '${attachedGateway?.name ?? gatewayId}' does not support ClickHouse's native protocol. Update the gateway, or clear the native port to use this account over HTTP only.`+ });+ }+const test = await buildGatewayConnectionTest(accountType, connectionDetails, credentials, orgId);if (!test) return false;@@ -644,7 +657,9 @@ export const pamAccountServiceFactory = (deps: TPamAccountServiceFactoryDep) =>gatewayId,gatewayV2Service,test.request,- CONNECTION_TEST_TIMEOUT_MS+ CONNECTION_TEST_TIMEOUT_MS,+ undefined,+ test.additionalPorts);// a null result means the gateway couldn't be reached (offline / pre-protocol) — skip rather than block@@ -974,9 +989,13 @@ export const pamAccountServiceFactory = (deps: TPamAccountServiceFactoryDep) =>const oldConn = validateConnectionDetails(accountType, existingConnectionDetails) as {host?: string;port?: number;+ nativePort?: number;};- const newConn = effectiveConnectionDetails as { host?: string; port?: number };- if (oldConn.host !== newConn.host || oldConn.port !== newConn.port) connectionTargetChanged = true;+ const newConn = effectiveConnectionDetails as { host?: string; port?: number; nativePort?: number };+ // nativePort is part of the target too: re-pointing it sends the stored credential somewhere new on+ // the next heartbeat, which is exactly what this flag exists to catch.+ if (oldConn.host !== newConn.host || oldConn.port !== newConn.port || oldConn.nativePort !== newConn.nativePort)+ connectionTargetChanged = true;const oldUsername = (existingCredentials as { username?: string }).username;const newUsername = (effectiveCredentials as { username?: string }).username;diff --git a/docs/documentation/platform/pam/accounts/clickhouse.mdx b/docs/documentation/platform/pam/accounts/clickhouse.mdxindex 70ab324546..6747ebc46c 100644--- a/docs/documentation/platform/pam/accounts/clickhouse.mdx+++ b/docs/documentation/platform/pam/accounts/clickhouse.mdx@@ -6,13 +6,16 @@ description: "Add and connect to ClickHouse databases."ClickHouse accounts let you manage access to a ClickHouse database. Users connect through Web Access or the CLI, and every statement they run is recorded in the [session](/documentation/platform/pam/sessions/overview).-Sessions reach ClickHouse over its HTTP interface, on port 8123 or 8443, rather than the native protocol on 9000. Every request passes through the [gateway](/documentation/platform/gateways/overview) in your own network, and the credential never reaches the client.+Sessions reach ClickHouse over both of its interfaces: the HTTP interface on port 8123 or 8443, and the native protocol on port 9000 or 9440. A session hands out one local port and detects which one a client is speaking, so you don't have to pick a protocol or run two sessions. Every request passes through the [gateway](/documentation/platform/gateways/overview) in your own network, and the credential never reaches the client.++Either interface can be turned off on the server. Set whichever ports it serves and leave the other empty. An account needs at least one of them.## Prerequisites- A ClickHouse user for Infisical to connect as.-- The HTTP interface enabled on the target. `http_port` (8123) is on by default in a stock ClickHouse configuration. `https_port` (8443) needs a certificate configured, and is what ClickHouse Cloud exposes.-- A [gateway](/documentation/platform/gateways/overview) that can reach that port. A gateway that predates ClickHouse support refuses the session with a version error.+- At least one of the two interfaces enabled on the target. Both are on by default in a stock ClickHouse configuration: `http_port` is 8123 and `tcp_port` is 9000. The TLS ports are `https_port` 8443 and `tcp_port_secure` 9440, and ClickHouse Cloud exposes both.+- Both interfaces share the same `<openSSL><server>` certificate, so one SSL setting covers them. A server with TLS on one interface and not the other isn't supported.+- A [gateway](/documentation/platform/gateways/overview) that can reach those ports. A gateway that predates ClickHouse support refuses the session with a version error.## Creating an account@@ -28,9 +31,10 @@ Sessions reach ClickHouse over its HTTP interface, on port 8123 or 8443, rather|-------|-------------|| **Name** | A descriptive name (e.g., `analytics-prod`) || **Host** | ClickHouse host |- | **Port** | The HTTP interface port. 8123 for plain HTTP, 8443 for HTTPS |+ | **HTTP Port** | The HTTP interface port. 8123 for plain HTTP, 8443 for HTTPS. Leave empty if the server only serves the native protocol |+ | **Native Port** | The native protocol port. 9000 for plain TCP, 9440 with SSL. Needed by `clickhouse-client` and other native drivers. Leave empty if the server only serves HTTP || **Database** | The database sessions open. Web Access lists the tables inside it |- | **SSL Enabled** | Use HTTPS for the connection. Required for port 8443 and for ClickHouse Cloud |+ | **SSL Enabled** | Use TLS for the connection. Applies to both interfaces, so pair it with ports 8443 and 9440. Required for ClickHouse Cloud || **Reject Unauthorized** | Reject connections with invalid certificates (only if SSL enabled) || **SSL Certificate** | Custom CA certificate (only if SSL enabled) |</Step>@@ -41,7 +45,7 @@ Sessions reach ClickHouse over its HTTP interface, on port 8123 or 8443, rather| **Password** | The user's password. Leave blank for a user created with `no_password` |</Step><Step title="Save">- Select **Create**. Infisical signs in to ClickHouse through the gateway and runs one statement to confirm the credential works before saving the account.+ Select **Create**. Infisical signs in to ClickHouse through the gateway and confirms the credential works before saving the account. Each port you set is checked, and the error names the one that failed.</Step></Steps>@@ -66,8 +70,8 @@ Command blocking matches the text of each statement, so a statement that builds<Tab title="Web Access">Web Access provides a browser-based interface with two tools:- - **Data Explorer** — browse tables, view data, filter and sort, export to CSV/JSON- - **SQL Editor** — write and run SQL queries+ - **Data Explorer**: browse tables, view data, filter and sort, export to CSV/JSON+ - **SQL Editor**: write and run SQL queriesTo connect:@@ -77,23 +81,28 @@ Command blocking matches the text of each statement, so a statement that buildsClickHouse has no schema layer inside a database, so the Data Explorer sidebar lists databases where it lists schemas for other account types.+ Web Access works whichever interface the server has. It speaks HTTP, and for a server with HTTP turned off the gateway runs the statement over the native protocol and returns the result. The browser experience is the same, with the two limits described under [Servers with HTTP turned off](#servers-with-http-turned-off).+</Tab><Tab title="CLI">- The CLI starts a local proxy that speaks ClickHouse's HTTP interface on `127.0.0.1`. Connect with TLS off and no certificate to trust, since the hop to the gateway is already an encrypted tunnel. The username and password a client sends are ignored, because the gateway authenticates for you.+ The CLI starts a local proxy on `127.0.0.1` that serves both of ClickHouse's interfaces on one port. Connect with TLS off and no certificate to trust, since the hop to the gateway is already an encrypted tunnel. The username and password a client sends are ignored, because the gateway authenticates for you.```bashinfisical pam access analytics/clickhouse-prod```- The command prints the port and a ready-made connection string. JDBC clients such as DBeaver and DataGrip, `clickhouse-connect`, `@clickhouse/client`, and `curl` all speak this interface. `clickhouse-client` and Python's `clickhouse-driver` speak only the native protocol, so they can't use this port.+ The command prints the port and a ready-made connection string. Point any client at that port and the protocol is detected from the first bytes it sends. Native drivers such as `clickhouse-client`, Python's `clickhouse-driver` and `clickhouse-go` work alongside HTTP clients such as JDBC (DBeaver, DataGrip), `clickhouse-connect`, `@clickhouse/client` and `curl`.```bash+ clickhouse-client --host 127.0.0.1 --port <port>curl 'http://127.0.0.1:<port>/?query=SELECT+1'```+ A native client needs the account to have a **Native Port** set. Without one, it is turned away with a message saying so.+**Flags:**- - `--port <port>` — use a specific local port (otherwise one is assigned automatically)- - `--reason <reason>` — provide an access reason (if required by template)+ - `--port <port>`: use a specific local port (otherwise one is assigned automatically)+ - `--reason <reason>`: provide an access reason (if required by template)</Tab></Tabs>@@ -110,7 +119,27 @@ Every statement a session runs is recorded, along with the outcome of each one,The template's **Command Blocking** policy applies to ClickHouse as well: a statement matching one of its patterns is rejected before it reaches ClickHouse, and the rejection is recorded. **Session Log Masking** patterns are applied to the recording before it's written.-Applying that policy means reading the statement first, so on an account that blocks commands a request body over one megabyte is refused, and one compressed with anything other than `gzip` or `deflate` is rejected outright. Send large inserts in smaller batches, or use an account without the policy, where the body streams through and only its first megabyte is recorded.+On the HTTP interface, applying that policy means reading the statement first, so on an account that blocks commands a request body over one megabyte is refused, and one compressed with anything other than `gzip` or `deflate` is rejected outright. Send large inserts in smaller batches, or use an account without the policy, where the body streams through and only its first megabyte is recorded.++The native protocol has no such limit. A statement arrives in its own packet, separate from any rows that follow, so it's always read in full and an insert's data never counts against the policy or fills the recording.++<Note>+ Over the native protocol, an `INSERT` that pushes rows from the client is read so that later statements on the same connection stay covered by the policy. A few column types can't be read yet, including `Map` with a non-`String` value, `Tuple`, `JSON` and `Nested`. Inserting into a table that has one of those columns is refused with a message naming the type. Reading those columns is unaffected, and so is inserting over the HTTP interface.+</Note>++## Servers with HTTP turned off++A server that serves only the native protocol works with native clients and with Web Access. Set the **Native Port** and leave **HTTP Port** empty.++Native clients need nothing special: `clickhouse-client`, Python's `clickhouse-driver` and `clickhouse-go` speak to the session's port directly.++**HTTP clients need the server to have an HTTP port.** A ClickHouse account with no HTTP port is a native-only account, and JDBC tools such as DBeaver and DataGrip, along with `clickhouse-connect` and ODBC, can't reach it. They fail when they connect, with a message saying so. Give the account an HTTP port if you need them.++Web Access is the exception, because Infisical controls both ends of it. It speaks HTTP, so the gateway runs each statement over the native protocol and builds the result itself, with ClickHouse formatting the values so every column type keeps working. Three limits apply to Web Access on such an account, and none of them applies to a native client:++- Only a `SELECT`, `WITH` or `EXPLAIN` returns rows. A `SHOW` or `DESCRIBE` has to be run from a native client, or rewritten against `system.tables` and `system.columns`.+- A statement returning more than 100,000 rows, or more than 64 MB, is refused. Narrow the result, or use a native client.+- One statement at a time. A semicolon inside a statement is refused, because the native protocol runs a single statement per request.## Next steps