@fjall/components-infrastructure 0.96.0 → 0.99.3

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

@@ -0,0 +1,371 @@
+import { CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_PROMETHEUS_PORT, clickHousePasswordSha256Snippet } from "./clickhouseConstants.js";
+import { renderUsersXml } from "./clickhouseXmlRenderer.js";
+export function generateServerConfigXml(options) {
+    const { backupBucketName, backupBucketRegion, coldTier } = options;
+    const storageBlock = coldTier !== undefined
+        ? `    <storage_configuration>
+        <!-- Same CH 26 rule as the no-cold-tier branch: a <local_ssd> disk
+             whose path equals the global <path> trips UNKNOWN_ELEMENT_IN_CONFIG
+             at boot. Use the implicit <default> disk for hot tier; only S3
+             cold needs an explicit <disks> entry. -->
+        <disks>
+            <s3_cold>
+                <type>s3</type>
+                <endpoint>https://${coldTier.bucketName}.s3.${coldTier.region}.amazonaws.com/cold/</endpoint>
+                <use_environment_credentials>true</use_environment_credentials>
+                <metadata_path>/var/lib/clickhouse/disks/s3_cold/</metadata_path>
+            </s3_cold>
+        </disks>
+        <policies>
+            <tiered>
+                <volumes>
+                    <hot>
+                        <disk>default</disk>
+                    </hot>
+                    <cold>
+                        <disk>s3_cold</disk>
+                    </cold>
+                </volumes>
+                <move_factor>0.05</move_factor>
+            </tiered>
+            <local_only>
+                <volumes>
+                    <default>
+                        <disk>default</disk>
+                    </default>
+                </volumes>
+            </local_only>
+        </policies>
+    </storage_configuration>`
+        : `    <storage_configuration>
+        <!-- CH 26.x reserves the implicit <default> disk and rejects any
+             explicit <disks><default>...</default></disks> override whose
+             resolved path equals the global <path>:
+               "Disk path ('/var/lib/clickhouse/') cannot be equal to <path>.
+                Use <default> disk instead. (UNKNOWN_ELEMENT_IN_CONFIG)"
+             So we drop the <disks> block entirely; policies referencing
+             <disk>default</disk> resolve to CH's built-in default. -->
+        <policies>
+            <!-- Single-volume tiered policy: 11 schema tables hardcode
+                 storage_policy='tiered'. -->
+            <tiered>
+                <volumes>
+                    <hot>
+                        <disk>default</disk>
+                    </hot>
+                </volumes>
+            </tiered>
+            <local_only>
+                <volumes>
+                    <default>
+                        <disk>default</disk>
+                    </default>
+                </volumes>
+            </local_only>
+        </policies>
+    </storage_configuration>`;
+    const backupEndpointBlock = `    <s3>
+        <backup_endpoint>
+            <endpoint>https://${backupBucketName}.s3.${backupBucketRegion}.amazonaws.com/</endpoint>
+            <use_environment_credentials>true</use_environment_credentials>
+        </backup_endpoint>
+    </s3>`;
+    return `<clickhouse>
+    <logger>
+        <level>warning</level>
+        <log>/var/log/clickhouse-server/clickhouse-server.log</log>
+        <errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog>
+        <size>100M</size>
+        <count>3</count>
+        <!-- Mirror to stderr so the awslogs driver captures startup +
+             crash banners. File-only logs die with the container. -->
+        <console>1</console>
+    </logger>
+    <!-- Bind to all IPv4 addresses. CH 26 defaults its listener set to
+         include \`[::1]\` (IPv6 loopback). Under awsvpc that fails because
+         the ENI has no IPv6 loopback assigned (errno 99 EADDRNOTAVAIL on
+         8123 / 9000 / 9004 / 9005 / 9009 / 9363); under host mode it would
+         work, but explicit beats implicit and keeps the listener identical
+         across network modes. -->
+    <listen_host>0.0.0.0</listen_host>
+    <!-- m7g.medium tuning philosophy: 1 vCPU sustained / 4 GB / 3 GB container.
+         Single-thread CPU has no headroom (raising max_threads beyond 1 just
+         oversubscribes the kernel scheduler), so we trade RAM for CPU — size
+         caches generously so dashboard reads hit cache rather than rescanning,
+         and let a single query use most of the budget if needed.
+         Re-tune these in lockstep when DEFAULT_CLICKHOUSE_INSTANCE_TYPE moves
+         to a larger box. -->
+    <!-- 0.75 ratio gives the kernel ~750 MB cushion on the 3 GB cgroup for
+         CH's untracked allocations (libc allocator, executable image, malloc
+         fragmentation, jemalloc virtual reservations on ARM64). The default
+         0.9 left only ~300 MB and OOM-killed the process at boot when cache
+         + thread init pushed the cgroup over the limit (exit 137 in CW).
+         Computed at runtime from the cgroup limit so it tracks instance size
+         when DEFAULT_CLICKHOUSE_INSTANCE_TYPE moves to a larger box. -->
+    <max_server_memory_usage_to_ram_ratio>0.75</max_server_memory_usage_to_ram_ratio>
+    <!-- Per-query caps (max_memory_usage, max_bytes_before_external_sort,
+         max_bytes_before_external_group_by) live in the profile blocks of
+         users.xml — ClickHouse 26.3.10 rejects them at top level with
+         UNKNOWN_ELEMENT_IN_CONFIG. The default localhost user inherits
+         ClickHouse's built-in defaults; workload users (app_writer,
+         audit_writer, backup_reader, schema_admin) carry explicit caps. -->
+    <!-- 384 MB mark cache + 128 MB index mark cache. CH counts these against
+         max_server_memory_usage, so the read-cache footprint is 512 MB total
+         (~17% of the budget). On a single-tenant dashboard workload this
+         pays back fast — same queries repeat, mark hits avoid index re-scans. -->
+    <mark_cache_size>402653184</mark_cache_size>
+    <index_mark_cache_size>134217728</index_mark_cache_size>
+    <!-- Filesystem page cache handles uncompressed-block warmth on the
+         host side; an in-CH uncompressed cache would just duplicate it. -->
+    <uncompressed_cache_size>0</uncompressed_cache_size>
+    <!-- Sized for m7g.medium (1 vCPU sustained). 4 concurrent queries is the
+         sweet spot: enough headroom for the OPTIMIZE FINAL sidecar + a single
+         dashboard read + one async insert + one ad-hoc, but low enough that
+         context switching does not dominate at the kernel scheduler level.
+         Bump in lockstep with instance size if DEFAULT_CLICKHOUSE_INSTANCE_TYPE
+         moves to a >=2 vCPU host. -->
+    <max_concurrent_queries>4</max_concurrent_queries>
+    <background_pool_size>2</background_pool_size>
+    <background_schedule_pool_size>2</background_schedule_pool_size>
+    <background_merges_mutations_concurrency_ratio>2</background_merges_mutations_concurrency_ratio>
+    <background_move_pool_size>1</background_move_pool_size>
+    <background_fetches_pool_size>1</background_fetches_pool_size>
+    <background_message_broker_schedule_pool_size>1</background_message_broker_schedule_pool_size>
+    <merge_tree>
+        <max_suspicious_broken_parts>5</max_suspicious_broken_parts>
+        <parts_to_delay_insert>150</parts_to_delay_insert>
+        <parts_to_throw_insert>300</parts_to_throw_insert>
+        <!-- ClickHouse 26.3.10 sanity-checks the free-pool thresholds against
+             background_pool_size * background_merges_mutations_concurrency_ratio
+             (= 2 * 2 = 4 here). The defaults (20 / 8 / 25) all exceed 4 and
+             trip BAD_ARGUMENTS at startup on a 1 vCPU m7g.medium. Lower each
+             to 1 so a mutation/merge/optimise can begin as soon as one pool
+             slot is free — appropriate for the small instance footprint. -->
+        <number_of_free_entries_in_pool_to_execute_mutation>1</number_of_free_entries_in_pool_to_execute_mutation>
+        <number_of_free_entries_in_pool_to_lower_max_size_of_merge>1</number_of_free_entries_in_pool_to_lower_max_size_of_merge>
+        <number_of_free_entries_in_pool_to_execute_optimize_entire_partition>1</number_of_free_entries_in_pool_to_execute_optimize_entire_partition>
+    </merge_tree>
+    <http_port>${CLICKHOUSE_HTTP_PORT}</http_port>
+    <custom_settings_prefixes>current_</custom_settings_prefixes>
+    <!-- HTTP keep-alive window. Must exceed @clickhouse/client idle_socket_ttl (15 s)
+         so the client always closes the socket first. Prevents ECONNRESET on reuse. -->
+    <keep_alive_timeout>30</keep_alive_timeout>
+    <query_log>
+        <database>system</database>
+        <table>query_log</table>
+        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
+        <ttl>event_date + INTERVAL 14 DAY DELETE</ttl>
+    </query_log>
+    <!-- All system log tables need bounded retention on 80GB EBS (mirror query_log's 14-day policy). -->
+    <asynchronous_metric_log>
+        <database>system</database>
+        <table>asynchronous_metric_log</table>
+        <ttl>event_date + INTERVAL 14 DAY DELETE</ttl>
+    </asynchronous_metric_log>
+    <metric_log>
+        <database>system</database>
+        <table>metric_log</table>
+        <ttl>event_date + INTERVAL 14 DAY DELETE</ttl>
+    </metric_log>
+    <part_log>
+        <database>system</database>
+        <table>part_log</table>
+        <ttl>event_date + INTERVAL 14 DAY DELETE</ttl>
+    </part_log>
+    <error_log>
+        <database>system</database>
+        <table>error_log</table>
+        <ttl>event_date + INTERVAL 14 DAY DELETE</ttl>
+    </error_log>
+${storageBlock}
+${backupEndpointBlock}
+    <!-- 256 MB query cache. Single-tenant dashboard pattern means the same
+         queries repeat at fixed cadences (5/15min refresh, manual reloads);
+         a hit returns in microseconds instead of re-scanning. Sized generously
+         relative to other caches because the workload pattern is uniquely
+         cache-friendly. -->
+    <query_cache>
+        <max_size_in_bytes>268435456</max_size_in_bytes>
+        <max_entries>1024</max_entries>
+        <max_entry_size_in_bytes>1048576</max_entry_size_in_bytes>
+    </query_cache>
+    <prometheus>
+        <endpoint>/metrics</endpoint>
+        <port>${CLICKHOUSE_PROMETHEUS_PORT}</port>
+        <metrics>true</metrics>
+        <events>true</events>
+        <asynchronous_metrics>true</asynchronous_metrics>
+    </prometheus>
+    <query_thread_log remove="1"/>
+    <opentelemetry_span_log remove="1"/>
+    <processors_profile_log remove="1"/>
+</clickhouse>`;
+}
+/**
+ * Construct-side thin wrapper around `renderUsersXml`. Always emits the
+ * prod shape: loopback-only `<default>` user, `from_env=` sha256 password
+ * directives. The container entrypoint wrapper (see
+ * `buildClickHouseEntrypointWrapper`) resolves the `USER_<NAME>_SHA256` env
+ * vars at server start from `sha256sum` of each ECS-injected plaintext.
+ *
+ * TODO secondary CIDRs: props.vpc.vpcCidrBlock returns only the primary CIDR.
+ * BYOC consumers with multi-CIDR VPCs need a per-CIDR `<ip>` emitter — see
+ * designs/2026-05-12-clickhouse-construct-leak-fixes.md § "Phase 1.5".
+ */
+export function generateUsersConfigXml(options) {
+    return renderUsersXml({
+        schemaAdmin: options.schemaAdmin,
+        profiles: options.profiles,
+        vpcCidr: options.vpcCidr,
+        defaultUserAccess: "loopback-only",
+        passwordSource: { mode: "from_env" }
+    });
+}
+// EC2 LaunchTemplate UserData is capped at 16,384 bytes; the pretty-printed
+// source overflows once XML/bash comments are included.
+function compactUserDataScript(script) {
+    return script
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .split("\n")
+        .map((line) => {
+        const trimmed = line.replace(/\s+$/, "").replace(/^\s+/, "");
+        if (trimmed.startsWith("#") && !trimmed.startsWith("#!"))
+            return "";
+        return trimmed;
+    })
+        .filter((line, index, all) => line !== "" || (index > 0 && all[index - 1] !== ""))
+        .join("\n");
+}
+/**
+ * Build the EC2 user-data script that bootstraps ClickHouse on the ASG instance.
+ *
+ * Per design D27 + D12: cold-storage and backups authenticate to S3 via IAM
+ * (the EC2 instance role's grants), not via env-var access keys. The rendered
+ * output contains zero `R2_*` / `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`
+ * references — `<use_environment_credentials>true</use_environment_credentials>`
+ * tells ClickHouse to use the IMDS-derived credentials instead.
+ */
+export function buildClickHouseUserData(options) {
+    const serverConfigXml = generateServerConfigXml(options);
+    const script = `#!/bin/bash
+set -euo pipefail
+
+DEVICE="${CLICKHOUSE_EBS_DEVICE_NAME}"
+MOUNT_POINT="${CLICKHOUSE_DATA_MOUNT_PATH}"
+
+# Host kernel tuning for ClickHouse. Applied before the container starts so
+# the settings are inherited via the docker daemon.
+#
+# 1. Transparent Huge Pages → madvise. ClickHouse explicitly recommends
+#    'madvise' over 'always': 'always' triggers latency spikes from khugepaged
+#    rewriting hot pages; 'never' loses the THP win on large allocations
+#    (mark/group-by hash tables). 'madvise' is the documented sweet spot.
+#    https://clickhouse.com/docs/operations/tips#transparenthugepages
+echo madvise > /sys/kernel/mm/transparent_hugepage/enabled || true
+echo madvise > /sys/kernel/mm/transparent_hugepage/defrag || true
+
+# 2. Raise file-descriptor ceiling for the docker daemon (and therefore the
+#    CH container). CH's default config requests 500K+ FDs for distributed
+#    table caches, S3 backup readers, and per-tenant connection pools; the
+#    default 1024 ulimit causes 'too many open files' under load. Set the
+#    systemd override before docker starts so the limit is in place when the
+#    ECS agent launches the CH task.
+mkdir -p /etc/systemd/system/docker.service.d
+cat > /etc/systemd/system/docker.service.d/override.conf << 'DOCKEROVERRIDE'
+[Service]
+LimitNOFILE=1048576
+LimitNPROC=unlimited
+DOCKEROVERRIDE
+systemctl daemon-reload
+systemctl restart docker || true
+
+# Wait for the EBS volume to be attached (up to 60 seconds)
+for i in $(seq 1 60); do
+  if [ -b "$DEVICE" ]; then
+    break
+  fi
+  sleep 1
+done
+
+if [ ! -b "$DEVICE" ]; then
+  echo "ERROR: EBS volume $DEVICE not found after 60 seconds" >&2
+  exit 1
+fi
+
+# Format only if not already formatted (idempotent)
+if ! blkid "$DEVICE" | grep -q ext4; then
+  mkfs.ext4 -m 0 "$DEVICE"
+fi
+
+# Mount
+mkdir -p "$MOUNT_POINT"
+mount "$DEVICE" "$MOUNT_POINT"
+
+# Persist across reboots
+if ! grep -q "$MOUNT_POINT" /etc/fstab; then
+  echo "$DEVICE $MOUNT_POINT ext4 defaults,nofail 0 2" >> /etc/fstab
+fi
+
+# Write ClickHouse server config (memory limits, storage policies, Prometheus)
+mkdir -p "$MOUNT_POINT/${CLICKHOUSE_CONFIG_SUBDIR}"
+cat > "$MOUNT_POINT/${CLICKHOUSE_CONFIG_SUBDIR}/fjall.xml" << 'CONFIGEOF'
+${serverConfigXml}
+CONFIGEOF
+
+# Pull ClickHouse users config from S3 (BucketDeployment uploads it to
+# s3://<backup-bucket>/config/users.d.xml at synth time). Retry up to 90×2s
+# to absorb BucketDeployment Lambda cold-start (~60-120s observed).
+mkdir -p "$MOUNT_POINT/${CLICKHOUSE_USERS_SUBDIR}"
+USERS_CONFIG_RETRIEVED=0
+for i in $(seq 1 90); do
+  if aws s3 cp "s3://${options.backupBucketName}/config/users.d.xml" \\
+     "$MOUNT_POINT/${CLICKHOUSE_USERS_SUBDIR}/fjall.xml.new" 2>/dev/null; then
+    mv "$MOUNT_POINT/${CLICKHOUSE_USERS_SUBDIR}/fjall.xml.new" \\
+       "$MOUNT_POINT/${CLICKHOUSE_USERS_SUBDIR}/fjall.xml"
+    USERS_CONFIG_RETRIEVED=1
+    break
+  fi
+  sleep 2
+done
+if [ "$USERS_CONFIG_RETRIEVED" != "1" ]; then
+  echo "ERROR: users.d/fjall.xml not retrieved from s3://${options.backupBucketName}/config/users.d.xml after 180s" >&2
+  exit 1
+fi
+
+chown -R 101:101 "$MOUNT_POINT"
+`;
+    return compactUserDataScript(script);
+}
+/**
+ * Build the bash wrapper executed as the CH container's entrypoint.
+ *
+ * The CH server reads `users.d/fjall.xml`, which carries
+ * `<password_sha256_hex from_env="USER_<NAME>_SHA256"/>` directives, and
+ * resolves those `from_env=` lookups against the server process's
+ * environment at startup. ECS injects the plaintext password for each user
+ * as `USER_<NAME>_PASSWORD` via `secretsImport`; this wrapper derives the
+ * matching `USER_<NAME>_SHA256` env var (via the same SHA-256 pipeline as
+ * the EC2 user-data loop in `buildClickHouseUserData()`) and then `exec`s
+ * the stock CH entrypoint so the server inherits the derived vars after
+ * the gosu privilege drop.
+ *
+ * Pure-bash iteration via `${!USER_@}` avoids spawning `env`/`grep` and
+ * guarantees only ECS-injected secrets are considered. The `case` filter
+ * skips any future `USER_*_HOST`/`USER_*_PORT` envs that don't match the
+ * password convention.
+ */
+export function buildClickHouseEntrypointWrapper() {
+    // `pipefail` so `printf | sha256sum | awk` aborts on mid-pipeline failure
+    // instead of exporting an empty hash; parity with the SSM live-reload script.
+    return `set -euo pipefail
+for var in "\${!USER_@}"; do
+  case "$var" in
+    *_PASSWORD)
+      base=\${var%_PASSWORD}
+      hash=$(${clickHousePasswordSha256Snippet('"${!var}"')})
+      export "\${base}_SHA256=$hash"
+      ;;
+  esac
+done
+exec /entrypoint.sh`;
+}

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

@@ -0,0 +1,56 @@
+import type { ClickHouseSchemaAdmin, ProfileSpec } from "./clickhouseSchemas.js";
+/**
+ * Pure helper for rendering the `users.d/fjall.xml` ClickHouse users config.
+ *
+ * Two callers, two shapes:
+ *  - **Prod** (construct): `passwordSource: { mode: "from_env" }`,
+ *    `defaultUserAccess: "loopback-only"`. The XML emits
+ *    `<password_sha256_hex from_env="USER_<NAME>_SHA256"/>` directives; the
+ *    EC2 user-data resolves these from env vars set by computing `sha256sum`
+ *    of each plaintext fetched from Secrets Manager at boot.
+ *  - **Dev** (gen-script): `passwordSource: { mode: "literal-hashes", hashes }`,
+ *    `defaultUserAccess: "permissive"`. The XML embeds the pre-computed
+ *    sha256 hex literally; the `<default>` user accepts RFC1918 + loopback so
+ *    docker-compose sidecars on the bridge network can authenticate.
+ *
+ * Only the schema-admin user is emitted into the XML — managed-password
+ * workload users are created at runtime by the migration helper and bind
+ * their profiles via customer SQL. The schema admin's profile is bound here,
+ * in the XML, because it must be live before any SQL runs.
+ */
+export interface RenderUsersXmlOptions {
+    schemaAdmin: ClickHouseSchemaAdmin;
+    profiles: Record<string, ProfileSpec>;
+    /**
+     * Primary VPC CIDR block — emitted into the schema admin's `<networks><ip>`.
+     * In prod the construct passes `props.vpc.vpcCidrBlock` (a CDK Token that
+     * resolves at deploy time); in dev the gen-script passes `"0.0.0.0/0"`
+     * because dev access is gated by `defaultUserAccess: "permissive"` on the
+     * `<default>` user.
+     */
+    vpcCidr: string;
+    defaultUserAccess: "loopback-only" | "permissive";
+    passwordSource: {
+        mode: "from_env";
+    } | {
+        mode: "literal-hashes";
+        hashes: Record<string, string>;
+    };
+}
+/**
+ * Pure renderer. Validates that `schemaAdmin.profile` exists in `profiles`,
+ * and (in literal-hashes mode) that the schema admin has a hash entry. No
+ * CDK dependency — the construct passes `vpc.vpcCidrBlock` as a string-valued
+ * Token that resolves through CFN at deploy time.
+ *
+ * **Schema-admin-only emission.** Only the schema admin lands in the XML.
+ * Managed-password workload users are created at runtime by the migration
+ * helper (`@fjall/clickhouse-migrations § provisionUsersFromEnv`) — they
+ * authenticate via plaintext from `USER_<NAME>_PASSWORD` env vars at runtime
+ * and bind their profiles via customer SQL.
+ *
+ * Quotas are SQL-managed. No `<quotas>` block is emitted — the schema admin
+ * references CH's built-in `default` quota at boot; SQL-defined quotas take
+ * over post-migration.
+ */
+export declare function renderUsersXml(opts: RenderUsersXmlOptions): string;

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

@@ -0,0 +1,112 @@
+function camelToSnakeCase(input) {
+    return input.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase());
+}
+function renderProfileSpec(spec) {
+    const lines = [];
+    for (const [key, value] of Object.entries(spec)) {
+        if (value === undefined)
+            continue;
+        const xmlName = camelToSnakeCase(key);
+        const xmlValue = typeof value === "boolean" ? (value ? "1" : "0") : String(value);
+        lines.push(`            <${xmlName}>${xmlValue}</${xmlName}>`);
+    }
+    return lines.join("\n");
+}
+function renderDefaultUserBlock(access) {
+    if (access === "loopback-only") {
+        return `        <default>
+            <networks>
+                <ip>127.0.0.1</ip>
+                <ip>::1</ip>
+            </networks>
+        </default>`;
+    }
+    return `        <default>
+            <password></password>
+            <networks>
+                <ip>127.0.0.1</ip>
+                <ip>::1</ip>
+                <ip>172.16.0.0/12</ip>
+                <ip>10.0.0.0/8</ip>
+                <ip>192.168.0.0/16</ip>
+            </networks>
+            <access_management>1</access_management>
+        </default>`;
+}
+function renderPasswordElement(name, passwordSource) {
+    if (passwordSource.mode === "from_env") {
+        const envName = `USER_${name.toUpperCase()}_SHA256`;
+        return `<password_sha256_hex from_env="${envName}"/>`;
+    }
+    const hash = passwordSource.hashes[name];
+    if (hash === undefined) {
+        throw new Error(`renderUsersXml: literal-hashes mode missing hash for user '${name}'`);
+    }
+    return `<password_sha256_hex>${hash}</password_sha256_hex>`;
+}
+function renderSchemaAdminBlock(schemaAdmin, vpcCidr, passwordSource) {
+    const passwordElement = renderPasswordElement(schemaAdmin.name, passwordSource);
+    return `        <${schemaAdmin.name}>
+            ${passwordElement}
+            <networks>
+                <ip>${vpcCidr}</ip>
+            </networks>
+            <profile>${schemaAdmin.profile}</profile>
+            <quota>default</quota>
+            <access_management>1</access_management>
+            <named_collection_control>1</named_collection_control>
+            <show_named_collections>1</show_named_collections>
+            <show_named_collections_secrets>1</show_named_collections_secrets>
+        </${schemaAdmin.name}>`;
+}
+function renderProfileBlock(name, spec) {
+    const body = renderProfileSpec(spec);
+    return `        <${name}>
+${body}
+        </${name}>`;
+}
+/**
+ * Pure renderer. Validates that `schemaAdmin.profile` exists in `profiles`,
+ * and (in literal-hashes mode) that the schema admin has a hash entry. No
+ * CDK dependency — the construct passes `vpc.vpcCidrBlock` as a string-valued
+ * Token that resolves through CFN at deploy time.
+ *
+ * **Schema-admin-only emission.** Only the schema admin lands in the XML.
+ * Managed-password workload users are created at runtime by the migration
+ * helper (`@fjall/clickhouse-migrations § provisionUsersFromEnv`) — they
+ * authenticate via plaintext from `USER_<NAME>_PASSWORD` env vars at runtime
+ * and bind their profiles via customer SQL.
+ *
+ * Quotas are SQL-managed. No `<quotas>` block is emitted — the schema admin
+ * references CH's built-in `default` quota at boot; SQL-defined quotas take
+ * over post-migration.
+ */
+export function renderUsersXml(opts) {
+    if (!(opts.schemaAdmin.profile in opts.profiles)) {
+        throw new Error(`renderUsersXml: schemaAdmin '${opts.schemaAdmin.name}' references unknown profile '${opts.schemaAdmin.profile}'. ` +
+            `Known profiles: ${Object.keys(opts.profiles).join(", ")}`);
+    }
+    const defaultBlock = renderDefaultUserBlock(opts.defaultUserAccess);
+    const adminBlock = renderSchemaAdminBlock(opts.schemaAdmin, opts.vpcCidr, opts.passwordSource);
+    const defaultProfileBlock = `        <default>
+            <optimize_move_to_prewhere>1</optimize_move_to_prewhere>
+            <!-- ALTER TABLE ... MODIFY TTL on a 30-day-partitioned table would otherwise
+                 trigger an immediate full-table rewrite (default = 1). On the m7g.medium
+                 box that's a merge-pool starvation event. Keep TTL changes lazy: parts
+                 re-evaluate TTL on their next natural merge, no forced rewrite. -->
+            <materialize_ttl_after_modify>0</materialize_ttl_after_modify>
+        </default>`;
+    const profileBlocks = Object.entries(opts.profiles)
+        .map(([name, spec]) => renderProfileBlock(name, spec))
+        .join("\n");
+    return `<clickhouse>
+    <users>
+${defaultBlock}
+${adminBlock}
+    </users>
+    <profiles>
+${defaultProfileBlock}
+${profileBlocks}
+    </profiles>
+</clickhouse>`;
+}

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

@@ -5,7 +5,7 @@ import { Construct } from "constructs";
 import { Secret } from "../secrets/index.js";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import { type RdsAlarmThresholds } from "../monitoring/index.js";
-import { type EngineConfig, type ProxyConfig, type CredentialsConfig, type AuroraEncryptionConfig, type AuroraWriterConfig, type AuroraReadersConfig, type DatabaseInsightsConfig } from "../../../utils/databaseTypes.js";
+import { type EngineConfig, type ProxyConfig, type CredentialsConfig, type AuroraEncryptionConfig, type AuroraWriterConfig, type AuroraReadersConfig, type DatabaseInsightsConfig, type SnapshotTarget } from "../../../utils/databaseTypes.js";
 interface RdsProps {
     vpc: IVpc;
     databaseName?: string;
@@ -61,6 +61,7 @@ export declare class RdsAurora extends Construct implements IConnectable {
     private databaseProxy?;
     private databaseCredentials;
     private cfnCluster?;
+    private databaseNameValue;
     constructor(scope: Construct, id: string, props: RdsProps);
     private buildReaders;
     private addProxy;
@@ -68,6 +69,12 @@ export declare class RdsAurora extends Construct implements IConnectable {
     getHostEndpoint(): string;
     getHostPort(): string;
     getCredentials(): Secret;
+    getClusterIdentifier(): string;
+    getSnapshotTarget(): Extract<SnapshotTarget, {
+        kind: "cluster";
+    }>;
+    getDatabaseName(): string;
+    getConnectionString(): string;
     getCfnCluster(): CfnDBCluster | undefined;
     getDatabaseCluster(): DatabaseCluster;
 }