@uptimizr/db-postgres 0.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions for
+      use, reproduction, or distribution of Your modifications, or for any
+      such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Uptimizr Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,118 @@
+# @uptimizr/db-postgres
+
+Optional **single-tenant PostgreSQL store** for the Uptimizr collector — for
+self-hosters who already run Postgres and want a familiar, multi-writer
+relational backend instead of the default single-file DuckDB store (ADR 0020,
+issue #84).
+
+It is a **re-home + dialect emitter, not a rewrite**: every analytics
+aggregation is authored once in [`@uptimizr/db`](../db) against the
+dialect-agnostic query layer, and this package renders them to Postgres SQL via
+the shared `postgresDialect`, plus a pooled [`pg`](https://node-postgres.com)
+client, schema/migrations, and metadata helpers that satisfy the same
+`CollectorStore` contract as DuckDB and ClickHouse.
+
+## When to use it
+
+Stay on the default DuckDB store unless you hit its single read-write process
+ceiling. Choose Postgres when you want **several collector instances** sharing
+one store, or when Postgres is simply the database your team already operates
+(managed Postgres, RDS, Cloud SQL, Supabase, Neon, …). Choose
+[`@uptimizr/db-clickhouse`](../db-clickhouse) instead for high-volume ingestion
+and large historical ranges.
+
+## Usage
+
+Select it via the collector's `COLLECTOR_STORE` env var:
+
+```bash
+COLLECTOR_STORE=postgres \
+POSTGRES_URL=postgresql://uptimizr:uptimizr@localhost:5432/uptimizr \
+  pnpm --filter @uptimizr/collector-server start
+```
+
+| Variable                           | Purpose                                                                                |
+| ---------------------------------- | -------------------------------------------------------------------------------------- |
+| `POSTGRES_URL` (or `DATABASE_URL`) | libpq connection URI (`?sslmode=require` etc. apply). The database must already exist. |
+| `POSTGRES_SCHEMA`                  | Schema the store's tables live in (default `public`; created on first boot).           |
+| `POSTGRES_POOL_MAX`                | Maximum pooled connections per collector process (default `10`).                       |
+
+A local Postgres is available via [`infra/docker`](../../../infra/docker)
+(`pnpm stack:up` starts a `postgres:16` service). The schema is migrated on store
+creation — migrations are idempotent, forward-only (ADR 0007) and serialized
+behind an advisory lock, so several instances may boot concurrently against one
+database. Postgres 14+ is supported (tested against 16).
+
+## Scope
+
+- **Single-tenant only** — no `org_id`, no tenant isolation. The multi-writer
+  rollups and scale tuning remain the scale tier; this package is the
+  single-instance relational adapter.
+- No stubbed features — the full analytics surface (heatmaps, perf percentiles,
+  click↔gaze rays, funnels) returns results identical to DuckDB on the
+  cross-engine parity fixtures.
+
+## Row-store fit gaps and how they are closed
+
+| Gap                            | Postgres rendering                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No `ASOF JOIN`                 | `Dialect.asofJoin(spec)` renders `[INNER\|LEFT] JOIN LATERAL (SELECT * FROM <right> WHERE keys… AND ts <= left.ts ORDER BY ts DESC LIMIT 1) ON TRUE` (`renderNearestRowJoin`). Same rows as a native ASOF join; one indexed lookup per left row instead of a single merge pass — fine at self-host scale, slower than DuckDB/ClickHouse on very large sessions. The `(project_id, session_id, ts)` index exists for exactly this. |
+| No MergeTree rollups           | `perf_daily` / `events_daily` are plain views recomputed at query time; the `-Merge` combinators reduce to `sum`/`avg`/`percentile_cont` pass-throughs, as on DuckDB.                                                                                                                                                                                                                                                             |
+| 1-indexed arrays               | Same convention as DuckDB and ClickHouse, so `position[1]` in the shared SQL is untouched; `arrayLength` → `cardinality`, `vectorNorm` → `sqrt(sum(v*v))` over `unnest`.                                                                                                                                                                                                                                                          |
+| `quantile` / `avgIf` / `any`   | `percentile_cont(q) WITHIN GROUP (ORDER BY …)`, `avg(…) FILTER (WHERE …)`, `min(…)` (a deterministic "any" that also works before PG 16's `any_value`).                                                                                                                                                                                                                                                                           |
+| JSON extraction, no `TRY_CAST` | `payload` is `jsonb`; `jsonText` → `#>>`, `jsonInt`/`jsonFloat` regex-guard the cast so absent / non-numeric keys yield NULL exactly like DuckDB's `TRY_CAST`. The payload round-trips replay-complete (`jsonb` is value-lossless for JSON numbers/strings; key order is irrelevant).                                                                                                                                             |
+| Parameters                     | The dialect emits named `$name::type` placeholders (explicit casts, so Postgres never infers a parameter type); `runPostgresQuery` rewrites them to positional `$1…$n` with the shared `toPositionalParams`.                                                                                                                                                                                                                      |
+| `count()` / `length(array)`    | Not valid Postgres — the shared SQL now uses `count(*)` and `Dialect.arrayLength`.                                                                                                                                                                                                                                                                                                                                                |
+| Timestamps                     | `timestamp` (without time zone) holding wall-clock UTC, bound as naive-UTC literals; epoch extraction, `::date` and bucketing are session-`TimeZone`-independent and identical to the other engines.                                                                                                                                                                                                                              |
+
+### Documented divergences
+
+None on the parity fixtures: all 68 `PARITY_CASES` match the golden and DuckDB,
+and every `build*` aggregation (69, across base / filtered / spatial option
+variants) matches DuckDB row-for-row. Two engine behaviours differ only where
+the query layer already declares them unspecified: ties on the right-hand
+timestamp of an ASOF join are broken arbitrarily on every engine, and
+`anyValue` picks an arbitrary group member on DuckDB/ClickHouse but the minimum
+on Postgres (callers only use it on values constant within the group).
+
+## Reusable relational helpers (for the SQL Server port, #85)
+
+The engine-neutral pieces live in `@uptimizr/db` (`src/query/relational.ts`) and
+are re-exported from its root:
+
+- `renderNearestRowJoin(spec, tokens)` — the ASOF emulation; SQL Server reuses
+  it with `{ inner: "CROSS APPLY", left: "OUTER APPLY", onTrue: "",
+selectPrefix: "SELECT TOP 1", selectSuffix: "" }`.
+- `renderNativeAsofJoin(spec)` — the DuckDB / ClickHouse rendering.
+- `toPositionalParams(sql, params, render)` — named → positional rewriting
+  (`@p1…` for `mssql`).
+- The query-time rollup strategy (plain views named `perf_daily` /
+  `events_daily` with `*_state` columns) and the `jsonb`-style regex-guarded
+  numeric extraction pattern are documented in `migrations.ts` and
+  `postgresDialect.ts` respectively and port 1:1.
+
+## Layout
+
+| File               | Responsibility                                                          |
+| ------------------ | ----------------------------------------------------------------------- |
+| `client.ts`        | Pooled `pg` wrapper (UTC session, schema search path, plain-JS values). |
+| `migrations.ts`    | Forward-only DDL (events, node_samples, metadata, query-time views).    |
+| `events.ts`        | Batched multi-row inserts + replay-complete session reads.              |
+| `projects.ts`      | Project + API-key metadata (SHA-256 hashes).                            |
+| `sceneRegistry.ts` | Per-`(project, scene)` representation upserts/reads (`ON CONFLICT`).    |
+| `queries.ts`       | `runPostgresQuery` — executes a rendered `QuerySpec`.                   |
+
+The `CollectorStore` itself is assembled from these building blocks in the
+collector server (`oss/apps/collector-server/src/postgresStore.ts`,
+`createPostgresStore`), mirroring the DuckDB and ClickHouse stores — this
+package stays a store-agnostic toolkit.
+
+## Tests
+
+- `dialect.test.ts` — pure unit checks (no server).
+- `postgresParity.test.ts` / `postgresStore.test.ts` — live suites that probe
+  `POSTGRES_URL` (or `DATABASE_URL`) first and **skip when no server is
+  reachable**, so the default `pnpm test` stays Docker-free. They use throwaway
+  schemas that are dropped on teardown.
+
+Licensed Apache-2.0.

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Postgres client — the optional single-tenant relational store (ADR 0020, #84).
+ *
+ * A thin wrapper over `pg`'s connection pool that centralizes connection
+ * settings and exposes the small surface the store needs: positional-parameter
+ * queries, DDL commands, and transactions. Mirrors the shape of the DuckDB and
+ * ClickHouse clients so the store assembly reads the same across engines.
+ *
+ * Postgres is a networked, multi-writer server safe for concurrent statements,
+ * so there is no single-writer serialization here — several collector instances
+ * can share one database, which is the point of this store.
+ *
+ * Value coercion: `pg` returns `int8` (`count(*)`, epoch-ms casts) and `numeric`
+ * (`avg`/`sum` over integers) as **strings**, and parses `date`/`timestamp`
+ * columns into local-time `Date`s. The pool installs type parsers so those come
+ * back as plain JS numbers / naive-UTC strings instead, matching the rows the
+ * DuckDB client returns (and the row shapes the query layer's types declare).
+ */
+import type { PostgresSettings } from "@uptimizr/db";
+/** A row of plain-JS values returned by a query. */
+export type PostgresRow = Record<string, unknown>;
+/** The statement surface available both on the pool and inside a transaction. */
+export interface PostgresExecutor {
+    /** Run a positional-parameter (`$1…$n`) query and return all rows. */
+    query<T = PostgresRow>(sql: string, values?: readonly unknown[]): Promise<T[]>;
+    /** Run a DDL/maintenance statement, ignoring any result set. */
+    command(sql: string): Promise<void>;
+}
+export interface PostgresClient extends PostgresExecutor {
+    /** Run `fn` inside one transaction (committed on success, rolled back on throw). */
+    transaction<T>(fn: (tx: PostgresExecutor) => Promise<T>): Promise<T>;
+    /** Drain the pool and release every connection. */
+    close(): Promise<void>;
+}
+/**
+ * Guard an operator-supplied identifier (the `POSTGRES_SCHEMA` name) before
+ * interpolating it into DDL / `search_path`. It comes from trusted env, not
+ * request input, but a strict allow-list keeps the statements injection-proof.
+ */
+export declare function assertSafeIdentifier(name: string, what?: string): string;
+/**
+ * Create a pooled Postgres client from {@link PostgresSettings}. Every
+ * connection pins `TimeZone=UTC` and `search_path` to the configured schema, so
+ * `now()`-based defaults and unqualified table names behave identically across
+ * collector instances regardless of the server's defaults. The schema itself is
+ * created by {@link migratePostgres} on first boot.
+ */
+export declare function createPostgresClient(settings: PostgresSettings): PostgresClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,oDAAoD;AACpD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,CAAC,CAAC,GAAG,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/E,gEAAgE;IAChE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,oFAAoF;IACpF,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrE,mDAAmD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAyCD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAyB,GAAG,MAAM,CAQxF;AAgBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,cAAc,CAqC/E"}

package/dist/client.js

@@ -0,0 +1,124 @@
+/**
+ * Postgres client — the optional single-tenant relational store (ADR 0020, #84).
+ *
+ * A thin wrapper over `pg`'s connection pool that centralizes connection
+ * settings and exposes the small surface the store needs: positional-parameter
+ * queries, DDL commands, and transactions. Mirrors the shape of the DuckDB and
+ * ClickHouse clients so the store assembly reads the same across engines.
+ *
+ * Postgres is a networked, multi-writer server safe for concurrent statements,
+ * so there is no single-writer serialization here — several collector instances
+ * can share one database, which is the point of this store.
+ *
+ * Value coercion: `pg` returns `int8` (`count(*)`, epoch-ms casts) and `numeric`
+ * (`avg`/`sum` over integers) as **strings**, and parses `date`/`timestamp`
+ * columns into local-time `Date`s. The pool installs type parsers so those come
+ * back as plain JS numbers / naive-UTC strings instead, matching the rows the
+ * DuckDB client returns (and the row shapes the query layer's types declare).
+ */
+import pg from "pg";
+// Postgres type OIDs whose default `pg` parsing is replaced (see module doc).
+const OID_INT8 = 20;
+const OID_NUMERIC = 1700;
+const OID_INT8_ARRAY = 1016;
+const OID_NUMERIC_ARRAY = 1231;
+const OID_DATE = 1082;
+const OID_TIMESTAMP = 1114;
+const OID_TIMESTAMPTZ = 1184;
+const identity = (value) => value;
+/**
+ * Build the per-pool type-parser table: 64-bit integers and numerics (scalar
+ * and array) become JS numbers; date/timestamp columns stay the naive text
+ * Postgres renders (`YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS[.fff]`) — the store never
+ * relies on `pg`'s local-time `Date` interpretation of a naive timestamp.
+ */
+function buildTypeParsers() {
+    const numericArray = (oid) => {
+        const parseStrings = pg.types.getTypeParser(oid, "text");
+        return (value) => parseStrings(value).map((v) => (v === null ? null : Number(v)));
+    };
+    const overrides = new Map([
+        [OID_INT8, Number],
+        [OID_NUMERIC, Number],
+        [OID_INT8_ARRAY, numericArray(OID_INT8_ARRAY)],
+        [OID_NUMERIC_ARRAY, numericArray(OID_NUMERIC_ARRAY)],
+        [OID_DATE, identity],
+        [OID_TIMESTAMP, identity],
+        [OID_TIMESTAMPTZ, identity],
+    ]);
+    return {
+        getTypeParser(oid, format) {
+            const override = format === "binary" ? undefined : overrides.get(oid);
+            return override ?? pg.types.getTypeParser(oid, format);
+        },
+    };
+}
+/**
+ * Guard an operator-supplied identifier (the `POSTGRES_SCHEMA` name) before
+ * interpolating it into DDL / `search_path`. It comes from trusted env, not
+ * request input, but a strict allow-list keeps the statements injection-proof.
+ */
+export function assertSafeIdentifier(name, what = "Postgres schema name") {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`Invalid ${what} ${JSON.stringify(name)}: ` +
+            "expected letters, digits and underscores (starting with a letter or underscore).");
+    }
+    return name;
+}
+function makeExecutor(run) {
+    return {
+        async query(sql, values) {
+            const result = await run(sql, values);
+            return result.rows;
+        },
+        async command(sql) {
+            await run(sql);
+        },
+    };
+}
+/**
+ * Create a pooled Postgres client from {@link PostgresSettings}. Every
+ * connection pins `TimeZone=UTC` and `search_path` to the configured schema, so
+ * `now()`-based defaults and unqualified table names behave identically across
+ * collector instances regardless of the server's defaults. The schema itself is
+ * created by {@link migratePostgres} on first boot.
+ */
+export function createPostgresClient(settings) {
+    const schema = assertSafeIdentifier(settings.schema);
+    const pool = new pg.Pool({
+        connectionString: settings.url,
+        max: settings.poolMax,
+        types: buildTypeParsers(),
+        // libpq startup options: UTC wall clock + the store's schema first in the
+        // search path (public stays reachable for extensions).
+        options: `-c TimeZone=UTC -c search_path=${schema},public`,
+    });
+    // A connection dropped by the server while idle would otherwise surface as an
+    // unhandled 'error' event and crash the process; the pool replaces it lazily.
+    pool.on("error", () => { });
+    const executor = makeExecutor((sql, values) => pool.query(sql, values ? [...values] : undefined));
+    return {
+        ...executor,
+        async transaction(fn) {
+            const conn = await pool.connect();
+            try {
+                await conn.query("BEGIN");
+                const tx = makeExecutor((sql, values) => conn.query(sql, values ? [...values] : undefined));
+                const result = await fn(tx);
+                await conn.query("COMMIT");
+                return result;
+            }
+            catch (error) {
+                await conn.query("ROLLBACK").catch(() => { });
+                throw error;
+            }
+            finally {
+                conn.release();
+            }
+        },
+        async close() {
+            await pool.end();
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AAqBpB,8EAA8E;AAC9E,MAAM,QAAQ,GAAG,EAAE,CAAC;AACpB,MAAM,WAAW,GAAG,IAAI,CAAC;AACzB,MAAM,cAAc,GAAG,IAAI,CAAC;AAC5B,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC;AACtB,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC;AAElD;;;;;GAKG;AACH,SAAS,gBAAgB;IACvB,MAAM,YAAY,GAAG,CAAC,GAAW,EAAE,EAAE;QACnC,MAAM,YAAY,GAAG,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,CAAqC,CAAC;QAC7F,OAAO,CAAC,KAAa,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5F,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAqC;QAC5D,CAAC,QAAQ,EAAE,MAAM,CAAC;QAClB,CAAC,WAAW,EAAE,MAAM,CAAC;QACrB,CAAC,cAAc,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;QAC9C,CAAC,iBAAiB,EAAE,YAAY,CAAC,iBAAiB,CAAC,CAAC;QACpD,CAAC,QAAQ,EAAE,QAAQ,CAAC;QACpB,CAAC,aAAa,EAAE,QAAQ,CAAC;QACzB,CAAC,eAAe,EAAE,QAAQ,CAAC;KAC5B,CAAC,CAAC;IACH,OAAO;QACL,aAAa,CAAC,GAAW,EAAE,MAA0B;YACnD,MAAM,QAAQ,GAAG,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtE,OAAO,QAAQ,IAAI,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,MAAgB,CAAC,CAAC;QACnE,CAAC;KACsB,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,IAAI,GAAG,sBAAsB;IAC9E,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI;YACzC,kFAAkF,CACrF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CACnB,GAA0E;IAE1E,OAAO;QACL,KAAK,CAAC,KAAK,CAAkB,GAAW,EAAE,MAA2B;YACnE,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACtC,OAAO,MAAM,CAAC,IAAW,CAAC;QAC5B,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAW;YACvB,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAA0B;IAC7D,MAAM,MAAM,GAAG,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC;QACvB,gBAAgB,EAAE,QAAQ,CAAC,GAAG;QAC9B,GAAG,EAAE,QAAQ,CAAC,OAAO;QACrB,KAAK,EAAE,gBAAgB,EAAE;QACzB,0EAA0E;QAC1E,uDAAuD;QACvD,OAAO,EAAE,kCAAkC,MAAM,SAAS;KAC3D,CAAC,CAAC;IACH,8EAA8E;IAC9E,8EAA8E;IAC9E,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAE3B,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAElG,OAAO;QACL,GAAG,QAAQ;QACX,KAAK,CAAC,WAAW,CAAI,EAAwC;YAC3D,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC1B,MAAM,EAAE,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;gBAC5F,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC5B,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC3B,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;gBAC7C,MAAM,KAAK,CAAC;YACd,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,CAAC;QACH,CAAC;QACD,KAAK,CAAC,KAAK;YACT,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,34 @@
+import { type SessionMeta } from "@uptimizr/db";
+import { type AnyEvent } from "@uptimizr/schema";
+import type { PostgresClient } from "./client.js";
+export type { SessionMeta };
+/**
+ * Batched insert of validated events. Reuses the shared {@link toEventRow} mapper
+ * so the promoted columns match the DuckDB store exactly; `ts` is bound as the
+ * naive-UTC literal every engine accepts and `payload` lands in `jsonb`.
+ *
+ * `node_transform` events (ADR 0027) are split out into the dedicated
+ * `node_samples` table rather than the wide `events` table. Both inserts run in
+ * one transaction, so a batch is never partially applied.
+ */
+export declare function insertEvents(client: PostgresClient, events: readonly AnyEvent[]): Promise<void>;
+/**
+ * Ordered read of a single session's events for replay/timeline. Returns
+ * fully-parsed, schema-validated events in `ts` order, merging the wide `events`
+ * table with the dedicated `node_samples` table (ADR 0027 §9). Gated upstream by
+ * `ENABLE_RAW_SESSION_RETENTION` (ADR 0003) — this function does not enforce it.
+ */
+export declare function getSessionEvents(client: PostgresClient, projectId: string, sessionId: string): Promise<AnyEvent[]>;
+/**
+ * Streaming counterpart to {@link getSessionEvents}: yields one validated event
+ * at a time in `ts` order (the path behind the collector's NDJSON replay
+ * response, ADR 0015). The session is read as one ordered result set; node
+ * samples are merged in by `ts` before yielding.
+ */
+export declare function streamSessionEvents(client: PostgresClient, projectId: string, sessionId: string): AsyncGenerator<AnyEvent>;
+/**
+ * Read a session's stored metadata (`device`/`scene`/`user`) from its
+ * `session_start` event. Returns `null` when the session has no start event.
+ */
+export declare function getSessionMeta(client: PostgresClient, projectId: string, sessionId: string): Promise<SessionMeta | null>;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAkB,KAAK,QAAQ,EAA2B,MAAM,kBAAkB,CAAC;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,aAAa,CAAC;AAEpE,YAAY,EAAE,WAAW,EAAE,CAAC;AA8F5B;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,SAAS,QAAQ,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAiBf;AAkGD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAIrB;AAED;;;;;GAKG;AACH,wBAAuB,mBAAmB,CACxC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,QAAQ,CAAC,CAK1B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAqB7B"}