zzstoatzz.io
comptime sql bindings for zig
ziglang
sql
comprehensive tests and security documentation
- parse.zig: 17 tests covering columns, params, edge cases
- parse.zig: doc comments on limits and sql injection safety
- docs/security.md: explains comptime-enforced injection prevention
- comparison to python t-strings (PEP 750) deferred composition pattern
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+66
docs/security.md
+66
docs/security.md
···
1
+
# security model
2
+
3
+
zql's design prevents sql injection by construction.
4
+
5
+
## the pattern
6
+
7
+
like python's t-strings (PEP 750), zql separates template structure from values:
8
+
9
+
```zig
10
+
// sql is comptime - fixed at compile time
11
+
const Q = zql.Query("SELECT * FROM users WHERE id = :id");
12
+
13
+
// values are separate - passed to prepared statement
14
+
c.query(Q.positional, Q.bind(.{ .id = user_id }));
15
+
```
16
+
17
+
the key insight from t-strings: **deferred composition**. don't combine template and values immediately - let a domain-specific processor (the database driver) do it safely.
18
+
19
+
## why comptime makes this safe
20
+
21
+
in python, t-strings are opt-in. you can still write:
22
+
23
+
```python
24
+
f"SELECT * FROM users WHERE id = {user_id}" # dangerous
25
+
```
26
+
27
+
in zig with zql, **comptime enforces the separation**:
28
+
29
+
```zig
30
+
// this doesn't compile - user_id isn't comptime
31
+
const Q = zql.Query("SELECT * FROM users WHERE id = '" ++ user_id ++ "'");
32
+
```
33
+
34
+
you literally cannot concatenate runtime values into the sql string.
35
+
36
+
## the flow
37
+
38
+
1. **comptime**: sql string parsed, `:name` → `?`, columns extracted
39
+
2. **comptime**: `bind()` validates struct has required params
40
+
3. **runtime**: `bind()` returns values as tuple in param order
41
+
4. **runtime**: database driver uses prepared statement
42
+
43
+
user input never touches the sql string. it's bound as parameters.
44
+
45
+
## what zql doesn't protect against
46
+
47
+
- sql logic bugs (wrong WHERE clause, etc.)
48
+
- authorization issues (query returns data user shouldn't see)
49
+
- denial of service (expensive queries)
50
+
- the database driver not using prepared statements properly
51
+
52
+
zql prevents injection. it doesn't prevent bad queries.
53
+
54
+
## comparison
55
+
56
+
| approach | injection risk |
57
+
|----------|---------------|
58
+
| string concat | high - user input in sql |
59
+
| f-strings (python) | high - opt-in safety |
60
+
| t-strings (python) | low - deferred composition |
61
+
| zql (zig) | **none** - comptime enforces separation |
62
+
63
+
## references
64
+
65
+
- [PEP 750 - Template Strings](https://peps.python.org/pep-0750/)
66
+
- [OWASP SQL Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html)
+149
-11
src/parse.zig
+149
-11
src/parse.zig
···
1
-
//! sql parsing utilities
1
+
//! comptime sql parsing
2
+
//!
3
+
//! extracts metadata from sql strings at compile time:
4
+
//! - column names from SELECT clauses
5
+
//! - named parameter names (:name -> ?)
6
+
//! - positional sql with named params converted
7
+
//!
8
+
//! sql injection safety:
9
+
//! - sql strings are comptime, so user input cannot be concatenated
10
+
//! - parameters are bound via prepared statements, not interpolated
11
+
//! - the :name syntax reinforces parameterized query patterns
12
+
//!
13
+
//! limitations:
14
+
//! - SELECT * returns empty columns (can't know schema)
15
+
//! - no subquery support in column extraction
16
+
//! - no quoted identifier support ("column name")
2
17
3
18
const std = @import("std");
4
19
20
+
/// max named parameters per query
5
21
pub const MAX_PARAMS = 32;
22
+
23
+
/// max columns per SELECT
6
24
pub const MAX_COLS = 64;
25
+
26
+
/// max sql string length
7
27
pub const MAX_SQL_LEN = 4096;
8
28
29
+
/// result of parsing a sql string at comptime
9
30
pub const ParseResult = struct {
31
+
/// sql with :name params replaced by ?
10
32
positional: [MAX_SQL_LEN]u8,
11
33
positional_len: usize,
34
+
35
+
/// total parameter count (named + positional)
12
36
param_count: usize,
37
+
38
+
/// extracted named parameter names in order
13
39
params: [MAX_PARAMS][]const u8,
14
40
params_len: usize,
41
+
42
+
/// extracted column names/aliases from SELECT
15
43
columns: [MAX_COLS][]const u8,
16
44
columns_len: usize,
17
45
};
···
157
185
return null;
158
186
}
159
187
160
-
test "parse columns" {
161
-
const result = comptime parse("SELECT id, name, age FROM users");
162
-
try std.testing.expectEqual(3, result.columns_len);
163
-
try std.testing.expectEqualStrings("id", result.columns[0]);
164
-
try std.testing.expectEqualStrings("name", result.columns[1]);
165
-
try std.testing.expectEqualStrings("age", result.columns[2]);
188
+
// -----------------------------------------------------------------------------
189
+
// column extraction tests
190
+
// -----------------------------------------------------------------------------
191
+
192
+
test "columns: basic select" {
193
+
const r = comptime parse("SELECT id, name, age FROM users");
194
+
try std.testing.expectEqual(3, r.columns_len);
195
+
try std.testing.expectEqualStrings("id", r.columns[0]);
196
+
try std.testing.expectEqualStrings("name", r.columns[1]);
197
+
try std.testing.expectEqualStrings("age", r.columns[2]);
198
+
}
166
199
167
-
// test slicing works correctly
168
-
const cols: []const []const u8 = result.columns[0..result.columns_len];
169
-
try std.testing.expectEqual(3, cols.len);
170
-
try std.testing.expectEqualStrings("id", cols[0]);
200
+
test "columns: with alias" {
201
+
const r = comptime parse("SELECT id, first_name AS name FROM users");
202
+
try std.testing.expectEqual(2, r.columns_len);
203
+
try std.testing.expectEqualStrings("id", r.columns[0]);
204
+
try std.testing.expectEqualStrings("name", r.columns[1]);
205
+
}
206
+
207
+
test "columns: with function" {
208
+
const r = comptime parse("SELECT COUNT(*) AS total, MAX(age) AS oldest FROM users");
209
+
try std.testing.expectEqual(2, r.columns_len);
210
+
try std.testing.expectEqualStrings("total", r.columns[0]);
211
+
try std.testing.expectEqualStrings("oldest", r.columns[1]);
212
+
}
213
+
214
+
test "columns: nested function" {
215
+
const r = comptime parse("SELECT COALESCE(name, 'unknown') AS name FROM users");
216
+
try std.testing.expectEqual(1, r.columns_len);
217
+
try std.testing.expectEqualStrings("name", r.columns[0]);
218
+
}
219
+
220
+
test "columns: table qualified" {
221
+
const r = comptime parse("SELECT u.id, u.name FROM users u");
222
+
try std.testing.expectEqual(2, r.columns_len);
223
+
try std.testing.expectEqualStrings("id", r.columns[0]);
224
+
try std.testing.expectEqualStrings("name", r.columns[1]);
225
+
}
226
+
227
+
test "columns: case expression" {
228
+
const r = comptime parse("SELECT CASE WHEN x > 0 THEN 1 ELSE 0 END AS flag FROM t");
229
+
try std.testing.expectEqual(1, r.columns_len);
230
+
try std.testing.expectEqualStrings("flag", r.columns[0]);
231
+
}
232
+
233
+
test "columns: empty string literal" {
234
+
const r = comptime parse("SELECT id, '' AS empty FROM users");
235
+
try std.testing.expectEqual(2, r.columns_len);
236
+
try std.testing.expectEqualStrings("id", r.columns[0]);
237
+
try std.testing.expectEqualStrings("empty", r.columns[1]);
238
+
}
239
+
240
+
test "columns: select star returns empty" {
241
+
const r = comptime parse("SELECT * FROM users");
242
+
try std.testing.expectEqual(0, r.columns_len);
243
+
}
244
+
245
+
test "columns: multiline sql" {
246
+
const r = comptime parse(
247
+
\\SELECT id, name,
248
+
\\ created_at
249
+
\\FROM users
250
+
);
251
+
try std.testing.expectEqual(3, r.columns_len);
252
+
try std.testing.expectEqualStrings("id", r.columns[0]);
253
+
try std.testing.expectEqualStrings("name", r.columns[1]);
254
+
try std.testing.expectEqualStrings("created_at", r.columns[2]);
255
+
}
256
+
257
+
test "columns: snippet function (fts5)" {
258
+
const r = comptime parse(
259
+
\\SELECT uri, snippet(docs_fts, 1, '<b>', '</b>', '...', 32) AS snippet
260
+
\\FROM docs_fts
261
+
);
262
+
try std.testing.expectEqual(2, r.columns_len);
263
+
try std.testing.expectEqualStrings("uri", r.columns[0]);
264
+
try std.testing.expectEqualStrings("snippet", r.columns[1]);
265
+
}
266
+
267
+
// -----------------------------------------------------------------------------
268
+
// parameter extraction tests
269
+
// -----------------------------------------------------------------------------
270
+
271
+
test "params: named" {
272
+
const r = comptime parse("SELECT * FROM users WHERE id = :id AND age > :min_age");
273
+
try std.testing.expectEqual(2, r.params_len);
274
+
try std.testing.expectEqualStrings("id", r.params[0]);
275
+
try std.testing.expectEqualStrings("min_age", r.params[1]);
276
+
}
277
+
278
+
test "params: positional passthrough" {
279
+
const r = comptime parse("SELECT * FROM users WHERE id = ? AND age > ?");
280
+
try std.testing.expectEqual(0, r.params_len); // no named params
281
+
try std.testing.expectEqual(2, r.param_count); // but two positional
282
+
}
283
+
284
+
test "params: mixed named and positional" {
285
+
const r = comptime parse("SELECT * FROM users WHERE id = :id AND age > ?");
286
+
try std.testing.expectEqual(1, r.params_len);
287
+
try std.testing.expectEqualStrings("id", r.params[0]);
288
+
try std.testing.expectEqual(2, r.param_count);
289
+
}
290
+
291
+
test "params: conversion to positional" {
292
+
const r = comptime parse("INSERT INTO users (name, age) VALUES (:name, :age)");
293
+
try std.testing.expectEqualStrings(
294
+
"INSERT INTO users (name, age) VALUES (?, ?)",
295
+
r.positional[0..r.positional_len],
296
+
);
297
+
}
298
+
299
+
test "params: underscore in name" {
300
+
const r = comptime parse("SELECT * FROM t WHERE x = :my_param_name");
301
+
try std.testing.expectEqual(1, r.params_len);
302
+
try std.testing.expectEqualStrings("my_param_name", r.params[0]);
303
+
}
304
+
305
+
test "params: no params" {
306
+
const r = comptime parse("SELECT id FROM users");
307
+
try std.testing.expectEqual(0, r.params_len);
308
+
try std.testing.expectEqual(0, r.param_count);
171
309
}