@argos-js/data 0.0.0-stage → 0.1.0

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 (131) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +799 -2
  3. package/dist/connection/index.d.ts +2 -0
  4. package/dist/connection/index.d.ts.map +1 -0
  5. package/dist/connection/index.js +18 -0
  6. package/dist/connection/index.js.map +1 -0
  7. package/dist/connection/manager.d.ts +93 -0
  8. package/dist/connection/manager.d.ts.map +1 -0
  9. package/dist/connection/manager.js +194 -0
  10. package/dist/connection/manager.js.map +1 -0
  11. package/dist/database.d.ts +29 -0
  12. package/dist/database.d.ts.map +1 -0
  13. package/dist/database.js +276 -0
  14. package/dist/database.js.map +1 -0
  15. package/dist/drivers/base-driver.d.ts +18 -0
  16. package/dist/drivers/base-driver.d.ts.map +1 -0
  17. package/dist/drivers/base-driver.js +211 -0
  18. package/dist/drivers/base-driver.js.map +1 -0
  19. package/dist/drivers/index.d.ts +11 -0
  20. package/dist/drivers/index.d.ts.map +1 -0
  21. package/dist/drivers/index.js +55 -0
  22. package/dist/drivers/index.js.map +1 -0
  23. package/dist/drivers/mavedb-edge.d.ts +8 -0
  24. package/dist/drivers/mavedb-edge.d.ts.map +1 -0
  25. package/dist/drivers/mavedb-edge.js +18 -0
  26. package/dist/drivers/mavedb-edge.js.map +1 -0
  27. package/dist/drivers/mongodb.d.ts +8 -0
  28. package/dist/drivers/mongodb.d.ts.map +1 -0
  29. package/dist/drivers/mongodb.js +18 -0
  30. package/dist/drivers/mongodb.js.map +1 -0
  31. package/dist/drivers/mssql.d.ts +8 -0
  32. package/dist/drivers/mssql.d.ts.map +1 -0
  33. package/dist/drivers/mssql.js +18 -0
  34. package/dist/drivers/mssql.js.map +1 -0
  35. package/dist/drivers/mysql.d.ts +8 -0
  36. package/dist/drivers/mysql.d.ts.map +1 -0
  37. package/dist/drivers/mysql.js +18 -0
  38. package/dist/drivers/mysql.js.map +1 -0
  39. package/dist/drivers/postgres.d.ts +8 -0
  40. package/dist/drivers/postgres.d.ts.map +1 -0
  41. package/dist/drivers/postgres.js +18 -0
  42. package/dist/drivers/postgres.js.map +1 -0
  43. package/dist/drivers/redis.d.ts +9 -0
  44. package/dist/drivers/redis.d.ts.map +1 -0
  45. package/dist/drivers/redis.js +50 -0
  46. package/dist/drivers/redis.js.map +1 -0
  47. package/dist/drivers/sqlite.d.ts +8 -0
  48. package/dist/drivers/sqlite.d.ts.map +1 -0
  49. package/dist/drivers/sqlite.js +18 -0
  50. package/dist/drivers/sqlite.js.map +1 -0
  51. package/dist/index.d.ts +14 -0
  52. package/dist/index.d.ts.map +1 -0
  53. package/dist/index.js +49 -0
  54. package/dist/index.js.map +1 -0
  55. package/dist/migrations/index.d.ts +7 -0
  56. package/dist/migrations/index.d.ts.map +1 -0
  57. package/dist/migrations/index.js +23 -0
  58. package/dist/migrations/index.js.map +1 -0
  59. package/dist/migrations/migrator.d.ts +79 -0
  60. package/dist/migrations/migrator.d.ts.map +1 -0
  61. package/dist/migrations/migrator.js +274 -0
  62. package/dist/migrations/migrator.js.map +1 -0
  63. package/dist/migrations/schema-builder.d.ts +318 -0
  64. package/dist/migrations/schema-builder.d.ts.map +1 -0
  65. package/dist/migrations/schema-builder.js +957 -0
  66. package/dist/migrations/schema-builder.js.map +1 -0
  67. package/dist/migrations/types.d.ts +58 -0
  68. package/dist/migrations/types.d.ts.map +1 -0
  69. package/dist/migrations/types.js +3 -0
  70. package/dist/migrations/types.js.map +1 -0
  71. package/dist/model.d.ts +107 -0
  72. package/dist/model.d.ts.map +1 -0
  73. package/dist/model.js +333 -0
  74. package/dist/model.js.map +1 -0
  75. package/dist/plugin.d.ts +38 -0
  76. package/dist/plugin.d.ts.map +1 -0
  77. package/dist/plugin.js +83 -0
  78. package/dist/plugin.js.map +1 -0
  79. package/dist/query-builder.d.ts +58 -0
  80. package/dist/query-builder.d.ts.map +1 -0
  81. package/dist/query-builder.js +534 -0
  82. package/dist/query-builder.js.map +1 -0
  83. package/dist/schema-adapter.d.ts +34 -0
  84. package/dist/schema-adapter.d.ts.map +1 -0
  85. package/dist/schema-adapter.js +511 -0
  86. package/dist/schema-adapter.js.map +1 -0
  87. package/dist/schema.d.ts +104 -0
  88. package/dist/schema.d.ts.map +1 -0
  89. package/dist/schema.js +190 -0
  90. package/dist/schema.js.map +1 -0
  91. package/dist/seeds/index.d.ts +3 -0
  92. package/dist/seeds/index.d.ts.map +1 -0
  93. package/dist/seeds/index.js +19 -0
  94. package/dist/seeds/index.js.map +1 -0
  95. package/dist/seeds/seeder.d.ts +27 -0
  96. package/dist/seeds/seeder.d.ts.map +1 -0
  97. package/dist/seeds/seeder.js +138 -0
  98. package/dist/seeds/seeder.js.map +1 -0
  99. package/dist/seeds/types.d.ts +60 -0
  100. package/dist/seeds/types.d.ts.map +1 -0
  101. package/dist/seeds/types.js +3 -0
  102. package/dist/seeds/types.js.map +1 -0
  103. package/dist/sync/dump.d.ts +80 -0
  104. package/dist/sync/dump.d.ts.map +1 -0
  105. package/dist/sync/dump.js +655 -0
  106. package/dist/sync/dump.js.map +1 -0
  107. package/dist/sync/index.d.ts +5 -0
  108. package/dist/sync/index.d.ts.map +1 -0
  109. package/dist/sync/index.js +21 -0
  110. package/dist/sync/index.js.map +1 -0
  111. package/dist/sync/introspector.d.ts +49 -0
  112. package/dist/sync/introspector.d.ts.map +1 -0
  113. package/dist/sync/introspector.js +750 -0
  114. package/dist/sync/introspector.js.map +1 -0
  115. package/dist/sync/synchronizer.d.ts +50 -0
  116. package/dist/sync/synchronizer.d.ts.map +1 -0
  117. package/dist/sync/synchronizer.js +506 -0
  118. package/dist/sync/synchronizer.js.map +1 -0
  119. package/dist/sync/types.d.ts +83 -0
  120. package/dist/sync/types.d.ts.map +1 -0
  121. package/dist/sync/types.js +3 -0
  122. package/dist/sync/types.js.map +1 -0
  123. package/dist/tenant/sequence.d.ts +36 -0
  124. package/dist/tenant/sequence.d.ts.map +1 -0
  125. package/dist/tenant/sequence.js +130 -0
  126. package/dist/tenant/sequence.js.map +1 -0
  127. package/dist/types.d.ts +81 -0
  128. package/dist/types.d.ts.map +1 -0
  129. package/dist/types.js +3 -0
  130. package/dist/types.js.map +1 -0
  131. package/package.json +38 -3
package/README.md CHANGED
@@ -1,3 +1,800 @@
1
- # Temporary Holding Version
1
+ # @argos-js/data
2
+
3
+ High-performance database layer, Universal Schema Normalizer, Active Record ORM, and Transactional SQL Migration Engine for **Argos-JS**.
4
+
5
+ ---
6
+
7
+ - 🔌 Multi-driver & dialect support: **SQLite**, **PostgreSQL**, **MySQL**, **MariaDB**, **MS SQL Server (T-SQL)**, **Oracle (PL/SQL)**, **Redis**, and **Edge/KV**
8
+ - 🌐 **Connection Manager & Registry**: Seamless multi-connection pool management (`DatabaseManager`), named connection selection, and model-level routing
9
+ - 🔄 **Database Introspection & Streaming Sync (`DatabaseSynchronizer`)**: Cross-dialect zero-downtime database migration engine (SQLite ➔ Postgres/MySQL/MaveDB) with foreign key isolation, chunked streaming, and sequence alignment
10
+ - 📦 **Canonical Database Dump & Restore (`DatabaseDumper` / `DatabaseRestorer`)**: Collation-safe agnostic dump bundle (`.argos`) with streaming `.ndjson` chunks, zero vendor lock-in, and automatic identity/sequence recalibration
11
+ - 🗑️ **Native Declarative Soft Deletes**: Automatic query scoping (`deleted_at IS NULL`), query modifiers (`.withTrashed()`, `.onlyTrashed()`), and lifecycle helpers (`.restore()`, `.forceDelete()`)
12
+ - 🧠 **Advanced Data Types, Vectors (AI) & Generated Columns**: Native `jsonb`, `vector(dim)` (pgvector), `inet`, `macAddress`, `money`, `enum`, `.as(...)` generated columns, and specialized indexes (GIN, HNSW, Full-Text)
13
+ - 📐 Universal Schema Normalizer (`defineTable`) compiling to native Drizzle schemas across all drivers
14
+ - 🧠 Active Record Models (`Model`) with CRUD, queries, and pagination
15
+ - 🛡️ Safe-sync table synchronization (`options.sync` / `db.syncTables`)
16
+ - ⚡ **Transactional SQL Migration Engine (`Migrator`)** with automatic batching, audit history, and rollback capabilities
17
+ - 🌱 **Database Seeder Engine (`DatabaseSeeder`)**: Isolated per-file transactional execution, chronological ordering, and duration profiling
18
+
19
+ ---
20
+
21
+ ## Transactional SQL Migration Engine
22
+
23
+ `@argos-js/data` provides a robust, driver-agnostic migration engine designed for production safety.
24
+
25
+ ### Audit Table (`_argos_migrations`)
26
+
27
+ The engine automatically ensures the existence of the internal `_argos_migrations` tracking table:
28
+
29
+ | Column | Type | Description |
30
+ |--------|------|-------------|
31
+ | `id` | `INTEGER` / `SERIAL` | Auto-incrementing primary key |
32
+ | `name` | `VARCHAR(255)` / `TEXT` | Unique migration file name |
33
+ | `batch` | `INTEGER` | Execution batch group number |
34
+ | `executed_at` | `TIMESTAMP` | Execution timestamp (defaults to current timestamp) |
35
+
36
+ ---
37
+
38
+ ### Migration Lifecycle & API
39
+
40
+ ```typescript
41
+ import { createDatabase, Migrator } from '@argos-js/data';
42
+
43
+ const db = createDatabase({
44
+ driver: 'sqlite',
45
+ database: './storage/database.sqlite',
46
+ });
47
+ await db.connect();
48
+
49
+ const migrator = new Migrator(db, {
50
+ migrationsDir: './app/database/migrations',
51
+ });
52
+ ```
53
+
54
+ #### 1. Run Pending Migrations (`runPendingMigrations`)
55
+
56
+ Executes all pending migrations in chronological order. Each migration runs inside an isolated database transaction. If any migration fails, its transaction rolls back immediately and stops execution.
57
+
58
+ ```typescript
59
+ const result = await migrator.runPendingMigrations();
60
+ // {
61
+ // migrated: ['20261002084000_create_products_table'],
62
+ // batch: 1,
63
+ // steps: [{ name: '20261002084000_create_products_table', durationMs: 12 }]
64
+ // }
65
+ ```
66
+
67
+ #### 2. Rollback Last Batch (`rollbackLastBatch`)
68
+
69
+ Rolls back the most recent migration batch. Migrations in that batch are executed in **reverse chronological order** (newest to oldest), running their `down(db)` functions within a transaction, and removing their records from `_argos_migrations`.
70
+
71
+ ```typescript
72
+ const result = await migrator.rollbackLastBatch();
73
+ // {
74
+ // rolledBack: ['20261002084000_create_products_table'],
75
+ // batch: 1,
76
+ // steps: [{ name: '20261002084000_create_products_table', durationMs: 8 }]
77
+ // }
78
+ ```
79
+
80
+ #### 3. Migration Status (`getMigrationStatus`)
81
+
82
+ Inspects both the filesystem and the database to produce an exact status report of all migrations:
83
+
84
+ ```typescript
85
+ const status = await migrator.getMigrationStatus();
86
+ // [
87
+ // {
88
+ // name: '20261002084000_create_products_table',
89
+ // status: 'applied',
90
+ // batch: 1,
91
+ // executed_at: '2026-10-02 11:45:00',
92
+ // fullPath: '/path/to/app/database/migrations/20261002084000_create_products_table.ts'
93
+ // },
94
+ // {
95
+ // name: '20261002090000_add_tags_to_products',
96
+ // status: 'pending',
97
+ // batch: null,
98
+ // executed_at: null,
99
+ // fullPath: '/path/to/app/database/migrations/20261002090000_add_tags_to_products.ts'
100
+ // }
101
+ // ]
102
+ ```
103
+
104
+ ---
105
+
106
+ ## Database Migrations Guide
107
+
108
+ Argos-JS provides a robust, dialect-agnostic database migration engine powered by a fluent Schema Builder. It removes manual DDL incompatibilities across **SQLite**, **PostgreSQL**, and **MySQL**, while supporting multi-tenant SaaS patterns out of the box.
109
+
110
+ ### 1. Migration CLI Lifecycle
111
+
112
+ Manage migrations through the unified Argos CLI:
113
+
114
+ ```bash
115
+ # Generate a new migration with the fluent Schema Builder template
116
+ argos create migration create_organizations_table
117
+ # (or shorthand)
118
+ argos c migration create_organizations_table
119
+
120
+ # Apply all pending migrations in transactional order
121
+ argos db migrate
122
+
123
+ # Revert the latest batch of applied migrations
124
+ argos db rollback
125
+
126
+ # Inspect status of all migrations (applied / pending with execution times)
127
+ argos db status
128
+ ```
129
+
130
+ ---
131
+
132
+ ### 2. Fluent Schema Builder (`SchemaBuilder` & `TableBlueprint`)
133
+
134
+ The fluent schema builder allows you to write migrations once and deploy them safely across any supported database engine.
135
+
136
+ #### Migration File Structure
137
+
138
+ ```typescript
139
+ import type { MigrationContext } from '@argos-js/data';
140
+
141
+ /**
142
+ * Migration: create_invoices_table
143
+ */
144
+ export async function up({ schema, db }: MigrationContext): Promise<void> {
145
+ await schema.createTable('invoices', (table) => {
146
+ // Agnostic primary key
147
+ table.id();
148
+
149
+ // Multi-tenant organization reference (UUID / UUIDv7)
150
+ table.uuidV7('organization_id').notNull().index('idx_invoices_org');
151
+
152
+ // Human-friendly sequential invoice number scoped per organization
153
+ table.integer('sequence_number').notNull();
154
+ table.string('invoice_code', 50).notNull();
155
+
156
+ // Financial decimal with precision & scale
157
+ table.decimal('amount', 12, 2).notNull();
158
+ table.string('currency', 3).default('BRL').notNull();
159
+
160
+ // Status and boolean flags
161
+ table.string('status', 30).default('draft').notNull();
162
+ table.boolean('is_paid').default(false).notNull();
163
+
164
+ // Description text (nullable)
165
+ table.text('notes').nullable();
166
+
167
+ // Dialect-specific timestamps (created_at, updated_at)
168
+ table.timestamps();
169
+
170
+ // Multi-column unique constraint
171
+ table.unique(['organization_id', 'sequence_number'], 'uniq_org_invoice_seq');
172
+ });
173
+ }
174
+
175
+ export async function down({ schema }: MigrationContext): Promise<void> {
176
+ await schema.dropTableIfExists('invoices');
177
+ }
178
+ ```
179
+
180
+ #### Agnostic Dialect Compilation
181
+
182
+ The Schema Builder compiles appropriate types for each database engine automatically:
183
+
184
+ | Blueprint Method | SQLite | PostgreSQL | MySQL |
185
+ |---|---|---|---|
186
+ | `table.id()` | `INTEGER PRIMARY KEY AUTOINCREMENT` | `BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY` | `BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY` |
187
+ | `table.uuid(col)` / `uuidV7(col)` | `TEXT` | `UUID` | `VARCHAR(36)` |
188
+ | `table.string(col, len)` | `VARCHAR(len)` | `VARCHAR(len)` | `VARCHAR(len)` |
189
+ | `table.text(col)` | `TEXT` | `TEXT` | `TEXT` |
190
+ | `table.integer(col)` | `INTEGER` | `INTEGER` | `INT` |
191
+ | `table.decimal(col, p, s)` | `DECIMAL(p, s)` | `DECIMAL(p, s)` | `DECIMAL(p, s)` |
192
+ | `table.boolean(col)` | `BOOLEAN` | `BOOLEAN` | `BOOLEAN` |
193
+ | `table.sequence(col, opts)` | `INTEGER` ou `VARCHAR(64)` | `INTEGER` ou `VARCHAR(64)` | `INT` ou `VARCHAR(64)` |
194
+ | `table.timestamps()` | `created_at TIMESTAMP...`, `updated_at TIMESTAMP...` | `created_at TIMESTAMPTZ...`, `updated_at TIMESTAMPTZ...` | `created_at TIMESTAMP...`, `updated_at TIMESTAMP... ON UPDATE CURRENT_TIMESTAMP` |
195
+
196
+ #### Chainable Column Modifiers
197
+
198
+ - `.notNull()`: Marks column as `NOT NULL`.
199
+ - `.nullable()`: Allows `NULL` values.
200
+ - `.unique()`: Adds inline `UNIQUE` constraint.
201
+ - `.default(value)`: Sets default value (`TRUE`/`FALSE`, strings, numbers, or `CURRENT_TIMESTAMP`).
202
+ - `.index(indexName?)`: Generates an index statement for the column.
203
+ - `.primaryKey()`: Designates the column as part of the primary key.
204
+
205
+ #### Altering Tables (`alterTable`)
206
+
207
+ ```typescript
208
+ export async function up({ schema }: MigrationContext): Promise<void> {
209
+ await schema.alterTable('invoices', (table) => {
210
+ table.string('billing_email', 255);
211
+ table.dropColumn('legacy_flag');
212
+ });
213
+ }
214
+ ```
215
+
216
+ ---
217
+
218
+ ### 3. Declarative `sequence` for Multi-Tenant / SaaS Architectures
219
+
220
+ Exposing global auto-incrementing IDs in public URLs creates severe security vulnerabilities (enumeration attacks, leaking competitor transaction volumes).
221
+
222
+ Argos-JS solves this natively through the **`sequence`** column type:
223
+ 1. **Internal Primary Key**: `t.uuidV7('id').primaryKey()` for secure, unguessable, ordered UUIDs.
224
+ 2. **Declarative Sequence**: `t.sequence({ by: 'organization_id', prefix: 'INV-', pad: 4 })` for human-friendly numbers (`INV-0001`, `INV-0002`) scoped per tenant.
225
+
226
+ #### Declarative Schema Definition
227
+
228
+ ```typescript
229
+ import { defineTable } from '@argos-js/data';
230
+
231
+ export const InvoicesTable = defineTable('invoices', (t) => ({
232
+ id: t.uuidV7('id').primaryKey(),
233
+ orgId: t.uuid('organization_id').notNull(),
234
+
235
+ // Fully automated: Argos generates and formats within the insert transaction
236
+ invoiceCode: t.sequence({ by: 'organization_id', prefix: 'INV-', pad: 4 }),
237
+
238
+ // Or numeric-only sequence (1, 2, 3...):
239
+ // sequenceNumber: t.sequence({ by: 'organization_id' }),
240
+
241
+ amount: t.decimal('amount', 10, 2).notNull(),
242
+ createdAt: t.timestamp('created_at'),
243
+ }));
244
+ ```
245
+
246
+ #### Zero-Boilerplate Controller Usage
247
+
248
+ In your controllers, **you do not need to call any sequence generator manually**:
249
+
250
+ ```typescript
251
+ app.post('/api/invoices', async (ctx) => {
252
+ const organizationId = ctx.state.organizationId;
253
+ const data = await ctx.validate({ amount: v.number().positive() });
254
+
255
+ // Just call create!
256
+ // Argos automatically:
257
+ // 1. Opens an atomic transaction
258
+ // 2. Computes the next sequence for this organization
259
+ // 3. Formats to "INV-0001"
260
+ // 4. Inserts the record
261
+ // 5. If the insert fails, the transaction rolls back so numbers are NEVER skipped!
262
+ const invoice = await InvoiceModel.create({
263
+ orgId: organizationId,
264
+ amount: data.amount,
265
+ });
266
+
267
+ return ctx.json({ invoice }, 201);
268
+ });
269
+ ```
270
+
271
+ #### Advanced / Direct Helper (`getNextTenantSequence`)
272
+
273
+ For custom procedures or manual batch tasks, you can also query the sequence directly:
274
+
275
+ ```typescript
276
+ import { getNextTenantSequence, formatSequence } from '@argos-js/data';
277
+
278
+ const nextNum = await getNextTenantSequence(ctx.db, organizationId, 'invoices');
279
+ const code = formatSequence(nextNum, { prefix: 'INV-', pad: 4 }); // "INV-0001"
280
+ ```
281
+
282
+ The internal control table `_argos_tenant_sequences` utilizes row-level transactional locks (`ON CONFLICT ... RETURNING` / `FOR UPDATE`), guaranteeing strictly consecutive numbering without collisions under heavy concurrency.
283
+
284
+ ---
285
+
286
+ ## Multi-Connection Architecture (Connection Manager / Registry)
287
+
288
+ `@argos-js/data` includes a built-in Connection Manager and Registry pattern (`DatabaseManager`), enabling enterprise-grade multi-database architectures:
289
+ - Multi-tenant architectures with segregated databases per organization.
290
+ - Read/write replica splitting or dedicated reporting/analytics warehouses.
291
+ - Legacy system data synchronization alongside modern application stores.
292
+
293
+ ### 1. Registering Multiple Connections
294
+
295
+ Configure named connections in your application bootstrap via `databasePlugin`:
296
+
297
+ ```typescript
298
+ import { ArgosApplication } from '@argos-js/core';
299
+ import { databasePlugin } from '@argos-js/data';
300
+
301
+ const app = new ArgosApplication();
302
+
303
+ await app.register(databasePlugin, {
304
+ default: 'primary',
305
+ connections: {
306
+ primary: {
307
+ driver: 'postgres',
308
+ host: process.env.DB_HOST,
309
+ database: process.env.DB_NAME,
310
+ user: process.env.DB_USER,
311
+ password: process.env.DB_PASSWORD,
312
+ },
313
+ analytics: {
314
+ driver: 'postgres',
315
+ connectionString: process.env.ANALYTICS_DB_URL,
316
+ },
317
+ cache_store: {
318
+ driver: 'sqlite',
319
+ database: './storage/cache.sqlite',
320
+ },
321
+ },
322
+ });
323
+ ```
324
+
325
+ ### 2. Transparent `db` Proxy & Named Connections
326
+
327
+ The exported `db` singleton serves as a transparent proxy to the configured `default` connection while providing on-demand access to named connection pools via `db.connection(name)`:
328
+
329
+ ```typescript
330
+ import { db } from '@argos-js/data';
331
+
332
+ // 1. Transparent delegation to the default connection ("primary")
333
+ const users = await db.query('SELECT * FROM users WHERE active = $1', [true]);
334
+ await db.table('orders').insert({ total: 150.0 });
335
+
336
+ // 2. Querying a specific named connection
337
+ const report = await db.connection('analytics').query(
338
+ 'SELECT metric_name, SUM(value) as total FROM event_metrics GROUP BY metric_name'
339
+ );
340
+
341
+ // 3. Executing DDL or queries on a local SQLite cache store
342
+ await db.connection('cache_store').execute(
343
+ 'INSERT INTO cache_entries (key, val) VALUES (?, ?)',
344
+ ['session_123', JSON.stringify({ userId: 1 })]
345
+ );
346
+ ```
347
+
348
+ ### 3. Model-Level Connection Binding (`static connection`)
349
+
350
+ Active Record models can bind to specific named databases via `static connection`. All CRUD and query builder operations (`all()`, `find()`, `where()`, `create()`, `save()`, `delete()`) automatically route to the configured database:
351
+
352
+ ```typescript
353
+ import { Model } from '@argos-js/data';
354
+
355
+ // Binds to default connection ("primary")
356
+ export class User extends Model {
357
+ public static override tableName = 'users';
358
+
359
+ public id!: number;
360
+ public name!: string;
361
+ public email!: string;
362
+ }
363
+
364
+ // Binds explicitly to the "analytics" connection
365
+ export class AuditLog extends Model {
366
+ public static override tableName = 'audit_logs';
367
+ public static override connection = 'analytics';
368
+
369
+ public id?: number;
370
+ public action!: string;
371
+ public performedAt!: string;
372
+ }
373
+
374
+ // In your application logic or HTTP controllers:
375
+ app.post('/api/users', async (ctx) => {
376
+ const { name, email } = await ctx.validate({
377
+ name: v.string().min(2),
378
+ email: v.string().email(),
379
+ });
380
+
381
+ // Saved to "primary" database
382
+ const user = await User.create({ name, email });
383
+
384
+ // Saved to "analytics" database
385
+ await AuditLog.create({
386
+ action: `USER_CREATED:${user.id}`,
387
+ performedAt: new Date().toISOString(),
388
+ });
389
+
390
+ return ctx.json({ user }, 201);
391
+ });
392
+ ```
393
+
394
+ ### 4. Running Migrations on Secondary Connections
395
+
396
+ The Argos CLI supports running migrations against any named database connection configured in your `config/database.ts`:
397
+
398
+ ```bash
399
+ # Run migrations on the default connection
400
+ argos db migrate
401
+
402
+ # Run migrations specifically on the "analytics" connection
403
+ argos db migrate --connection=analytics
404
+
405
+ # Rollback last migration batch on the "analytics" connection
406
+ argos db rollback --connection=analytics
407
+
408
+ # Inspect migration status for the "analytics" connection
409
+ argos db status --connection=analytics
410
+ ```
411
+
412
+ ### 5. Graceful Shutdown & Pool Management
413
+
414
+ All active connection pools are safely closed on application shutdown or manually via:
415
+
416
+ ```typescript
417
+ import { databaseManager } from '@argos-js/data';
418
+
419
+ // Closes all pooled connections (PostgreSQL, MySQL, SQLite)
420
+ await databaseManager.closeAll();
421
+ ```
422
+
423
+ ---
424
+
425
+ ## Database Introspection & Cross-Dialect Streaming Sync (`argos db sync`)
426
+
427
+ `@argos-js/data` includes a built-in Introspection and Streaming Synchronization engine (`DatabaseIntrospector` and `DatabaseSynchronizer`), enabling seamless cross-dialect database migrations (e.g., migrating a local development SQLite database into cloud PostgreSQL, MySQL, or MaveDB with zero data loss).
428
+
429
+ ### How It Works
430
+
431
+ The synchronization runs in four discrete, safe phases:
432
+
433
+ 1. **Phase 1 (Structure)**: Introspects the source database (`DatabaseIntrospector`), parses tables, columns, data types, primary keys, nullability, unique keys, and indices. It then creates matching tables in the target database using `TableBlueprint`, automatically mapping types to the target dialect.
434
+ 2. **Phase 2 (Constraint Isolation)**: Temporarily disables foreign key constraint checks in the target database (`PRAGMA foreign_keys = OFF`, `SET session_replication_role = 'replica'`, or `SET FOREIGN_KEY_CHECKS = 0`) to prevent insertion order deadlocks.
435
+ 3. **Phase 3 (Streaming Data Migration)**: Streams records in paginated cursor/offset batches (`batchSize = 1000` default), normalizes values (converting integer booleans, ISO date strings, JSON structures), and executes transactional bulk inserts.
436
+ 4. **Phase 4 (Post-Sync & Sequence Alignment)**: Re-enables foreign key checks and realigns auto-increment sequences / serial counters in the target database to match the highest inserted ID. Multi-tenant sequences in `_argos_tenant_sequences` are preserved with exact parity.
437
+
438
+ ### Programmatic API
439
+
440
+ ```typescript
441
+ import { DatabaseSynchronizer, databaseManager } from '@argos-js/data';
442
+
443
+ const synchronizer = new DatabaseSynchronizer();
444
+
445
+ const result = await synchronizer.sync({
446
+ from: 'sqlite_local', // Connection name or DatabaseClient instance
447
+ to: 'postgres_production', // Connection name or DatabaseClient instance
448
+ batchSize: 2000,
449
+ truncate: true, // Empties destination tables before sync
450
+ onProgress: (progress) => {
451
+ console.log(`[Phase: ${progress.phase}] Current table: ${progress.currentTable}`);
452
+ },
453
+ });
454
+
455
+ console.log(`Migrated ${result.rowsMigrated} rows across ${result.tablesMigrated} tables in ${result.durationMs}ms`);
456
+ ```
457
+
458
+ ### CLI Command
459
+
460
+ ```bash
461
+ # Sync from default connection to production
462
+ argos db sync --to production
463
+
464
+ # Sync from named local connection to cloud postgres with truncate
465
+ argos db sync --from sqlite_dev --to cloud_postgres --truncate
466
+
467
+ # Transparent alias
468
+ argos sync --from sqlite_dev --to mysql_prod --batch-size 5000
469
+ ```
470
+
471
+ ---
472
+
473
+ ## Database Seeder Engine (`DatabaseSeeder`)
474
+
475
+ `@argos-js/data` provides an isolated, transactional database seeder engine to populate development, test, and initial production environments with dummy or catalog data.
476
+
477
+ ### Key Capabilities
478
+
479
+ - 🔒 **Per-file Transaction Isolation**: Each seed file executes within its own dedicated database transaction. If a seed throws an unhandled error, its changes roll back atomically without leaving corrupted records.
480
+ - 🕒 **Ordered Chronological Execution**: Seeds in `app/database/seeds/` are executed in strict alphabetical/chronological order (e.g. `20261002140000_initial_roles.seed.ts`, `20261002140500_default_admin.seed.ts`).
481
+ - 🎯 **Specific Seed Execution**: Execute a single seed file or pattern using the `specificSeed` option.
482
+ - ⏱️ **Duration Profiling**: Automatically tracks and reports execution duration for every individual seed file as well as the total run time.
483
+ - 🌐 **Multi-Connection Aware**: Target any registered connection from `DatabaseManager` dynamically.
484
+
485
+ ### Seed Context & File Structure
486
+
487
+ Each seed file exports an async `run` function accepting a `SeedContext`:
488
+
489
+ ```typescript
490
+ import type { SeedContext } from '@argos-js/data';
491
+
492
+ export async function run({ db }: SeedContext): Promise<void> {
493
+ // Use transactional db client or Active Record models
494
+ await db.execute("INSERT INTO roles (name) VALUES ('admin'), ('editor')");
495
+ }
496
+ ```
497
+
498
+ ### Programmatic Usage
499
+
500
+ ```typescript
501
+ import { createDatabase, DatabaseSeeder } from '@argos-js/data';
502
+
503
+ const db = createDatabase({
504
+ driver: 'sqlite',
505
+ database: './storage/database.sqlite',
506
+ });
507
+ await db.connect();
508
+
509
+ const seeder = new DatabaseSeeder(db, {
510
+ seedsDir: './app/database/seeds',
511
+ });
512
+
513
+ // Run all pending seeds
514
+ const result = await seeder.run();
515
+ console.log(`Seeded ${result.seeded.length} files in ${result.totalDurationMs}ms`);
516
+
517
+ // Run a specific seed file
518
+ await seeder.run({
519
+ specificSeed: 'initial_roles',
520
+ });
521
+
522
+ // Run against a specific connection configured in DatabaseManager
523
+ await seeder.run({
524
+ connection: 'secondary',
525
+ });
526
+ ```
527
+
528
+ ---
529
+
530
+ ## Supported SQL Dialects & Agnostic Mapping Matrix
531
+
532
+ `@argos-js/data` natively supports multi-engine schemas with zero vendor lock-in. `TableBlueprint` and `DatabaseIntrospector` map agnostic types to native SQL types across all supported engines:
533
+
534
+ | Agnostic Type | SQLite | PostgreSQL | MySQL | MariaDB | MS SQL Server (T-SQL) | Oracle (PL/SQL) |
535
+ |---|---|---|---|---|---|---|
536
+ | `table.id()` | `INTEGER PRIMARY KEY AUTOINCREMENT` | `BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY` | `BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY` | `BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY` | `BIGINT IDENTITY(1,1) PRIMARY KEY` | `NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY` |
537
+ | `table.boolean()` | `BOOLEAN` (0/1) | `BOOLEAN` | `BOOLEAN` | `BOOLEAN` | `BIT` | `NUMBER(1) CHECK ({col} IN (0, 1))` |
538
+ | `table.string(len)` | `VARCHAR(len)` | `VARCHAR(len)` | `VARCHAR(len)` | `VARCHAR(len)` | `NVARCHAR(len)` | `VARCHAR2(len)` |
539
+ | `table.text()` | `TEXT` | `TEXT` | `TEXT` | `TEXT` | `NVARCHAR(MAX)` | `CLOB` |
540
+ | `table.integer()` | `INTEGER` | `INTEGER` | `INT` | `INT` | `INT` | `NUMBER(10)` |
541
+ | `table.bigint()` | `INTEGER` | `BIGINT` | `BIGINT` | `BIGINT` | `BIGINT` | `NUMBER(19)` |
542
+ | `table.decimal(p, s)` | `DECIMAL(p, s)` | `DECIMAL(p, s)` | `DECIMAL(p, s)` | `DECIMAL(p, s)` | `DECIMAL(p, s)` | `NUMBER(p, s)` |
543
+ | `table.timestamps()` | `TIMESTAMP DEFAULT CURRENT_TIMESTAMP` | `TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP` | `TIMESTAMP DEFAULT CURRENT_TIMESTAMP` | `TIMESTAMP DEFAULT CURRENT_TIMESTAMP` | `DATETIME2(6) DEFAULT SYSUTCDATETIME()` | `TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP` |
544
+ | **FK Isolation** | `PRAGMA foreign_keys = OFF/ON` | `SET session_replication_role = 'replica'/'origin'` | `SET FOREIGN_KEY_CHECKS = 0/1` | `SET FOREIGN_KEY_CHECKS = 0/1` | `ALTER TABLE {t} NOCHECK/CHECK CONSTRAINT ALL` | `ALTER TABLE {t} DISABLE/ENABLE CONSTRAINT {c}` |
545
+
546
+ > **Collation Safety (MariaDB)**: Automatically sanitizes incompatible MySQL 8 collations (`utf8mb4_0900_ai_ci`) to ensure portable, error-free exports and imports across MariaDB and older MySQL engines.
547
+
548
+ ---
549
+
550
+ ## Canonical Database Dump & Restore (`DatabaseDumper` / `DatabaseRestorer`)
551
+
552
+ Provides cross-dialect database snapshot and restore capabilities via an agnostic `.argos` package bundle:
553
+
554
+ ### Bundle Structure (`<name>.argos/`)
555
+ ```text
556
+ dump_20261002150000.argos/
557
+ ├── manifest.json # Metadata: version, sourceDialect, totalRecords, tables record counts
558
+ ├── schema.json # Normalized IntrospectedSchema (collation-safe, vendor-agnostic)
559
+ └── data/ # Streaming chunked newline-delimited JSON
560
+ ├── departments.ndjson
561
+ └── employees.ndjson
562
+ ```
563
+
564
+ ### Programmatic Usage
565
+
566
+ ```typescript
567
+ import { createDatabase, DatabaseDumper, DatabaseRestorer } from '@argos-js/data';
568
+
569
+ const sourceDb = createDatabase({ driver: 'sqlite', database: './storage/dev.sqlite' });
570
+ const targetDb = createDatabase({ driver: 'postgres', connectionString: 'postgres://user:pass@localhost/prod' });
571
+
572
+ // 1. Export database to canonical .argos package
573
+ const dumper = new DatabaseDumper();
574
+ const dumpResult = await dumper.dump({
575
+ connection: sourceDb,
576
+ outputPath: './storage/dumps/backup.argos',
577
+ batchSize: 1000,
578
+ onProgress: (p) => console.log(`[Dump] ${p.tableName}: ${p.transferredRows}/${p.totalRows}`),
579
+ });
580
+
581
+ // 2. Restore package into destination database
582
+ const restorer = new DatabaseRestorer();
583
+ const restoreResult = await restorer.restore({
584
+ connection: targetDb,
585
+ inputPath: './storage/dumps/backup.argos',
586
+ truncate: true,
587
+ onProgress: (p) => console.log(`[Restore] ${p.tableName}: ${p.transferredRows}/${p.totalRows}`),
588
+ });
589
+ ```
590
+
591
+ ---
592
+
593
+ ## Soft Deletes Guide
594
+
595
+ `@argos-js/data` provides declarative, native, and modern Soft Deletes support across migrations, universal schema definitions (`defineTable`), and Active Record `Model`.
596
+
597
+ When soft deletes are enabled, calling `.delete()` or `.destroy()` will not remove records physically from the database. Instead, it updates the `deleted_at` timestamp. All standard queries automatically filter out soft-deleted records (`WHERE deleted_at IS NULL`) unless explicitly requested otherwise.
598
+
599
+ ### 1. Schema & Migrations
600
+
601
+ #### In Migrations (`TableBlueprint`)
602
+ You can define soft deletes via `table.softDeletes()` or as an option inside `table.timestamps()`:
603
+
604
+ ```typescript
605
+ import { Migration, TableBlueprint } from '@argos-js/data';
606
+
607
+ export const up: Migration = async (db) => {
608
+ await db.schema.createTable('products', (table: TableBlueprint) => {
609
+ table.id();
610
+ table.string('name');
611
+ table.decimal('price', 10, 2);
612
+
613
+ // Explicit soft delete column with automatic index (idx_products_deleted_at)
614
+ table.softDeletes(); // adds nullable 'deleted_at' + index
615
+
616
+ // Or via timestamps options:
617
+ // table.timestamps({ softDeletes: true }); // created_at, updated_at, deleted_at
618
+ });
619
+ };
620
+ ```
621
+
622
+ The DDL generates the appropriate nullable timestamp column across all dialects (`sqlite`, `postgres`, `mysql`, `mariadb`, `mssql`, `oracle`) along with the automatic index `idx_{table}_{column}`.
623
+
624
+ #### In Universal Schema (`defineTable`)
625
+ You can activate soft deletes declaratively on the table definition:
626
+
627
+ ```typescript
628
+ import { defineTable, column } from '@argos-js/data';
629
+
630
+ export const products = defineTable('products', {
631
+ id: column.id(),
632
+ name: column.string(255),
633
+ price: column.decimal(10, 2),
634
+ }, {
635
+ softDeletes: true, // auto-provisions deleted_at and deletedAt fields
636
+ });
637
+ ```
638
+
639
+ ---
640
+
641
+ ### 2. Active Record `Model`
642
+
643
+ Activate soft deletes on your model by setting `public static softDeletes = true;` or linking it to a `defineTable` with `{ softDeletes: true }`:
644
+
645
+ ```typescript
646
+ import { Model } from '@argos-js/data';
647
+
648
+ export class Product extends Model {
649
+ public static table = 'products';
650
+ public static softDeletes = true;
651
+
652
+ public declare id: number;
653
+ public declare name: string;
654
+ public declare deleted_at?: string | null;
655
+ }
656
+ ```
657
+
658
+ #### Query Scoping
659
+
660
+ All reading operations (`all()`, `find()`, `where()`, `first()`) implicitly scope queries to only active records (`WHERE deleted_at IS NULL`):
661
+
662
+ ```typescript
663
+ // Only active records (deleted_at IS NULL)
664
+ const activeProducts = await Product.all();
665
+ const product = await Product.find(1);
666
+ const cheapProducts = await Product.where('price', '<', 50).get();
667
+ ```
668
+
669
+ #### Query Modifiers
670
+
671
+ - **`.withTrashed()`**: Includes both active and soft-deleted records.
672
+ - **`.onlyTrashed()`**: Returns strictly records that have been soft-deleted (`WHERE deleted_at IS NOT NULL`).
673
+
674
+ ```typescript
675
+ // Include soft-deleted records
676
+ const allProductsIncludingTrashed = await Product.withTrashed().get();
677
+ const trashedProduct = await Product.withTrashed().where('id', 1).first();
678
+
679
+ // Only retrieve soft-deleted records
680
+ const trashBin = await Product.onlyTrashed().get();
681
+ ```
682
+
683
+ #### Mutations & Lifecycle
684
+
685
+ - **`.delete()` / `.destroy()`**: Performs logical deletion (`UPDATE ... SET deleted_at = CURRENT_TIMESTAMP`).
686
+ - **`.restore()`**: Restores a soft-deleted record back to active state (`UPDATE ... SET deleted_at = NULL`).
687
+ - **`.forceDelete()`**: Performs physical, permanent deletion (`DELETE FROM ... WHERE ...`).
688
+
689
+ ```typescript
690
+ // 1. Soft Delete an instance or by query
691
+ const product = await Product.find(1);
692
+ await product.delete(); // updates deleted_at on DB and instance
693
+
694
+ await Product.where('price', '>', 1000).delete(); // bulk soft-delete
695
+
696
+ // 2. Restore
697
+ const trashed = await Product.onlyTrashed().where('id', 1).first();
698
+ await trashed.restore(); // restored! deleted_at is now null
699
+
700
+ // Or bulk restore:
701
+ await Product.where('name', 'Vintage Wine').restore();
702
+
703
+ // 3. Permanent Physical Delete
704
+ const obsolete = await Product.withTrashed().where('id', 2).first();
705
+ await obsolete.forceDelete(); // physically removed via DELETE FROM
706
+ ```
707
+
708
+ ---
709
+
710
+ ### 3. Introspection, Sync & Dumps
711
+
712
+ The introspector (`DatabaseIntrospector`) and synchronizer (`DatabaseSynchronizer`) automatically recognize `deleted_at` as a `soft_delete` column type and ensure soft-deleted records and their exact timestamps are faithfully preserved during cross-database sync, canonical dumps, and restores.
713
+
714
+ ---
715
+
716
+ ## Advanced Data Types, Vectors (AI) & Specialized Indexes
717
+
718
+ `@argos-js/data` provides cross-dialect support for modern and advanced data types, AI vector embeddings, computed/generated columns, and specialized indexes (GIN, HNSW, Full-Text).
719
+
720
+ ### 1. Advanced Column Types
721
+
722
+ | Method | Postgres | MySQL / MariaDB | SQLite | MSSQL | Oracle |
723
+ |---|---|---|---|---|---|
724
+ | `table.jsonb(name)` | `JSONB` | `JSON` | `TEXT` | `NVARCHAR(MAX)` | `CLOB` |
725
+ | `table.vector(name, dim)` | `vector({dim})` | `BLOB` | `BLOB` | `VARBINARY(MAX)` | `BLOB` |
726
+ | `table.inet(name)` | `INET` | `VARCHAR(45)` | `VARCHAR(45)` | `NVARCHAR(45)` | `VARCHAR2(45)` |
727
+ | `table.macAddress(name)` | `MACADDR` | `VARCHAR(17)` | `VARCHAR(17)` | `NVARCHAR(17)` | `VARCHAR2(17)` |
728
+ | `table.enum(name, values)` | `VARCHAR(255) CHECK` | `ENUM(...)` | `TEXT CHECK` | `NVARCHAR(255) CHECK` | `VARCHAR2(255) CHECK` |
729
+ | `table.money(name, p, s)` | `DECIMAL(19, 4)` | `DECIMAL(19, 4)` | `DECIMAL(19, 4)` | `DECIMAL(19, 4)` | `NUMBER(19, 4)` |
730
+ | `table.date(name)` | `DATE` | `DATE` | `DATE` | `DATE` | `DATE` |
731
+ | `table.time(name)` | `TIME` | `TIME` | `TIME` | `TIME` | `VARCHAR2(8)` |
732
+
733
+ ### 2. Generated (Computed) Columns (`.as(...)`)
734
+
735
+ You can define stored or virtual computed columns using `.as(expression, options)`:
736
+
737
+ ```typescript
738
+ await db.schema.createTable('invoices', (table) => {
739
+ table.id();
740
+ table.decimal('subtotal', 10, 2);
741
+ table.decimal('tax', 10, 2);
742
+
743
+ // Compiles to STORED generated column across dialects (PERSISTED in MSSQL)
744
+ table.decimal('total', 10, 2).as('subtotal + tax', { mode: 'stored' });
745
+ });
746
+ ```
747
+
748
+ The synchronizer and canonical dumper automatically identify generated columns and safely exclude them from `INSERT` operations during migrations and restores.
749
+
750
+ ### 3. Specialized Indexes & Extensions
751
+
752
+ #### Enable PostgreSQL Extensions
753
+ ```typescript
754
+ await schema.enableExtension('vector'); // executes CREATE EXTENSION IF NOT EXISTS "vector"
755
+ ```
756
+
757
+ #### Specialized Indexes (GIN, GIST, HNSW, Full-Text)
758
+ ```typescript
759
+ await db.schema.createTable('articles', (table) => {
760
+ table.id();
761
+ table.string('title');
762
+ table.jsonb('metadata');
763
+ table.vector('embedding', 1536);
764
+
765
+ // GIN Index
766
+ table.index('metadata', { using: 'gin', name: 'idx_articles_metadata_gin' });
767
+
768
+ // Vector Search Index (HNSW with cosine similarity)
769
+ table.vectorIndex('embedding', { metric: 'cosine', method: 'hnsw' });
770
+
771
+ // Full-Text Search Index
772
+ table.fullText(['title'], { name: 'idx_articles_title_ft' });
773
+ });
774
+ ```
775
+
776
+ ### 4. Query Helpers & Vector Search
777
+
778
+ The `QueryBuilder` and Active Record `Model` include native helpers for advanced querying:
779
+
780
+ ```typescript
781
+ // 1. Vector Proximity Search (Cosine <=> in pgvector)
782
+ const similarArticles = await Article.nearest('embedding', [0.05, 0.12, 0.99], {
783
+ metric: 'cosine',
784
+ limit: 5,
785
+ }).get();
786
+
787
+ // 2. Cross-Dialect JSON Querying (json_extract / ->> / JSON_UNQUOTE / JSON_VALUE)
788
+ const techArticles = await Article.whereJson('metadata.category', 'tech').get();
789
+
790
+ // 3. Dialect-Agnostic Full-Text Search (@@ plainto_tsquery / MATCH AGAINST / LIKE fallback)
791
+ const results = await Article.search('title', 'Distributed').get();
792
+ ```
793
+
794
+ ---
795
+
796
+ ## License
797
+
798
+ MIT
799
+
2
800
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.