Skip to content

Commit b0a4ca0

Browse files
huangyiirenehuangyiirene
authored
Merge pull request #158 from objectstack-ai/copilot/migrate-sql-driver
2 parents 106a706 + acee47c commit b0a4ca0

File tree

6 files changed

+600
-22
lines changed

6 files changed

+600
-22
lines changed

‎packages/drivers/sql/MIGRATION.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# SQL Driver Migration Guide (Phase 4)
2+
3+
## Overview
4+
5+
The SQL driver has been migrated to support the standard `DriverInterface` from `@objectstack/spec` while maintaining full backward compatibility with the existing `Driver` interface from `@objectql/types`.
6+
7+
## What Changed
8+
9+
### 1. Driver Metadata
10+
11+
The driver now exposes metadata for ObjectStack compatibility:
12+
13+
```typescript
14+
const driver = new SqlDriver(config);
15+
console.log(driver.name); // 'SqlDriver'
16+
console.log(driver.version); // '3.0.1'
17+
console.log(driver.supports); // { transactions: true, joins: true, ... }
18+
```
19+
20+
### 2. Lifecycle Methods
21+
22+
New optional lifecycle methods for DriverInterface compatibility:
23+
24+
```typescript
25+
// Connect (no-op, connection established in constructor)
26+
await driver.connect();
27+
28+
// Check connection health
29+
const healthy = await driver.checkHealth(); // true/false
30+
31+
// Disconnect (existing method)
32+
await driver.disconnect();
33+
```
34+
35+
### 3. QueryAST Format Support
36+
37+
The driver now supports the new QueryAST format from `@objectstack/spec`:
38+
39+
#### Legacy UnifiedQuery Format (Still Supported)
40+
```typescript
41+
const query = {
42+
fields: ['name', 'age'],
43+
filters: [['age', '>', 18]],
44+
sort: [['name', 'asc']],
45+
limit: 10,
46+
skip: 0,
47+
aggregate: [{ func: 'sum', field: 'price', alias: 'total' }]
48+
};
49+
```
50+
51+
#### New QueryAST Format (Now Supported)
52+
```typescript
53+
const query = {
54+
object: 'users',
55+
fields: ['name', 'age'],
56+
filters: [['age', '>', 18]],
57+
sort: [{ field: 'name', order: 'asc' }],
58+
top: 10, // Instead of 'limit'
59+
skip: 0,
60+
aggregations: [{ function: 'sum', field: 'price', alias: 'total' }]
61+
};
62+
```
63+
64+
### Key Differences
65+
66+
| Aspect | Legacy Format | QueryAST Format |
67+
|--------|--------------|-----------------|
68+
| Limit | `limit: 10` | `top: 10` |
69+
| Sort | `[['field', 'dir']]` | `[{field, order}]` |
70+
| Aggregations | `aggregate: [{func, field, alias}]` | `aggregations: [{function, field, alias}]` |
71+
72+
## Migration Strategy
73+
74+
The driver uses a **normalization layer** that automatically converts QueryAST format to the internal format:
75+
76+
```typescript
77+
private normalizeQuery(query: any): any {
78+
// Converts 'top' → 'limit'
79+
// Converts 'aggregations' → 'aggregate'
80+
// Handles both sort formats
81+
}
82+
```
83+
84+
This means:
85+
- ✅ Existing code continues to work without changes
86+
- ✅ New code can use QueryAST format
87+
- ✅ Both formats work interchangeably
88+
- ✅ No breaking changes
89+
90+
## Usage Examples
91+
92+
### Using Legacy Format (Unchanged)
93+
```typescript
94+
import { SqlDriver } from '@objectql/driver-sql';
95+
96+
const driver = new SqlDriver({
97+
client: 'postgresql',
98+
connection: { /* ... */ }
99+
});
100+
101+
// Works as before
102+
const results = await driver.find('users', {
103+
filters: [['active', '=', true]],
104+
sort: [['created_at', 'desc']],
105+
limit: 20
106+
});
107+
```
108+
109+
### Using QueryAST Format (New)
110+
```typescript
111+
import { SqlDriver } from '@objectql/driver-sql';
112+
113+
const driver = new SqlDriver({
114+
client: 'postgresql',
115+
connection: { /* ... */ }
116+
});
117+
118+
// New format
119+
const results = await driver.find('users', {
120+
filters: [['active', '=', true]],
121+
sort: [{ field: 'created_at', order: 'desc' }],
122+
top: 20
123+
});
124+
```
125+
126+
### Using with ObjectStack Kernel
127+
```typescript
128+
import { ObjectQL } from '@objectql/core';
129+
import { SqlDriver } from '@objectql/driver-sql';
130+
131+
const app = new ObjectQL({
132+
datasources: {
133+
default: new SqlDriver({ /* config */ })
134+
}
135+
});
136+
137+
await app.init();
138+
139+
// The kernel will use QueryAST format internally
140+
const ctx = app.createContext({ userId: 'user123' });
141+
const repo = ctx.object('users');
142+
const users = await repo.find({ filters: [['active', '=', true]] });
143+
```
144+
145+
## Testing
146+
147+
Comprehensive tests have been added in `test/queryast.test.ts`:
148+
149+
```bash
150+
npm test -- queryast.test.ts
151+
```
152+
153+
Test coverage includes:
154+
- Driver metadata exposure
155+
- Lifecycle methods (connect, checkHealth, disconnect)
156+
- QueryAST format with `top` parameter
157+
- Object-based sort notation
158+
- Aggregations with QueryAST format
159+
- Backward compatibility with legacy format
160+
- Mixed format support
161+
162+
## Implementation Details
163+
164+
### Files Changed
165+
- `package.json`: Added `@objectstack/spec@^0.2.0` dependency
166+
- `src/index.ts`:
167+
- Added driver metadata properties
168+
- Added `normalizeQuery()` method (~40 lines)
169+
- Added `connect()` and `checkHealth()` methods (~20 lines)
170+
- Updated `find()`, `count()`, `aggregate()` to use normalization
171+
- `test/queryast.test.ts`: New comprehensive test suite (200+ lines)
172+
173+
### Lines of Code
174+
- **Added**: ~260 lines (including tests and docs)
175+
- **Modified**: ~10 lines (method signatures)
176+
- **Deleted**: 0 lines
177+
178+
## Next Steps
179+
180+
This migration establishes the pattern for migrating other drivers:
181+
182+
1. ✅ SQL Driver (completed)
183+
2. 🔜 Memory Driver (recommended next - used for testing)
184+
3. 🔜 MongoDB Driver (NoSQL representative)
185+
4. 🔜 Other drivers (bulk migration)
186+
187+
## Backward Compatibility Guarantee
188+
189+
**100% backward compatible** - all existing code using the SQL driver will continue to work without any changes. The QueryAST support is additive, not replacing.
190+
191+
## References
192+
193+
- [ObjectStack Spec Package](https://www.npmjs.com/package/@objectstack/spec)
194+
- [Runtime Integration Docs](../../foundation/core/RUNTIME_INTEGRATION.md)
195+
- [Driver Interface Documentation](../../foundation/types/src/driver.ts)

‎packages/drivers/sql/README.md‎

Lines changed: 87 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,27 @@
11
# @objectql/driver-sql
22

3-
Knex.js based SQL driver for ObjectQL. Supports PostgreSQL, MySQL, SQLite, and simpler databases.
3+
Knex.js based SQL driver for ObjectQL. Supports PostgreSQL, MySQL, SQLite, and other SQL databases.
4+
5+
**Phase 4 Update**: Now implements the standard `DriverInterface` from `@objectstack/spec` with full backward compatibility.
6+
7+
## Features
8+
9+
- ✅ **ObjectStack Spec Compatible**: Implements `DriverInterface` from `@objectstack/spec`
10+
- ✅ **QueryAST Support**: Supports both legacy UnifiedQuery and new QueryAST formats
11+
- ✅ **Multiple Databases**: PostgreSQL, MySQL, SQLite, and more via Knex
12+
- ✅ **Transactions**: Full transaction support with begin/commit/rollback
13+
- ✅ **Aggregations**: COUNT, SUM, AVG, MIN, MAX with GROUP BY
14+
- ✅ **Schema Management**: Auto-create/update tables from metadata
15+
- ✅ **Introspection**: Discover existing database schemas
16+
- ✅ **100% Backward Compatible**: All existing code continues to work
417

518
## Installation
619

720
```bash
821
npm install @objectql/driver-sql
922
```
1023

11-
## Usage
24+
## Basic Usage
1225

1326
```typescript
1427
import { SqlDriver } from '@objectql/driver-sql';
@@ -27,3 +40,75 @@ const objectql = new ObjectQL({
2740
}
2841
});
2942
```
43+
44+
## QueryAST Format (New)
45+
46+
The driver now supports the QueryAST format from `@objectstack/spec`:
47+
48+
```typescript
49+
// New QueryAST format
50+
const results = await driver.find('users', {
51+
fields: ['name', 'email'],
52+
filters: [['active', '=', true]],
53+
sort: [{ field: 'created_at', order: 'desc' }],
54+
top: 10, // Instead of 'limit'
55+
skip: 0
56+
});
57+
58+
// Aggregations
59+
const stats = await driver.aggregate('orders', {
60+
aggregations: [
61+
{ function: 'sum', field: 'amount', alias: 'total' },
62+
{ function: 'count', field: '*', alias: 'count' }
63+
],
64+
groupBy: ['customer_id'],
65+
filters: [['status', '=', 'completed']]
66+
});
67+
```
68+
69+
## Legacy Format (Still Supported)
70+
71+
All existing code continues to work:
72+
73+
```typescript
74+
// Legacy UnifiedQuery format
75+
const results = await driver.find('users', {
76+
fields: ['name', 'email'],
77+
filters: [['active', '=', true]],
78+
sort: [['created_at', 'desc']],
79+
limit: 10,
80+
skip: 0
81+
});
82+
```
83+
84+
## Driver Metadata
85+
86+
The driver exposes metadata for ObjectStack compatibility:
87+
88+
```typescript
89+
console.log(driver.name); // 'SqlDriver'
90+
console.log(driver.version); // '3.0.1'
91+
console.log(driver.supports); // { transactions: true, joins: true, ... }
92+
```
93+
94+
## Lifecycle Methods
95+
96+
```typescript
97+
// Connect (optional - connection is automatic)
98+
await driver.connect();
99+
100+
// Check health
101+
const healthy = await driver.checkHealth(); // true/false
102+
103+
// Disconnect
104+
await driver.disconnect();
105+
```
106+
107+
## Migration Guide
108+
109+
See [MIGRATION.md](./MIGRATION.md) for detailed migration information from legacy format to QueryAST format.
110+
111+
## License
112+
113+
MIT
114+

‎packages/drivers/sql/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
},
2424
"dependencies": {
2525
"@objectql/types": "workspace:*",
26+
"@objectstack/spec": "^0.2.0",
2627
"knex": "^3.1.0"
2728
},
2829
"devDependencies": {

0 commit comments

Comments
 (0)