@jskit-ai/database-runtime 0.1.263 → 0.1.264

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ - `./server/testDatabases` exports `createPackageTestKnex(t, { environment })`, the Knex a package's own data test runs on when it creates its tables in the test: an in-memory SQLite database, or on a `DB_CLIENT=pg` run a schema of the test's own in `TEST_DB_NAME` (on DB_HOST, DB_PORT, DB_USER and DB_PASSWORD), in UTC, with a pool of up to eight connections for concurrent transactions, dropped with everything in it after the test. It refuses `NODE_ENV=production`, and a pg run without `TEST_DB_NAME` fails (`TestDatabaseMissingError`).
6
+ - `listForeignKeys(knex)` (`./server/foreignKeyMigrations`) answers every foreign key of the connected database's tables in one statement, each with its table, its columns in order and the table and columns it references, on MySQL, MariaDB, PostgreSQL (the current schema) and SQLite (whose keys have no name). `testDatabaseRun` takes `checkDatabase(knex)`, run once on the prepared `TEST_DB_NAME` before any test file: its answer joins the summary and a throw fails the run.
5
7
  - `@jskit-ai/database-runtime-mysql` and `@jskit-ai/database-runtime-postgres` take `@jskit-ai/database-runtime` as a required peer at the same version, where it was a dependency, as `@jskit-ai/resource-runtime` and `@jskit-ai/crud-core` do: the application declares it beside its driver (`npm install @jskit-ai/database-runtime @jskit-ai/database-runtime-mysql`) and holds its one copy. npm installs a required peer as it installed the dependency.
6
8
  - **Breaking (data-access redesign).** `./shared/visibility` is removed (`applyVisibility`, `applyVisibilityOwners`, `DEFAULT_VISIBILITY_COLUMNS`, also re-exported from `./shared`): a table resource declares its `ownership`, and every handle statement is scoped by it. `./shared` and `./shared/repositoryOptions` no longer export `applyForUpdate`, `createWithTransaction`, `joinOrOpenTransaction`, `lockScopedRecordId`, `resolveQueryOptions`, `resolveRepoClient`, `resolveTransaction` and `runInTransaction`: a transaction is the table handle's `withTransaction(options, work)`, a row lock its `lock` or `lockMany`, and a call's client and transaction ride in the `options` it passes on. The Before | Now table in the existing-application migration guide maps each one.
7
9
  - `./server/testDatabases` exports `requireTestDatabase(environment)`, which answers `TEST_DB_NAME` and throws `TestDatabaseMissingError` without it, so a data test fails instead of skipping, and `tableNames(knex)`, the tables of the test database.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jskit-ai/database-runtime",
3
- "version": "0.1.263",
3
+ "version": "0.1.264",
4
4
  "type": "module",
5
5
  "scripts": {
6
6
  "test": "jskit test"
@@ -63,11 +63,11 @@
63
63
  },
64
64
  {
65
65
  "subpath": "./server/foreignKeyMigrations",
66
- "summary": "Adds a single-column foreign key only when it is missing, refusing rows without a parent, for constraints migrations on fresh and already-migrated databases."
66
+ "summary": "Adds a single-column foreign key only when it is missing, refusing rows without a parent, for constraints migrations on fresh and already-migrated databases, and lists every foreign key the connected database holds."
67
67
  },
68
68
  {
69
69
  "subpath": "./server/testDatabases",
70
- "summary": "Gives each test file or browser worker running at once its own disposable copy of TEST_DB_NAME or BROWSER_TEST_DB_NAME, restored from a schema snapshot keyed by the migrations' names and contents (MySQL, MariaDB and PostgreSQL), and counts the statements a piece of work sends, for query-count guards."
70
+ "summary": "Gives each test file or browser worker running at once its own disposable copy of TEST_DB_NAME or BROWSER_TEST_DB_NAME, restored from a schema snapshot keyed by the migrations' names and contents (MySQL, MariaDB and PostgreSQL), counts the statements a piece of work sends, for query-count guards, and gives a package's own data test its Knex: SQLite in memory, or a PostgreSQL schema of its own on a DB_CLIENT=pg run (createPackageTestKnex)."
71
71
  },
72
72
  {
73
73
  "subpath": "./shared",
@@ -82,6 +82,6 @@
82
82
  }
83
83
  },
84
84
  "peerDependencies": {
85
- "@jskit-ai/kernel": "0.2.14"
85
+ "@jskit-ai/kernel": "0.2.15"
86
86
  }
87
87
  }
@@ -119,4 +119,67 @@ async function dropForeignKeyIfPresent(knex, key) {
119
119
  return true;
120
120
  }
121
121
 
122
- export { addMissingForeignKey, dropForeignKeyIfPresent, hasForeignKey };
122
+ // Every foreign key of the connected database's tables, one row per column: the key's name, its table and column,
123
+ // the referenced table and column, and the column's place in the key. Keys to another schema are left out.
124
+ const FOREIGN_KEY_COLUMNS = Object.freeze({
125
+ mysql: `SELECT CONSTRAINT_NAME AS name, TABLE_NAME AS tableName, COLUMN_NAME AS columnName,
126
+ REFERENCED_TABLE_NAME AS referencedTableName, REFERENCED_COLUMN_NAME AS referencedColumnName
127
+ FROM information_schema.KEY_COLUMN_USAGE
128
+ WHERE TABLE_SCHEMA = DATABASE() AND REFERENCED_TABLE_SCHEMA = DATABASE()
129
+ ORDER BY TABLE_NAME, CONSTRAINT_NAME, ORDINAL_POSITION`,
130
+ postgres: `SELECT c.conname AS name, t.relname AS "tableName", a.attname AS "columnName",
131
+ r.relname AS "referencedTableName", p.attname AS "referencedColumnName"
132
+ FROM pg_constraint c
133
+ JOIN pg_class t ON t.oid = c.conrelid
134
+ JOIN pg_class r ON r.oid = c.confrelid
135
+ CROSS JOIN LATERAL unnest(c.conkey, c.confkey) WITH ORDINALITY AS k(attnum, refnum, position)
136
+ JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum
137
+ JOIN pg_attribute p ON p.attrelid = c.confrelid AND p.attnum = k.refnum
138
+ WHERE c.contype = 'f' AND t.relnamespace = to_regnamespace(current_schema()) AND r.relnamespace = t.relnamespace
139
+ ORDER BY t.relname, c.conname, k.position`,
140
+ // SQLite keys have no name: each is told apart by its table and id.
141
+ sqlite: `SELECT m.name || '#' || k.id AS name, m.name AS tableName, k."from" AS columnName,
142
+ k."table" AS referencedTableName, k."to" AS referencedColumnName
143
+ FROM sqlite_master m JOIN pragma_foreign_key_list(m.name) k
144
+ WHERE m.type = 'table'
145
+ ORDER BY m.name, k.id, k.seq`
146
+ });
147
+
148
+ // The rows of a raw statement, as each driver answers them.
149
+ const RAW_ROWS = Object.freeze({
150
+ mysql: ([rows]) => rows,
151
+ postgres: ({ rows }) => rows,
152
+ sqlite: (rows) => rows
153
+ });
154
+
155
+ /**
156
+ * The foreign keys the connected database holds, each with its table, its columns in order, and the table and
157
+ * columns it references. A SQLite key's name is "", since SQLite keeps none.
158
+ * @param {import("./types.js").RuntimeKnex} knex
159
+ * @returns {Promise<Array<{ name: string, tableName: string, columns: string[], referencedTableName: string, referencedColumns: string[] }>>}
160
+ */
161
+ async function listForeignKeys(knex) {
162
+ const detected = detectDialectFromClient(knex);
163
+ const dialect = detected.includes("sqlite") ? "sqlite" : detected;
164
+ if (!Object.hasOwn(FOREIGN_KEY_COLUMNS, dialect)) {
165
+ throw new Error(`Listing foreign keys does not support the ${detected || "unknown"} dialect.`);
166
+ }
167
+ const keys = new Map();
168
+ for (const row of RAW_ROWS[dialect](await knex.raw(FOREIGN_KEY_COLUMNS[dialect]))) {
169
+ const id = `${row.tableName}\u0000${row.name}`;
170
+ if (!keys.has(id)) {
171
+ keys.set(id, {
172
+ name: dialect === "sqlite" ? "" : row.name,
173
+ tableName: row.tableName,
174
+ columns: [],
175
+ referencedTableName: row.referencedTableName,
176
+ referencedColumns: []
177
+ });
178
+ }
179
+ keys.get(id).columns.push(row.columnName);
180
+ keys.get(id).referencedColumns.push(row.referencedColumnName);
181
+ }
182
+ return [...keys.values()];
183
+ }
184
+
185
+ export { addMissingForeignKey, dropForeignKeyIfPresent, hasForeignKey, listForeignKeys };
@@ -22,13 +22,13 @@
22
22
  // of a server the test booted, countRuntimeQueries(); expectFlatQueries() in @jskit-ai/resource-runtime/test compares
23
23
  // those counts at a few rows and at many. A data test never skips: requireTestDatabase() fails it when TEST_DB_NAME is
24
24
  // not set.
25
- import { createHash } from "node:crypto";
25
+ import { createHash, randomBytes } from "node:crypto";
26
26
  import diagnosticsChannel from "node:diagnostics_channel";
27
27
  import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
28
28
  import os from "node:os";
29
29
  import path from "node:path";
30
30
  import { fileURLToPath } from "node:url";
31
- import { parseDatabaseUrl } from "../shared/databaseConnection.js";
31
+ import { parseDatabaseUrl, resolveKnexConnectionFromEnvironment, resolveKnexPool } from "../shared/databaseConnection.js";
32
32
  import { detectDialectFromClient } from "../shared/dialect.js";
33
33
  import { RUNTIME_QUERY_CHANNEL } from "./database.js";
34
34
  import { loadKnexFactory } from "./knexFactory.js";
@@ -482,8 +482,10 @@ function refusedPrivilege(error) {
482
482
  * @param {number} options.count How many test files run at once: at most the run's test budget.
483
483
  * @param {TestDatabaseSchema} [options.schema]
484
484
  * @param {string} [options.appRoot]
485
+ * @param {(knex: import("knex").Knex) => Promise<string>} [options.checkDatabase] Runs once on the prepared TEST_DB_NAME,
486
+ * before any test file: what it answers joins the summary, and a throw fails the run.
485
487
  */
486
- async function testDatabaseRun({ knexConfig, environment, count, schema, appRoot = process.cwd() }) {
488
+ async function testDatabaseRun({ knexConfig, environment, count, schema, appRoot = process.cwd(), checkDatabase }) {
487
489
  const oneAtATime = (reason) => ({
488
490
  concurrency: 1,
489
491
  env: {},
@@ -503,6 +505,7 @@ async function testDatabaseRun({ knexConfig, environment, count, schema, appRoot
503
505
  if (!refusedPrivilege(error)) throw error;
504
506
  return oneAtATime(`the database user may not prepare ${testDatabase} (${error.code})`);
505
507
  }
508
+ const checked = checkDatabase ? await withKnex(knexConfig, prepared.databases[0], checkDatabase) : "";
506
509
  // mkdtemp makes the directory for this user alone; the settings file holds the connection password.
507
510
  const directory = mkdtempSync(path.join(os.tmpdir(), "jskit-test-databases-"));
508
511
  const { client, connection, migrations } = knexConfig;
@@ -516,7 +519,7 @@ async function testDatabaseRun({ knexConfig, environment, count, schema, appRoot
516
519
  concurrency: prepared.databases.length,
517
520
  env: { JSKIT_TEST_DATABASES: directory },
518
521
  preload: TEST_DATABASE_FILE,
519
- summary: prepared.summary,
522
+ summary: `${prepared.summary}${checked ? `; ${checked}` : ""}`,
520
523
  cleanup: () => rmSync(directory, { recursive: true, force: true })
521
524
  };
522
525
  }
@@ -597,6 +600,55 @@ function requireTestDatabase(environment) {
597
600
  return name;
598
601
  }
599
602
 
603
+ // A package test's PostgreSQL connections: enough for the concurrent transactions a lock or race test opens at once.
604
+ const PACKAGE_TEST_POOL = Object.freeze({ min: 0, max: 8 });
605
+
606
+ /**
607
+ * The Knex a package's own data test runs on, for a test that creates its own tables: an in-memory SQLite database,
608
+ * or, on a run whose DB_CLIENT is pg, a schema of the test's own in TEST_DB_NAME on the server DB_HOST, DB_PORT,
609
+ * DB_USER and DB_PASSWORD name, its sessions in UTC as an application's are. So one test file proves its data paths on
610
+ * both: the PostgreSQL run of the same files is the proof of the row locks, the many-row writes and the upserts there.
611
+ * The Knex is destroyed after the test, and the schema dropped with everything in it. A pg run without TEST_DB_NAME
612
+ * fails (TestDatabaseMissingError), as every data test does; `knex.client.config.client` tells a test which it got.
613
+ * @param {{ after(cleanup: () => unknown): unknown }} context The test's context (node:test's `t`).
614
+ * @param {{ environment: import("@jskit-ai/kernel/server/types").RuntimeEnv }} options The test's environment, such as
615
+ * `process.env`.
616
+ * @returns {Promise<import("knex").Knex>}
617
+ */
618
+ async function createPackageTestKnex(context, { environment }) {
619
+ const knexFactory = loadKnexFactory();
620
+ if (String(environment.DB_CLIENT || "").trim() !== "pg") {
621
+ const knex = knexFactory({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
622
+ context.after(() => knex.destroy());
623
+ return knex;
624
+ }
625
+ if (environment.NODE_ENV === "production") {
626
+ throw new Error("Package data tests never run with NODE_ENV=production.");
627
+ }
628
+ const connection = {
629
+ ...resolveKnexConnectionFromEnvironment(environment, { client: "pg", defaultPort: 5432 }),
630
+ database: requireTestDatabase(environment)
631
+ };
632
+ const schema = `jskit_test_${process.pid}_${randomBytes(6).toString("hex")}`;
633
+ const admin = knexFactory({ client: "pg", connection, pool: { min: 0, max: 1 } });
634
+ try {
635
+ await admin.raw("CREATE SCHEMA ??", [schema]);
636
+ } catch (error) {
637
+ await admin.destroy();
638
+ throw error;
639
+ }
640
+ const knex = knexFactory({ client: "pg", connection, searchPath: [schema], pool: { ...resolveKnexPool("pg"), ...PACKAGE_TEST_POOL } });
641
+ context.after(async () => {
642
+ try {
643
+ await knex.destroy();
644
+ await admin.raw("DROP SCHEMA IF EXISTS ?? CASCADE", [schema]);
645
+ } finally {
646
+ await admin.destroy();
647
+ }
648
+ });
649
+ return knex;
650
+ }
651
+
600
652
  /**
601
653
  * The tables of the database `knex` is connected to, sorted: MySQL's and MariaDB's base tables, PostgreSQL's in the
602
654
  * current schema, SQLite's own tables (its internal ones aside).
@@ -621,6 +673,7 @@ export {
621
673
  RUN_SETTINGS_FILE,
622
674
  TestDatabaseMissingError,
623
675
  countQueries,
676
+ createPackageTestKnex,
624
677
  countRuntimeQueries,
625
678
  matchesSnapshot,
626
679
  prepareTestDatabases,
@@ -12,8 +12,6 @@
12
12
  * contract; `runtime.database` reads its dialect from it.
13
13
  * @typedef {object} RuntimeDatabaseDriver
14
14
  * @property {string} DIALECT_ID The dialect id: "mysql2" or "pg".
15
- * @property {(knex: RuntimeKnex, options?: { tableName?: string, idColumn?: string }) => Promise<object>} [introspectCrudTableSnapshot]
16
- * Reads a table's columns for CRUD generation; the MySQL driver has it.
17
15
  */
18
16
 
19
17
  export {};
@@ -4,7 +4,8 @@ import knexFactory from "knex";
4
4
  import {
5
5
  addMissingForeignKey,
6
6
  dropForeignKeyIfPresent,
7
- hasForeignKey
7
+ hasForeignKey,
8
+ listForeignKeys
8
9
  } from "../src/server/foreignKeyMigrations.js";
9
10
 
10
11
  // Runs in a disposable PostgreSQL schema of the test database: run with DB_NAME set to TEST_DB_NAME
@@ -90,3 +91,23 @@ test("PostgreSQL foreign key helpers find and drop a key by the name the databas
90
91
  assert.equal(await keyCount(knex), 0);
91
92
  assert.equal(await hasForeignKey(knex, KEY), false);
92
93
  });
94
+
95
+ test("listForeignKeys on PostgreSQL answers the schema's keys, each column of a key in order", { skip: SKIP }, async (t) => {
96
+ const knex = await testDatabase(t);
97
+ await knex.raw("ALTER TABLE children ADD CONSTRAINT children_parent_link FOREIGN KEY (parent_id) REFERENCES parents (id)");
98
+ await knex.schema.createTable("pairs", (table) => {
99
+ table.integer("a");
100
+ table.integer("b");
101
+ table.primary(["a", "b"]);
102
+ });
103
+ await knex.schema.createTable("pair_links", (table) => {
104
+ table.integer("pair_b");
105
+ table.integer("pair_a");
106
+ table.foreign(["pair_b", "pair_a"], "pair_links_pair_fk").references(["b", "a"]).inTable("pairs");
107
+ });
108
+
109
+ assert.deepEqual(await listForeignKeys(knex), [
110
+ { name: "children_parent_link", tableName: "children", columns: ["parent_id"], referencedTableName: "parents", referencedColumns: ["id"] },
111
+ { name: "pair_links_pair_fk", tableName: "pair_links", columns: ["pair_b", "pair_a"], referencedTableName: "pairs", referencedColumns: ["b", "a"] }
112
+ ]);
113
+ });
@@ -4,7 +4,8 @@ import knexFactory from "knex";
4
4
  import {
5
5
  addMissingForeignKey,
6
6
  dropForeignKeyIfPresent,
7
- hasForeignKey
7
+ hasForeignKey,
8
+ listForeignKeys
8
9
  } from "../src/server/foreignKeyMigrations.js";
9
10
 
10
11
  const KEY = { tableName: "children", columnName: "parent_id", parentTable: "parents", onDelete: "SET NULL" };
@@ -46,3 +47,26 @@ test("addMissingForeignKey adds a missing key once, refuses rows without a paren
46
47
  /children\.parent_id foreign key: the guardians table does not exist/u
47
48
  );
48
49
  });
50
+
51
+ test("listForeignKeys answers every key of the database, each column of a key in order", async (t) => {
52
+ const knex = knexFactory({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
53
+ t.after(() => knex.destroy());
54
+ await knex.schema.createTable("parents", (table) => table.integer("id").primary());
55
+ await knex.schema.createTable("pairs", (table) => {
56
+ table.integer("a");
57
+ table.integer("b");
58
+ table.primary(["a", "b"]);
59
+ });
60
+ await knex.schema.createTable("children", (table) => {
61
+ table.increments("id");
62
+ table.integer("parent_id").references("id").inTable("parents");
63
+ table.integer("pair_b");
64
+ table.integer("pair_a");
65
+ table.foreign(["pair_b", "pair_a"]).references(["b", "a"]).inTable("pairs");
66
+ });
67
+
68
+ assert.deepEqual((await listForeignKeys(knex)).sort((left, right) => left.columns[0].localeCompare(right.columns[0])), [
69
+ { name: "", tableName: "children", columns: ["pair_b", "pair_a"], referencedTableName: "pairs", referencedColumns: ["b", "a"] },
70
+ { name: "", tableName: "children", columns: ["parent_id"], referencedTableName: "parents", referencedColumns: ["id"] }
71
+ ]);
72
+ });