@fjall/components-infrastructure 16.0.1 → 17.0.0

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

@@ -1,3 +1,4 @@
+import type { ClickHouseInstanceType } from "@fjall/util/clickhouse";
 /** Database name created at ClickHouse bootstrap; consumed by BACKUP DATABASE,
  *  OPTIMIZE TABLE, and the DatabaseName CfnOutput so all four sites share one source. */
 export declare const CLICKHOUSE_DATABASE_NAME = "analytics";
@@ -42,28 +43,67 @@ export declare const DEFAULT_CLICKHOUSE_INSTANCE_TYPE = "m7g.medium";
  *  that pulls once per launch. Upstream CH CI runs its full perf + stress
  *  matrix on the Ubuntu build; Alpine is community-tier coverage. */
 export declare const CLICKHOUSE_IMAGE = "docker.io/clickhouse/clickhouse-server:26.3.17.56";
+/** Absolute floor of the disk-critical alarm, in GiB.
+ *
+ *  A pure percentage cannot express "about to break": 85 % used is 12 GiB
+ *  free on an 80 GiB volume and 600 GiB free on a 4 TiB one, and only one of
+ *  those is an incident. But a pure constant cannot either, because the other
+ *  half of the failure scales with the data — ClickHouse will not select a
+ *  merge whose source parts need more than the free space allows, and parts
+ *  grow with the table. So the default floor is the LARGER of this constant
+ *  and `CLICKHOUSE_DISK_FREE_CRITICAL_SHARE` of the volume: the constant
+ *  guards response time on a small disk, the share guards merge headroom on a
+ *  large one. See `resolveClickHouseStorage`.
+ *
+ *  20 GiB is days of ingest headroom at the observed rate — enough lead time
+ *  to grow the volume, which takes an instance restart and cannot be done in
+ *  minutes. */
+export declare const CLICKHOUSE_DISK_FREE_CRITICAL_GIB = 20;
+/** Share of the volume the disk-critical floor rises to on larger disks.
+ *  At 5 %, a 4 TiB volume pages with 200 GiB free — roughly twice a large
+ *  part, so merges still have room to complete while the operator responds.
+ *  The two halves cross over at 400 GiB, the default volume size. */
+export declare const CLICKHOUSE_DISK_FREE_CRITICAL_SHARE = 0.05;
 /** EBS volume configuration.
  *
- *  Sized for the 30-organisation baseline the 2026-08 capacity review set,
- *  not for today's tenant count: the 80 GiB the cluster launched on binds at
- *  roughly 20-25 organisations once `log_events` and `application_metrics`
- *  carry a full retention window each, which is BELOW that baseline. 400 GiB
- *  buys the headroom to reach it without a second resize, and gp3 storage is
- *  cheap relative to an out-of-disk ClickHouse (merges stop, inserts start
- *  failing, and the recovery is a restore rather than a resize).
- *
- *  Raising this alone is not enough — `buildClickHouseUserData` must grow the
- *  ext4 filesystem to match, because ModifyVolume resizes the block device
- *  and nothing else. The pair moves together; see the `resize2fs` step there.
- *  Applying an increase to a RUNNING cluster therefore needs the instance to
- *  relaunch (user data runs at boot), and EBS permits one modification per
- *  volume per 6 hours.
- *
- *  IOPS and throughput stay at the gp3 baseline: they are size-independent on
- *  gp3, and the workload is merge- and scan-bound rather than IOPS-starved. */
+ *  `CLICKHOUSE_EBS_VOLUME_SIZE_GB` is the DEFAULT for
+ *  `ClickHouseDatabaseProps.storageGb`, not a fixed size. 400 GiB is sized
+ *  for a mid-size multi-tenant analytics workload — order of tens of tenant
+ *  organisations each carrying full `log_events` / `application_metrics`
+ *  retention windows — with enough headroom that the first resize is a
+ *  deliberate capacity decision rather than an early surprise. (The
+ *  reference deployment's history is the evidence: 80 GiB bound at roughly
+ *  two-thirds of that scale.) gp3 storage is cheap relative to an
+ *  out-of-disk ClickHouse — merges stop, inserts start failing, and the
+ *  recovery is a restore rather than a resize. Workloads outside that
+ *  profile set `storageGb` directly, exactly as they would size an RDS
+ *  volume.
+ *
+ *  Raising the size alone is not enough — `buildClickHouseUserData` must grow
+ *  the ext4 filesystem to match, because ModifyVolume resizes the block
+ *  device and nothing else. The pair moves together: the declared size is
+ *  embedded in the user data, so a `storageGb` change versions the launch
+ *  template and triggers the instance refresh whose boot runs `resize2fs`.
+ *  EBS permits one modification per volume per 6 hours.
+ *
+ *  IOPS and throughput default to the gp3 baseline — the figures the volume
+ *  price already includes — and are the construct's `iops` / `throughputMbps`
+ *  props, the way RDS exposes provisioned IOPS and throughput on gp3. They are
+ *  size-independent on gp3 and the default workload is merge- and scan-bound
+ *  rather than IOPS-starved, so the baseline is the right default; a caller
+ *  whose scans are bandwidth-bound raises them, within the bounds and ratios
+ *  `resolveClickHouseVolumePerformance` enforces. */
 export declare const CLICKHOUSE_EBS_VOLUME_SIZE_GB = 400;
 export declare const CLICKHOUSE_EBS_IOPS = 3000;
 export declare const CLICKHOUSE_EBS_THROUGHPUT_MBPS = 125;
+/** Volume and backup-retention bounds. Re-exported, NOT redeclared:
+ *  `@fjall/generator` enforces the same numbers when it scaffolds or rewrites
+ *  an `infrastructure.ts` declaration, and a second copy here is exactly the
+ *  drift `backupRetentionDays` shipped for as long as it borrowed the RDS
+ *  schema (generator 35 vs construct 3650). One source, two enforcement
+ *  sites. */
+export { CLICKHOUSE_MIN_STORAGE_GB, CLICKHOUSE_MAX_STORAGE_GB, CLICKHOUSE_MIN_IOPS, CLICKHOUSE_MAX_IOPS, CLICKHOUSE_MAX_IOPS_PER_GB, CLICKHOUSE_MIN_THROUGHPUT_MBPS, CLICKHOUSE_MAX_THROUGHPUT_MBPS, CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS, CLICKHOUSE_MIN_BACKUP_RETENTION_DAYS, CLICKHOUSE_MAX_BACKUP_RETENTION_DAYS, CLICKHOUSE_INSTANCE_TYPES } from "@fjall/util/clickhouse";
+export type { ClickHouseInstanceType } from "@fjall/util/clickhouse";
 /** Host memory reserved from the ClickHouse container: kernel + ECS agent +
  *  the host-metrics timer. The ECS agent advertises MemTotal minus
  *  CLICKHOUSE_ECS_RESERVED_MEMORY_MIB, and MemTotal itself runs below the
@@ -81,13 +121,25 @@ export declare const CLICKHOUSE_ECS_RESERVED_MEMORY_MIB = 256;
 /** Hardware spec of every instance type the ClickHouse construct supports.
  *  Values are the AWS nominal figures. Single source of truth for BOTH the
  *  container memory limit (`clickHouseTaskMemoryMiB`) and the derived server
- *  tuning + default profiles (`clickhouseTuning.ts`) — adding a type here is
- *  the only step needed to support it end to end. */
+ *  tuning + default profiles (`clickhouseTuning.ts`).
+ *
+ *  Keyed on `ClickHouseInstanceType` — the supported-type vocabulary lives in
+ *  `@fjall/util/clickhouse` so the generator can validate `instanceType` at
+ *  scaffold time against the same list. The `Record` key type makes the
+ *  parity two-way at compile time: a vocabulary entry without a spec row is a
+ *  missing-property error, a spec row outside the vocabulary is an
+ *  excess-property error. Supporting a new type = add it to the tuple there
+ *  and the spec row here; everything else derives. */
 export interface ClickHouseInstanceSpec {
     vcpus: number;
     memoryGib: number;
 }
-export declare const CLICKHOUSE_INSTANCE_SPECS: Record<string, ClickHouseInstanceSpec>;
+export declare const CLICKHOUSE_INSTANCE_SPECS: Record<ClickHouseInstanceType, ClickHouseInstanceSpec>;
+/** Guarded string-keyed lookup into `CLICKHOUSE_INSTANCE_SPECS` for
+ *  caller-supplied types (props carry `string`); `undefined` for unknown
+ *  types, which every caller converts into its own named synth throw. The
+ *  exhaustively-keyed Record above stays the compile-time contract. */
+export declare function clickHouseInstanceSpec(instanceType: string): ClickHouseInstanceSpec | undefined;
 /** Derived memory-only view of CLICKHOUSE_INSTANCE_SPECS. */
 export declare const CLICKHOUSE_INSTANCE_MEMORY_GIB: Record<string, number>;
 /** ECS container memory for the ClickHouse server task, derived from the
@@ -179,6 +231,7 @@ export declare const CLICKHOUSE_HOST_METRICS: {
     readonly namespace: "CWAgent";
     readonly memoryMetric: "mem_used_percent";
     readonly diskMetric: "disk_used_percent";
+    readonly diskFreeMetric: "disk_free_gib";
     readonly asgDimension: "AutoScalingGroupName";
 };
 /** Shared secret generation options (all ClickHouse users share the same policy). */
@@ -248,3 +301,62 @@ export declare const BACKUP_TASK_MEMORY_MIB = 256;
 export declare const BACKUP_TASK_CPU_UNITS = 256;
 /** Backup object expiration: 14 days (retains 14 daily snapshots). */
 export declare const BACKUP_RETENTION_DAYS = 14;
+/** Scratch database the backup task restores into to prove the backup it just
+ *  wrote can be read back. Dropped on the way in and on the way out; never
+ *  queried by the application. */
+export declare const CLICKHOUSE_BACKUP_SCRATCH_DATABASE = "fjall_backup_verify";
+/** Multiple of the critical free-space floor the verify restore must leave
+ *  clear to proceed.
+ *
+ *  A full restore writes a second copy of the database onto the volume it is
+ *  verifying, so the check has to be bounded by the same quantity the disk
+ *  alarm pages on — otherwise the mechanism that protects the data is also
+ *  the mechanism most likely to fill the disk. Twice the floor rather than
+ *  once so a verify can never itself be the thing that pages: at exactly the
+ *  floor the restore would land the volume on the alarm threshold and hold it
+ *  there until the scratch database is dropped. */
+export declare const CLICKHOUSE_BACKUP_VERIFY_FREE_SPACE_MARGIN = 2;
+/** Backup task log markers. Distinct full tokens, because the CloudWatch
+ *  metric filters that read them match on substrings — a shared `BACKUP_`
+ *  stem would make the OK filter count the failures too. */
+export declare const CLICKHOUSE_BACKUP_VERIFY_OK_MARKER = "BACKUP_VERIFY_OK";
+export declare const CLICKHOUSE_BACKUP_VERIFY_FAILED_MARKER = "BACKUP_VERIFY_FAILED";
+export declare const CLICKHOUSE_BACKUP_VERIFY_SKIPPED_MARKER = "BACKUP_VERIFY_SKIPPED_FOR_SIZE";
+/** Bounds on the verify restore's wall-clock ceiling, in seconds.
+ *
+ *  Without a ceiling a hung RESTORE is the one backup failure with NO signal
+ *  at all: BACKUP_CREATED has already been emitted so the heartbeat is
+ *  satisfied, and the verify alarms count markers rather than their absence,
+ *  so a task that never finishes reports nothing. `timeout` turns that
+ *  silence into exit 124, which takes the same branch as a raised restore
+ *  and pages.
+ *
+ *  The ceiling scales with the volume (`clickHouseBackupVerifyTimeoutSeconds`
+ *  below) because the largest restore the free-space gate admits scales with
+ *  it: on the default 400 GiB the floor of one hour already covers it, but a
+ *  multi-TiB volume can legitimately need hours, and a fixed hour would page
+ *  FAILED on every healthy verify past the size where the restore outgrows
+ *  it. The 20-hour cap keeps a daily-scheduled verify from overlapping its
+ *  successor — two concurrent runs share the scratch database destructively,
+ *  so the bound must land inside the schedule interval. */
+export declare const CLICKHOUSE_BACKUP_VERIFY_MIN_TIMEOUT_SECONDS = 3600;
+export declare const CLICKHOUSE_BACKUP_VERIFY_MAX_TIMEOUT_SECONDS = 72000;
+/** Verify-restore timeout for a given data-volume size.
+ *
+ *  Worst case admitted by the free-space gate is a database of roughly half
+ *  the volume (it must fit beside itself). Writing that back at the gp3
+ *  baseline throughput (`CLICKHOUSE_EBS_THROUGHPUT_MBPS`) bounds the healthy
+ *  duration; doubled for read + merge overhead, then clamped to the
+ *  floor/cap pair above. At the 400 GiB default this resolves to the
+ *  one-hour floor, so the default behaviour is unchanged from the flat bound
+ *  it replaced.
+ *
+ *  Deliberately the BASELINE throughput, not the provisioned `throughputMbps`
+ *  prop. The volume's provisioned figure is an upper bound the instance may
+ *  not reach — an m7g.medium's EBS bandwidth sits under the gp3 baseline, and
+ *  no default-tier host reaches a provisioned 1,000 MiB/s — so a bound that
+ *  tightened with provisioning would page FAILED on healthy restores on
+ *  exactly the hosts customers start on. The baseline-derived bound is loose
+ *  on a provisioned volume, which only delays a hung-restore page; the cap
+ *  keeps that delay inside the schedule interval either way. */
+export declare function clickHouseBackupVerifyTimeoutSeconds(storageGb: number): number;

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

@@ -42,28 +42,66 @@ export const DEFAULT_CLICKHOUSE_INSTANCE_TYPE = "m7g.medium";
  *  that pulls once per launch. Upstream CH CI runs its full perf + stress
  *  matrix on the Ubuntu build; Alpine is community-tier coverage. */
 export const CLICKHOUSE_IMAGE = "docker.io/clickhouse/clickhouse-server:26.3.17.56";
+/** Absolute floor of the disk-critical alarm, in GiB.
+ *
+ *  A pure percentage cannot express "about to break": 85 % used is 12 GiB
+ *  free on an 80 GiB volume and 600 GiB free on a 4 TiB one, and only one of
+ *  those is an incident. But a pure constant cannot either, because the other
+ *  half of the failure scales with the data — ClickHouse will not select a
+ *  merge whose source parts need more than the free space allows, and parts
+ *  grow with the table. So the default floor is the LARGER of this constant
+ *  and `CLICKHOUSE_DISK_FREE_CRITICAL_SHARE` of the volume: the constant
+ *  guards response time on a small disk, the share guards merge headroom on a
+ *  large one. See `resolveClickHouseStorage`.
+ *
+ *  20 GiB is days of ingest headroom at the observed rate — enough lead time
+ *  to grow the volume, which takes an instance restart and cannot be done in
+ *  minutes. */
+export const CLICKHOUSE_DISK_FREE_CRITICAL_GIB = 20;
+/** Share of the volume the disk-critical floor rises to on larger disks.
+ *  At 5 %, a 4 TiB volume pages with 200 GiB free — roughly twice a large
+ *  part, so merges still have room to complete while the operator responds.
+ *  The two halves cross over at 400 GiB, the default volume size. */
+export const CLICKHOUSE_DISK_FREE_CRITICAL_SHARE = 0.05;
 /** EBS volume configuration.
  *
- *  Sized for the 30-organisation baseline the 2026-08 capacity review set,
- *  not for today's tenant count: the 80 GiB the cluster launched on binds at
- *  roughly 20-25 organisations once `log_events` and `application_metrics`
- *  carry a full retention window each, which is BELOW that baseline. 400 GiB
- *  buys the headroom to reach it without a second resize, and gp3 storage is
- *  cheap relative to an out-of-disk ClickHouse (merges stop, inserts start
- *  failing, and the recovery is a restore rather than a resize).
+ *  `CLICKHOUSE_EBS_VOLUME_SIZE_GB` is the DEFAULT for
+ *  `ClickHouseDatabaseProps.storageGb`, not a fixed size. 400 GiB is sized
+ *  for a mid-size multi-tenant analytics workload — order of tens of tenant
+ *  organisations each carrying full `log_events` / `application_metrics`
+ *  retention windows — with enough headroom that the first resize is a
+ *  deliberate capacity decision rather than an early surprise. (The
+ *  reference deployment's history is the evidence: 80 GiB bound at roughly
+ *  two-thirds of that scale.) gp3 storage is cheap relative to an
+ *  out-of-disk ClickHouse — merges stop, inserts start failing, and the
+ *  recovery is a restore rather than a resize. Workloads outside that
+ *  profile set `storageGb` directly, exactly as they would size an RDS
+ *  volume.
  *
- *  Raising this alone is not enough — `buildClickHouseUserData` must grow the
- *  ext4 filesystem to match, because ModifyVolume resizes the block device
- *  and nothing else. The pair moves together; see the `resize2fs` step there.
- *  Applying an increase to a RUNNING cluster therefore needs the instance to
- *  relaunch (user data runs at boot), and EBS permits one modification per
- *  volume per 6 hours.
+ *  Raising the size alone is not enough — `buildClickHouseUserData` must grow
+ *  the ext4 filesystem to match, because ModifyVolume resizes the block
+ *  device and nothing else. The pair moves together: the declared size is
+ *  embedded in the user data, so a `storageGb` change versions the launch
+ *  template and triggers the instance refresh whose boot runs `resize2fs`.
+ *  EBS permits one modification per volume per 6 hours.
  *
- *  IOPS and throughput stay at the gp3 baseline: they are size-independent on
- *  gp3, and the workload is merge- and scan-bound rather than IOPS-starved. */
+ *  IOPS and throughput default to the gp3 baseline — the figures the volume
+ *  price already includes — and are the construct's `iops` / `throughputMbps`
+ *  props, the way RDS exposes provisioned IOPS and throughput on gp3. They are
+ *  size-independent on gp3 and the default workload is merge- and scan-bound
+ *  rather than IOPS-starved, so the baseline is the right default; a caller
+ *  whose scans are bandwidth-bound raises them, within the bounds and ratios
+ *  `resolveClickHouseVolumePerformance` enforces. */
 export const CLICKHOUSE_EBS_VOLUME_SIZE_GB = 400;
 export const CLICKHOUSE_EBS_IOPS = 3000;
 export const CLICKHOUSE_EBS_THROUGHPUT_MBPS = 125;
+/** Volume and backup-retention bounds. Re-exported, NOT redeclared:
+ *  `@fjall/generator` enforces the same numbers when it scaffolds or rewrites
+ *  an `infrastructure.ts` declaration, and a second copy here is exactly the
+ *  drift `backupRetentionDays` shipped for as long as it borrowed the RDS
+ *  schema (generator 35 vs construct 3650). One source, two enforcement
+ *  sites. */
+export { CLICKHOUSE_MIN_STORAGE_GB, CLICKHOUSE_MAX_STORAGE_GB, CLICKHOUSE_MIN_IOPS, CLICKHOUSE_MAX_IOPS, CLICKHOUSE_MAX_IOPS_PER_GB, CLICKHOUSE_MIN_THROUGHPUT_MBPS, CLICKHOUSE_MAX_THROUGHPUT_MBPS, CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS, CLICKHOUSE_MIN_BACKUP_RETENTION_DAYS, CLICKHOUSE_MAX_BACKUP_RETENTION_DAYS, CLICKHOUSE_INSTANCE_TYPES } from "@fjall/util/clickhouse";
 /** Host memory reserved from the ClickHouse container: kernel + ECS agent +
  *  the host-metrics timer. The ECS agent advertises MemTotal minus
  *  CLICKHOUSE_ECS_RESERVED_MEMORY_MIB, and MemTotal itself runs below the
@@ -93,6 +131,15 @@ export const CLICKHOUSE_INSTANCE_SPECS = {
     "r7g.xlarge": { vcpus: 4, memoryGib: 32 },
     "r8g.xlarge": { vcpus: 4, memoryGib: 32 }
 };
+/** Guarded string-keyed lookup into `CLICKHOUSE_INSTANCE_SPECS` for
+ *  caller-supplied types (props carry `string`); `undefined` for unknown
+ *  types, which every caller converts into its own named synth throw. The
+ *  exhaustively-keyed Record above stays the compile-time contract. */
+export function clickHouseInstanceSpec(instanceType) {
+    return Object.hasOwn(CLICKHOUSE_INSTANCE_SPECS, instanceType)
+        ? CLICKHOUSE_INSTANCE_SPECS[instanceType]
+        : undefined;
+}
 /** 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,
@@ -210,6 +257,7 @@ export const CLICKHOUSE_HOST_METRICS = {
     namespace: "CWAgent",
     memoryMetric: "mem_used_percent",
     diskMetric: "disk_used_percent",
+    diskFreeMetric: "disk_free_gib",
     asgDimension: "AutoScalingGroupName"
 };
 /** Shared secret generation options (all ClickHouse users share the same policy). */
@@ -295,3 +343,66 @@ export const BACKUP_TASK_MEMORY_MIB = 256;
 export const BACKUP_TASK_CPU_UNITS = 256;
 /** Backup object expiration: 14 days (retains 14 daily snapshots). */
 export const BACKUP_RETENTION_DAYS = 14;
+/** Scratch database the backup task restores into to prove the backup it just
+ *  wrote can be read back. Dropped on the way in and on the way out; never
+ *  queried by the application. */
+export const CLICKHOUSE_BACKUP_SCRATCH_DATABASE = "fjall_backup_verify";
+/** Multiple of the critical free-space floor the verify restore must leave
+ *  clear to proceed.
+ *
+ *  A full restore writes a second copy of the database onto the volume it is
+ *  verifying, so the check has to be bounded by the same quantity the disk
+ *  alarm pages on — otherwise the mechanism that protects the data is also
+ *  the mechanism most likely to fill the disk. Twice the floor rather than
+ *  once so a verify can never itself be the thing that pages: at exactly the
+ *  floor the restore would land the volume on the alarm threshold and hold it
+ *  there until the scratch database is dropped. */
+export const CLICKHOUSE_BACKUP_VERIFY_FREE_SPACE_MARGIN = 2;
+/** Backup task log markers. Distinct full tokens, because the CloudWatch
+ *  metric filters that read them match on substrings — a shared `BACKUP_`
+ *  stem would make the OK filter count the failures too. */
+export const CLICKHOUSE_BACKUP_VERIFY_OK_MARKER = "BACKUP_VERIFY_OK";
+export const CLICKHOUSE_BACKUP_VERIFY_FAILED_MARKER = "BACKUP_VERIFY_FAILED";
+export const CLICKHOUSE_BACKUP_VERIFY_SKIPPED_MARKER = "BACKUP_VERIFY_SKIPPED_FOR_SIZE";
+/** Bounds on the verify restore's wall-clock ceiling, in seconds.
+ *
+ *  Without a ceiling a hung RESTORE is the one backup failure with NO signal
+ *  at all: BACKUP_CREATED has already been emitted so the heartbeat is
+ *  satisfied, and the verify alarms count markers rather than their absence,
+ *  so a task that never finishes reports nothing. `timeout` turns that
+ *  silence into exit 124, which takes the same branch as a raised restore
+ *  and pages.
+ *
+ *  The ceiling scales with the volume (`clickHouseBackupVerifyTimeoutSeconds`
+ *  below) because the largest restore the free-space gate admits scales with
+ *  it: on the default 400 GiB the floor of one hour already covers it, but a
+ *  multi-TiB volume can legitimately need hours, and a fixed hour would page
+ *  FAILED on every healthy verify past the size where the restore outgrows
+ *  it. The 20-hour cap keeps a daily-scheduled verify from overlapping its
+ *  successor — two concurrent runs share the scratch database destructively,
+ *  so the bound must land inside the schedule interval. */
+export const CLICKHOUSE_BACKUP_VERIFY_MIN_TIMEOUT_SECONDS = 3600;
+export const CLICKHOUSE_BACKUP_VERIFY_MAX_TIMEOUT_SECONDS = 72000;
+/** Verify-restore timeout for a given data-volume size.
+ *
+ *  Worst case admitted by the free-space gate is a database of roughly half
+ *  the volume (it must fit beside itself). Writing that back at the gp3
+ *  baseline throughput (`CLICKHOUSE_EBS_THROUGHPUT_MBPS`) bounds the healthy
+ *  duration; doubled for read + merge overhead, then clamped to the
+ *  floor/cap pair above. At the 400 GiB default this resolves to the
+ *  one-hour floor, so the default behaviour is unchanged from the flat bound
+ *  it replaced.
+ *
+ *  Deliberately the BASELINE throughput, not the provisioned `throughputMbps`
+ *  prop. The volume's provisioned figure is an upper bound the instance may
+ *  not reach — an m7g.medium's EBS bandwidth sits under the gp3 baseline, and
+ *  no default-tier host reaches a provisioned 1,000 MiB/s — so a bound that
+ *  tightened with provisioning would page FAILED on healthy restores on
+ *  exactly the hosts customers start on. The baseline-derived bound is loose
+ *  on a provisioned volume, which only delays a hung-restore page; the cap
+ *  keeps that delay inside the schedule interval either way. */
+export function clickHouseBackupVerifyTimeoutSeconds(storageGb) {
+    const worstCaseRestoreMib = (storageGb / 2) * 1024;
+    const derived = Math.ceil((worstCaseRestoreMib / CLICKHOUSE_EBS_THROUGHPUT_MBPS) * 2);
+    return Math.min(CLICKHOUSE_BACKUP_VERIFY_MAX_TIMEOUT_SECONDS, Math.max(CLICKHOUSE_BACKUP_VERIFY_MIN_TIMEOUT_SECONDS, derived));
+}

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

@@ -23,6 +23,19 @@ export type ClickHouseSchemaAdmin = z.infer<typeof ClickHouseSchemaAdminSchema>;
  */
 export declare const ManagedPasswordNameSchema: z.ZodString;
 export type ManagedPasswordName = z.infer<typeof ManagedPasswordNameSchema>;
+/**
+ * One setting's constraint inside a profile's `<constraints>` block.
+ * `max`/`min` bound what a statement-level `SETTINGS` clause may set the
+ * value to; `readonly` forbids changing it at all. A statement that tries
+ * to exceed a bound fails with 452 SETTING_CONSTRAINT_VIOLATION instead of
+ * silently widening its own budget.
+ */
+export declare const SettingConstraintSchema: z.ZodObject<{
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    readonly: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export type SettingConstraint = z.infer<typeof SettingConstraintSchema>;
 /**
  * Per-profile resource-cap shape. Field names mirror the ClickHouse XML
  * element names (snake_case at the wire; camelCase here for TS ergonomics).
@@ -31,8 +44,18 @@ export type ManagedPasswordName = z.infer<typeof ManagedPasswordNameSchema>;
  * `renderUsersXml` maps each present field to the snake_case XML element
  * via `camelToSnakeCase`. Unknown fields are rejected by `.strict()` so a
  * typo at the consumer doesn't silently ship a no-op profile.
+ *
+ * `constraints` is the one non-scalar member: it renders as the profile's
+ * `<constraints>` block (keys camelCase here, snake_case at the wire, same
+ * as the scalar settings), making the named ceilings unraisable from a
+ * statement-level `SETTINGS` clause.
  */
 export declare const ProfileSpecSchema: z.ZodObject<{
+    constraints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        readonly: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>>>;
     maxThreads: z.ZodOptional<z.ZodNumber>;
     maxInsertThreads: z.ZodOptional<z.ZodNumber>;
     maxConcurrentQueriesForUser: z.ZodOptional<z.ZodNumber>;
@@ -62,6 +85,15 @@ export declare const ProfileSpecSchema: z.ZodObject<{
     materializeTtlAfterModify: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type ProfileSpec = z.infer<typeof ProfileSpecSchema>;
+/**
+ * Deep-frozen `ProfileSpec` — matches the `Object.freeze` depth of the
+ * derived defaults so the type system forbids what the runtime freeze
+ * throws on. `Readonly<ProfileSpec>` alone is shallow: it left the nested
+ * constraint objects typed mutable while frozen at runtime.
+ */
+export type FrozenProfileSpec = Readonly<Omit<ProfileSpec, "constraints">> & {
+    readonly constraints?: Readonly<Record<string, Readonly<SettingConstraint>>>;
+};
 /**
  * Re-exported for the construct's Stage 1 validation. Profile keys MUST
  * match the same lowercase snake_case shape as user names — they emit as
@@ -88,4 +120,4 @@ export declare const PROFILE_NAME_PATTERN: RegExp;
  * 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>>>;
+export declare const ClickHouseDefaultProfiles: Readonly<Record<string, FrozenProfileSpec>>;

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

@@ -9,6 +9,12 @@ import { deriveClickHouseDefaultProfiles } from "./clickhouseTuning.js";
  *  surfaces as a parse failure in the runner). Keeps the XML element names
  *  emit-safe (no escaping needed). */
 const NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+/** Constraint-record keys — camelCase (or snake_case) setting names with a
+ *  leading lowercase letter. Record keys are the one profile surface
+ *  `.strict()` cannot police, and they emit as XML element names via
+ *  `camelToSnakeCase`, so the emit-safety NAME_PATTERN guarantees for
+ *  user/profile names must come from the key schema itself here. */
+const CONSTRAINT_KEY_PATTERN = /^[a-z][a-zA-Z0-9_]*$/;
 /**
  * Schema-admin user — the framework's bootstrap-privileged identity that
  * customer SQL runs as. Owns DDL, schema migrations, GRANTs. Rendered into
@@ -41,6 +47,21 @@ export const ManagedPasswordNameSchema = z
     .min(1)
     .max(63)
     .regex(NAME_PATTERN, "Must be lowercase snake_case");
+/**
+ * One setting's constraint inside a profile's `<constraints>` block.
+ * `max`/`min` bound what a statement-level `SETTINGS` clause may set the
+ * value to; `readonly` forbids changing it at all. A statement that tries
+ * to exceed a bound fails with 452 SETTING_CONSTRAINT_VIOLATION instead of
+ * silently widening its own budget.
+ */
+export const SettingConstraintSchema = z
+    .object({
+    min: z.number().int().nonnegative().optional(),
+    max: z.number().int().nonnegative().optional(),
+    readonly: z.literal(true).optional()
+})
+    .strict()
+    .refine((c) => c.min !== undefined || c.max !== undefined || c.readonly === true, "A setting constraint must declare min, max or readonly");
 /**
  * Per-profile resource-cap shape. Field names mirror the ClickHouse XML
  * element names (snake_case at the wire; camelCase here for TS ergonomics).
@@ -49,9 +70,19 @@ export const ManagedPasswordNameSchema = z
  * `renderUsersXml` maps each present field to the snake_case XML element
  * via `camelToSnakeCase`. Unknown fields are rejected by `.strict()` so a
  * typo at the consumer doesn't silently ship a no-op profile.
+ *
+ * `constraints` is the one non-scalar member: it renders as the profile's
+ * `<constraints>` block (keys camelCase here, snake_case at the wire, same
+ * as the scalar settings), making the named ceilings unraisable from a
+ * statement-level `SETTINGS` clause.
  */
 export const ProfileSpecSchema = z
     .object({
+    constraints: z
+        .record(z
+        .string()
+        .regex(CONSTRAINT_KEY_PATTERN, "Constraint keys must be camelCase (or snake_case) setting names"), SettingConstraintSchema)
+        .optional(),
     maxThreads: z.number().int().positive().optional(),
     maxInsertThreads: z.number().int().positive().optional(),
     maxConcurrentQueriesForUser: z.number().int().positive().optional(),

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

@@ -0,0 +1,58 @@
+/**
+ * Default critical free-space floor for a volume of `storageGb`.
+ *
+ * The larger of the absolute floor and a share of the volume — neither alone
+ * is right at both ends of the size range. See
+ * `CLICKHOUSE_DISK_FREE_CRITICAL_GIB` for the reasoning; rounded to whole GiB
+ * so the alarm description reads as a number an operator would say out loud.
+ */
+export declare function defaultDiskFreeCriticalGib(storageGb: number): number;
+export interface ClickHouseStorageResolution {
+    /** EBS volume size in GiB, defaulted and validated. */
+    storageGb: number;
+    /** Critical free-space floor in GiB, defaulted and validated. */
+    diskFreeCriticalGib: number;
+}
+/**
+ * Resolve and validate the two values that together decide when a ClickHouse
+ * volume is considered nearly full.
+ *
+ * They are validated as a PAIR because neither is checkable alone: a 100 GiB
+ * volume is fine until someone sets a 60 GiB free-space floor, and a 60 GiB
+ * floor is fine until someone shrinks the volume under it. Split across two
+ * validators, each would pass on its own and the deployed stack would carry a
+ * critical alarm that can never leave ALARM.
+ *
+ * Throws rather than annotating: both are numbers the caller typed, and a
+ * warning on a synth that still emits a permanently-breaching pager is worse
+ * than a failed synth with the arithmetic in the message.
+ */
+export declare function resolveClickHouseStorage(storageGb: number | undefined, diskFreeCriticalGib: number | undefined): ClickHouseStorageResolution;
+export interface ClickHouseVolumePerformanceInput {
+    /** Validated volume size from `resolveClickHouseStorage` — the IOPS ceiling
+     *  is a function of it. */
+    storageGb: number;
+    iops: number | undefined;
+    throughputMbps: number | undefined;
+}
+export interface ClickHouseVolumePerformanceResolution {
+    /** Provisioned IOPS, defaulted and validated. */
+    iops: number;
+    /** Provisioned throughput in MiB/s, defaulted and validated. */
+    throughputMbps: number;
+}
+/**
+ * Resolve and validate the gp3 performance pair for the data volume.
+ *
+ * Same shape as `resolveClickHouseStorage`: each value has a band of its own,
+ * but EBS also constrains them against each other and against the size —
+ * throughput needs four IOPS per MiB/s, and IOPS needs a GiB per 500 — so a
+ * value legal on its own is rejected by CreateVolume mid-deploy once its
+ * partner is in view. Checking the pair at synth turns that rollback into a
+ * message that names the figure the other half needs.
+ *
+ * Both checks are the ones aws-cdk-lib's `Volume` applies too; this resolver
+ * exists so the failure names `ClickHouseDatabase` props and their cure
+ * rather than a CDK-internal field.
+ */
+export declare function resolveClickHouseVolumePerformance(input: ClickHouseVolumePerformanceInput): ClickHouseVolumePerformanceResolution;

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

@@ -0,0 +1,87 @@
+import { CLICKHOUSE_DISK_FREE_CRITICAL_GIB, CLICKHOUSE_DISK_FREE_CRITICAL_SHARE, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS, CLICKHOUSE_MAX_IOPS, CLICKHOUSE_MAX_IOPS_PER_GB, CLICKHOUSE_MAX_STORAGE_GB, CLICKHOUSE_MAX_THROUGHPUT_MBPS, CLICKHOUSE_MIN_IOPS, CLICKHOUSE_MIN_STORAGE_GB, CLICKHOUSE_MIN_THROUGHPUT_MBPS } from "./clickhouseConstants.js";
+/**
+ * Largest share of the volume the critical free-space floor may claim. A
+ * floor at half the disk would page from the day the cluster passed 50 %
+ * used, which is a capacity-planning fact, not an incident; at a fifth, the
+ * alarm means what its description says — the disk is nearly gone.
+ */
+const MAX_FLOOR_SHARE_OF_VOLUME = 0.2;
+/**
+ * Default critical free-space floor for a volume of `storageGb`.
+ *
+ * The larger of the absolute floor and a share of the volume — neither alone
+ * is right at both ends of the size range. See
+ * `CLICKHOUSE_DISK_FREE_CRITICAL_GIB` for the reasoning; rounded to whole GiB
+ * so the alarm description reads as a number an operator would say out loud.
+ */
+export function defaultDiskFreeCriticalGib(storageGb) {
+    return Math.max(CLICKHOUSE_DISK_FREE_CRITICAL_GIB, Math.round(storageGb * CLICKHOUSE_DISK_FREE_CRITICAL_SHARE));
+}
+/**
+ * Resolve and validate the two values that together decide when a ClickHouse
+ * volume is considered nearly full.
+ *
+ * They are validated as a PAIR because neither is checkable alone: a 100 GiB
+ * volume is fine until someone sets a 60 GiB free-space floor, and a 60 GiB
+ * floor is fine until someone shrinks the volume under it. Split across two
+ * validators, each would pass on its own and the deployed stack would carry a
+ * critical alarm that can never leave ALARM.
+ *
+ * Throws rather than annotating: both are numbers the caller typed, and a
+ * warning on a synth that still emits a permanently-breaching pager is worse
+ * than a failed synth with the arithmetic in the message.
+ */
+export function resolveClickHouseStorage(storageGb, diskFreeCriticalGib) {
+    const size = storageGb ?? CLICKHOUSE_EBS_VOLUME_SIZE_GB;
+    if (!Number.isInteger(size) ||
+        size < CLICKHOUSE_MIN_STORAGE_GB ||
+        size > CLICKHOUSE_MAX_STORAGE_GB) {
+        throw new Error(`ClickHouseDatabase: storageGb must be an integer between ${CLICKHOUSE_MIN_STORAGE_GB} and ${CLICKHOUSE_MAX_STORAGE_GB} GiB; got ${size}.`);
+    }
+    const floor = diskFreeCriticalGib ?? defaultDiskFreeCriticalGib(size);
+    if (!Number.isFinite(floor) || floor <= 0) {
+        throw new Error(`ClickHouseDatabase: alarms.diskFreeCriticalGib must be a positive number of GiB; got ${floor}.`);
+    }
+    const ceiling = size * MAX_FLOOR_SHARE_OF_VOLUME;
+    if (floor > ceiling) {
+        throw new Error(`ClickHouseDatabase: alarms.diskFreeCriticalGib (${floor} GiB) exceeds a fifth of storageGb (${size} GiB → ${ceiling} GiB). A floor that large keeps the disk-critical alarm in ALARM on a healthy cluster; raise storageGb or lower the floor.`);
+    }
+    return { storageGb: size, diskFreeCriticalGib: floor };
+}
+/**
+ * Resolve and validate the gp3 performance pair for the data volume.
+ *
+ * Same shape as `resolveClickHouseStorage`: each value has a band of its own,
+ * but EBS also constrains them against each other and against the size —
+ * throughput needs four IOPS per MiB/s, and IOPS needs a GiB per 500 — so a
+ * value legal on its own is rejected by CreateVolume mid-deploy once its
+ * partner is in view. Checking the pair at synth turns that rollback into a
+ * message that names the figure the other half needs.
+ *
+ * Both checks are the ones aws-cdk-lib's `Volume` applies too; this resolver
+ * exists so the failure names `ClickHouseDatabase` props and their cure
+ * rather than a CDK-internal field.
+ */
+export function resolveClickHouseVolumePerformance(input) {
+    const iops = input.iops ?? CLICKHOUSE_EBS_IOPS;
+    if (!Number.isInteger(iops) ||
+        iops < CLICKHOUSE_MIN_IOPS ||
+        iops > CLICKHOUSE_MAX_IOPS) {
+        throw new Error(`ClickHouseDatabase: iops must be an integer between ${CLICKHOUSE_MIN_IOPS} and ${CLICKHOUSE_MAX_IOPS}; got ${iops}.`);
+    }
+    const iopsCeilingForSize = input.storageGb * CLICKHOUSE_MAX_IOPS_PER_GB;
+    if (iops > iopsCeilingForSize) {
+        throw new Error(`ClickHouseDatabase: iops (${iops}) exceeds ${CLICKHOUSE_MAX_IOPS_PER_GB} per GiB of storageGb (${input.storageGb} GiB → ${iopsCeilingForSize}). EBS rejects the volume; raise storageGb to at least ${Math.ceil(iops / CLICKHOUSE_MAX_IOPS_PER_GB)} GiB or lower iops.`);
+    }
+    const throughputMbps = input.throughputMbps ?? CLICKHOUSE_EBS_THROUGHPUT_MBPS;
+    if (!Number.isInteger(throughputMbps) ||
+        throughputMbps < CLICKHOUSE_MIN_THROUGHPUT_MBPS ||
+        throughputMbps > CLICKHOUSE_MAX_THROUGHPUT_MBPS) {
+        throw new Error(`ClickHouseDatabase: throughputMbps must be an integer between ${CLICKHOUSE_MIN_THROUGHPUT_MBPS} and ${CLICKHOUSE_MAX_THROUGHPUT_MBPS} MiB/s; got ${throughputMbps}.`);
+    }
+    const iopsNeeded = throughputMbps * CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS;
+    if (iops < iopsNeeded) {
+        throw new Error(`ClickHouseDatabase: throughputMbps (${throughputMbps} MiB/s) needs ${CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS} IOPS per MiB/s, so at least ${iopsNeeded} iops; got ${iops}. EBS rejects the volume; raise iops to ${iopsNeeded} or lower throughputMbps to ${Math.floor(iops / CLICKHOUSE_IOPS_PER_THROUGHPUT_MBPS)}.`);
+    }
+    return { iops, throughputMbps };
+}