@argos-js/data 0.0.0-stage → 0.1.1
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/LICENSE +21 -0
- package/README.md +799 -2
- package/dist/connection/index.d.ts +2 -0
- package/dist/connection/index.d.ts.map +1 -0
- package/dist/connection/index.js +18 -0
- package/dist/connection/index.js.map +1 -0
- package/dist/connection/manager.d.ts +93 -0
- package/dist/connection/manager.d.ts.map +1 -0
- package/dist/connection/manager.js +194 -0
- package/dist/connection/manager.js.map +1 -0
- package/dist/database.d.ts +29 -0
- package/dist/database.d.ts.map +1 -0
- package/dist/database.js +276 -0
- package/dist/database.js.map +1 -0
- package/dist/drivers/base-driver.d.ts +18 -0
- package/dist/drivers/base-driver.d.ts.map +1 -0
- package/dist/drivers/base-driver.js +211 -0
- package/dist/drivers/base-driver.js.map +1 -0
- package/dist/drivers/index.d.ts +11 -0
- package/dist/drivers/index.d.ts.map +1 -0
- package/dist/drivers/index.js +55 -0
- package/dist/drivers/index.js.map +1 -0
- package/dist/drivers/mavedb-edge.d.ts +8 -0
- package/dist/drivers/mavedb-edge.d.ts.map +1 -0
- package/dist/drivers/mavedb-edge.js +18 -0
- package/dist/drivers/mavedb-edge.js.map +1 -0
- package/dist/drivers/mongodb.d.ts +8 -0
- package/dist/drivers/mongodb.d.ts.map +1 -0
- package/dist/drivers/mongodb.js +18 -0
- package/dist/drivers/mongodb.js.map +1 -0
- package/dist/drivers/mssql.d.ts +8 -0
- package/dist/drivers/mssql.d.ts.map +1 -0
- package/dist/drivers/mssql.js +18 -0
- package/dist/drivers/mssql.js.map +1 -0
- package/dist/drivers/mysql.d.ts +8 -0
- package/dist/drivers/mysql.d.ts.map +1 -0
- package/dist/drivers/mysql.js +18 -0
- package/dist/drivers/mysql.js.map +1 -0
- package/dist/drivers/postgres.d.ts +8 -0
- package/dist/drivers/postgres.d.ts.map +1 -0
- package/dist/drivers/postgres.js +18 -0
- package/dist/drivers/postgres.js.map +1 -0
- package/dist/drivers/redis.d.ts +9 -0
- package/dist/drivers/redis.d.ts.map +1 -0
- package/dist/drivers/redis.js +50 -0
- package/dist/drivers/redis.js.map +1 -0
- package/dist/drivers/sqlite.d.ts +8 -0
- package/dist/drivers/sqlite.d.ts.map +1 -0
- package/dist/drivers/sqlite.js +18 -0
- package/dist/drivers/sqlite.js.map +1 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +49 -0
- package/dist/index.js.map +1 -0
- package/dist/migrations/index.d.ts +7 -0
- package/dist/migrations/index.d.ts.map +1 -0
- package/dist/migrations/index.js +23 -0
- package/dist/migrations/index.js.map +1 -0
- package/dist/migrations/migrator.d.ts +79 -0
- package/dist/migrations/migrator.d.ts.map +1 -0
- package/dist/migrations/migrator.js +274 -0
- package/dist/migrations/migrator.js.map +1 -0
- package/dist/migrations/schema-builder.d.ts +318 -0
- package/dist/migrations/schema-builder.d.ts.map +1 -0
- package/dist/migrations/schema-builder.js +957 -0
- package/dist/migrations/schema-builder.js.map +1 -0
- package/dist/migrations/types.d.ts +58 -0
- package/dist/migrations/types.d.ts.map +1 -0
- package/dist/migrations/types.js +3 -0
- package/dist/migrations/types.js.map +1 -0
- package/dist/model.d.ts +107 -0
- package/dist/model.d.ts.map +1 -0
- package/dist/model.js +333 -0
- package/dist/model.js.map +1 -0
- package/dist/plugin.d.ts +38 -0
- package/dist/plugin.d.ts.map +1 -0
- package/dist/plugin.js +83 -0
- package/dist/plugin.js.map +1 -0
- package/dist/query-builder.d.ts +58 -0
- package/dist/query-builder.d.ts.map +1 -0
- package/dist/query-builder.js +534 -0
- package/dist/query-builder.js.map +1 -0
- package/dist/schema-adapter.d.ts +34 -0
- package/dist/schema-adapter.d.ts.map +1 -0
- package/dist/schema-adapter.js +511 -0
- package/dist/schema-adapter.js.map +1 -0
- package/dist/schema.d.ts +104 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +190 -0
- package/dist/schema.js.map +1 -0
- package/dist/seeds/index.d.ts +3 -0
- package/dist/seeds/index.d.ts.map +1 -0
- package/dist/seeds/index.js +19 -0
- package/dist/seeds/index.js.map +1 -0
- package/dist/seeds/seeder.d.ts +27 -0
- package/dist/seeds/seeder.d.ts.map +1 -0
- package/dist/seeds/seeder.js +138 -0
- package/dist/seeds/seeder.js.map +1 -0
- package/dist/seeds/types.d.ts +60 -0
- package/dist/seeds/types.d.ts.map +1 -0
- package/dist/seeds/types.js +3 -0
- package/dist/seeds/types.js.map +1 -0
- package/dist/sync/dump.d.ts +80 -0
- package/dist/sync/dump.d.ts.map +1 -0
- package/dist/sync/dump.js +655 -0
- package/dist/sync/dump.js.map +1 -0
- package/dist/sync/index.d.ts +5 -0
- package/dist/sync/index.d.ts.map +1 -0
- package/dist/sync/index.js +21 -0
- package/dist/sync/index.js.map +1 -0
- package/dist/sync/introspector.d.ts +49 -0
- package/dist/sync/introspector.d.ts.map +1 -0
- package/dist/sync/introspector.js +750 -0
- package/dist/sync/introspector.js.map +1 -0
- package/dist/sync/synchronizer.d.ts +50 -0
- package/dist/sync/synchronizer.d.ts.map +1 -0
- package/dist/sync/synchronizer.js +506 -0
- package/dist/sync/synchronizer.js.map +1 -0
- package/dist/sync/types.d.ts +83 -0
- package/dist/sync/types.d.ts.map +1 -0
- package/dist/sync/types.js +3 -0
- package/dist/sync/types.js.map +1 -0
- package/dist/tenant/sequence.d.ts +36 -0
- package/dist/tenant/sequence.d.ts.map +1 -0
- package/dist/tenant/sequence.js +130 -0
- package/dist/tenant/sequence.js.map +1 -0
- package/dist/types.d.ts +81 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +3 -0
- package/dist/types.js.map +1 -0
- package/package.json +38 -3
package/README.md
CHANGED
|
@@ -1,3 +1,800 @@
|
|
|
1
|
-
#
|
|
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.
|