repository·main·Indexed 43 days ago
https://github.com/pointfreeco/swift-structured-queriesA Swift library for building type-safe, composable SQL statements. It provides a query-building layer with features like schema mapping via the @Table macro, support for SELECT, INSERT, UPDATE, and DELETE, and Common Table Expressions (CTEs). Designed to be database agnostic and optimized for SQLite, it focuses on generating SQL checked at compile-time rather than database execution.
StructuredQueriesSQLiteCore provides core SQLite extensions for the StructuredQueries framework. It extends the base functionality with SQLite-specific features such as support for custom database functions, specialized query representations, custom collations, and casting mechanisms tailored for SQLite's type system.StructuredQueries is a Swift library designed for building SQL statements in a safe, expressive, and composable manner. It is not an ORM, but rather a tool for generating SQL that reads closely to the language itself while providing type safety to prevent runtime errors caused by typos or type mismatches.
Key features include:
@Table macro to map Swift types to database tables.SELECT, INSERT, UPDATE, DELETE, joins, and common table expressions.#sql macro to introduce custom SQL strings safely at any granularity.Note: This library focuses exclusively on building SQL statements. It does not include database drivers to execute them. You must integrate it with a library that handles actual database requests (e.g., GRDB via SQLiteData).
The StructuredQueries library is designed for building SQL in a type-safe, expressive, and composable manner. It is organized into several modules depending on your needs:
StructuredQueriesCore: The foundational module containing the core functionality. StructuredQueries automatically exports this.StructuredQueriesSQLiteCore: Provides SQLite-specific helpers, including full-text search and type-safe temporary triggers.StructuredQueriesSQLite: Includes everything from StructuredQueriesSQLiteCore plus SQLite-specific macros like @DatabaseFunction.For general library usage, refer to the StructuredQueriesCore documentation.
StructuredQueriesSQLite module provides core SQLite extensions for the StructuredQueries framework. It automatically exports the functionality of StructuredQueriesSQLiteCore. Use this module to access both the core SQLite integration logic and the macros required to support that functionality.You can use Values to seed a query with data that uses specific column names. By passing rows defined by @Table or @Selection (using their .Columns property) into a Values statement, the automatic SQLite names ("column1", etc.) are aliased back to your actual domain model column names. This is particularly useful for creating Common Table Expressions (CTEs).
Select(
Values {
HighScore.Columns(score: 100, player: "Blob")
}
)
// SELECT "column1" AS "score", "column2" AS "player"
// FROM (VALUES (100, 'Blob')) AS "highScores"To bridge the gap between raw database values and your Swift models, use the binding system:
QueryBindable: A protocol used to make a type capable of being bound to a query.QueryBinding: Represents the mapping logic for a specific field or value.QueryBindingError: An error type thrown when a binding operation fails (e.g., type mismatch or missing data).Use these to control how specific database columns are transformed into Swift properties during query execution.
@Selection can represent differentThe Select API relies on specific supporting types to manage data shapes and column selection:
SelectOf: A type used to represent the projection or the specific subset of data selected by a query.ValuesColumns: A type used to manage and represent the collection of columns being operated upon in a query.When a type conforms to PrimaryKeyedTable, the @Table macro generates a nested Draft type. This type contains all the same fields as the original type, but the primary key field is optional. This is useful for inserting rows where the database is responsible for generating the ID (e.g., auto-incrementing integers or UUIDs).
You can use the insert(_:onConflict:) method to insert a row using a Draft object. To retrieve the generated ID or the full record after insertion, chain the returning(_:) method.
// Inserting a draft and returning the new ID
Reminder
.insert { Reminder.Draft(title: "Get groceries") }
.returning(\.id)
// Inserting a draft and returning the full record
Reminder
.insert { Reminder.Draft(title: "Get groceries") }
.returning(\.self)For complex data mapping, StructuredQueries provides a decoding layer similar to Decodable:
QueryRepresentable: A protocol for types that can be represented in a query format.QueryDecodable: A protocol for types that can be decoded from query results.QueryDecoder: The engine responsible for traversing query results and instantiating your Swift types.QueryDecodingError: Errors encountered during the decoding process, such as missing keys or invalid data formats.This layer is ideal when you want to map database rows to nested or complex Swift structures.
When you interpolate a Swift value into an #sql string, the macro automatically captures it as a separate statement binding (using ? in the underlying SQL) to protect against SQL injection.
To avoid ambiguity and deprecation warnings when working with strings, use explicit interpolation methods:
\(bind: value) to explicitly indicate you want to bind a string as a value. This is the safest way to handle user input.\(raw: value) to inject a string directly into the SQL text. Warning: This makes your queries susceptible to SQL injection attacks. Use this only for trusted, static SQL fragments.| Method | Usage | Resulting SQL |
|---|---|---|
| Implicit | \(searchText) | ... LIKE ? (with warning) |
| Explicit Bind | \(bind: searchText) | ... LIKE ? (safe) |
| Raw | \(raw: searchText) | ... LIKE 'value' (unsafe) |
let searchText = "%get%"
// 1. Explicitly bind as a value (Safe)
#sql("SELECT ... WHERE title LIKE \(bind: searchText)", as: Reminder.self)
// 2. Interpolate as raw SQL (Dangerous - avoid!)
#sql("SELECT ... WHERE title LIKE '\(raw: searchText)'", as: Reminder.self)FTS5 virtual table within your TableDefinition.