@telorun/sql 0.12.0 → 0.12.1

package/README.md

@@ -23,9 +23,9 @@ Built to be language-agnostic and infinitely extensible.
 
 ```bash
 # Reconcile your manifest into a running backend
-$ telo ./examples/hello-api
+$ telo ./examples/todo-app
 
-{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
+{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8077"}
 ```
 
 ## Why use Telo?

package/dist/sql-connection-base.d.ts

@@ -20,6 +20,18 @@ export declare abstract class SqlConnectionBase implements SqlConnection {
     teardown(): Promise<void>;
     runInTransaction<T>(body: (bind: (entry: ZoneEntry) => void) => Promise<T>): Promise<T>;
     hasOpenTransaction(ctx?: InvokeContext): boolean;
+    /**
+     * Every statement this connection runs funnels through here — `executeTemplate`
+     * and `executeScript` both delegate — so it is the single instrumentation point.
+     *
+     * `db.query.text` is the statement, never the parameters: the values ARE the
+     * data, and a record carrying them would put row contents in the log. The
+     * statement itself is safe for a parameterized query (it is the template), and
+     * is `debug`-only regardless, because `Sql.Command` can carry inline literals.
+     *
+     * The disabled path allocates nothing and takes no clock reading — a query is
+     * the hottest thing this module does.
+     */
     execute<T>(sql: string, params?: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
     executeTemplate<T>(fragments: string[], values: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
     /** Hand the whole script to the driver as one statement. Backends whose driver

package/dist/sql-connection-base.js

@@ -1,4 +1,4 @@
-import { InvokeError, } from "@telorun/sdk";
+import { InvokeError, SEVERITY, } from "@telorun/sdk";
 import { CompiledQuery } from "kysely";
 /**
  * The dialect-neutral half of a connection: statement execution, transaction
@@ -35,16 +35,55 @@ export class SqlConnectionBase {
         await this.db.destroy();
     }
     async runInTransaction(body) {
-        return this.db
-            .transaction()
-            .execute((trx) => body((entry) => this.#executors.set(entry, trx)));
+        this.ctx.log.debug("Transaction started");
+        try {
+            const result = await this.db
+                .transaction()
+                .execute((trx) => body((entry) => this.#executors.set(entry, trx)));
+            this.ctx.log.debug("Transaction committed");
+            return result;
+        }
+        catch (err) {
+            // The error reaches the caller, but the ROLLBACK does not: a caller that
+            // maps the failure to a response sees nothing saying its writes were
+            // discarded, and that is the fact worth reconstructing afterwards.
+            this.ctx.log.debug("Transaction rolled back", undefined, { error: err });
+            throw err;
+        }
     }
     hasOpenTransaction(ctx) {
         return this.ctx.zonesFor(this, ctx).some((entry) => this.#executors.has(entry));
     }
+    /**
+     * Every statement this connection runs funnels through here — `executeTemplate`
+     * and `executeScript` both delegate — so it is the single instrumentation point.
+     *
+     * `db.query.text` is the statement, never the parameters: the values ARE the
+     * data, and a record carrying them would put row contents in the log. The
+     * statement itself is safe for a parameterized query (it is the template), and
+     * is `debug`-only regardless, because `Sql.Command` can carry inline literals.
+     *
+     * The disabled path allocates nothing and takes no clock reading — a query is
+     * the hottest thing this module does.
+     */
     async execute(sql, params = [], zone, ctx) {
         const executor = this.resolveExecutor(zone, ctx);
-        return executor.executeQuery(CompiledQuery.raw(sql, params));
+        if (!this.ctx.log.enabled(SEVERITY.debug)) {
+            return executor.executeQuery(CompiledQuery.raw(sql, params));
+        }
+        const startedAt = Date.now();
+        const result = await executor.executeQuery(CompiledQuery.raw(sql, params));
+        this.ctx.log.debug("Statement executed", {
+            "db.query.text": sql,
+            "db.response.returned_rows": result.rows.length,
+            // OTel's own name for this quantity, in OTel's own unit: SECONDS, as a
+            // double. Metric names and attribute keys are separate namespaces, so
+            // reusing the name is safe — what would not be safe is the name with the
+            // wrong magnitude, which is why this is not milliseconds. Units live in
+            // the convention, never in the key.
+            "db.client.operation.duration": (Date.now() - startedAt) / 1000,
+        });
+        return result;
     }
     async executeTemplate(fragments, values, zone, ctx) {
         let sql = fragments[0] ?? "";

package/dist/sql-migrations-controller.js

@@ -61,10 +61,32 @@ class SqlMigrationsResource {
             migrationTableName: "migrations",
             migrationLockTableName: "migration_locks",
         });
-        const { error } = await migrator.migrateToLatest();
+        const { error, results } = await migrator.migrateToLatest();
+        // A schema change is the least reversible thing an app does at boot, and the
+        // per-migration outcome was being discarded — so a run that applied four
+        // migrations and a run that found none to apply looked identical afterwards.
+        // `info`, because which migrations a deployment applied is the fact you go
+        // looking for when a schema is not what you expected.
+        // `sql.migration.name`, not `db.migration.name`: OTel owns `db.*` and defines
+        // no migration attribute, and §6.2 forbids inventing keys inside a namespace
+        // someone else governs.
+        for (const applied of results ?? []) {
+            if (applied.status === "Success") {
+                this.ctx.log.info("Migration applied", { "sql.migration.name": applied.migrationName });
+            }
+            else if (applied.status === "Error") {
+                // The cause rides on the record: this is the error-severity line an
+                // operator finds first, and the migration name alone cannot say what
+                // went wrong. `error` keeps the type, stack and cause chain (§4.2).
+                this.ctx.log.error("Migration failed", { "sql.migration.name": applied.migrationName }, { error });
+            }
+        }
         if (error) {
             throw error;
         }
+        if (!results?.length) {
+            this.ctx.log.debug("No pending migrations");
+        }
     }
 }
 function failMissingConnection() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sql",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Telo SQL module - SQL database resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,7 +43,7 @@
     "@types/node": "^20.0.0",
     "esbuild": "^0.25.12",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.67.0"
+    "@telorun/sdk": "0.70.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/sql-connection-base.ts

@@ -1,5 +1,6 @@
 import {
   InvokeError,
+  SEVERITY,
   type InvokeContext,
   type ResourceContext,
   type ZoneEntry,
@@ -50,15 +51,38 @@ export abstract class SqlConnectionBase implements SqlConnection {
   async runInTransaction<T>(
     body: (bind: (entry: ZoneEntry) => void) => Promise<T>,
   ): Promise<T> {
-    return this.db
-      .transaction()
-      .execute((trx: Transaction<any>) => body((entry) => this.#executors.set(entry, trx)));
+    this.ctx.log.debug("Transaction started");
+    try {
+      const result = await this.db
+        .transaction()
+        .execute((trx: Transaction<any>) => body((entry) => this.#executors.set(entry, trx)));
+      this.ctx.log.debug("Transaction committed");
+      return result;
+    } catch (err) {
+      // The error reaches the caller, but the ROLLBACK does not: a caller that
+      // maps the failure to a response sees nothing saying its writes were
+      // discarded, and that is the fact worth reconstructing afterwards.
+      this.ctx.log.debug("Transaction rolled back", undefined, { error: err });
+      throw err;
+    }
   }
 
   hasOpenTransaction(ctx?: InvokeContext): boolean {
     return this.ctx.zonesFor(this, ctx).some((entry) => this.#executors.has(entry));
   }
 
+  /**
+   * Every statement this connection runs funnels through here — `executeTemplate`
+   * and `executeScript` both delegate — so it is the single instrumentation point.
+   *
+   * `db.query.text` is the statement, never the parameters: the values ARE the
+   * data, and a record carrying them would put row contents in the log. The
+   * statement itself is safe for a parameterized query (it is the template), and
+   * is `debug`-only regardless, because `Sql.Command` can carry inline literals.
+   *
+   * The disabled path allocates nothing and takes no clock reading — a query is
+   * the hottest thing this module does.
+   */
   async execute<T>(
     sql: string,
     params: unknown[] = [],
@@ -66,7 +90,22 @@ export abstract class SqlConnectionBase implements SqlConnection {
     ctx?: InvokeContext,
   ): Promise<QueryResult<T>> {
     const executor = this.resolveExecutor(zone, ctx);
-    return executor.executeQuery<T>(CompiledQuery.raw(sql, params));
+    if (!this.ctx.log.enabled(SEVERITY.debug)) {
+      return executor.executeQuery<T>(CompiledQuery.raw(sql, params));
+    }
+    const startedAt = Date.now();
+    const result = await executor.executeQuery<T>(CompiledQuery.raw(sql, params));
+    this.ctx.log.debug("Statement executed", {
+      "db.query.text": sql,
+      "db.response.returned_rows": result.rows.length,
+      // OTel's own name for this quantity, in OTel's own unit: SECONDS, as a
+      // double. Metric names and attribute keys are separate namespaces, so
+      // reusing the name is safe — what would not be safe is the name with the
+      // wrong magnitude, which is why this is not milliseconds. Units live in
+      // the convention, never in the key.
+      "db.client.operation.duration": (Date.now() - startedAt) / 1000,
+    });
+    return result;
   }
 
   async executeTemplate<T>(

package/src/sql-migrations-controller.ts

@@ -97,10 +97,35 @@ class SqlMigrationsResource implements ResourceInstance {
       migrationLockTableName: "migration_locks",
     });
 
-    const { error } = await migrator.migrateToLatest();
+    const { error, results } = await migrator.migrateToLatest();
+    // A schema change is the least reversible thing an app does at boot, and the
+    // per-migration outcome was being discarded — so a run that applied four
+    // migrations and a run that found none to apply looked identical afterwards.
+    // `info`, because which migrations a deployment applied is the fact you go
+    // looking for when a schema is not what you expected.
+    // `sql.migration.name`, not `db.migration.name`: OTel owns `db.*` and defines
+    // no migration attribute, and §6.2 forbids inventing keys inside a namespace
+    // someone else governs.
+    for (const applied of results ?? []) {
+      if (applied.status === "Success") {
+        this.ctx.log.info("Migration applied", { "sql.migration.name": applied.migrationName });
+      } else if (applied.status === "Error") {
+        // The cause rides on the record: this is the error-severity line an
+        // operator finds first, and the migration name alone cannot say what
+        // went wrong. `error` keeps the type, stack and cause chain (§4.2).
+        this.ctx.log.error(
+          "Migration failed",
+          { "sql.migration.name": applied.migrationName },
+          { error },
+        );
+      }
+    }
     if (error) {
       throw error;
     }
+    if (!results?.length) {
+      this.ctx.log.debug("No pending migrations");
+    }
   }
 }