@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.6

package/docs/handbook/start/project-and-cli.md

@@ -51,7 +51,7 @@ refused (exit 2), so switching never drops tables or orphans data. Change
 | | `cloudflare` | `bun` | `none` |
 |---|---|---|---|
 | `sqlite` | preset over D1 (the default) | native bun:sqlite | plan and types only |
-| `postgres` | preset over Hyperdrive and `pg` | native Bun.SQL PostgreSQL pool | plan and types only |
+| `postgres` | preset over Hyperdrive and `pg` | preset over a `pg.Pool` (node-postgres) | plan and types only |
 | a dialect package | plan and types only; compose `src/service.ts` with its storage adapter | plan and types only | plan and types only |
 
 Each selection needs packages in the project. `mantle generate` checks them
@@ -72,13 +72,14 @@ it a supported combination; inspect peer warnings before starting the service.
 | identity `mantle` | `better-auth`, `@better-auth/oauth-provider`, `@better-auth/mcp`, `@better-auth/cimd` |
 | feature `mcp` | `@modelcontextprotocol/server`, `@modelcontextprotocol/ext-apps` |
 | feature `admin` | `@aotter/mantle-ui` (its `dist/admin` is the console, bound as `ASSETS` in `wrangler.jsonc`) |
-| dialect `postgres` on `cloudflare` | `pg` |
+| dialect `postgres` (host `cloudflare` or `bun`) | `pg` |
 | host `bun` | `bun-types` |
 | feature `mcp` with an identity, without `admin` | `@aotter/mantle-ui` (the staff MCP App) |
 
 On Cloudflare the project also installs `wrangler`, `@cloudflare/workers-types` and
-`@types/node` itself. A TypeScript Cloudflare/PostgreSQL project also installs
-`@types/pg` as a dev dependency for the generated `pg` import.
+`@types/node` itself. A TypeScript PostgreSQL project, on Cloudflare or Bun, also installs
+`@types/pg` as a dev dependency for the generated `pg` import; node-postgres is
+the PostgreSQL driver on every host.
 
 ## `mantle generate`
 
@@ -121,7 +122,7 @@ diff without applying it, for the `sqlite` dialect; see [Deploy and operate](../
 ### PostgreSQL on Cloudflare
 
 `mantle generate --dialect postgres` writes the same preset over Hyperdrive:
-`src/service.ts` opens a `pg` client per operation from `env.HYPERDRIVE`, and
+`src/service.ts` opens one `pg` client per request from `env.HYPERDRIVE`, and
 `wrangler.jsonc` binds `HYPERDRIVE` with a placeholder id and a
 `localConnectionString` for `wrangler dev`. Before deploying, create the config
 with caching off and put its id in place of the placeholder; generate warns
@@ -131,6 +132,14 @@ until you do:
 wrangler hyperdrive create my-app --caching-disabled --connection-string="postgres://user:pass@host:5432/db"
 ```
 
+Reads run under the role's own statement limit, so give it one, and UTC, before
+the first boot (locally too); the boot error names any other setting:
+
+```sql
+ALTER ROLE app SET statement_timeout = '10s';
+ALTER ROLE app SET TimeZone = 'UTC';
+```
+
 ## 0.1.x projects
 
 `apiVersion: cms.mantle.aotter.net/v1` manifests, a `version: 1` config, `mantle validate`,
@@ -143,16 +152,15 @@ wrangler hyperdrive create my-app --caching-disabled --connection-string="postgr
 for the generated project's typecheck, the selected feature/identity packages,
 then set DATABASE_URL in `.env` and run `bun src/index.ts`. For SQLite pass
 `--dialect sqlite` and optionally DATABASE_FILE (default mantle.sqlite).
-The preset is written once, uses native drivers from `@aotter/mantle/bun`, and
+The preset is written once, uses `pg` for PostgreSQL and bun:sqlite for SQLite (`@aotter/mantle/bun`), and
 owns Bun.serve, trusted socket IP and shutdown/background work. Admin binds the
 installed UI bundle. Enabled schedule Triggers fail generation; use `host: none`
 with an explicit scheduler when schedules are required. Behind a reverse proxy,
 set TRUSTED_PROXIES to its addresses: otherwise every client shares the proxy's
 address, and with it one sign-in rate limit.
 
-PostgreSQL pools must set `prepare: false`: Bun otherwise re-encodes JSON strings,
-and the role needs TEMPORARY on the database (`GRANT TEMPORARY ON DATABASE app TO
-app_role`), which describing a result takes.
-Mantle refuses another setting. Native raw result metadata comes from PostgreSQL
-with three extra round trips per result, preserving microseconds and exact numeric
-scale. No pg dependency or PostgreSQL clone is added. See ADR-0038.
+PostgreSQL on Bun is node-postgres, as on Workers (ADR-0039): the entry builds a
+`pg.Pool` with `pipeline: true`, and each request borrows one pooled client
+(`requestScoped`). Install `pg`. The role needs no privilege beyond converging its
+tables (no `TEMPORARY`); set `statement_timeout` and `TimeZone` UTC on the role,
+which boot checks.

package/docs/skills/develop/SKILL.md

@@ -47,7 +47,11 @@ Choose in this order, stopping at the first that works:
 
 ## SQL rules that trip agents
 
-- PostgreSQL syntax over declared Schemas only. References: `input.<name>`,
+- SQL over declared Schemas only, in the project's own dialect: PostgreSQL's
+  syntax on PostgreSQL, a SQLite subset on D1. Each dialect is its own target:
+  a manifest need not compile for the other, and a SQLite spelling such as
+  `json_each` or `->> '$.a'` is refused on PostgreSQL with the PostgreSQL one
+  (rewrite table: `docs/handbook/concepts/runtime-and-adapters.md`). References: `input.<name>`,
   `auth.uid()`, `auth.role()`, `now()`; search is `mantle.search(t, q)`.
 - Native columns are snake_case in SQL (`created_at`, `author_id`) and
   camelCase in `ctx.store` JSON and in `indexes`.
@@ -60,7 +64,9 @@ Choose in this order, stopping at the first that works:
 - `LIMIT` needs `ORDER BY`. No `OFFSET`, `RIGHT JOIN` or `CURRENT_TIMESTAMP`
   on any dialect. On SQLite (D1) also no `WITH`, `UNION`, `ILIKE` or jsonb
   operators, and `CAST(x AS int)` only on an integer literal: use `round(x)`.
-  PostgreSQL accepts these (`docs/handbook/reference/view.md`).
+  PostgreSQL accepts these (`docs/handbook/reference/view.md`). On PostgreSQL
+  unnest with `jsonb_array_elements_text(t.col) WITH ORDINALITY AS j(value, n)`,
+  not `json_each`; unstated `NULLS` follow PostgreSQL (last ascending).
 - Unquoted aliases fold to lower case: `AS "orderCount"` keeps the case.
 - The runtime injects scope and TTL into every Schema reference, and
   published-only into public Views. Never repeat them.

package/docs/skills/provision/SKILL.md

@@ -47,7 +47,10 @@ Confirm the active Cloudflare account with the user before creating anything.
    `pnpm exec wrangler hyperdrive create <name> --caching-disabled --connection-string=...`
    (the connection string by hidden input) and replace the placeholder id in
    `hyperdrive[0]`, keeping the binding `HYPERDRIVE`. An existing 0.1.x
-   database is never reused: 0.2 starts on a new one.
+   database is never reused: 0.2 starts on a new one. PostgreSQL uses
+   node-postgres on every host (Hyperdrive on Cloudflare, a `pg.Pool` on Bun);
+   set `statement_timeout` (10s or less) and `TimeZone` `UTC` on the database
+   role, which boot checks on both.
 2. **Origin.** Set `PUBLIC_ORIGIN` in `vars` to the deployed HTTPS origin.
    Update it together with any OAuth callback when a custom domain is added.
 3. **Sign-in (identity `mantle`).** Choose one production method and edit

package/docs/skills/update/SKILL.md

@@ -41,6 +41,9 @@ pnpm exec mantle generate --check
 pnpm exec tsc --noEmit
 ```
 
+   An existing PostgreSQL service also follows the upgrade notes in
+   `docs/handbook/releases/index.md` (SQL rewrites, `mantle generate` for the
+   new dialect version, the regenerated `src/service.ts`).
 6. The preset (`src/service.ts`, `src/index.ts`, `src/handlers.ts`,
    `wrangler.jsonc`) is never
    rewritten. Generate into a scratch directory with the same manifests and

package/docs/upgrade-0.1-to-0.2.md

@@ -50,7 +50,7 @@ command; it never installs anything.
 - `features` is a subset of `mcp`, `admin`, `web`, in that order. The 0.1.x
   features `spec`, `runtime` and `api` are dropped: REST is always mounted.
 - `dialect` is `sqlite` (alias `d1`, the default, left out) or `postgres`
-  (PostgreSQL through Hyperdrive on `cloudflare`; Bun.SQL on `bun`, where it
+  (PostgreSQL through Hyperdrive on `cloudflare`; node-postgres on `bun`, where it
   is the default). A 0.1.x project was SQLite: keep `sqlite` (with
   `--host bun`, pass `--dialect sqlite`) unless the data also moves to
   PostgreSQL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.6",
   "description": "Mantle: a manifest-driven service core. Store authored as SQL, surfaces as Fetch functions, and the mantle CLI.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -84,8 +84,8 @@
     "@pgsql/types": "18.0.0",
     "libpg-query": "18.1.5",
     "pgsql-deparser": "18.3.8",
-    "yaml": "^2.9.0",
-    "zod": "^4.5.4",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5",
     "semver": "^7.8.5"
   },
   "devDependencies": {
@@ -103,8 +103,9 @@
     "bun-types": "1.3.14",
     "pg": "8.23.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
-    "wrangler": "4.126.0",
+    "vitest": "^5.0.1",
+    "@cloudflare/workers-types": "^5.20261008.1",
+    "wrangler": "4.137.0",
     "@types/semver": "^7.7.1"
   },
   "peerDependencies": {

package/dist/postgres/textRows.d.ts

@@ -1,10 +0,0 @@
-/** Result description for transports without RowDescription (Bun.SQL).
- * PostgreSQL describes an unexecuted query through CREATE TEMP TABLE AS ... WITH NO DATA.
- * It owns OIDs/typmods, including CASE, COALESCE, CTEs and planner-folded expressions.
- */
-import type { SqlNode as N } from '../spec/domain/index.js';
-export declare function describeResult(ast: N): {
-    query: string;
-    names: string[] | undefined;
-} | undefined;
-//# sourceMappingURL=textRows.d.ts.map

package/dist/postgres/textRows.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"textRows.d.ts","sourceRoot":"","sources":["../../src/postgres/textRows.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,CAAC,EAAE,MAAM,yBAAyB,CAAC;AAgB5D,wBAAgB,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,CAUjG"}

package/dist/postgres/textRows.js

@@ -1,44 +0,0 @@
-import { print } from './print.js';
-/** PostgreSQL parse_target.c FigureColname rules for the closed Mantle expression grammar. */
-function outputName(n) {
-    if (!n)
-        return ['?column?', 0];
-    if (n.ColumnRef)
-        return [n.ColumnRef.fields.filter((f) => f.String).at(-1)?.String.sval ?? '?column?', 2];
-    if (n.FuncCall)
-        return [n.FuncCall.funcname.at(-1).String.sval, 2];
-    if (n.CoalesceExpr)
-        return ['coalesce', 2];
-    if (n.MinMaxExpr)
-        return [n.MinMaxExpr.op === 'IS_GREATEST' ? 'greatest' : 'least', 2];
-    if (n.A_Expr?.kind === 'AEXPR_NULLIF')
-        return ['nullif', 2];
-    if (n.TypeCast) {
-        const inner = outputName(n.TypeCast.arg);
-        return inner[1] > 1 ? inner : [n.TypeCast.typeName.names.at(-1).String.sval, 1];
-    }
-    if (n.CaseExpr) {
-        const inner = outputName(n.CaseExpr.defresult);
-        return inner[1] > 1 ? inner : ['case', 1];
-    }
-    if (n.SubLink?.subLinkType === 'EXISTS_SUBLINK')
-        return ['exists', 2];
-    if (n.SubLink?.subLinkType === 'EXPR_SUBLINK') {
-        const t = n.SubLink.subselect?.SelectStmt?.targetList?.[0]?.ResTarget;
-        return t?.name ? [t.name, 2] : outputName(t?.val);
-    }
-    return ['?column?', 0];
-}
-export function describeResult(ast) {
-    const body = ast.SelectStmt ?? ast.InsertStmt ?? ast.UpdateStmt ?? ast.DeleteStmt;
-    const targets = ast.SelectStmt ? body.targetList : body?.returningClause?.exprs;
-    if (!targets?.length)
-        return undefined;
-    // `*` and `t.*` expand to columns only PostgreSQL knows: name none, so each column keeps its own name
-    const star = targets.some((t) => t.ResTarget.val?.ColumnRef?.fields?.at(-1)?.A_Star);
-    return {
-        query: ast.SelectStmt ? print(ast) : `WITH _mantle_result AS (${print(ast)}) SELECT * FROM _mantle_result`,
-        names: star ? undefined : targets.map((t) => t.ResTarget.name ?? outputName(t.ResTarget.val)[0]),
-    };
-}
-//# sourceMappingURL=textRows.js.map

package/dist/postgres/textRows.js.map

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