@fjall/components-infrastructure 10.1.2 → 11.0.0

package/dist/lib/resources/aws/database/clickhouseConstants.js

@@ -10,19 +10,17 @@ export const CLICKHOUSE_DATABASE_NAME = "analytics";
  *  of 2 vCPU) for the rest of the hour. Graviton3 is also ~25% faster on
  *  columnar scans than Graviton2.
  *
- *  Settings are tuned for 1 vCPU sustained (max_threads=1 across all profiles,
- *  max_concurrent_queries=8) — see clickhouseUserData.ts. Bumping to a larger
- *  instance MUST be paired with raising those thread/concurrency caps.
- *
  *  Next size up (2026-07-31 right-sizing, designs/2026-07-31-clickhouse-
  *  factory-fit-for-purpose.md): `r8g.medium` (1 vCPU Graviton4, 8 GiB,
  *  ~+30%/core over Graviton3) — CH's own doctrine floors production at
  *  8 GiB, and the memory-bound single-tenant profile wants RAM before
  *  cores. `m7g.large` (2 vCPU, 8 GiB) only when CPU-bound. Set via
  *  `clickhouseInstanceType` CDK context or the `instanceType` prop —
- *  the container memory limit derives automatically via
- *  `clickHouseTaskMemoryMiB()`, but the thread/concurrency caps in
- *  clickhouseUserData.ts still need a lockstep re-tune. */
+ *  the container memory limit, server pools/caches, and profile resource
+ *  caps ALL derive from the type automatically (`clickHouseTaskMemoryMiB()`,
+ *  `deriveClickHouseServerTuning()`, `deriveClickHouseDefaultProfiles()`).
+ *  A size change needs no manual re-tune — but it DOES need an instance
+ *  refresh + server restart to take effect (config is baked into user-data). */
 export const DEFAULT_CLICKHOUSE_INSTANCE_TYPE = "m7g.medium";
 /** ClickHouse container image. Explicit `docker.io/` prefix is required so
  *  string-form consumers in `ecsImages.ts#getContainerImage()` route through
@@ -62,23 +60,26 @@ export const CLICKHOUSE_HOST_RESERVE_MIB = 1024;
  *  derived from nominal memory, so the host reserve is what absorbs this
  *  withholding at task placement. */
 export const CLICKHOUSE_ECS_RESERVED_MEMORY_MIB = 256;
-/** Total memory (GiB) of the instance types the ClickHouse construct knows
- *  how to size a container for. Values are the AWS nominal figures. */
-export const CLICKHOUSE_INSTANCE_MEMORY_GIB = {
-    "t4g.medium": 4,
-    "m7g.medium": 4,
-    "m8g.medium": 4,
-    "r7g.medium": 8,
-    "r8g.medium": 8,
-    "m7g.large": 8,
-    "m8g.large": 8,
-    "r7g.large": 16,
-    "r8g.large": 16,
-    "m7g.xlarge": 16,
-    "m8g.xlarge": 16,
-    "r7g.xlarge": 32,
-    "r8g.xlarge": 32
+export const CLICKHOUSE_INSTANCE_SPECS = {
+    "t4g.medium": { vcpus: 2, memoryGib: 4 },
+    "m7g.medium": { vcpus: 1, memoryGib: 4 },
+    "m8g.medium": { vcpus: 1, memoryGib: 4 },
+    "r7g.medium": { vcpus: 1, memoryGib: 8 },
+    "r8g.medium": { vcpus: 1, memoryGib: 8 },
+    "m7g.large": { vcpus: 2, memoryGib: 8 },
+    "m8g.large": { vcpus: 2, memoryGib: 8 },
+    "r7g.large": { vcpus: 2, memoryGib: 16 },
+    "r8g.large": { vcpus: 2, memoryGib: 16 },
+    "m7g.xlarge": { vcpus: 4, memoryGib: 16 },
+    "m8g.xlarge": { vcpus: 4, memoryGib: 16 },
+    "r7g.xlarge": { vcpus: 4, memoryGib: 32 },
+    "r8g.xlarge": { vcpus: 4, memoryGib: 32 }
 };
+/** Derived memory-only view of CLICKHOUSE_INSTANCE_SPECS. */
+export const CLICKHOUSE_INSTANCE_MEMORY_GIB = Object.fromEntries(Object.entries(CLICKHOUSE_INSTANCE_SPECS).map(([type, spec]) => [
+    type,
+    spec.memoryGib
+]));
 /** ECS container memory for the ClickHouse server task, derived from the
  *  instance type so a size change cannot leave the hand-set container cap
  *  behind (the pre-2026-07 shape: a hardcoded 3072 that silently starved —
@@ -241,6 +242,14 @@ export const CLICKHOUSE_CLOUDMAP_SERVICE_NAME = "clickhouse";
  *  live-reload path into a silent no-op without any compile/test signal,
  *  so this lives as a single source of truth. */
 export const CLICKHOUSE_SERVER_CONTAINER_NAME = "clickhouse";
+/** ECS service name for the ClickHouse server. Coupled cross-repo value:
+ *  the webapp log collector excludes this service from customer log
+ *  collection by exact name (`CLICKHOUSE_SERVER_SERVICE_NAME` at
+ *  `webapp/app/.server/services/monitoring/logGroupResolution.ts`) —
+ *  deliberately duplicated rather than shared, so a webapp deploy is never
+ *  release-coupled to a constructs mint. Renaming this service breaks that
+ *  exclusion silently; update both sites together. */
+export const CLICKHOUSE_SERVICE_NAME = "ClickHouseService";
 /** Materialised views that benefit from periodic OPTIMIZE to reduce part count at read time.
  *  These are not ReplacingMergeTree (no dedup needed) but un-merged parts force
  *  read-time aggregation which degrades query performance.

package/dist/lib/resources/aws/database/clickhouseSchemas.d.ts

@@ -68,4 +68,24 @@ export type ProfileSpec = z.infer<typeof ProfileSpecSchema>;
  * XML element names with no escaping.
  */
 export declare const PROFILE_NAME_PATTERN: RegExp;
+/**
+ * Four workload-class default profiles at the DEFAULT instance type's scale.
+ * Since the 2026-08-12 instance-scaled derivation the canonical source is
+ * `deriveClickHouseDefaultProfiles(instanceType)` in `clickhouseTuning.ts` —
+ * the construct derives its default `profiles:` from the RESOLVED instance
+ * type, so this constant serves only consumers with no instance in hand
+ * (parity tests, docs). At `DEFAULT_CLICKHOUSE_INSTANCE_TYPE` the derivation
+ * reproduces the historical hand-tuned values byte-for-byte (pinned by
+ * clickhouseTuning.test.ts).
+ *
+ * `high_throughput_ingest.maxConcurrentQueriesForUser` (6) mirrors the
+ * webapp's client-side FIFO gate
+ * (`webapp/app/.server/lib/clickhouse/appQuerySlots.ts`) — a users.xml
+ * parity test enforces the pair, and the derivation deliberately never
+ * scales it.
+ *
+ * Frozen via `Object.freeze` on the outer record AND each sub-object so a
+ * consumer cannot mutate the defaults in place. Pass your own `profiles:`
+ * map to the construct to extend / override; never mutate this constant.
+ */
 export declare const ClickHouseDefaultProfiles: Readonly<Record<string, Readonly<ProfileSpec>>>;

package/dist/lib/resources/aws/database/clickhouseSchemas.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { DEFAULT_CLICKHOUSE_INSTANCE_TYPE } from "./clickhouseConstants.js";
+import { deriveClickHouseDefaultProfiles } from "./clickhouseTuning.js";
 /** ClickHouse user/profile name pattern — lowercase snake_case, leading
  *  letter only. Shared by `ClickHouseSchemaAdminSchema.name`, the per-profile
  *  key regex applied inside `ClickHouseDatabase`'s construct-time validation
@@ -86,82 +88,23 @@ export const ProfileSpecSchema = z
  */
 export const PROFILE_NAME_PATTERN = NAME_PATTERN;
 /**
- * Four workload-class default profiles. Cap values lifted byte-for-byte
- * from the pre-Phase-4b inline `<app_writer>` / `<audit_writer>` /
- * `<backup_reader>` / `<schema_admin>` blocks at
- * `clickhouseUserData.ts:296-382` — zero behavioural drift from the
- * pre-4b prod resource caps, EXCEPT high_throughput_ingest's
- * `maxConcurrentQueriesForUser`, deliberately raised 2→6 (2026-07-28):
- * the webapp overview fires 6–10 queries per page load and the cap of 2
- * threw TOO_MANY_SIMULTANEOUS_QUERIES instead of queueing (CH does not
- * queue past this cap — `queue_max_wait_ms` empirically does not apply).
- * Consumers pair it with a client-side FIFO gate
- * (`webapp/app/.server/lib/clickhouse/appQuerySlots.ts`) whose limit
- * MUST mirror this value — a users.xml parity test enforces the pair.
+ * Four workload-class default profiles at the DEFAULT instance type's scale.
+ * Since the 2026-08-12 instance-scaled derivation the canonical source is
+ * `deriveClickHouseDefaultProfiles(instanceType)` in `clickhouseTuning.ts` —
+ * the construct derives its default `profiles:` from the RESOLVED instance
+ * type, so this constant serves only consumers with no instance in hand
+ * (parity tests, docs). At `DEFAULT_CLICKHOUSE_INSTANCE_TYPE` the derivation
+ * reproduces the historical hand-tuned values byte-for-byte (pinned by
+ * clickhouseTuning.test.ts).
  *
- * Frozen via `Object.freeze` on the outer record AND each sub-object so
- * a consumer cannot mutate the defaults in place. Pass your own
- * `profiles:` map to the construct to extend / override; never mutate
- * this constant.
+ * `high_throughput_ingest.maxConcurrentQueriesForUser` (6) mirrors the
+ * webapp's client-side FIFO gate
+ * (`webapp/app/.server/lib/clickhouse/appQuerySlots.ts`) — a users.xml
+ * parity test enforces the pair, and the derivation deliberately never
+ * scales it.
+ *
+ * Frozen via `Object.freeze` on the outer record AND each sub-object so a
+ * consumer cannot mutate the defaults in place. Pass your own `profiles:`
+ * map to the construct to extend / override; never mutate this constant.
  */
-const _ClickHouseDefaultProfilesRaw = {
-    high_throughput_ingest: {
-        maxThreads: 1,
-        maxInsertThreads: 1,
-        maxConcurrentQueriesForUser: 6,
-        logQueriesMinQueryDurationMs: 100,
-        optimizeMoveToPrewhere: true,
-        useQueryConditionCache: true,
-        useSkipIndexesIfFinal: true,
-        applyRowPolicyAfterFinal: true,
-        applyPrewhereAfterFinal: true,
-        doNotMergeAcrossPartitionsSelectFinal: true,
-        asyncInsert: true,
-        waitForAsyncInsert: true,
-        asyncInsertMaxDataSize: 10000000,
-        asyncInsertBusyTimeoutMinMs: 50,
-        asyncInsertBusyTimeoutMaxMs: 2000,
-        asyncInsertUseAdaptiveBusyTimeout: true,
-        asyncInsertDeduplicate: true,
-        inputFormatParallelParsing: false,
-        outputFormatParallelFormatting: false,
-        queryPlanOptimizeLazyMaterialization: true,
-        maxMemoryUsage: 1610612736,
-        maxMemoryUsageForUser: 2147483648,
-        maxBytesBeforeExternalSort: 536870912,
-        maxBytesBeforeExternalGroupBy: 536870912,
-        maxExecutionTime: 30,
-        maxRowsToRead: 10000000
-    },
-    audit_append: {
-        maxThreads: 1,
-        maxInsertThreads: 1,
-        maxConcurrentQueriesForUser: 2,
-        maxMemoryUsage: 500000000,
-        maxExecutionTime: 10,
-        asyncInsert: true,
-        waitForAsyncInsert: true
-    },
-    read_only: {
-        maxThreads: 1,
-        maxConcurrentQueriesForUser: 1,
-        maxMemoryUsage: 1000000000,
-        maxExecutionTime: 3600
-    },
-    ddl_admin: {
-        maxThreads: 1,
-        maxConcurrentQueriesForUser: 1,
-        maxMemoryUsage: 1000000000,
-        maxExecutionTime: 1800
-    }
-};
-export const ClickHouseDefaultProfiles = Object.freeze({
-    high_throughput_ingest: Object.freeze({
-        ..._ClickHouseDefaultProfilesRaw.high_throughput_ingest
-    }),
-    audit_append: Object.freeze({
-        ..._ClickHouseDefaultProfilesRaw.audit_append
-    }),
-    read_only: Object.freeze({ ..._ClickHouseDefaultProfilesRaw.read_only }),
-    ddl_admin: Object.freeze({ ..._ClickHouseDefaultProfilesRaw.ddl_admin })
-});
+export const ClickHouseDefaultProfiles = deriveClickHouseDefaultProfiles(DEFAULT_CLICKHOUSE_INSTANCE_TYPE);

package/dist/lib/resources/aws/database/clickhouseTuning.d.ts

@@ -0,0 +1,64 @@
+import type { ProfileSpec } from "./clickhouseSchemas.js";
+/**
+ * Server-level tuning values derived from the instance type. Consumed by
+ * `generateServerConfigXml` — every value here lands in the rendered
+ * `config.d/fjall.xml`, so a change means a launch-template refresh +
+ * instance refresh + server restart to take effect (the schedule-pool
+ * per-type cap in particular is computed once at pool creation).
+ */
+export interface ClickHouseServerTuning {
+    maxConcurrentQueries: number;
+    backgroundPoolSize: number;
+    backgroundSchedulePoolSize: number;
+    backgroundMovePoolSize: number;
+    backgroundFetchesPoolSize: number;
+    backgroundMessageBrokerSchedulePoolSize: number;
+    mergesMutationsConcurrencyRatio: number;
+    freeEntriesToExecuteMutation: number;
+    freeEntriesToLowerMaxSizeOfMerge: number;
+    freeEntriesToExecuteOptimizeEntirePartition: number;
+    markCacheBytes: number;
+    indexMarkCacheBytes: number;
+    queryCacheBytes: number;
+}
+/** Ratio ClickHouse >= 25.9 applies to the schedule pool to derive the
+ *  per-type concurrent-task cap (`background_schedule_pool_max_parallel_tasks_per_type_ratio`
+ *  default). Mirrored here only so the derivation test can assert the cap
+ *  stays >= 2 for every supported instance type. */
+export declare const SCHEDULE_POOL_PER_TYPE_CAP_RATIO = 0.8;
+/**
+ * `max_server_memory_usage_to_ram_ratio` rendered into the server config.
+ * 0.75 gives the kernel a cushion on the cgroup for CH's untracked
+ * allocations (libc allocator, executable image, malloc fragmentation,
+ * jemalloc virtual reservations on ARM64); the default 0.9 left ~300 MB on
+ * the 4 GiB host and OOM-killed the process at boot (exit 137). Exported so
+ * the cache-budget test computes against the same ratio the XML ships —
+ * re-tuning it here moves both sites together.
+ */
+export declare const MAX_SERVER_MEMORY_RAM_RATIO = 0.75;
+/** Retention for every configured system log table. One policy, eight
+ *  `<ttl>` sites in the rendered config — interpolated so a retention
+ *  change is a single edit. */
+export declare const SYSTEM_LOG_TTL = "event_date + INTERVAL 14 DAY DELETE";
+/**
+ * Derive the server-level pool/cache/concurrency configuration from the
+ * instance type. Replaces the hand-tuned m7g.medium constants that silently
+ * stopped fitting when the instance type moved (the 2026-08-03 r8g.medium
+ * flip scaled only the container memory limit; every pool and cache stayed
+ * at 4 GiB values until the 2026-08-12 prod investigation caught it).
+ */
+export declare function deriveClickHouseServerTuning(instanceType: string): ClickHouseServerTuning;
+/**
+ * Derive the four workload-class default profiles from the instance type.
+ * Memory caps, external-spill thresholds and row-read ceilings scale with
+ * instance memory; thread caps scale with vCPUs. At the default
+ * m7g.medium this reproduces the historical hand-tuned values exactly
+ * (pinned by clickhouseTuning.test.ts).
+ *
+ * `high_throughput_ingest.maxConcurrentQueriesForUser` deliberately does
+ * NOT scale: it mirrors the webapp's client-side FIFO gate
+ * (`webapp/app/.server/lib/clickhouse/appQuerySlots.ts`) — a users.xml
+ * parity test on the webapp side enforces the pair, so the value is a
+ * client contract, not an instance-capacity knob.
+ */
+export declare function deriveClickHouseDefaultProfiles(instanceType: string): Readonly<Record<string, Readonly<ProfileSpec>>>;

package/dist/lib/resources/aws/database/clickhouseTuning.js

@@ -0,0 +1,182 @@
+import { CLICKHOUSE_INSTANCE_SPECS } from "./clickhouseConstants.js";
+/** 4 GiB / 1 vCPU (m7g.medium) baseline the scaling formulas anchor to.
+ *  These are the proven prod values the construct shipped hand-tuned before
+ *  derivation existed — `deriveClickHouseServerTuning("m7g.medium")` must
+ *  reproduce them exactly (pinned by clickhouseTuning.test.ts), with the one
+ *  deliberate exception of the schedule pool (see SCHEDULE_POOL_FLOOR). */
+const BASELINE_MEMORY_GIB = 4;
+const BASE_MARK_CACHE_BYTES = 402653184; // 384 MiB
+const BASE_INDEX_MARK_CACHE_BYTES = 134217728; // 128 MiB
+const BASE_QUERY_CACHE_BYTES = 268435456; // 256 MiB
+const BASE_MAX_CONCURRENT_QUERIES_PER_VCPU = 8;
+/**
+ * Floor on `background_schedule_pool_size`, independent of instance size.
+ *
+ * ClickHouse >= 25.9 (upstream PR #84008) caps same-type concurrent
+ * background tasks at `floor(pool_size * 0.8)` and logs
+ * `<Warning> BgSchPool: Temporarily pause scheduling of tasks with id ...`
+ * every time the cap defers a task. The pre-derivation hand-tuned pool of 2
+ * produced a cap of 1 — the warning fired on essentially every task start
+ * (~35k lines/hour observed on prod, 2026-08-12) and serialised ALL
+ * background scheduling (merge selection, TTL moves, parts cleanup, S3 blob
+ * deletion) through two threads. Schedule-pool threads are dispatchers, not
+ * workers — they spend their lives sleeping between ticks — so the floor
+ * costs thread stacks, not CPU. 8 gives a per-type cap of 6.
+ *
+ * The cap is computed ONCE at pool creation: raising this value requires a
+ * server restart, not a config reload.
+ */
+const SCHEDULE_POOL_FLOOR = 8;
+/** Ratio ClickHouse >= 25.9 applies to the schedule pool to derive the
+ *  per-type concurrent-task cap (`background_schedule_pool_max_parallel_tasks_per_type_ratio`
+ *  default). Mirrored here only so the derivation test can assert the cap
+ *  stays >= 2 for every supported instance type. */
+export const SCHEDULE_POOL_PER_TYPE_CAP_RATIO = 0.8;
+/**
+ * `max_server_memory_usage_to_ram_ratio` rendered into the server config.
+ * 0.75 gives the kernel a cushion on the cgroup for CH's untracked
+ * allocations (libc allocator, executable image, malloc fragmentation,
+ * jemalloc virtual reservations on ARM64); the default 0.9 left ~300 MB on
+ * the 4 GiB host and OOM-killed the process at boot (exit 137). Exported so
+ * the cache-budget test computes against the same ratio the XML ships —
+ * re-tuning it here moves both sites together.
+ */
+export const MAX_SERVER_MEMORY_RAM_RATIO = 0.75;
+/** Retention for every configured system log table. One policy, eight
+ *  `<ttl>` sites in the rendered config — interpolated so a retention
+ *  change is a single edit. */
+export const SYSTEM_LOG_TTL = "event_date + INTERVAL 14 DAY DELETE";
+function resolveSpec(instanceType) {
+    const spec = CLICKHOUSE_INSTANCE_SPECS[instanceType];
+    if (spec === undefined) {
+        throw new Error(`ClickHouseDatabase: unknown instance type '${instanceType}' — cannot ` +
+            "derive server tuning. Supported: " +
+            `${Object.keys(CLICKHOUSE_INSTANCE_SPECS).join(", ")}. Add the ` +
+            "type's spec to CLICKHOUSE_INSTANCE_SPECS (clickhouseConstants.ts) " +
+            "to support it.");
+    }
+    return spec;
+}
+/** Linear memory scale relative to the 4 GiB baseline. Every supported spec
+ *  is a power-of-two multiple of 4 GiB, so the scale is always an integer
+ *  and every derived byte value stays exact. */
+function memoryScale(spec) {
+    return spec.memoryGib / BASELINE_MEMORY_GIB;
+}
+/**
+ * Derive the server-level pool/cache/concurrency configuration from the
+ * instance type. Replaces the hand-tuned m7g.medium constants that silently
+ * stopped fitting when the instance type moved (the 2026-08-03 r8g.medium
+ * flip scaled only the container memory limit; every pool and cache stayed
+ * at 4 GiB values until the 2026-08-12 prod investigation caught it).
+ */
+export function deriveClickHouseServerTuning(instanceType) {
+    const spec = resolveSpec(instanceType);
+    const scale = memoryScale(spec);
+    // Merge/mutation workers burn CPU — scale with vCPUs, floor at the proven
+    // 1-vCPU value. The ratio then allows 2x slots for merge SELECTION, while
+    // actual execution stays bounded by the pool.
+    const backgroundPoolSize = Math.max(2, 2 * spec.vcpus);
+    const mergesMutationsConcurrencyRatio = 2;
+    // ClickHouse sanity-checks the merge_tree free-entry thresholds against
+    // pool * ratio at startup (BAD_ARGUMENTS when a threshold exceeds the
+    // slot count). Deriving from the slot count keeps the invariant by
+    // construction: slots/4 approximates the proportion the CH defaults
+    // (20/8/25 against 32 slots) express, floored at 1 so small pools can
+    // always start a merge/mutation the moment a slot frees.
+    const slots = backgroundPoolSize * mergesMutationsConcurrencyRatio;
+    const freeEntries = Math.max(1, Math.floor(slots / 4));
+    return {
+        // Slots time-slice rather than parallelise on small hosts; 8 per vCPU is
+        // the proven m7g.medium value (raised 4→8 2026-07-28 for the webapp
+        // overview's 6-10 queries/page fan-out).
+        maxConcurrentQueries: BASE_MAX_CONCURRENT_QUERIES_PER_VCPU * spec.vcpus,
+        backgroundPoolSize,
+        backgroundSchedulePoolSize: Math.max(SCHEDULE_POOL_FLOOR, 4 * spec.vcpus),
+        // Moves are I/O-bound (S3 cold-tier uploads); fetches serve replication
+        // (none in this single-node design) and the broker pool serves Kafka
+        // (none) — both stay minimal at every size.
+        backgroundMovePoolSize: spec.vcpus >= 4 ? 2 : 1,
+        backgroundFetchesPoolSize: 1,
+        backgroundMessageBrokerSchedulePoolSize: 1,
+        mergesMutationsConcurrencyRatio,
+        freeEntriesToExecuteMutation: freeEntries,
+        freeEntriesToLowerMaxSizeOfMerge: freeEntries,
+        freeEntriesToExecuteOptimizeEntirePartition: freeEntries,
+        markCacheBytes: BASE_MARK_CACHE_BYTES * scale,
+        indexMarkCacheBytes: BASE_INDEX_MARK_CACHE_BYTES * scale,
+        queryCacheBytes: BASE_QUERY_CACHE_BYTES * scale
+    };
+}
+/**
+ * Derive the four workload-class default profiles from the instance type.
+ * Memory caps, external-spill thresholds and row-read ceilings scale with
+ * instance memory; thread caps scale with vCPUs. At the default
+ * m7g.medium this reproduces the historical hand-tuned values exactly
+ * (pinned by clickhouseTuning.test.ts).
+ *
+ * `high_throughput_ingest.maxConcurrentQueriesForUser` deliberately does
+ * NOT scale: it mirrors the webapp's client-side FIFO gate
+ * (`webapp/app/.server/lib/clickhouse/appQuerySlots.ts`) — a users.xml
+ * parity test on the webapp side enforces the pair, so the value is a
+ * client contract, not an instance-capacity knob.
+ */
+export function deriveClickHouseDefaultProfiles(instanceType) {
+    const spec = resolveSpec(instanceType);
+    const scale = memoryScale(spec);
+    return Object.freeze({
+        high_throughput_ingest: Object.freeze({
+            maxThreads: spec.vcpus,
+            maxInsertThreads: spec.vcpus,
+            maxConcurrentQueriesForUser: 6,
+            logQueriesMinQueryDurationMs: 100,
+            optimizeMoveToPrewhere: true,
+            useQueryConditionCache: true,
+            useSkipIndexesIfFinal: true,
+            applyRowPolicyAfterFinal: true,
+            applyPrewhereAfterFinal: true,
+            doNotMergeAcrossPartitionsSelectFinal: true,
+            asyncInsert: true,
+            waitForAsyncInsert: true,
+            asyncInsertMaxDataSize: 10000000,
+            asyncInsertBusyTimeoutMinMs: 50,
+            asyncInsertBusyTimeoutMaxMs: 2000,
+            asyncInsertUseAdaptiveBusyTimeout: true,
+            asyncInsertDeduplicate: true,
+            inputFormatParallelParsing: false,
+            outputFormatParallelFormatting: false,
+            queryPlanOptimizeLazyMaterialization: true,
+            maxMemoryUsage: 1610612736 * scale, // 1.5 GiB baseline
+            maxMemoryUsageForUser: 2147483648 * scale, // 2 GiB baseline
+            maxBytesBeforeExternalSort: 536870912 * scale, // 512 MiB baseline
+            maxBytesBeforeExternalGroupBy: 536870912 * scale,
+            maxExecutionTime: 30,
+            // The ceiling an unbounded consumer query dies against (TOO_MANY_ROWS).
+            // Scales with memory so a bigger node's tables get proportionate
+            // headroom — but consumers must still time-bound their scans; this is
+            // a guard rail, not a budget to grow into.
+            maxRowsToRead: 10000000 * scale
+        }),
+        audit_append: Object.freeze({
+            maxThreads: 1,
+            maxInsertThreads: 1,
+            maxConcurrentQueriesForUser: 2,
+            maxMemoryUsage: 500000000 * scale,
+            maxExecutionTime: 10,
+            asyncInsert: true,
+            waitForAsyncInsert: true
+        }),
+        read_only: Object.freeze({
+            maxThreads: spec.vcpus,
+            maxConcurrentQueriesForUser: 1,
+            maxMemoryUsage: 1000000000 * scale,
+            maxExecutionTime: 3600
+        }),
+        ddl_admin: Object.freeze({
+            maxThreads: spec.vcpus,
+            maxConcurrentQueriesForUser: 1,
+            maxMemoryUsage: 1000000000 * scale,
+            maxExecutionTime: 1800
+        })
+    });
+}

package/dist/lib/resources/aws/database/clickhouseUserData.d.ts

@@ -11,6 +11,13 @@ export interface BuildClickHouseUserDataOptions {
     backupBucketName: string;
     /** AWS region of the backup bucket. */
     backupBucketRegion: string;
+    /**
+     * Resolved EC2 instance type. Server pools, caches and concurrency caps
+     * derive from it via `deriveClickHouseServerTuning` — must be a key of
+     * `CLICKHOUSE_INSTANCE_SPECS` (unknown types throw at synth, same contract
+     * as `clickHouseTaskMemoryMiB`).
+     */
+    instanceType: string;
     /**
      * Optional S3 cold-tier configuration.
      * When omitted, single-tier hot storage on the EC2 EBS volume is used.