@omnitron-dev/titan-database 0.3.5 → 0.4.8
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/README.md +24 -84
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,102 +1,42 @@
|
|
|
1
1
|
# @omnitron-dev/titan-database
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Database connections, typed queries and explicit migrations for Titan applications. The module integrates Kysely and Kysera with Titan's dependency injection and lifecycle.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Capabilities
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- Named PostgreSQL, MySQL and SQLite connections.
|
|
8
|
+
- Typed query builders, repositories, transactions and optional RLS integration.
|
|
9
|
+
- Migration runners with locking and checksum validation.
|
|
10
|
+
- Read-only PostgreSQL schema readiness checks using an existing pool.
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
## Quick start
|
|
13
|
+
|
|
14
|
+
```sh
|
|
10
15
|
pnpm add @omnitron-dev/titan-database
|
|
11
16
|
```
|
|
12
17
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
The native driver requires Node-API 10. PostgreSQL and MySQL can run without it.
|
|
16
|
-
|
|
17
|
-
## Overview
|
|
18
|
-
|
|
19
|
-
Provides database connectivity for Titan applications using Kysely as the query builder. Supports PostgreSQL and SQLite dialects, declarative migrations, and row-level security (RLS) via `AsyncLocalStorage` context propagation.
|
|
20
|
-
|
|
21
|
-
### Key Features
|
|
22
|
-
|
|
23
|
-
- Kysely-based typed query builder
|
|
24
|
-
- Declarative migration system
|
|
25
|
-
- Row-level security (RLS) with async context
|
|
26
|
-
- Multi-dialect support (PostgreSQL, SQLite)
|
|
27
|
-
- Connection pooling and health checks
|
|
18
|
+
```ts
|
|
19
|
+
import { TitanDatabaseModule } from '@omnitron-dev/titan-database';
|
|
28
20
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
Use `@omnitron-dev/titan-database/migration` for standalone runners and
|
|
37
|
-
`@omnitron-dev/omnitron/migration` in Omnitron applications. Schema changes run
|
|
38
|
-
explicitly; migration decorator metadata does not execute at DI startup.
|
|
39
|
-
|
|
40
|
-
`createHardenedRunner` preserves legacy history, lock identity and checksums.
|
|
41
|
-
The shared engine commits each body and history atomically, supports explicit
|
|
42
|
-
whole-batch transactions, and keeps inspection read-only. Preserve the journal
|
|
43
|
-
and checksum format when moving an existing deployment. SQL definitions can use
|
|
44
|
-
`defineSqlMigration`; arbitrary callbacks need a stable explicit checksum.
|
|
45
|
-
|
|
46
|
-
## Read-only component readiness
|
|
21
|
+
export function database(connection: string) {
|
|
22
|
+
return TitanDatabaseModule.forRoot({
|
|
23
|
+
connection: { dialect: 'postgres', connection },
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
```
|
|
47
27
|
|
|
48
|
-
|
|
49
|
-
It borrows an existing PostgreSQL pool, checks the component's declared table/column,
|
|
50
|
-
key, trigger and routine requirements in a read-only repeatable-read transaction,
|
|
51
|
-
and leaves the pool open. Importing the entry loads no driver, DI graph or migrator.
|
|
52
|
-
Omnitron applications can use the same API through `@omnitron-dev/omnitron/readiness`.
|
|
28
|
+
Pass a PostgreSQL connection URL from application configuration and add the returned module to your Titan application. Resolve `DATABASE_MANAGER` to obtain the configured connections. Install the driver required by your chosen dialect; native SQLite drivers must match the Node runtime.
|
|
53
29
|
|
|
54
|
-
|
|
55
|
-
nullable columns and columns with defaults are accepted; `insert: true` rejects
|
|
56
|
-
additional required inputs the component cannot supply. `defaultExpression` checks
|
|
57
|
-
an exact PostgreSQL `pg_get_expr` expression when the default's meaning matters;
|
|
58
|
-
`default` checks only its presence. `schema` selects an explicit schema, otherwise
|
|
59
|
-
the connection's `current_schema()` applies. These are PostgreSQL guarantees.
|
|
30
|
+
## Migrations and readiness
|
|
60
31
|
|
|
61
|
-
|
|
62
|
-
PostgreSQL index, so an immediate primary/unique constraint and a standalone
|
|
63
|
-
`UNIQUE INDEX` satisfy the same contract. `INCLUDE` columns are payload, not key
|
|
64
|
-
columns. Partial, expression, invalid, unfinished, dropping and deferred indexes
|
|
65
|
-
do not establish this guarantee. Foreign keys are checked independently, including
|
|
66
|
-
their target schema, ordered columns and update/delete actions. The inspection
|
|
67
|
-
does not create constraints or rewrite an application's migrations.
|
|
32
|
+
Apply migrations explicitly through `@omnitron-dev/titan-database/migration`. Creating the DI module does not create tables or run migrations. Use the runner's own transaction, retry and checksum options; the module's `transactionOptions` and `migrations` configuration groups are currently not applied.
|
|
68
33
|
|
|
69
|
-
`
|
|
70
|
-
`formattedType` optionally binds PostgreSQL's `format_type` spelling, including
|
|
71
|
-
precision and length. An insert table requires writable, non-generated columns
|
|
72
|
-
unless their generated expression is explicitly declared. A read projection can
|
|
73
|
-
leave that distinction unspecified. Routine contracts check ordered `argumentTypes`
|
|
74
|
-
(zero arguments by default), body, language, volatility, invoker security and
|
|
75
|
-
configuration. They require ordinary scalar functions without variadic/default
|
|
76
|
-
arguments, so an unrelated overload cannot satisfy readiness. `returnType` uses
|
|
77
|
-
`format_type` (for example `bigint`). Trigger functions must return `trigger`.
|
|
78
|
-
`configuration` is an exact set of `pg_proc.proconfig` entries, empty by default.
|
|
79
|
-
`schemaSearchPath: true` additionally requires exactly
|
|
80
|
-
`pg_catalog, <checked schema>, pg_temp`, using PostgreSQL identifier quoting.
|
|
81
|
-
Built-ins precede the component schema and temporary objects come last; other
|
|
82
|
-
intentional settings must still be declared. This avoids relying on the caller's
|
|
83
|
-
mutable search path for component-owned functions.
|
|
34
|
+
`requirePostgresSchema` from `@omnitron-dev/titan-database/readiness` checks a declared schema contract through an existing pool. It reads metadata without applying DDL or taking ownership of that pool. Its result covers the declared requirements, not every possible difference between database schemas.
|
|
84
35
|
|
|
85
|
-
|
|
86
|
-
Defaults are **10 seconds per statement** and **1 second per lock wait**, restored
|
|
87
|
-
when the read-only transaction ends. These are not a total-operation deadline.
|
|
88
|
-
Configure a finite pool `connectionTimeoutMillis` separately: acquiring a
|
|
89
|
-
connection is the owner's responsibility and cannot be cancelled by a fake timeout
|
|
90
|
-
around the borrowed pool. Function requirements prove only declared properties;
|
|
91
|
-
this is not a universal PostgreSQL schema-equivalence or SQL-security proof.
|
|
36
|
+
## Documentation
|
|
92
37
|
|
|
93
|
-
|
|
94
|
-
the component name and individual violations. This does not apply migrations,
|
|
95
|
-
alter journals, prove every database invariant or replace query authorization.
|
|
96
|
-
The stack's declared migration phase owns schema changes; application startup
|
|
97
|
-
checks compatibility before accepting traffic. A later unrelated migration does
|
|
98
|
-
not require modifying an older component's migration registry.
|
|
38
|
+
[Public API](src/index.ts) · [Connection options](src/database.types.ts) · [Package exports](package.json) · [Omni](../../README.md)
|
|
99
39
|
|
|
100
40
|
## License
|
|
101
41
|
|
|
102
|
-
MIT
|
|
42
|
+
[MIT](../../LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@omnitron-dev/titan-database",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.8",
|
|
4
4
|
"description": "Database module for Titan framework with Kysely, migrations, RLS, and multi-dialect support",
|
|
5
5
|
"author": "LuxQuant",
|
|
6
6
|
"license": "MIT",
|
|
@@ -67,14 +67,14 @@
|
|
|
67
67
|
"@kysera/rls": "^0.10.2",
|
|
68
68
|
"@kysera/soft-delete": "^0.10.2",
|
|
69
69
|
"@kysera/timestamps": "^0.10.2",
|
|
70
|
-
"@omnitron-dev/eventemitter": "0.
|
|
70
|
+
"@omnitron-dev/eventemitter": "0.4.8",
|
|
71
71
|
"@types/better-sqlite3": "^9.6.0",
|
|
72
72
|
"kysely": "^0.29.8",
|
|
73
73
|
"zod": "^4.6.7",
|
|
74
74
|
"@kysera/dal": "^0.10.2"
|
|
75
75
|
},
|
|
76
76
|
"peerDependencies": {
|
|
77
|
-
"@omnitron-dev/titan": "0.
|
|
77
|
+
"@omnitron-dev/titan": "0.4.8",
|
|
78
78
|
"better-sqlite3": "^13.0.3",
|
|
79
79
|
"mysql2": "^3.20.0",
|
|
80
80
|
"pg": "^8.20.0"
|
|
@@ -91,7 +91,7 @@
|
|
|
91
91
|
}
|
|
92
92
|
},
|
|
93
93
|
"devDependencies": {
|
|
94
|
-
"@omnitron-dev/titan": "0.
|
|
94
|
+
"@omnitron-dev/titan": "0.4.8",
|
|
95
95
|
"@types/node": "^26.6.6",
|
|
96
96
|
"reflect-metadata": "^0.2.2",
|
|
97
97
|
"typescript": "npm:@typescript/typescript6@^6.0.2",
|
|
@@ -103,7 +103,7 @@
|
|
|
103
103
|
"url": "git+https://github.com/omnitron-dev/omni.git",
|
|
104
104
|
"directory": "packages/titan-database"
|
|
105
105
|
},
|
|
106
|
-
"gitHead": "
|
|
106
|
+
"gitHead": "1ae8568eebc2581e2cc2428bd3ca1cf570ed3f03",
|
|
107
107
|
"scripts": {
|
|
108
108
|
"build": "../../scripts/build-package.sh -p ./tsconfig.json",
|
|
109
109
|
"test": "vitest run",
|