@tmlmobilidade/databases 20260509.340.15 → 20260511.1451.46

package/dist/clients/go-clickhouse.js

@@ -44,6 +44,12 @@ export class GOClickHouseClient {
         Logger.info('[GOClickHouseClient] Connecting to database...');
         const connectionString = await this.getConnectionString();
         this.client = createClient({
+            clickhouse_settings: {
+                connect_timeout: 360 * 1000,
+                http_receive_timeout: 360 * 1000,
+                http_send_timeout: 360 * 1000,
+                max_execution_time: 360 * 1000,
+            },
             keep_alive: { enabled: false },
             log: {
                 level: ClickHouseLogLevel.OFF,

package/dist/templates/clickhouse.d.ts

@@ -7,6 +7,13 @@ export declare abstract class ClickHouseInterfaceTemplate<T extends object> {
     protected readonly abstract schema: ClickHouseSchema<T>;
     protected readonly abstract tableName: string;
     protected readonly engine: ClickHouseTableEngine;
+    /**
+     * When `true` (default), `init()` runs `ensureDatabase()` + `ensureTable()` so
+     * the schema is created from this class. Set to `false` for tables whose schema
+     * is owned externally (e.g. by a `.sql` DDL file applied at startup); the
+     * interface then becomes a typed insert/query helper only.
+     */
+    protected readonly manageSchema: boolean;
     protected readonly orderBy: string;
     protected readonly partitionBy: null | string;
     private client;

package/dist/templates/clickhouse.js

@@ -8,6 +8,13 @@ import { Logger } from '@tmlmobilidade/logger';
 /* * */
 export class ClickHouseInterfaceTemplate {
     engine = 'MergeTree';
+    /**
+     * When `true` (default), `init()` runs `ensureDatabase()` + `ensureTable()` so
+     * the schema is created from this class. Set to `false` for tables whose schema
+     * is owned externally (e.g. by a `.sql` DDL file applied at startup); the
+     * interface then becomes a typed insert/query helper only.
+     */
+    manageSchema = true;
     orderBy = '_id';
     partitionBy = null;
     client;
@@ -113,13 +120,17 @@ export class ClickHouseInterfaceTemplate {
             throw new Error('CLICKHOUSE: databaseName is required.');
         if (!this.tableName)
             throw new Error('CLICKHOUSE: tableName is required.');
-        if (!this.schema || Object.entries(this.schema).length === 0)
+        if (this.manageSchema && (!this.schema || Object.entries(this.schema).length === 0)) {
             throw new Error('CLICKHOUSE: schema is required and cannot be empty.');
+        }
         // Connect to the ClickHouse client
         this.client = await this.connectToClient();
-        // Ensure the database and table exist, and perform any additional setup
-        await this.ensureDatabase();
-        await this.ensureTable();
+        // Only own the schema when this interface is the source of truth.
+        // External DDL owners (see `manageSchema`) skip this entirely.
+        if (this.manageSchema) {
+            await this.ensureDatabase();
+            await this.ensureTable();
+        }
         await this.postInit();
     }
     /**
@@ -198,8 +209,8 @@ export class ClickHouseInterfaceTemplate {
 			CREATE TABLE IF NOT EXISTS "${this.databaseName}"."${this.tableName}" (
 				${Object.entries(this.schema).map(([key, column]) => `${key} ${column.type}`).join(', ')}
 			) ENGINE = ${this.getEngineString()}
-			${this.orderBy ? `ORDER BY ${this.orderBy}` : ''}
-			${this.partitionBy ? `PARTITION BY ${this.partitionBy}` : ''}
+			${this.orderBy ? `ORDER BY (${this.orderBy})` : ''}
+			${this.partitionBy ? `PARTITION BY (${this.partitionBy})` : ''}
 		`;
         // Perform the query to create the table
         try {
@@ -239,6 +250,8 @@ export class ClickHouseInterfaceTemplate {
         switch (this.engine) {
             case 'MergeTree':
                 return `MergeTree()`;
+            case 'ReplacingMergeTree':
+                return `ReplacingMergeTree()`;
             default:
                 throw new Error(`CLICKHOUSE [${this.databaseName}/${this.tableName}]: Unsupported engine type: ${this.engine}`);
         }

package/dist/types/clickhouse/table-engines.d.ts

@@ -3,4 +3,4 @@
  * Please avoid using other engines before consulting with the team
  * as ClickHouse has many engines with different features and limitations.
  */
-export type ClickHouseTableEngine = 'MergeTree';
+export type ClickHouseTableEngine = 'MergeTree' | 'ReplacingMergeTree';

package/dist/utils/clickhouse/prepare-named-query-params.js

@@ -1,4 +1,5 @@
 /* * */
+import { getClickHouseParamType } from './get-clickhouse-param-type.js';
 import { validateSqlParam } from './validate-sql-param.js';
 /**
  * Prepares a SQL query with named parameters by validating the parameter keys
@@ -27,7 +28,7 @@ export function prepareNamedQueryParams(query, params, context) {
         usedKeys.add(key);
         const value = providedParams[key];
         queryParams[key] = value;
-        return `{${key}:${this.getClickHouseParamType(value)}}`;
+        return `{${key}:${getClickHouseParamType(value)}}`;
     });
     // Also include explicitly typed placeholders already present in query (e.g. {id:UInt64}).
     for (const match of normalizedQuery.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*):[^}]+\}/g)) {

package/dist/utils/clickhouse/query-from-file.d.ts

@@ -1,4 +1,9 @@
 import { type ClickHouseClient } from '@clickhouse/client';
+/**
+ * Split script into top-level `;`-terminated statements. Ignores semicolons inside `--` / `block`
+ * comments and single-quoted strings (naive `.split(';')` breaks DDL when comments contain `;`).
+ */
+export declare function splitClickHouseStatements(sql: string): string[];
 /**
  * Executes a query from a .sql file with optional parameter substitutions.
  * @param client The ClickHouse client to use for executing the query.
@@ -15,3 +20,8 @@ import { type ClickHouseClient } from '@clickhouse/client';
  * });
  */
 export declare function queryFromFile<T>(client: ClickHouseClient, filePath: string, params?: Record<string, number | string>): Promise<T[]>;
+/**
+ * Like {@link queryFromFile}, but runs each `;`-terminated statement separately. Use when the file
+ * contains multiple statements (ClickHouse rejects multi-statement queries by default).
+ */
+export declare function queryEachStatementFromFile<T>(client: ClickHouseClient, filePath: string, params?: Record<string, number | string>): Promise<T[]>;

package/dist/utils/clickhouse/query-from-file.js

@@ -2,6 +2,97 @@
 import { prepareNamedQueryParams } from './prepare-named-query-params.js';
 import { Logger } from '@tmlmobilidade/logger';
 import { readFile } from 'node:fs/promises';
+function chunkHasExecutableLine(chunk) {
+    return chunk.split('\n').some((line) => {
+        const t = line.trim();
+        return t !== '' && !t.startsWith('--');
+    });
+}
+/**
+ * Split script into top-level `;`-terminated statements. Ignores semicolons inside `--` / `block`
+ * comments and single-quoted strings (naive `.split(';')` breaks DDL when comments contain `;`).
+ */
+export function splitClickHouseStatements(sql) {
+    const out = [];
+    let buf = '';
+    let i = 0;
+    let lineComment = false;
+    let blockComment = false;
+    let inString = false;
+    while (i < sql.length) {
+        const c = sql[i];
+        const next = i + 1 < sql.length ? sql[i + 1] : undefined;
+        if (!c) {
+            break;
+        }
+        if (lineComment) {
+            buf += c;
+            if (c === '\n') {
+                lineComment = false;
+            }
+            i += 1;
+            continue;
+        }
+        if (blockComment) {
+            buf += c;
+            if (c === '*' && next === '/') {
+                buf += '/';
+                i += 2;
+                blockComment = false;
+                continue;
+            }
+            i += 1;
+            continue;
+        }
+        if (inString) {
+            buf += c;
+            if (c === '\'' && next === '\'') {
+                buf += '\'';
+                i += 2;
+                continue;
+            }
+            if (c === '\'') {
+                inString = false;
+            }
+            i += 1;
+            continue;
+        }
+        if (c === '-' && next === '-') {
+            lineComment = true;
+            buf += '--';
+            i += 2;
+            continue;
+        }
+        if (c === '/' && next === '*') {
+            blockComment = true;
+            buf += '/*';
+            i += 2;
+            continue;
+        }
+        if (c === '\'') {
+            inString = true;
+            buf += c;
+            i += 1;
+            continue;
+        }
+        if (c === ';') {
+            const chunk = buf.trim();
+            buf = '';
+            i += 1;
+            if (chunk && chunkHasExecutableLine(chunk)) {
+                out.push(chunk);
+            }
+            continue;
+        }
+        buf += c;
+        i += 1;
+    }
+    const tail = buf.trim();
+    if (tail && chunkHasExecutableLine(tail)) {
+        out.push(tail);
+    }
+    return out;
+}
 /**
  * Executes a query from a .sql file with optional parameter substitutions.
  * @param client The ClickHouse client to use for executing the query.
@@ -40,3 +131,35 @@ export async function queryFromFile(client, filePath, params) {
         throw error;
     }
 }
+/**
+ * Like {@link queryFromFile}, but runs each `;`-terminated statement separately. Use when the file
+ * contains multiple statements (ClickHouse rejects multi-statement queries by default).
+ */
+export async function queryEachStatementFromFile(client, filePath, params) {
+    let sql;
+    try {
+        sql = await readFile(filePath, { encoding: 'utf-8' });
+    }
+    catch (error) {
+        Logger.error(`CLICKHOUSE: Error @ queryEachStatementFromFile(): Failed to read SQL file "${filePath}": ${error.message}`);
+        throw error;
+    }
+    const statements = splitClickHouseStatements(sql);
+    const merged = [];
+    for (const statement of statements) {
+        const { query, queryParams } = prepareNamedQueryParams(statement, params, filePath);
+        try {
+            const result = await client.query({
+                format: 'JSONEachRow',
+                query,
+                query_params: queryParams,
+            });
+            merged.push(...(await result.json()));
+        }
+        catch (error) {
+            Logger.error(`CLICKHOUSE: Error @ queryEachStatementFromFile(): Failed to execute statement from file "${filePath}": ${error.message}`);
+            throw error;
+        }
+    }
+    return merged;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/databases",
-	"version": "20260509.340.15",
+	"version": "20260511.1451.46",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"