How vapor/sql-kit works
Project Type and Purpose
• This is an open-source Swift library (SQLKit) for building, serializing, and executing SQL queries in a database-agnostic way.
• Its main purpose is to provide a protocol-based, fluent API for DQL, DML, and DDL across multiple SQL dialects (Postgres, MySQL, SQLite, etc.), without managing connections.
File Structure Analysis
• Sources/SQLKit – core library
• Builders (Prototypes & Implementations) – fluent query builder API
• Expressions – AST types representing SQL statements/fragments
• SQLSerializer – serializes AST to SQL strings with bindings
• Database – SQLDatabase, SQLDialect interfaces
• Rows – encoding/decoding of results (SQLRow, SQLRowDecoder)
• Utilities – helpers (coding keys, string handling)
• Deprecated – backward-compat layers
• Docs.docc – inline documentation
• Sources/SQLKitBenchmark – benchmarking suite for library performance
• Tests/SQLKitTests – unit/integration tests covering builders, serialization, decoding, dialect features
• Configuration:
• Package.swift – SwiftPM manifest
• .github – CI workflows, codecov, dependabot
• .gitignore, LICENSE
README Insights
• Confirms SQLKit is purely a query-building/serialization library.
• Describes core abstractions (SQLDatabase, SQLExpression, various builders).
• Mentions external “kit” packages (PostgresKit, MySQLKit, SQLiteKit) that supply drivers implementing SQLDatabase.
Main Components
a. Core Library Modules (internal):
– Protocol Layer: SQLExpression, SQLDatabase, SQLDialect, SQLQueryBuilder protocols
– Builders: Prototype interfaces → Concrete Implementations → Fluent API
– Expressions/AST: clauses, queries, syntax nodes
– Serializer: SQLSerializer producing SQL + bindings
– Rows: SQLRow, encoders/decoders for results
– Utilities: shared helpers
b. External Integrations:
– Database Driver Packages (PostgresKit, MySQLKit, SQLiteKit)
– Underlying SwiftNIO for async I/O
c. Consumer Application:
– Calls db.select(), db.insert(), db.update(), etc.
– Supplies Codable models for run() / all(decoding:)
Relationships and Data Flow
1. Consumer Code → calls methods on SQLDatabase (driver)
2. Driver’s SQLDatabase extension methods → instantiate appropriate Builder
3. Fluent Builder → constructs an SQLExpression (AST) via Prototypes & Implementations
4. SQLSerializer + SQLDialect → serialize AST to SQL string + parameter bindings
5. Driver hands SQL + bindings to real DB connection (via SwiftNIO)
6. DB returns raw rows → driver wraps into SQLRow
7. SQLRowDecoder / Codable flows decode rows into models → returned to Consumer
Architectural Patterns & Principles
• Protocol-based, dependency inversion: Core protocols aren’t tied to any one database.
• Fluent builder pattern: Prototypes → chaining → implementations produce AST.
• Separation of concerns: AST (Expressions) vs. Serialization (Serializer & Dialect) vs. Execution (Driver).
• Extensibility points: New dialects, custom expressions, custom builders.
Essential Elements to Capture
• Protocol boundaries (SQLDatabase, SQLExpression, SQLDialect)
• Builder layering (Prototypes vs. Implementations)
• AST vs. Serializer separation
• External driver link implementing the core database interface
• Data flow loops for query execution and result decoding
• Extensibility hotspots for new dialects or custom builders