@jskit-ai/database-runtime-postgres 0.1.156 → 0.1.158

package/package.json

@@ -1,72 +1,34 @@
 {
   "name": "@jskit-ai/database-runtime-postgres",
-  "version": "0.1.156",
+  "version": "0.1.158",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "exports": {
     "./client": "./src/client/index.js",
-    "./server/providers/DatabaseRuntimePostgresServiceProvider": "./src/server/providers/DatabaseRuntimePostgresServiceProvider.js",
+    "./server/providers/PostgresDatabaseDriverProvider": "./src/server/providers/PostgresDatabaseDriverProvider.js",
     "./shared": "./src/shared/index.js",
     "./shared/dialect": "./src/shared/dialect.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.159"
+    "@jskit-ai/database-runtime": "0.1.161",
+    "pg": "^8.13.1"
   },
   "jskit": {
     "kind": "runtime",
-    "options": {
-      "db-host": {
-        "required": false,
-        "values": [],
-        "defaultValue": "localhost",
-        "promptLabel": "Database host",
-        "promptHint": "Postgres host (for example 127.0.0.1)"
-      },
-      "db-port": {
-        "required": false,
-        "values": [],
-        "defaultValue": "5432",
-        "promptLabel": "Database port",
-        "promptHint": "Postgres port (usually 5432)"
-      },
-      "db-name": {
-        "required": true,
-        "values": [],
-        "promptLabel": "Database name",
-        "promptHint": "Database name to connect to"
-      },
-      "db-user": {
-        "required": true,
-        "values": [],
-        "promptLabel": "Database user",
-        "promptHint": "Database username"
-      },
-      "db-password": {
-        "required": true,
-        "values": [],
-        "inputType": "password",
-        "promptLabel": "Database password",
-        "promptHint": "Database password"
-      }
-    },
     "capabilities": {
       "provides": [
-        "runtime.database.driver",
-        "runtime.database.driver.postgres"
+        "runtime.database.driver"
       ],
-      "requires": [
-        "runtime.database"
-      ]
+      "requires": []
     },
     "runtime": {
       "server": {
-        "providerEntrypoint": "src/server/providers/DatabaseRuntimePostgresServiceProvider.js",
         "providers": [
           {
-            "entrypoint": "src/server/providers/DatabaseRuntimePostgresServiceProvider.js",
-            "export": "DatabaseRuntimePostgresServiceProvider"
+            "entrypoint": "src/server/providers/PostgresDatabaseDriverProvider.js",
+            "export": "PostgresDatabaseDriverProvider"
           }
         ]
       },
@@ -79,7 +41,7 @@
         "surfaces": [
           {
             "subpath": "./server",
-            "summary": "Exports Postgres database runtime provider."
+            "summary": "Provides the exclusive runtime.database.driver capability for PostgreSQL."
           },
           {
             "subpath": "./shared",
@@ -89,115 +51,8 @@
             "subpath": "./client",
             "summary": "Exports no runtime API today (reserved client entrypoint)."
           }
-        ],
-        "containerTokens": {
-          "server": [
-            "runtime.database.driver.postgres"
-          ],
-          "client": []
-        }
+        ]
       }
-    },
-    "ci": {
-      "environment": {
-        "DB_CLIENT": "pg",
-        "DB_HOST": "127.0.0.1",
-        "DB_PORT": "54320",
-        "DB_NAME": "jskit_ci",
-        "DB_USER": "jskit_ci",
-        "DB_PASSWORD": "jskit_ci_only_password"
-      },
-      "services": [
-        {
-          "id": "postgres",
-          "image": "postgres:16",
-          "environment": {
-            "POSTGRES_DB": "jskit_ci",
-            "POSTGRES_USER": "jskit_ci",
-            "POSTGRES_PASSWORD": "jskit_ci_only_password"
-          },
-          "ports": [
-            "54320:5432"
-          ],
-          "healthCheck": {
-            "command": "pg_isready --username=jskit_ci --dbname=jskit_ci",
-            "interval": "10s",
-            "timeout": "5s",
-            "retries": 10
-          }
-        }
-      ],
-      "steps": []
-    },
-    "mutations": {
-      "dependencies": {
-        "runtime": {
-          "@jskit-ai/database-runtime": "0.1.159",
-          "pg": "^8.13.1"
-        },
-        "dev": {}
-      },
-      "packageJson": {
-        "scripts": {}
-      },
-      "procfile": {},
-      "files": [],
-      "text": [
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_CLIENT",
-          "value": "pg",
-          "reason": "Configure database client driver for runtime wiring.",
-          "category": "runtime-config",
-          "id": "database-client-postgres"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_HOST",
-          "value": "${option:db-host}",
-          "reason": "Configure database host.",
-          "category": "runtime-config",
-          "id": "database-host"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_PORT",
-          "value": "${option:db-port}",
-          "reason": "Configure database port.",
-          "category": "runtime-config",
-          "id": "database-port"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_NAME",
-          "value": "${option:db-name}",
-          "reason": "Configure database name.",
-          "category": "runtime-config",
-          "id": "database-name"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_USER",
-          "value": "${option:db-user}",
-          "reason": "Configure database user.",
-          "category": "runtime-config",
-          "id": "database-user"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_PASSWORD",
-          "value": "${option:db-password}",
-          "reason": "Configure database password.",
-          "category": "runtime-config",
-          "id": "database-password"
-        }
-      ]
     }
   }
 }

package/patterns/postgres-application/PATTERN.md

@@ -0,0 +1,80 @@
+---
+id: database/postgres-application
+title: PostgreSQL application database
+summary: Configure a JSKIT application for PostgreSQL with a fixed driver, ordinary environment values, and rebuildable Knex migrations.
+keywords: database, knex, migrations, pg, postgres, postgresql
+requires: @jskit-ai/database-runtime-postgres
+---
+
+# PostgreSQL application database
+
+## Use when
+
+Use this pattern when an application deliberately chooses PostgreSQL. Install
+`@jskit-ai/database-runtime-postgres`; its normal npm dependencies provide the
+database runtime, Knex, and `pg` without a package-setup wizard.
+
+## Do not use when
+
+Do not use this pattern for MySQL, a database-neutral library, or a service that
+does not own its database connection. Do not install both JSKIT drivers unless
+the application genuinely selects between them at runtime.
+
+## Product decisions
+
+Decide the database name, credentials, host, deployment secret source, backup
+policy, and application migrations. Those are application and environment
+decisions, not framework questions.
+
+## Invariants
+
+- The application depends directly on the selected JSKIT driver.
+- Credentials stay outside Git.
+- `knexfile.js` fixes `pg`; a single-driver application does not require
+  `DB_CLIENT`.
+- Schema changes are ordinary immutable migrations.
+- The current package graph, environment, and migrations are authoritative.
+
+## Framework APIs
+
+Use `createKnexMigrationConfigFromApp()` from
+`@jskit-ai/database-runtime/server/knexMigrationConfig`. The running JSKIT
+application automatically selects the sole installed database driver, while
+Knex discovers package-owned migrations from the installed dependency graph.
+
+## Example files
+
+`example/package.json` contains the runtime dependency and database scripts.
+`example/knexfile.js` loads an optional local `.env` and fixes the PostgreSQL
+dialect. `example/scripts/prepare-database.js` is the portable
+migrate-then-seed entrypoint for managed sessions and deployments.
+`example/.env.example` names the five connection values without a secret.
+
+## Variation points
+
+Change scripts, migration location, connection values, and secret injection to
+fit the application. Supply `DATABASE_URL` instead of individual values when
+the environment owns a URL. Add `DB_CLIENT=pg` only when a shared external tool
+explicitly needs a dialect selector. When the product needs initial data,
+import one idempotent app-owned seed function in `prepare-database.js` and pass
+it as `seed` to `prepareDatabaseFromApp()`.
+
+## Verification
+
+- Install dependencies once with `npm install`.
+- Run `npm run db:prepare` against a fresh disposable database.
+- Run `npm run db:migrate:status` and the application verification command.
+- Exercise one transaction and one negative connection case.
+- When a seed exists, run `db:prepare` twice and require the second run to be safe.
+
+`example/.github/workflows/verify.yml` is a normal app-owned CI workflow with
+an explicit PostgreSQL service. Adapt it as source rather than generating it
+from package metadata.
+
+## Avoid
+
+- framework questionnaires for credentials
+- generated `.env` secrets
+- depending on a live schema as the source contract
+- a second driver installed “just in case”
+- migration receipts, provenance, replay logs, or generator ownership

package/patterns/postgres-application/example/.env.example

@@ -0,0 +1,5 @@
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_NAME=application
+DB_USER=application
+DB_PASSWORD=replace-me

package/patterns/postgres-application/example/.github/workflows/verify.yml

@@ -0,0 +1,38 @@
+name: Verify
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: app_test
+          POSTGRES_USER: app_test
+          POSTGRES_PASSWORD: app_test_password
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U app_test -d app_test"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+    env:
+      DB_HOST: 127.0.0.1
+      DB_PORT: 5432
+      DB_NAME: app_test
+      DB_USER: app_test
+      DB_PASSWORD: app_test_password
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npm run db:migrate
+      - run: npm run verify

package/patterns/postgres-application/example/knexfile.js

@@ -0,0 +1,11 @@
+import { createKnexMigrationConfigFromApp } from "@jskit-ai/database-runtime/server/knexMigrationConfig";
+
+try {
+  process.loadEnvFile?.(".env");
+} catch (error) {
+  if (error?.code !== "ENOENT") {
+    throw error;
+  }
+}
+
+export default await createKnexMigrationConfigFromApp({ client: "pg" });

package/patterns/postgres-application/example/package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "db:prepare": "node ./scripts/prepare-database.js",
+    "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
+    "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
+    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+  },
+  "dependencies": {
+    "@jskit-ai/database-runtime-postgres": "0.1.158"
+  }
+}

package/patterns/postgres-application/example/scripts/prepare-database.js

@@ -0,0 +1,3 @@
+import { prepareDatabaseFromApp } from "@jskit-ai/database-runtime/server/databaseSetup";
+
+await prepareDatabaseFromApp({ client: "pg" });

package/src/server/providers/PostgresDatabaseDriverProvider.js

@@ -0,0 +1,16 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import * as postgresDriver from "../../shared/index.js";
+
+const PostgresDatabaseDriverProvider = defineProvider({
+  id: "runtime.database.driver.postgres",
+  provides: {
+    driver: "runtime.database.driver"
+  },
+  setup() {
+    return {
+      driver: Object.freeze({ ...postgresDriver })
+    };
+  }
+});
+
+export { PostgresDatabaseDriverProvider };

package/test/applicationPattern.test.js

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+const patternUrl = new URL("../patterns/postgres-application/", import.meta.url);
+
+test("PostgreSQL application pattern is driver-fixed and questionnaire-free", async () => {
+  const [document, manifestSource, knexfile] = await Promise.all([
+    readFile(new URL("PATTERN.md", patternUrl), "utf8"),
+    readFile(new URL("example/package.json", patternUrl), "utf8"),
+    readFile(new URL("example/knexfile.js", patternUrl), "utf8")
+  ]);
+  const manifest = JSON.parse(manifestSource);
+
+  assert.equal(manifest.dependencies["@jskit-ai/database-runtime-postgres"], "0.1.157");
+  assert.match(knexfile, /client: "pg"/u);
+  assert.doesNotMatch(`${document}\n${knexfile}`, /promptLabel|promptHint|\$\{option:/u);
+});

package/test/entrypoints.boundary.test.js

@@ -4,15 +4,15 @@ import test from "node:test";
 
 import * as clientApi from "../src/client/index.js";
 import * as sharedApi from "../src/shared/index.js";
-import { DatabaseRuntimePostgresServiceProvider } from "../src/server/providers/DatabaseRuntimePostgresServiceProvider.js";
+import { PostgresDatabaseDriverProvider } from "../src/server/providers/PostgresDatabaseDriverProvider.js";
 
 test("package exports include explicit shared and provider entrypoints", async () => {
   const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
   const exportsMap = packageJson && typeof packageJson === "object" ? packageJson.exports : {};
   assert.equal(exportsMap["./server"], undefined);
   assert.equal(
-    exportsMap["./server/providers/DatabaseRuntimePostgresServiceProvider"],
-    "./src/server/providers/DatabaseRuntimePostgresServiceProvider.js"
+    exportsMap["./server/providers/PostgresDatabaseDriverProvider"],
+    "./src/server/providers/PostgresDatabaseDriverProvider.js"
   );
   assert.equal(exportsMap["./shared"], "./src/shared/index.js");
 });
@@ -21,12 +21,13 @@ test("client entrypoint exports no postgres runtime api", () => {
   assert.deepEqual(Object.keys(clientApi), []);
 });
 
-test("server provider module exports postgres service provider only", () => {
-  assert.equal(typeof DatabaseRuntimePostgresServiceProvider, "function");
+test("server provider module exports the declarative postgres driver provider", () => {
+  assert.equal(PostgresDatabaseDriverProvider.id, "runtime.database.driver.postgres");
+  assert.deepEqual(PostgresDatabaseDriverProvider.provides, { driver: "runtime.database.driver" });
 });
 
 test("shared entrypoint exports postgres dialect helpers", () => {
   assert.equal(sharedApi.DIALECT_ID, "pg");
   assert.equal(sharedApi.getDialectId(), "pg");
-  assert.equal(typeof sharedApi.DatabaseRuntimePostgresServiceProvider, "undefined");
+  assert.equal(typeof sharedApi.PostgresDatabaseDriverProvider, "undefined");
 });

package/test/packageMetadata.test.js

@@ -1,24 +1,23 @@
 import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 import packageJson from "../package.json" with { type: "json" };
 
-const packageMetadata = packageJson.jskit;
-import { DIALECT_ID } from "../src/shared/dialect.js";
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
-test("database-runtime-postgres contributes canonical synthetic Postgres CI requirements", () => {
-  assert.equal(packageMetadata.ci.environment.DB_CLIENT, DIALECT_ID);
-  assert.equal(packageMetadata.ci.environment.DB_HOST, "127.0.0.1");
-  assert.equal(packageMetadata.ci.environment.DB_PORT, "54320");
-  assert.match(packageMetadata.ci.environment.DB_PASSWORD, /ci_only/u);
+test("database-runtime-postgres owns its driver while CI remains app-owned source", async () => {
+  const workflow = await readFile(
+    path.join(PACKAGE_ROOT, "patterns/postgres-application/example/.github/workflows/verify.yml"),
+    "utf8"
+  );
 
-  const service = packageMetadata.ci.services.find((entry) => entry.id === "postgres");
-  assert.equal(service.image, "postgres:16");
-  assert.equal(service.environment.POSTGRES_DB, packageMetadata.ci.environment.DB_NAME);
-  assert.equal(service.environment.POSTGRES_USER, packageMetadata.ci.environment.DB_USER);
-  assert.equal(service.environment.POSTGRES_PASSWORD, packageMetadata.ci.environment.DB_PASSWORD);
-  assert.deepEqual(service.ports, ["54320:5432"]);
-  assert.match(service.healthCheck.command, /pg_isready/u);
-
-  const clientMutation = packageMetadata.mutations.text.find((entry) => entry.key === "DB_CLIENT");
-  assert.equal(clientMutation.value, DIALECT_ID);
+  assert.equal(packageJson.dependencies.pg, "^8.13.1");
+  assert.equal(Object.hasOwn(packageJson.jskit, "options"), false);
+  assert.equal(Object.hasOwn(packageJson.jskit, "mutations"), false);
+  assert.equal(Object.hasOwn(packageJson.jskit, "ci"), false);
+  assert.match(workflow, /image: postgres:17/u);
+  assert.match(workflow, /npm run db:migrate/u);
+  assert.match(workflow, /npm run verify/u);
 });

package/test/providerRuntime.test.js

@@ -1,33 +1,23 @@
-import test from "node:test";
 import assert from "node:assert/strict";
-import { DatabaseRuntimePostgresServiceProvider } from "../src/server/providers/DatabaseRuntimePostgresServiceProvider.js";
+import test from "node:test";
 
-function createSingletonApp() {
-  const singletons = new Map();
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { PostgresDatabaseDriverProvider } from "../src/server/providers/PostgresDatabaseDriverProvider.js";
 
-  return {
-    has(token) {
-      return singletons.has(token);
-    },
-    singleton(token, factory) {
-      singletons.set(token, factory(this));
-    },
-    make(token) {
-      if (!singletons.has(token)) {
-        throw new Error(`Token ${String(token)} is not registered.`);
-      }
-      return singletons.get(token);
+test("PostgresDatabaseDriverProvider provides the exclusive database driver capability", async () => {
+  let driver;
+  const consumer = defineProvider({
+    id: "test.postgres.consumer",
+    requires: { databaseDriver: "runtime.database.driver" },
+    setup({ databaseDriver }) {
+      driver = databaseDriver;
+      return {};
     }
-  };
-}
-
-test("DatabaseRuntimePostgresServiceProvider registers postgres driver api", () => {
-  const app = createSingletonApp();
-  const provider = new DatabaseRuntimePostgresServiceProvider();
-  provider.register(app);
+  });
+  const runtime = createCapabilityRuntime({ providers: [PostgresDatabaseDriverProvider, consumer] });
 
-  assert.equal(app.has("runtime.database.driver.postgres"), true);
-  const api = app.make("runtime.database.driver.postgres");
-  assert.equal(api.DIALECT_ID, "pg");
-  assert.equal(api.getDialectId(), "pg");
+  await runtime.start();
+  assert.equal(driver.DIALECT_ID, "pg");
+  assert.equal(driver.getDialectId(), "pg");
+  await runtime.shutdown();
 });

package/src/server/providers/DatabaseRuntimePostgresServiceProvider.js

@@ -1,21 +0,0 @@
-import * as postgresDialect from "../../shared/index.js";
-
-const POSTGRES_DATABASE_DRIVER_API = Object.freeze({
-  ...postgresDialect
-});
-
-class DatabaseRuntimePostgresServiceProvider {
-  static id = "runtime.database.driver.postgres";
-
-  register(app) {
-    if (!app || typeof app.singleton !== "function") {
-      throw new Error("DatabaseRuntimePostgresServiceProvider requires application singleton().");
-    }
-
-    app.singleton("runtime.database.driver.postgres", () => POSTGRES_DATABASE_DRIVER_API);
-  }
-
-  boot() {}
-}
-
-export { DatabaseRuntimePostgresServiceProvider };