Skip to content

Commit cd420db

Browse files
committed
Implement tiered API architecture and AdvancedSQLDatabase protocol
- Redefined SQLDatabase protocol to provide a simple, buffered API for general use - Introduced AdvancedSQLDatabase protocol for high-performance AsyncThrowingStream streaming - Added .advanced property to all connections and pools for discoverability of performance features - Implemented non-isolated pool streaming helpers using a struct wrapper pattern to manage actor isolation correctly - Added native @p1 placeholder support consistency across all providers (MSSQL, Postgres, MySQL, SQLite) - Implemented queryStream and queryJsonStream for SQLite by wrapping native query logic - Updated all existing integration tests (>400) to use the new tiered API structure - Added TieredAPITests for all providers verified against live Docker databases - Updated README.md with the new architecture, usage examples, and Advanced Features section
1 parent 7909c55 commit cd420db

17 files changed

+479
-989
lines changed

README.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ A unified Swift package for connecting to **Microsoft SQL Server**, **PostgreSQL
1212

1313
## Table of Contents
1414

15+
- [🏆 Advanced Features](#-advanced-features)
16+
- [JSON Streaming](#json-streaming)
17+
- [Reactive Row Streaming](#reactive-row-streaming)
18+
- [Connection Pool Warp Speed](#connection-pool-warp-speed)
19+
- [Unified SQLDatabase API](#unified-sqldatabase-api)
20+
1521
- [Features](#features)
1622
- [🏆 JSON Streaming — Industry First](#-json-streaming--industry-first)
1723
- [Vapor Web API Integration](#vapor-web-api--true-http-streaming)
@@ -344,6 +350,40 @@ You can import only the drivers you need — each is an independent library modu
344350

345351
---
346352

353+
---
354+
355+
## 🏆 Advanced Features
356+
357+
CosmoSQLClient provides a suite of advanced features designed for high-throughput, low-latency applications. These are accessible via the property on any connection or pool.
358+
359+
360+
361+
### JSON Streaming
362+
363+
> **No other Swift SQL library has this.** delivers each complete JSON object the instant its closing arrives — without ever buffering the full result array.
364+
365+
SQL Server fragments output at ~2033-character row boundaries that do **not** align with JSON object boundaries. uses — backed by a stateful parser — to detect exact boundaries across arbitrary chunk splits, yielding each complete JSON object as a value the moment it is fully received.
366+
367+
368+
369+
### Reactive Row Streaming
370+
371+
Rows are yielded as they arrive from the socket. This is perfect for reactive processing or pushing data directly to a web socket.
372+
373+
374+
375+
### Connection Pool Warp Speed
376+
377+
- **Pool Pre-warming**: Call during application startup so that the very first database request is instant.
378+
379+
---
380+
381+
## Unified SQLDatabase API
382+
383+
For easy migration and general use, all providers implement the core protocol. This provides a familiar buffered API similar to other Swift database drivers.
384+
385+
386+
347387
## Quick Start
348388

349389
### Microsoft SQL Server

Sources/CosmoMSSQL/MSSQLConnection.swift

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@ import Foundation
2424
// }
2525
// ```
2626

27-
public final class MSSQLConnection: SQLDatabase, @unchecked Sendable {
27+
public final class MSSQLConnection: SQLDatabase, AdvancedSQLDatabase, @unchecked Sendable {
28+
29+
public var advanced: any AdvancedSQLDatabase { self }
2830

2931
// MARK: - Public configuration
3032

@@ -430,7 +432,7 @@ public final class MSSQLConnection: SQLDatabase, @unchecked Sendable {
430432
///
431433
/// Rows are yielded incrementally as TDS packets arrive — without buffering
432434
/// the entire result set.
433-
public func queryStream(_ sql: String, _ binds: [SQLValue] = []) -> AsyncThrowingStream<SQLRow, Error> {
435+
public func queryStream(_ sql: String, _ binds: [SQLValue]) -> AsyncThrowingStream<SQLRow, any Error> {
434436
AsyncThrowingStream { cont in
435437
Task { [self] in
436438
do {
@@ -497,7 +499,7 @@ public final class MSSQLConnection: SQLDatabase, @unchecked Sendable {
497499
/// let product = try JSONDecoder().decode(Product.self, from: data)
498500
/// }
499501
/// ```
500-
public func queryJsonStream(_ sql: String, _ binds: [SQLValue] = []) -> AsyncThrowingStream<Data, Error> {
502+
public func queryJsonStream(_ sql: String, _ binds: [SQLValue]) -> AsyncThrowingStream<Data, any Error> {
501503
AsyncThrowingStream { cont in
502504
Task { [self] in
503505
do {

0 commit comments

Comments
 (0)