@omnitron-dev/titan-database 0.4.6 → 0.4.9

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.
Files changed (2) hide show
  1. package/README.md +24 -84
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,102 +1,42 @@
1
1
  # @omnitron-dev/titan-database
2
2
 
3
- > Database module for the Titan framework — Kysely, migrations, RLS, multi-dialect
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
- Part of the [Omni](../../README.md) monorepo — Fullstack Type-Safe RPC Framework.
5
+ ## Capabilities
6
6
 
7
- ## Installation
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
- ```bash
12
+ ## Quick start
13
+
14
+ ```sh
10
15
  pnpm add @omnitron-dev/titan-database
11
16
  ```
12
17
 
13
- Install the driver for each database your application uses. For SQLite, install
14
- `better-sqlite3@^13.0.3` and use Node.js 22.14+ on 22.x or 23.6+.
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
- ## Architecture and migrations
30
-
31
- Kysera owns query extensions, repositories, savepoints, retry policies and the
32
- migration engine. Titan adds connection lifecycle, DI and transaction context.
33
- Nested transactions reuse Kysera DAL savepoints; a different database receives
34
- its own transaction. This does not provide distributed atomicity.
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
- `@omnitron-dev/titan-database/readiness` exports `requirePostgresSchema(pool, requirements)`.
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
- Declare only the objects the component consumes. Compatible additional tables,
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
- `unique` declares ordered whole-table keys. Readiness checks the enforcing
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
- `typeSchema` supports named enum/domain types outside `pg_catalog`.
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
- The third argument accepts positive `statementTimeoutMs` and `lockTimeoutMs`.
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
- A mismatch throws `SchemaReadinessError` with code `database_schema_incompatible`,
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.4.6",
3
+ "version": "0.4.9",
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.4.6",
70
+ "@omnitron-dev/eventemitter": "0.4.9",
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.4.6",
77
+ "@omnitron-dev/titan": "0.4.9",
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.4.6",
94
+ "@omnitron-dev/titan": "0.4.9",
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": "3a912fa181e97ddd238a28bb355cd7445c1b7364",
106
+ "gitHead": "c6005ff1d0cde480cfa6b0bc346c9b53b2e638bf",
107
107
  "scripts": {
108
108
  "build": "../../scripts/build-package.sh -p ./tsconfig.json",
109
109
  "test": "vitest run",