@uptimizr/db 0.8.2 → 1.0.1

package/dist/query/postgresDialect.js

@@ -0,0 +1,167 @@
+/**
+ * PostgreSQL dialect for the query layer (ADR 0020, #84).
+ *
+ * Postgres is the optional single-tenant *relational* store: a multi-writer
+ * server many self-hosters already operate, for shops that "only want Postgres"
+ * and have outgrown DuckDB's single read-write process. This dialect renders the
+ * engine-specific fragments of each shared aggregation (`aggregations.ts`) to
+ * Postgres SQL, so the bulk of every query stays shared with DuckDB/ClickHouse.
+ *
+ * Like the other dialects it is *single-tenant* — no `org_id`, no tenant
+ * isolation — which keeps it relocatable across the open-core boundary.
+ *
+ * Binding model: parameters are emitted as named `$name::type` placeholders
+ * (every logical {@link ParamType} carries an explicit cast so Postgres never has
+ * to infer a parameter type from context) and rewritten to positional `$1…$n`
+ * by `toPositionalParams` in the `@uptimizr/db-postgres` runner. Timestamp params
+ * are bound as naive-UTC strings (see {@link toPostgresTimestamp}) against
+ * `timestamp` (without time zone) columns, so ordering, bucketing, and `::date`
+ * truncation are wall-clock-UTC exactly as on DuckDB and ClickHouse, independent
+ * of the session `TimeZone`.
+ *
+ * Row-store fit gaps (issue #84) and how they are closed here:
+ * - **No `ASOF JOIN`.** `asofJoin` renders the shared nearest-row emulation
+ *   (`renderNearestRowJoin`, `relational.ts`) as `JOIN LATERAL (… ORDER BY ts
+ *   DESC LIMIT 1) ON TRUE`.
+ * - **No MergeTree rollups.** The daily rollups are plain views that recompute
+ *   at query time (see the `@uptimizr/db-postgres` migrations), so the `-Merge`
+ *   combinators reduce to pass-through aggregates, as on DuckDB.
+ * - **Arrays are 1-indexed** — the same convention DuckDB and ClickHouse use, so
+ *   `position[1]` in the shared SQL needs no translation; `arrayLength` maps to
+ *   `cardinality` and `vectorNorm` unnests the array.
+ * - **JSON** lives in a `jsonb` column; extraction is `#>>` with a text[] path,
+ *   and the numeric extractors regex-guard the cast (Postgres has no `TRY_CAST`)
+ *   so an absent / non-numeric key yields NULL exactly like DuckDB's `TRY_CAST`.
+ */
+import { renderNearestRowJoin } from "./relational.js";
+/** Map a logical {@link ParamType} to the explicit Postgres cast it is bound with. */
+function pgCast(type) {
+    switch (type) {
+        case "string":
+            return "text";
+        case "u32":
+            return "integer";
+        case "f64":
+            return "double precision";
+        case "timestamp":
+            return "timestamp";
+        case "date":
+            return "date";
+    }
+}
+/**
+ * Format an epoch-millisecond timestamp as a naive-UTC `YYYY-MM-DD HH:MM:SS.mmm`
+ * string for binding to a Postgres `timestamp` (without time zone) column/param.
+ * Mirrors the DuckDB / ClickHouse literal format so all stores order and bucket
+ * time identically.
+ */
+export function toPostgresTimestamp(epochMs) {
+    const d = new Date(epochMs);
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return (`${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ` +
+        `${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}.${p(d.getUTCMilliseconds(), 3)}`);
+}
+/** Join keywords for the Postgres flavour of the nearest-row ASOF emulation. */
+export const POSTGRES_NEAREST_ROW_JOIN = {
+    inner: "INNER JOIN LATERAL",
+    left: "LEFT JOIN LATERAL",
+    onTrue: "ON TRUE",
+    selectPrefix: "SELECT",
+    selectSuffix: "LIMIT 1",
+};
+/** Render a trusted compile-time key path as a Postgres `text[]` literal. */
+function jsonPath(path) {
+    return `'{${path.map((k) => `"${k}"`).join(",")}}'`;
+}
+/** `(column #>> '{path}')` — the JSON value at `path` as text, NULL when absent. */
+function jsonAt(column, path) {
+    return `(${column} #>> ${jsonPath(path)})`;
+}
+/**
+ * Regex-guarded numeric cast of a JSON text extraction. Postgres has no
+ * `TRY_CAST`, so the value is only cast when it matches the numeric shape;
+ * anything else (absent key, non-numeric string) yields NULL — parity with
+ * DuckDB's `TRY_CAST(... AS BIGINT|DOUBLE)`.
+ */
+function guardedCast(extract, pattern, type) {
+    return `CASE WHEN ${extract} ~ '${pattern}' THEN ${extract}::${type} END`;
+}
+export const postgresDialect = {
+    name: "postgres",
+    placeholder(name, type) {
+        return `$${name}::${pgCast(type)}`;
+    },
+    timestampValue(epochMs) {
+        return toPostgresTimestamp(epochMs);
+    },
+    quantile(expr, q) {
+        // `percentile_cont` interpolates linearly between adjacent ranks (type-7),
+        // exactly like DuckDB's `quantile_cont` and ClickHouse's `quantile`; NULLs
+        // are ignored and an empty input yields NULL. Cast so integer-typed
+        // expressions (e.g. `long_frames` sums) are accepted.
+        return `percentile_cont(${q}) WITHIN GROUP (ORDER BY (${expr})::double precision)`;
+    },
+    vectorNorm(expr) {
+        // Postgres has no vector norm; unnest the array in a correlated scalar
+        // subquery. Works for any length (matches L2Norm / list_dot_product).
+        return `sqrt((SELECT sum(v * v) FROM unnest(${expr}) AS u(v)))`;
+    },
+    arrayLength(expr) {
+        // `cardinality` returns 0 for an empty array (`array_length` returns NULL).
+        return `cardinality(${expr})`;
+    },
+    avgIf(value, cond) {
+        return `avg(${value}) FILTER (WHERE ${cond})`;
+    },
+    anyValue(expr) {
+        // `min` is a valid "any" (the callers use it on values constant within the
+        // group), ignores NULLs like DuckDB's `any_value`, and — unlike PG 16's
+        // `any_value()` — works on every supported Postgres version.
+        return `min(${expr})`;
+    },
+    timeBucketMs(tsExpr, intervalPlaceholder) {
+        // Integer epoch-ms floored to the interval grid (same arithmetic as DuckDB /
+        // ClickHouse). Divide in double precision so the interval param's integer
+        // type can never turn `/` into a truncating integer division.
+        const ms = `(EXTRACT(EPOCH FROM ${tsExpr}) * 1000)::bigint`;
+        const bucket = `(${intervalPlaceholder} * 1000)`;
+        return `(floor(${ms}::double precision / ${bucket}) * ${bucket})::bigint`;
+    },
+    epochMs(tsExpr) {
+        // EXTRACT(EPOCH) of a naive timestamp is wall-clock UTC seconds; the store
+        // writes millisecond precision, so `* 1000` is exact before the cast.
+        return `(EXTRACT(EPOCH FROM ${tsExpr}) * 1000)::bigint`;
+    },
+    toDate(expr) {
+        return `CAST(${expr} AS DATE)`;
+    },
+    toText(expr) {
+        return `CAST(${expr} AS TEXT)`;
+    },
+    jsonText(column, ...path) {
+        return jsonAt(column, path);
+    },
+    jsonInt(column, ...path) {
+        return guardedCast(jsonAt(column, path), "^-?[0-9]+$", "bigint");
+    },
+    jsonFloat(column, ...path) {
+        // Numeric path components index a JSON array (0-based) natively in `#>>`.
+        return guardedCast(jsonAt(column, path), "^-?[0-9]+(\\.[0-9]+)?([eE][-+]?[0-9]+)?$", "double precision");
+    },
+    // The daily rollups are query-time views (pre-grouped by day), so each read
+    // GROUP BY sees exactly one source row per group and the "merge" of a single
+    // precomputed value is a plain pass-through aggregate — as on DuckDB.
+    countMerge(stateExpr) {
+        return `sum(${stateExpr})`;
+    },
+    avgMerge(stateExpr) {
+        return `avg(${stateExpr})`;
+    },
+    quantileMerge(stateExpr, q) {
+        return `percentile_cont(${q}) WITHIN GROUP (ORDER BY (${stateExpr})::double precision)`;
+    },
+    asofJoin(spec) {
+        return renderNearestRowJoin(spec, POSTGRES_NEAREST_ROW_JOIN);
+    },
+};
+//# sourceMappingURL=postgresDialect.js.map

package/dist/query/postgresDialect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgresDialect.js","sourceRoot":"","sources":["../../src/query/postgresDialect.ts"],"names":[],"mappings":"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"}

package/dist/query/relational.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Engine-neutral building blocks shared by the *relational* dialects
+ * (ADR 0020) — the pieces that are not Postgres-specific and that the SQL
+ * Server port (#85) is expected to reuse verbatim:
+ *
+ * 1. {@link renderNativeAsofJoin} — the `ASOF JOIN` clause for engines that
+ *    have one (DuckDB, ClickHouse).
+ * 2. {@link renderNearestRowJoin} — the ASOF *emulation* for row stores that
+ *    lack it: a correlated nearest-row subquery (`LATERAL … LIMIT 1` on
+ *    Postgres, `CROSS/OUTER APPLY … TOP 1` on SQL Server). Only the join
+ *    keywords differ, so they are injected as {@link NearestRowJoinTokens}.
+ * 3. {@link toPositionalParams} — rewrite the query layer's named `$name`
+ *    placeholders to an engine's positional form (`$1` on Postgres, `@p1` on
+ *    SQL Server) at execution time, so dialects stay pure string builders that
+ *    never need to count parameters.
+ *
+ * Everything here is pure (no I/O, no client coupling) and isomorphic.
+ */
+import type { AsofJoinSpec } from "./dialect.js";
+/** Render `ASOF INNER|LEFT JOIN <right> AS <alias> ON <keys> AND <ts predicate>`. */
+export declare function renderNativeAsofJoin(spec: AsofJoinSpec): string;
+/**
+ * Engine keywords for {@link renderNearestRowJoin}. Postgres:
+ * `{ inner: "INNER JOIN LATERAL", left: "LEFT JOIN LATERAL", onTrue: "ON TRUE",
+ * selectPrefix: "SELECT", selectSuffix: "LIMIT 1" }`. SQL Server would use
+ * `CROSS APPLY` / `OUTER APPLY`, an empty `onTrue`, and `SELECT TOP 1` / `""`.
+ */
+export interface NearestRowJoinTokens {
+    /** Introducer for the inner (row-dropping) variant. */
+    readonly inner: string;
+    /** Introducer for the left (row-keeping) variant. */
+    readonly left: string;
+    /** Trailing join condition, e.g. `ON TRUE` (empty for `APPLY`). */
+    readonly onTrue: string;
+    /** `SELECT` keyword, optionally carrying a row cap (`SELECT TOP 1`). */
+    readonly selectPrefix: string;
+    /** Trailing row cap after `ORDER BY` (`LIMIT 1`), or empty. */
+    readonly selectSuffix: string;
+}
+/**
+ * Emulate an ASOF join on an engine without one: for every left row, a
+ * correlated subquery picks the single right row with equal keys and the
+ * nearest timestamp in the requested direction. Exactly the semantics of
+ * `ASOF JOIN` (ties on the right timestamp are broken arbitrarily on every
+ * engine).
+ *
+ * Trade-off (documented in `@uptimizr/db-postgres`): the planner evaluates the
+ * subquery once per left row — an index-backed nearest-row lookup — instead of
+ * DuckDB/ClickHouse's single merge pass. Fine at the self-host scale this store
+ * targets; the `(project_id, session_id, ts)` indexes exist for exactly this.
+ */
+export declare function renderNearestRowJoin(spec: AsofJoinSpec, t: NearestRowJoinTokens): string;
+/** Result of {@link toPositionalParams}: the rewritten SQL and ordered values. */
+export interface PositionalQuery {
+    readonly sql: string;
+    readonly values: unknown[];
+}
+/**
+ * Rewrite named `$name` placeholders into positional ones. Each distinct name
+ * is assigned the next index on first sight (so a name bound several times maps
+ * to one value), and `render(index)` produces the engine's token (`$1`, `@p1`).
+ * A placeholder with no bound value is a programming error and throws.
+ *
+ * Only bare `$identifier` tokens are rewritten; the query layer never emits a
+ * `$` in any other position (no dollar-quoting, no JSON `$.path` on these
+ * dialects), so no literal-awareness is needed.
+ */
+export declare function toPositionalParams(sql: string, params: Readonly<Record<string, unknown>>, render: (index: number) => string): PositionalQuery;
+//# sourceMappingURL=relational.d.ts.map

package/dist/query/relational.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relational.d.ts","sourceRoot":"","sources":["../../src/query/relational.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAK/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAoBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAYxF;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAChC,eAAe,CAejB"}

package/dist/query/relational.js

@@ -0,0 +1,94 @@
+/**
+ * Engine-neutral building blocks shared by the *relational* dialects
+ * (ADR 0020) — the pieces that are not Postgres-specific and that the SQL
+ * Server port (#85) is expected to reuse verbatim:
+ *
+ * 1. {@link renderNativeAsofJoin} — the `ASOF JOIN` clause for engines that
+ *    have one (DuckDB, ClickHouse).
+ * 2. {@link renderNearestRowJoin} — the ASOF *emulation* for row stores that
+ *    lack it: a correlated nearest-row subquery (`LATERAL … LIMIT 1` on
+ *    Postgres, `CROSS/OUTER APPLY … TOP 1` on SQL Server). Only the join
+ *    keywords differ, so they are injected as {@link NearestRowJoinTokens}.
+ * 3. {@link toPositionalParams} — rewrite the query layer's named `$name`
+ *    placeholders to an engine's positional form (`$1` on Postgres, `@p1` on
+ *    SQL Server) at execution time, so dialects stay pure string builders that
+ *    never need to count parameters.
+ *
+ * Everything here is pure (no I/O, no client coupling) and isomorphic.
+ */
+/** Render `ASOF INNER|LEFT JOIN <right> AS <alias> ON <keys> AND <ts predicate>`. */
+export function renderNativeAsofJoin(spec) {
+    const kind = spec.kind === "left" ? "ASOF LEFT JOIN" : "ASOF INNER JOIN";
+    const keys = spec.keys.map(([l, r]) => `${l} = ${spec.alias}.${r}`).join(" AND ");
+    return `${kind} ${spec.right} AS ${spec.alias}
+        ON ${keys} AND ${spec.leftTs} ${spec.op} ${spec.alias}.${spec.rightTs}`;
+}
+/**
+ * Flip a `leftTs <op> rightTs` comparison into the `rightTs <op'> leftTs` form a
+ * correlated subquery filters with, plus the sort direction that puts the
+ * nearest right row first.
+ */
+function nearestRowPredicate(op) {
+    switch (op) {
+        case ">=":
+            return { flipped: "<=", order: "DESC" };
+        case ">":
+            return { flipped: "<", order: "DESC" };
+        case "<=":
+            return { flipped: ">=", order: "ASC" };
+        case "<":
+            return { flipped: ">", order: "ASC" };
+    }
+}
+/**
+ * Emulate an ASOF join on an engine without one: for every left row, a
+ * correlated subquery picks the single right row with equal keys and the
+ * nearest timestamp in the requested direction. Exactly the semantics of
+ * `ASOF JOIN` (ties on the right timestamp are broken arbitrarily on every
+ * engine).
+ *
+ * Trade-off (documented in `@uptimizr/db-postgres`): the planner evaluates the
+ * subquery once per left row — an index-backed nearest-row lookup — instead of
+ * DuckDB/ClickHouse's single merge pass. Fine at the self-host scale this store
+ * targets; the `(project_id, session_id, ts)` indexes exist for exactly this.
+ */
+export function renderNearestRowJoin(spec, t) {
+    const { flipped, order } = nearestRowPredicate(spec.op);
+    const a = spec.alias;
+    const keys = spec.keys.map(([l, r]) => `${a}.${r} = ${l}`).join(" AND ");
+    const introducer = spec.kind === "left" ? t.left : t.inner;
+    const suffix = t.selectSuffix ? ` ${t.selectSuffix}` : "";
+    const onTrue = t.onTrue ? ` ${t.onTrue}` : "";
+    return `${introducer} (
+          ${t.selectPrefix} * FROM ${spec.right} AS ${a}
+          WHERE ${keys} AND ${a}.${spec.rightTs} ${flipped} ${spec.leftTs}
+          ORDER BY ${a}.${spec.rightTs} ${order}${suffix}
+        ) AS ${a}${onTrue}`;
+}
+/**
+ * Rewrite named `$name` placeholders into positional ones. Each distinct name
+ * is assigned the next index on first sight (so a name bound several times maps
+ * to one value), and `render(index)` produces the engine's token (`$1`, `@p1`).
+ * A placeholder with no bound value is a programming error and throws.
+ *
+ * Only bare `$identifier` tokens are rewritten; the query layer never emits a
+ * `$` in any other position (no dollar-quoting, no JSON `$.path` on these
+ * dialects), so no literal-awareness is needed.
+ */
+export function toPositionalParams(sql, params, render) {
+    const indexByName = new Map();
+    const values = [];
+    const rewritten = sql.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, name) => {
+        let index = indexByName.get(name);
+        if (index === undefined) {
+            if (!Object.prototype.hasOwnProperty.call(params, name)) {
+                throw new Error(`Unbound query parameter "$${name}"`);
+            }
+            index = values.push(params[name]);
+            indexByName.set(name, index);
+        }
+        return render(index);
+    });
+    return { sql: rewritten, values };
+}
+//# sourceMappingURL=relational.js.map

package/dist/query/relational.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relational.js","sourceRoot":"","sources":["../../src/query/relational.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/db",
-  "version": "0.8.2",
+  "version": "1.0.1",
   "description": "OSS storage contracts (dialect-agnostic query layer, neutral event/metadata types) and the single-file DuckDB store for Uptimizr.",
   "keywords": [
     "uptimizr",
@@ -39,11 +39,12 @@
     }
   },
   "bin": {
-    "uptimizr-db-migrate": "./dist/cli/migrate.js",
-    "uptimizr-db-new-project": "./dist/cli/createProject.js"
+    "uptimizr-db-migrate": "./bin/uptimizr-db-migrate.js",
+    "uptimizr-db-new-project": "./bin/uptimizr-db-new-project.js"
   },
   "files": [
     "dist",
+    "bin",
     "README.md",
     "LICENSE",
     "AGENTS.md",
@@ -51,7 +52,7 @@
   ],
   "dependencies": {
     "@duckdb/node-api": "^1.5.5-r.4",
-    "@uptimizr/schema": "0.6.1"
+    "@uptimizr/schema": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",