@jskit-ai/database-runtime 0.1.252 → 0.1.254
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/package.json +14 -3
- package/src/server/database.js +46 -0
- package/src/server/databaseSetup.js +42 -13
- package/src/server/foreignKeyMigrations.js +122 -0
- package/src/server/knexFactory.js +1 -0
- package/src/server/knexMigrationConfig.js +131 -10
- package/src/server/providers/DatabaseProvider.js +11 -43
- package/src/server/types.js +20 -0
- package/src/shared/duplicateEntry.js +15 -1
- package/src/shared/index.js +3 -1
- package/src/shared/repositoryOptions.js +50 -12
- package/src/shared/transactionManager.js +17 -18
- package/test/databaseSetup.test.js +8 -2
- package/test/duplicateEntry.test.js +11 -1
- package/test/foreignKeyMigrations.postgres.test.js +92 -0
- package/test/foreignKeyMigrations.test.js +48 -0
- package/test/knexMigrationConfig.test.js +276 -3
- package/test/packageMetadata.test.js +1 -1
- package/test/providerRuntime.test.js +1 -2
- package/test/repositoryOptions.test.js +15 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jskit-ai/database-runtime",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.254",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"scripts": {
|
|
6
6
|
"test": "node --test --test-concurrency=1"
|
|
@@ -9,6 +9,8 @@
|
|
|
9
9
|
"./server/providers/DatabaseProvider": "./src/server/providers/DatabaseProvider.js",
|
|
10
10
|
"./server/databaseSetup": "./src/server/databaseSetup.js",
|
|
11
11
|
"./server/knexMigrationConfig": "./src/server/knexMigrationConfig.js",
|
|
12
|
+
"./server/foreignKeyMigrations": "./src/server/foreignKeyMigrations.js",
|
|
13
|
+
"./server/types": "./src/server/types.js",
|
|
12
14
|
"./shared": "./src/shared/index.js",
|
|
13
15
|
"./shared/dateUtils": "./src/shared/dateUtils.js",
|
|
14
16
|
"./shared/databaseClient": "./src/shared/databaseClient.js",
|
|
@@ -27,7 +29,8 @@
|
|
|
27
29
|
"runtime.database"
|
|
28
30
|
],
|
|
29
31
|
"requires": [
|
|
30
|
-
"runtime.database.driver"
|
|
32
|
+
"runtime.database.driver",
|
|
33
|
+
"runtime.env"
|
|
31
34
|
]
|
|
32
35
|
},
|
|
33
36
|
"runtime": {
|
|
@@ -58,15 +61,23 @@
|
|
|
58
61
|
"subpath": "./server/knexMigrationConfig",
|
|
59
62
|
"summary": "Builds fixed-dialect Knex migration configuration and discovers immutable migrations directly from installed JSKIT packages."
|
|
60
63
|
},
|
|
64
|
+
{
|
|
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."
|
|
67
|
+
},
|
|
61
68
|
{
|
|
62
69
|
"subpath": "./shared",
|
|
63
70
|
"summary": "Exports shared repository helpers (transactions, record ids, JSON columns, visibility, duplicate-entry detection and date/time serialization)."
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"subpath": "./server/types",
|
|
74
|
+
"summary": "Types of the runtime.database capability and of the runtime.database.driver contract every driver package implements, for features that require them."
|
|
64
75
|
}
|
|
65
76
|
]
|
|
66
77
|
}
|
|
67
78
|
}
|
|
68
79
|
},
|
|
69
80
|
"peerDependencies": {
|
|
70
|
-
"@jskit-ai/kernel": "0.2.
|
|
81
|
+
"@jskit-ai/kernel": "0.2.5"
|
|
71
82
|
}
|
|
72
83
|
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { normalizeDatabaseClient, toKnexClientId } from "../shared/databaseClient.js";
|
|
2
|
+
import { resolveKnexConnectionFromEnvironment } from "../shared/databaseConnection.js";
|
|
3
|
+
import { createTransactionManager } from "../shared/transactionManager.js";
|
|
4
|
+
import { loadKnexFactory } from "./knexFactory.js";
|
|
5
|
+
|
|
6
|
+
/** @param {import("./types.js").RuntimeDatabaseDriver} driver */
|
|
7
|
+
function resolveDriverDialectId(driver) {
|
|
8
|
+
const dialectId = normalizeDatabaseClient(driver.DIALECT_ID, { allowEmpty: true });
|
|
9
|
+
if (!dialectId) {
|
|
10
|
+
throw new Error("The installed database driver did not expose a valid dialect id.");
|
|
11
|
+
}
|
|
12
|
+
return dialectId;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* The database connection every feature shares: the installed driver, its Knex client and a transaction manager.
|
|
17
|
+
* @param {object} dependencies
|
|
18
|
+
* @param {import("./types.js").RuntimeDatabaseDriver} dependencies.driver
|
|
19
|
+
* @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} dependencies.env
|
|
20
|
+
*/
|
|
21
|
+
function createDatabase({ driver, env }) {
|
|
22
|
+
const dialectId = resolveDriverDialectId(driver);
|
|
23
|
+
const configuredClient = normalizeDatabaseClient(env.DB_CLIENT, { allowEmpty: true });
|
|
24
|
+
if (configuredClient && configuredClient !== dialectId) {
|
|
25
|
+
throw new Error(`DB_CLIENT="${configuredClient}" does not match installed database driver "${dialectId}".`);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** @type {import("./types.js").RuntimeKnex} */
|
|
29
|
+
const knex = loadKnexFactory()({
|
|
30
|
+
client: toKnexClientId(dialectId),
|
|
31
|
+
connection: resolveKnexConnectionFromEnvironment(env, {
|
|
32
|
+
client: dialectId,
|
|
33
|
+
defaultPort: dialectId === "pg" ? 5432 : 3306,
|
|
34
|
+
context: "database runtime"
|
|
35
|
+
})
|
|
36
|
+
});
|
|
37
|
+
const transactionManager = createTransactionManager({ knex });
|
|
38
|
+
|
|
39
|
+
return Object.freeze({
|
|
40
|
+
driver,
|
|
41
|
+
knex,
|
|
42
|
+
transactionManager
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export { createDatabase };
|
|
@@ -9,23 +9,39 @@ function normalizeMigrationResult(result) {
|
|
|
9
9
|
const migrations = Array.isArray(migrationValues)
|
|
10
10
|
? migrationValues.map((value) => String(value || "").trim()).filter(Boolean)
|
|
11
11
|
: [];
|
|
12
|
-
return Object.freeze({
|
|
12
|
+
return Object.freeze({
|
|
13
|
+
batch,
|
|
14
|
+
migrations: Object.freeze(migrations)
|
|
15
|
+
});
|
|
13
16
|
}
|
|
14
17
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
+
/**
|
|
19
|
+
* Migrates the database an application's Knex instance reaches, then runs its seed, if any, in one transaction.
|
|
20
|
+
* @param {object} options
|
|
21
|
+
* @param {import("./types.js").RuntimeKnex} options.knex
|
|
22
|
+
* @param {(context: { knex: import("./types.js").RuntimeKnexTransaction, appRoot: string, environment: import("@jskit-ai/kernel/server/types").RuntimeEnv }) => unknown} [options.seed]
|
|
23
|
+
* @param {string} [options.appRoot]
|
|
24
|
+
* @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The application's environment, such as `process.env`.
|
|
25
|
+
*/
|
|
26
|
+
async function runDatabaseSetup({ knex, seed, appRoot = process.cwd(), environment }) {
|
|
27
|
+
// readable-check: allow method-probe - input validation: the application passes its own Knex instance
|
|
28
|
+
if (typeof knex !== "function" || typeof knex.transaction !== "function") {
|
|
29
|
+
throw new TypeError("runDatabaseSetup requires the application's Knex instance.");
|
|
30
|
+
}
|
|
31
|
+
if (!environment) {
|
|
32
|
+
throw new TypeError("runDatabaseSetup requires the application's environment, such as process.env.");
|
|
18
33
|
}
|
|
19
|
-
|
|
34
|
+
// readable-check: allow method-probe - input validation: the application may pass its own seed
|
|
35
|
+
if (seed != null && typeof seed !== "function") {
|
|
20
36
|
throw new TypeError("runDatabaseSetup seed must be a function when supplied.");
|
|
21
37
|
}
|
|
22
38
|
|
|
23
39
|
const migrationResult = normalizeMigrationResult(await knex.migrate.latest());
|
|
24
|
-
if (
|
|
25
|
-
return Object.freeze({
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
40
|
+
if (seed == null) {
|
|
41
|
+
return Object.freeze({
|
|
42
|
+
...migrationResult,
|
|
43
|
+
seeded: false
|
|
44
|
+
});
|
|
29
45
|
}
|
|
30
46
|
|
|
31
47
|
await runInTransaction(knex, async (transaction) => {
|
|
@@ -36,16 +52,29 @@ async function runDatabaseSetup({ knex, seed, appRoot = process.cwd(), environme
|
|
|
36
52
|
}));
|
|
37
53
|
});
|
|
38
54
|
|
|
39
|
-
return Object.freeze({
|
|
55
|
+
return Object.freeze({
|
|
56
|
+
...migrationResult,
|
|
57
|
+
seeded: true
|
|
58
|
+
});
|
|
40
59
|
}
|
|
41
60
|
|
|
61
|
+
/**
|
|
62
|
+
* Migrates the database the application's environment names, with the application's and its
|
|
63
|
+
* installed packages' migrations, then runs its seed, if any.
|
|
64
|
+
* @param {object} options
|
|
65
|
+
* @param {string} options.client The dialect id: "mysql2" or "pg".
|
|
66
|
+
* @param {string} [options.appRoot]
|
|
67
|
+
* @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The application's environment, such as `process.env`.
|
|
68
|
+
* @param {string} [options.migrationsDirectory]
|
|
69
|
+
* @param {Parameters<typeof runDatabaseSetup>[0]["seed"]} [options.seed]
|
|
70
|
+
*/
|
|
42
71
|
async function prepareDatabaseFromApp({
|
|
43
72
|
client,
|
|
44
73
|
appRoot = process.cwd(),
|
|
45
|
-
environment
|
|
74
|
+
environment,
|
|
46
75
|
migrationsDirectory = "migrations",
|
|
47
76
|
seed
|
|
48
|
-
}
|
|
77
|
+
}) {
|
|
49
78
|
const normalizedAppRoot = path.resolve(appRoot);
|
|
50
79
|
const config = await createKnexMigrationConfigFromApp({
|
|
51
80
|
client,
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import { detectDialectFromClient } from "../shared/dialect.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A single-column foreign key that a constraints migration adds once its parent table exists.
|
|
5
|
+
* @typedef {object} ForeignKey
|
|
6
|
+
* @property {string} tableName
|
|
7
|
+
* @property {string} columnName
|
|
8
|
+
* @property {string} parentTable
|
|
9
|
+
* @property {string} [parentColumn] Defaults to "id".
|
|
10
|
+
* @property {string} [name] Defaults to Knex's `<table>_<column>_foreign`.
|
|
11
|
+
* @property {string} [onDelete]
|
|
12
|
+
* @property {string} [onUpdate]
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* The name of the foreign key that links the column to the parent column, whatever that name is,
|
|
17
|
+
* or null when no key does. SQLite keys have no name, so a SQLite key's is "".
|
|
18
|
+
* @param {import("./types.js").RuntimeKnex} knex
|
|
19
|
+
* @param {ForeignKey} key
|
|
20
|
+
* @returns {Promise<string | null>}
|
|
21
|
+
*/
|
|
22
|
+
async function findForeignKeyName(knex, { tableName, columnName, parentTable, parentColumn = "id" }) {
|
|
23
|
+
const dialect = detectDialectFromClient(knex);
|
|
24
|
+
if (dialect === "mysql") {
|
|
25
|
+
const row = await knex("information_schema.KEY_COLUMN_USAGE")
|
|
26
|
+
.whereRaw("TABLE_SCHEMA = DATABASE()")
|
|
27
|
+
.where({
|
|
28
|
+
TABLE_NAME: tableName,
|
|
29
|
+
COLUMN_NAME: columnName,
|
|
30
|
+
REFERENCED_TABLE_NAME: parentTable,
|
|
31
|
+
REFERENCED_COLUMN_NAME: parentColumn
|
|
32
|
+
})
|
|
33
|
+
.first("CONSTRAINT_NAME");
|
|
34
|
+
return row ? row.CONSTRAINT_NAME : null;
|
|
35
|
+
}
|
|
36
|
+
if (dialect === "postgres") {
|
|
37
|
+
const { rows } = await knex.raw(
|
|
38
|
+
`SELECT c.conname FROM pg_constraint c
|
|
39
|
+
JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1]
|
|
40
|
+
JOIN pg_attribute p ON p.attrelid = c.confrelid AND p.attnum = c.confkey[1]
|
|
41
|
+
WHERE c.contype = 'f' AND cardinality(c.conkey) = 1
|
|
42
|
+
AND c.conrelid = to_regclass(?) AND c.confrelid = to_regclass(?)
|
|
43
|
+
AND a.attname = ? AND p.attname = ?`,
|
|
44
|
+
[tableName, parentTable, columnName, parentColumn]
|
|
45
|
+
);
|
|
46
|
+
return rows.length > 0 ? rows[0].conname : null;
|
|
47
|
+
}
|
|
48
|
+
if (dialect.includes("sqlite")) {
|
|
49
|
+
const keys = await knex.raw("PRAGMA foreign_key_list(??)", [tableName]);
|
|
50
|
+
return keys.some((key) => key.table === parentTable && key.from === columnName && key.to === parentColumn)
|
|
51
|
+
? ""
|
|
52
|
+
: null;
|
|
53
|
+
}
|
|
54
|
+
throw new Error(`Foreign key migrations do not support the ${dialect || "unknown"} dialect.`);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Whether a foreign key already links the column to the parent column, whatever its name.
|
|
59
|
+
* @param {import("./types.js").RuntimeKnex} knex
|
|
60
|
+
* @param {ForeignKey} key
|
|
61
|
+
*/
|
|
62
|
+
async function hasForeignKey(knex, key) {
|
|
63
|
+
return (await findForeignKeyName(knex, key)) !== null;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Adds the foreign key unless it already exists, so a constraints migration runs on a fresh
|
|
68
|
+
* database and on one an earlier migration already gave the key. Refuses, naming the table, column
|
|
69
|
+
* and count, when rows have no parent; it never deletes data.
|
|
70
|
+
* @param {import("./types.js").RuntimeKnex} knex
|
|
71
|
+
* @param {ForeignKey} key
|
|
72
|
+
* @returns {Promise<boolean>} Whether it added the key.
|
|
73
|
+
*/
|
|
74
|
+
async function addMissingForeignKey(knex, key) {
|
|
75
|
+
const { tableName, columnName, parentTable, parentColumn = "id", name, onDelete, onUpdate } = key;
|
|
76
|
+
if (await hasForeignKey(knex, key)) {
|
|
77
|
+
return false;
|
|
78
|
+
}
|
|
79
|
+
if (!(await knex.schema.hasTable(parentTable))) {
|
|
80
|
+
throw new Error(`Cannot add the ${tableName}.${columnName} foreign key: the ${parentTable} table does not exist.`);
|
|
81
|
+
}
|
|
82
|
+
const [{ orphans }] = await knex(tableName)
|
|
83
|
+
.whereNotNull(columnName)
|
|
84
|
+
.whereNotExists(
|
|
85
|
+
knex(parentTable).select(knex.raw("1")).whereRaw("??.?? = ??.??", [parentTable, parentColumn, tableName, columnName])
|
|
86
|
+
)
|
|
87
|
+
.count({ orphans: "*" });
|
|
88
|
+
if (Number(orphans) > 0) {
|
|
89
|
+
throw new Error(
|
|
90
|
+
`Cannot add the ${tableName}.${columnName} foreign key to ${parentTable}.${parentColumn}: ` +
|
|
91
|
+
`${orphans} ${tableName} row(s) have a ${columnName} with no ${parentTable} row. ` +
|
|
92
|
+
"Repair or remove those rows, then migrate again; the migration deletes nothing."
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
await knex.schema.alterTable(tableName, (table) => {
|
|
96
|
+
const reference = table.foreign(columnName, name).references(parentColumn).inTable(parentTable);
|
|
97
|
+
if (onDelete) reference.onDelete(onDelete);
|
|
98
|
+
if (onUpdate) reference.onUpdate(onUpdate);
|
|
99
|
+
});
|
|
100
|
+
return true;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Drops the foreign key when it exists, for a constraints migration's down().
|
|
105
|
+
* @param {import("./types.js").RuntimeKnex} knex
|
|
106
|
+
* @param {ForeignKey} key
|
|
107
|
+
* @returns {Promise<boolean>} Whether it dropped the key.
|
|
108
|
+
*/
|
|
109
|
+
async function dropForeignKeyIfPresent(knex, key) {
|
|
110
|
+
const name = await findForeignKeyName(knex, key);
|
|
111
|
+
if (name === null) {
|
|
112
|
+
return false;
|
|
113
|
+
}
|
|
114
|
+
// Knex's SQLite table rebuild finds the key by its column (its name is ""); the others drop it by
|
|
115
|
+
// the name the database holds, which may differ from key.name.
|
|
116
|
+
await knex.schema.alterTable(key.tableName, (table) => {
|
|
117
|
+
table.dropForeign(key.columnName, name || undefined);
|
|
118
|
+
});
|
|
119
|
+
return true;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export { addMissingForeignKey, dropForeignKeyIfPresent, hasForeignKey };
|
|
@@ -11,6 +11,7 @@ function loadKnexFactory() {
|
|
|
11
11
|
const knexFactory =
|
|
12
12
|
typeof moduleValue === "function"
|
|
13
13
|
? moduleValue
|
|
14
|
+
// readable-check: allow method-probe - platform object: a required module is the factory or an ES namespace that holds it
|
|
14
15
|
: typeof moduleValue?.default === "function"
|
|
15
16
|
? moduleValue.default
|
|
16
17
|
: null;
|
|
@@ -7,13 +7,29 @@ import {
|
|
|
7
7
|
} from "../shared/databaseClient.js";
|
|
8
8
|
import { resolveKnexConnectionFromEnvironment } from "../shared/databaseConnection.js";
|
|
9
9
|
|
|
10
|
+
/**
|
|
11
|
+
* The Knex configuration for migrating the database the application's environment names.
|
|
12
|
+
* @param {object} options
|
|
13
|
+
* @param {string} options.client The dialect id: "mysql2" or "pg".
|
|
14
|
+
* @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The application's environment, such as `process.env`.
|
|
15
|
+
* @param {string} [options.appRoot]
|
|
16
|
+
* @param {string} [options.migrationsDirectory]
|
|
17
|
+
* @param {readonly string[]} [options.packageMigrationDirectories]
|
|
18
|
+
* @param {readonly string[]} [options.packageConstraintDirectories]
|
|
19
|
+
*/
|
|
10
20
|
function createKnexMigrationConfig({
|
|
11
21
|
client,
|
|
12
|
-
environment
|
|
22
|
+
environment,
|
|
13
23
|
appRoot = process.cwd(),
|
|
14
24
|
migrationsDirectory = "migrations",
|
|
15
|
-
|
|
16
|
-
|
|
25
|
+
// readable-check: allow dependency-default - data: a list of directory paths, not a collaborator
|
|
26
|
+
packageMigrationDirectories = [],
|
|
27
|
+
// readable-check: allow dependency-default - data: a list of directory paths, not a collaborator
|
|
28
|
+
packageConstraintDirectories = []
|
|
29
|
+
}) {
|
|
30
|
+
if (!environment) {
|
|
31
|
+
throw new TypeError("createKnexMigrationConfig requires the application's environment, such as process.env.");
|
|
32
|
+
}
|
|
17
33
|
const dialectId = normalizeDatabaseClient(client);
|
|
18
34
|
const resolvedMigrationsDirectory = path.resolve(appRoot, migrationsDirectory);
|
|
19
35
|
|
|
@@ -25,9 +41,12 @@ function createKnexMigrationConfig({
|
|
|
25
41
|
context: "knex migrations"
|
|
26
42
|
}),
|
|
27
43
|
migrations: {
|
|
44
|
+
// Packages create the tables application migrations build on; package constraints
|
|
45
|
+
// can then reference application tables such as users.
|
|
28
46
|
directory: [
|
|
29
|
-
resolvedMigrationsDirectory,
|
|
30
47
|
...packageMigrationDirectories.map((directory) => path.resolve(directory)),
|
|
48
|
+
resolvedMigrationsDirectory,
|
|
49
|
+
...packageConstraintDirectories.map((directory) => path.resolve(directory)),
|
|
31
50
|
path.join(resolvedMigrationsDirectory, "constraints")
|
|
32
51
|
],
|
|
33
52
|
extension: "cjs",
|
|
@@ -45,12 +64,88 @@ async function directoryExists(directory) {
|
|
|
45
64
|
}
|
|
46
65
|
}
|
|
47
66
|
|
|
67
|
+
/**
|
|
68
|
+
* A package's `jskit.migrations.after`: the installed JSKIT packages whose
|
|
69
|
+
* migrations its own follow, or none.
|
|
70
|
+
* @param {{ packageId: string, packageMetadata: Record<string, any> }} installedPackage
|
|
71
|
+
* @param {ReadonlySet<string>} installedPackageIds
|
|
72
|
+
*/
|
|
73
|
+
function migrationsAfterOf({ packageId, packageMetadata }, installedPackageIds) {
|
|
74
|
+
const { directories, after: declared } = packageMetadata.migrations ?? {};
|
|
75
|
+
if (declared === undefined) {
|
|
76
|
+
return [];
|
|
77
|
+
}
|
|
78
|
+
if (directories === undefined) {
|
|
79
|
+
throw new TypeError(`${packageId} package.json#jskit.migrations.after needs jskit.migrations.directories.`);
|
|
80
|
+
}
|
|
81
|
+
if (!Array.isArray(declared) || declared.some((entry) => typeof entry !== "string" || !entry.trim())) {
|
|
82
|
+
throw new TypeError(`${packageId} package.json#jskit.migrations.after must be an array of package names.`);
|
|
83
|
+
}
|
|
84
|
+
const after = declared.map((entry) => entry.trim());
|
|
85
|
+
for (const prerequisite of after) {
|
|
86
|
+
if (prerequisite === packageId) {
|
|
87
|
+
throw new TypeError(`${packageId} package.json#jskit.migrations.after names the package itself.`);
|
|
88
|
+
}
|
|
89
|
+
if (!installedPackageIds.has(prerequisite)) {
|
|
90
|
+
throw new Error(
|
|
91
|
+
`${packageId} package.json#jskit.migrations.after names ${prerequisite}, which is not an installed JSKIT package.`
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return after;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Package migration directories in path order, except that a directory of a
|
|
100
|
+
* package whose `jskit.migrations.after` names other packages runs after all of
|
|
101
|
+
* their directories. With no `after` the path order is unchanged.
|
|
102
|
+
* @param {readonly string[]} directories
|
|
103
|
+
* @param {ReadonlyMap<string, string>} packageIdOf the package that declares each directory
|
|
104
|
+
* @param {ReadonlyMap<string, readonly string[]>} afterOf each package's `after`
|
|
105
|
+
*/
|
|
106
|
+
function orderPackageMigrationDirectories(directories, packageIdOf, afterOf) {
|
|
107
|
+
const directoriesOf = new Map();
|
|
108
|
+
for (const directory of directories) {
|
|
109
|
+
const packageId = packageIdOf.get(directory);
|
|
110
|
+
directoriesOf.set(packageId, [...(directoriesOf.get(packageId) || []), directory]);
|
|
111
|
+
}
|
|
112
|
+
const ordered = [];
|
|
113
|
+
const states = new Map();
|
|
114
|
+
|
|
115
|
+
function visit(directory, ancestry) {
|
|
116
|
+
const packageId = packageIdOf.get(directory);
|
|
117
|
+
if (states.get(directory) === "ordered") {
|
|
118
|
+
return;
|
|
119
|
+
}
|
|
120
|
+
if (states.get(directory) === "visiting") {
|
|
121
|
+
throw new Error(`Package migrations cannot each run after the other: ${[...ancestry, packageId].join(" -> ")}.`);
|
|
122
|
+
}
|
|
123
|
+
states.set(directory, "visiting");
|
|
124
|
+
for (const prerequisite of afterOf.get(packageId) || []) {
|
|
125
|
+
for (const prerequisiteDirectory of directoriesOf.get(prerequisite) || []) {
|
|
126
|
+
visit(prerequisiteDirectory, [...ancestry, packageId]);
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
states.set(directory, "ordered");
|
|
130
|
+
ordered.push(directory);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
for (const directory of directories) {
|
|
134
|
+
visit(directory, []);
|
|
135
|
+
}
|
|
136
|
+
return ordered;
|
|
137
|
+
}
|
|
138
|
+
|
|
48
139
|
async function discoverPackageMigrationDirectories({ appRoot = process.cwd() } = {}) {
|
|
49
140
|
const normalizedAppRoot = path.resolve(appRoot);
|
|
50
|
-
const
|
|
141
|
+
const installedPackages = await discoverInstalledPackages({ appRoot: normalizedAppRoot });
|
|
142
|
+
const installedPackageIds = new Set(installedPackages.map(({ packageId }) => packageId));
|
|
143
|
+
const packageIdOf = new Map();
|
|
144
|
+
const afterOf = new Map();
|
|
51
145
|
|
|
52
|
-
for (const installedPackage of
|
|
146
|
+
for (const installedPackage of installedPackages) {
|
|
53
147
|
const declaredDirectories = installedPackage.packageMetadata?.migrations?.directories;
|
|
148
|
+
afterOf.set(installedPackage.packageId, migrationsAfterOf(installedPackage, installedPackageIds));
|
|
54
149
|
if (typeof declaredDirectories === "undefined") {
|
|
55
150
|
continue;
|
|
56
151
|
}
|
|
@@ -84,20 +179,46 @@ async function discoverPackageMigrationDirectories({ appRoot = process.cwd() } =
|
|
|
84
179
|
`${installedPackage.packageId} declares a missing package migration directory: ${relativeDirectory}.`
|
|
85
180
|
);
|
|
86
181
|
}
|
|
87
|
-
|
|
182
|
+
if (!packageIdOf.has(absoluteDirectory)) {
|
|
183
|
+
packageIdOf.set(absoluteDirectory, installedPackage.packageId);
|
|
184
|
+
}
|
|
88
185
|
}
|
|
89
186
|
}
|
|
90
187
|
|
|
91
|
-
|
|
188
|
+
const pathOrder = [...packageIdOf.keys()].sort((left, right) => left.localeCompare(right));
|
|
189
|
+
return Object.freeze(orderPackageMigrationDirectories(pathOrder, packageIdOf, afterOf));
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* A package's migration directory may hold a constraints/ subdirectory; it runs after the
|
|
194
|
+
* application's migrations/, like the application's own migrations/constraints/.
|
|
195
|
+
* @param {readonly string[]} packageMigrationDirectories
|
|
196
|
+
*/
|
|
197
|
+
async function packageConstraintDirectoriesOf(packageMigrationDirectories) {
|
|
198
|
+
const directories = [];
|
|
199
|
+
for (const directory of packageMigrationDirectories) {
|
|
200
|
+
const constraintsDirectory = path.join(directory, "constraints");
|
|
201
|
+
if (await directoryExists(constraintsDirectory)) {
|
|
202
|
+
directories.push(constraintsDirectory);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
return Object.freeze(directories);
|
|
92
206
|
}
|
|
93
207
|
|
|
94
|
-
|
|
208
|
+
/**
|
|
209
|
+
* The Knex migration configuration of an application: its own migrations and those of every
|
|
210
|
+
* installed JSKIT package that declares some.
|
|
211
|
+
* @param {Omit<Parameters<typeof createKnexMigrationConfig>[0],
|
|
212
|
+
* "packageMigrationDirectories" | "packageConstraintDirectories">} options
|
|
213
|
+
*/
|
|
214
|
+
async function createKnexMigrationConfigFromApp(options) {
|
|
95
215
|
const appRoot = path.resolve(options.appRoot || process.cwd());
|
|
96
216
|
const packageMigrationDirectories = await discoverPackageMigrationDirectories({ appRoot });
|
|
97
217
|
return createKnexMigrationConfig({
|
|
98
218
|
...options,
|
|
99
219
|
appRoot,
|
|
100
|
-
packageMigrationDirectories
|
|
220
|
+
packageMigrationDirectories,
|
|
221
|
+
packageConstraintDirectories: await packageConstraintDirectoriesOf(packageMigrationDirectories)
|
|
101
222
|
});
|
|
102
223
|
}
|
|
103
224
|
|
|
@@ -1,43 +1,5 @@
|
|
|
1
1
|
import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
|
|
2
|
-
import {
|
|
3
|
-
import { resolveKnexConnectionFromEnvironment } from "../../shared/databaseConnection.js";
|
|
4
|
-
import { createTransactionManager } from "../../shared/transactionManager.js";
|
|
5
|
-
import { loadKnexFactory } from "../knexFactory.js";
|
|
6
|
-
|
|
7
|
-
function resolveDriverDialectId(driver) {
|
|
8
|
-
const dialectId = normalizeDatabaseClient(
|
|
9
|
-
driver?.DIALECT_ID || driver?.dialectId || driver?.dialect || driver?.getDialectId?.(),
|
|
10
|
-
{ allowEmpty: true }
|
|
11
|
-
);
|
|
12
|
-
if (!dialectId) {
|
|
13
|
-
throw new Error("The installed database driver did not expose a valid dialect id.");
|
|
14
|
-
}
|
|
15
|
-
return dialectId;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
function createDatabase({ driver, env }) {
|
|
19
|
-
const dialectId = resolveDriverDialectId(driver);
|
|
20
|
-
const configuredClient = normalizeDatabaseClient(env.DB_CLIENT, { allowEmpty: true });
|
|
21
|
-
if (configuredClient && configuredClient !== dialectId) {
|
|
22
|
-
throw new Error(`DB_CLIENT="${configuredClient}" does not match installed database driver "${dialectId}".`);
|
|
23
|
-
}
|
|
24
|
-
|
|
25
|
-
const knex = loadKnexFactory()({
|
|
26
|
-
client: toKnexClientId(dialectId),
|
|
27
|
-
connection: resolveKnexConnectionFromEnvironment(env, {
|
|
28
|
-
client: dialectId,
|
|
29
|
-
defaultPort: dialectId === "pg" ? 5432 : 3306,
|
|
30
|
-
context: "database runtime"
|
|
31
|
-
})
|
|
32
|
-
});
|
|
33
|
-
const transactionManager = createTransactionManager({ knex });
|
|
34
|
-
|
|
35
|
-
return Object.freeze({
|
|
36
|
-
driver,
|
|
37
|
-
knex,
|
|
38
|
-
transactionManager
|
|
39
|
-
});
|
|
40
|
-
}
|
|
2
|
+
import { createDatabase } from "../database.js";
|
|
41
3
|
|
|
42
4
|
const DatabaseProvider = defineProvider({
|
|
43
5
|
id: "runtime.database",
|
|
@@ -48,14 +10,20 @@ const DatabaseProvider = defineProvider({
|
|
|
48
10
|
provides: {
|
|
49
11
|
database: "runtime.database"
|
|
50
12
|
},
|
|
13
|
+
/**
|
|
14
|
+
* @param {object} dependencies
|
|
15
|
+
* @param {import("../types.js").RuntimeDatabaseDriver} dependencies.driver
|
|
16
|
+
* @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} dependencies.env
|
|
17
|
+
*/
|
|
51
18
|
setup({ driver, env }) {
|
|
52
19
|
return { database: createDatabase({ driver, env }) };
|
|
53
20
|
},
|
|
21
|
+
/**
|
|
22
|
+
* @param {unknown} _dependencies
|
|
23
|
+
* @param {{ outputs: { database: import("../types.js").RuntimeDatabase } }} lifecycle
|
|
24
|
+
*/
|
|
54
25
|
async shutdown(_dependencies, { outputs }) {
|
|
55
|
-
|
|
56
|
-
if (knex && typeof knex.destroy === "function") {
|
|
57
|
-
await knex.destroy();
|
|
58
|
-
}
|
|
26
|
+
await outputs.database.knex.destroy();
|
|
59
27
|
}
|
|
60
28
|
});
|
|
61
29
|
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
// The types of the database capabilities, for features that require them.
|
|
2
|
+
|
|
3
|
+
/** @typedef {ReturnType<typeof import("./database.js").createDatabase>} RuntimeDatabase */
|
|
4
|
+
/** @typedef {import("knex").Knex} RuntimeKnex A Knex client: the one `runtime.database` shares, or one an application passes in. */
|
|
5
|
+
/** @typedef {RuntimeDatabase["transactionManager"]} RuntimeTransactionManager The transaction manager `runtime.database` shares. */
|
|
6
|
+
/** @typedef {import("knex").Knex.Transaction} RuntimeKnexTransaction A Knex transaction: the `trx` a repository or service call runs in, as the transaction manager hands it to its work. */
|
|
7
|
+
/** @typedef {import("knex").Knex.QueryBuilder} RuntimeKnexQueryBuilder A Knex query that a hook or helper narrows. */
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* The `runtime.database.driver` capability: the shared exports of the
|
|
11
|
+
* installed dialect package (`@jskit-ai/database-runtime-mysql` or
|
|
12
|
+
* `@jskit-ai/database-runtime-postgres`). Each driver package implements this
|
|
13
|
+
* contract; `runtime.database` reads its dialect from it.
|
|
14
|
+
* @typedef {object} RuntimeDatabaseDriver
|
|
15
|
+
* @property {string} DIALECT_ID The dialect id: "mysql2" or "pg".
|
|
16
|
+
* @property {(knex: RuntimeKnex, options?: { tableName?: string, idColumn?: string }) => Promise<object>} [introspectCrudTableSnapshot]
|
|
17
|
+
* Reads a table's columns for CRUD generation; the MySQL driver has it.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
export {};
|
|
@@ -46,4 +46,18 @@ function isDuplicateEntryError(error, options) {
|
|
|
46
46
|
return findDuplicateEntryError(error, options) !== null;
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
/**
|
|
50
|
+
* True when an insert lost a race to a concurrent insert of the same row,
|
|
51
|
+
* outside a caller's transaction: the call held no `options.trx`, its own
|
|
52
|
+
* transaction rolled back in full (json-rest-api's `transactionOutcome`), and
|
|
53
|
+
* the error is a duplicate entry. The caller may then read the winner's row.
|
|
54
|
+
* Inside a caller's transaction the failed statement cannot be recovered, so
|
|
55
|
+
* it is never such a race.
|
|
56
|
+
* @param {{ transactionOutcome?: string } | null | undefined} error
|
|
57
|
+
* @param {{ trx?: unknown }} options The insert call's options.
|
|
58
|
+
*/
|
|
59
|
+
function isLostDuplicateInsertRace(error, options) {
|
|
60
|
+
return !options.trx && error?.transactionOutcome === "rolledBack" && isDuplicateEntryError(error);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export { findDuplicateEntryError, isDuplicateEntryError, isLostDuplicateInsertRace };
|
package/src/shared/index.js
CHANGED
|
@@ -9,9 +9,10 @@ export {
|
|
|
9
9
|
} from "./dateUtils.js";
|
|
10
10
|
export { normalizeDialect, detectDialectFromClient } from "./dialect.js";
|
|
11
11
|
export { normalizeDatabaseClient, toKnexClientId } from "./databaseClient.js";
|
|
12
|
-
export { findDuplicateEntryError, isDuplicateEntryError } from "./duplicateEntry.js";
|
|
12
|
+
export { findDuplicateEntryError, isDuplicateEntryError, isLostDuplicateInsertRace } from "./duplicateEntry.js";
|
|
13
13
|
export { DEFAULT_VISIBILITY_COLUMNS, applyVisibility, applyVisibilityOwners } from "./visibility.js";
|
|
14
14
|
export {
|
|
15
|
+
resolveTransaction,
|
|
15
16
|
resolveQueryOptions,
|
|
16
17
|
resolveRepoClient,
|
|
17
18
|
applyForUpdate,
|
|
@@ -26,5 +27,6 @@ export {
|
|
|
26
27
|
retryDeadlocks,
|
|
27
28
|
runInTransaction,
|
|
28
29
|
createWithTransaction,
|
|
30
|
+
joinOrOpenTransaction,
|
|
29
31
|
lockScopedRecordId
|
|
30
32
|
} from "./repositoryOptions.js";
|