Contents

vkuttyp/cosmosqlclient-swift

A lightweight, high-performance database client for Swift built natively on [SwiftNIO](https://github.com/apple/swift-nio). CosmoSQLClient-Swift provides a unified `async/await` API for Microsoft SQL Server, PostgreSQL, MySQL/MariaDB, and SQLite, with zero external C library depe

Key Features

  • Unified API: A single SQLDatabase protocol for all four database engines, enabling backend-agnostic application code.
  • Native Protocol Implementation: Pure Swift implementations of TDS 7.4 (SQL Server), PostgreSQL v3, and MySQL v10 wire protocols.
  • High-Performance Streaming: Reactive row streaming and industry-first JSON streaming (queryJsonStream) that yields objects as they arrive without full result buffering.
  • Zero-Dependency Core: No requirement for FreeTDS, ODBC, or other legacy C libraries.
  • Lightweight & Efficient: Designed for low-latency and high-throughput, matching or beating native drivers in many scenarios.
  • Strict Concurrency: Fully compatible with Swift 6 strict concurrency requirements.

Supported Database Engines

| Engine | Protocol | Key Features | |---|---|---| | SQL Server | TDS 7.4 | Integrated Security (NTLM), Stored Procedures, Named Instances, TLS/SSL | | PostgreSQL | v3 | MD5/Scram-SHA-256 Auth, Transactions, Parameterized Queries | | MySQL / MariaDB | v10 | Standard Auth, Transactions, Parameterized Queries | | SQLite | Native | In-memory support, WAL mode, Logical/Binary Backup |

Installation

Add CosmoSQLClient-Swift to your Package.swift dependencies:

dependencies: [
    .package(url: "https://github.com/vkuttyp/CosmoSQLClient-Swift.git", from: "1.0.0")
]

Then, add the specific driver to your target:

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "CosmoMSSQL", package: "CosmoSQLClient-Swift"),
        .product(name: "CosmoPostgres", package: "CosmoSQLClient-Swift"),
        .product(name: "CosmoMySQL", package: "CosmoSQLClient-Swift"),
        .product(name: "CosmoSQLite", package: "CosmoSQLClient-Swift")
    ]
)

Quick Start

Basic Query (SQL Server)

import CosmoMSSQL

let config = try MSSQLConnection.Configuration(connectionString: 
    "Server=localhost;Database=Sales;User Id=sa;Password=your_password;Encrypt=True;TrustServerCertificate=True;"
)

let conn = try await MSSQLConnection.connect(configuration: config)
defer { Task { try? await conn.close() } }

let rows = try await conn.query(
    "SELECT id, name, salary FROM employees WHERE active = @p1",
    [.bool(true)]
)

for row in rows {
    let name = row["name"].asString() ?? "Unknown"
    print("Employee: \(name)")
}

JSON Streaming (Industry First)

Stream large JSON results directly from the wire, yielding objects immediately as they are fully received.

// Decodes directly into your Codable model, one object at a time
for try await product in conn.queryJsonStream(
    "SELECT Id, Name, Price FROM Products FOR JSON PATH",
    as: Product.self) 
{
    print("Received: \(product.Name)")
}

Unified API (`SQLDatabase` Protocol)

Write business logic once and run it on any supported database:

func fetchUsers(db: any SQLDatabase) async throws -> [User] {
    return try await db.query("SELECT * FROM users", as: User.self)
}

// Works identically with any CosmoSQL driver
let mssqlUsers = try await fetchUsers(db: mssqlConn)
let pgUsers    = try await fetchUsers(db: postgresConn)

Technical Architecture

CosmoSQLClient-Swift utilizes a non-blocking I/O architecture powered by SwiftNIO.

  • Async/Await Native: Built from the ground up for Swift's modern concurrency model.
  • Stateful Parsing: Uses state machine based protocol decoders to ensure efficient, zero-copy processing of network packets.
  • Actor-Based Pooling: Built-in connection pooling ensures thread-safe and efficient connection management under load.

Performance Benchmarks

Measured on Apple Silicon (M-series) against local databases.

| Scenario | CosmoSQL (Swift) | Native Driver / Competitor | |---|---|---| | MSSQL Warm Query | 0.95 ms | 1.58 ms (FreeTDS) | | Postgres Single-Row | 0.24 ms | 0.30 ms (postgres-nio) |

License

Licensed under the MIT License.

Package Metadata

Repository: vkuttyp/cosmosqlclient-swift

Default branch: main

README: README.md