qryndel 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- qryndel-0.3.0/AUTHORS.md +8 -0
- qryndel-0.3.0/CHANGELOG.md +194 -0
- qryndel-0.3.0/LICENSE +21 -0
- qryndel-0.3.0/MANIFEST.in +18 -0
- qryndel-0.3.0/PKG-INFO +340 -0
- qryndel-0.3.0/README.md +306 -0
- qryndel-0.3.0/SECURITY.md +52 -0
- qryndel-0.3.0/docs/AI_ASSISTED_DEVELOPMENT.md +10 -0
- qryndel-0.3.0/docs/GITHUB_RELEASE.md +57 -0
- qryndel-0.3.0/docs/ROADMAP.md +35 -0
- qryndel-0.3.0/docs/architecture.md +64 -0
- qryndel-0.3.0/docs/language-reference.md +252 -0
- qryndel-0.3.0/docs/real-world-testing.md +45 -0
- qryndel-0.3.0/docs/rfcs/README.md +18 -0
- qryndel-0.3.0/examples/__init__.py +1 -0
- qryndel-0.3.0/examples/agent_guardrails.py +61 -0
- qryndel-0.3.0/examples/basic_filter.qryndel +3 -0
- qryndel-0.3.0/examples/checks/fixture_types.qryndel +18 -0
- qryndel-0.3.0/examples/example1.qryndel +2 -0
- qryndel-0.3.0/examples/example10_join_where.qryndel +6 -0
- qryndel-0.3.0/examples/example11_nested_return.qryndel +2 -0
- qryndel-0.3.0/examples/example12_nested_where.qryndel +3 -0
- qryndel-0.3.0/examples/example13_nested_order_by.qryndel +3 -0
- qryndel-0.3.0/examples/example2.qryndel +3 -0
- qryndel-0.3.0/examples/example20_rule_basic.qryndel +2 -0
- qryndel-0.3.0/examples/example21_rule_nested.qryndel +3 -0
- qryndel-0.3.0/examples/example23_rule_multiple.qryndel +3 -0
- qryndel-0.3.0/examples/example24_insert.qryndel +6 -0
- qryndel-0.3.0/examples/example25_update.qryndel +3 -0
- qryndel-0.3.0/examples/example26_delete.qryndel +2 -0
- qryndel-0.3.0/examples/example27_rule_update.qryndel +4 -0
- qryndel-0.3.0/examples/example28_group_by.qryndel +6 -0
- qryndel-0.3.0/examples/example29_transaction.qryndel +5 -0
- qryndel-0.3.0/examples/example3.qryndel +3 -0
- qryndel-0.3.0/examples/example30_types.qryndel +10 -0
- qryndel-0.3.0/examples/example31_left_join.qryndel +5 -0
- qryndel-0.3.0/examples/example32_order_value.qryndel +5 -0
- qryndel-0.3.0/examples/example33_spend_per_user.qryndel +10 -0
- qryndel-0.3.0/examples/example34_stock_drift.qryndel +8 -0
- qryndel-0.3.0/examples/example35_restock.qryndel +2 -0
- qryndel-0.3.0/examples/example4.qryndel +3 -0
- qryndel-0.3.0/examples/example5_and.qryndel +3 -0
- qryndel-0.3.0/examples/example6_or.qryndel +3 -0
- qryndel-0.3.0/examples/example7_order_limit.qryndel +5 -0
- qryndel-0.3.0/examples/example8_distinct.qryndel +2 -0
- qryndel-0.3.0/examples/example9_join.qryndel +4 -0
- qryndel-0.3.0/pyproject.toml +54 -0
- qryndel-0.3.0/qryndel/__init__.py +50 -0
- qryndel-0.3.0/qryndel/ast_nodes.py +403 -0
- qryndel-0.3.0/qryndel/backends/__init__.py +40 -0
- qryndel-0.3.0/qryndel/backends/base.py +40 -0
- qryndel-0.3.0/qryndel/backends/sqlite.py +574 -0
- qryndel-0.3.0/qryndel/budgets.py +47 -0
- qryndel-0.3.0/qryndel/capabilities.py +161 -0
- qryndel-0.3.0/qryndel/cli.py +181 -0
- qryndel-0.3.0/qryndel/contracts.py +356 -0
- qryndel-0.3.0/qryndel/errors.py +50 -0
- qryndel-0.3.0/qryndel/executor.py +255 -0
- qryndel-0.3.0/qryndel/explain.py +85 -0
- qryndel-0.3.0/qryndel/expressions.py +116 -0
- qryndel-0.3.0/qryndel/grammar.lark +147 -0
- qryndel-0.3.0/qryndel/logical_plan.py +305 -0
- qryndel-0.3.0/qryndel/metrics.py +30 -0
- qryndel-0.3.0/qryndel/optimizer.py +97 -0
- qryndel-0.3.0/qryndel/parser.py +572 -0
- qryndel-0.3.0/qryndel/rules.py +249 -0
- qryndel-0.3.0/qryndel/safety.py +150 -0
- qryndel-0.3.0/qryndel/schema.py +79 -0
- qryndel-0.3.0/qryndel/schema_drift.py +219 -0
- qryndel-0.3.0/qryndel/sdk.py +212 -0
- qryndel-0.3.0/qryndel/semantic.py +752 -0
- qryndel-0.3.0/qryndel.egg-info/PKG-INFO +340 -0
- qryndel-0.3.0/qryndel.egg-info/SOURCES.txt +110 -0
- qryndel-0.3.0/qryndel.egg-info/dependency_links.txt +1 -0
- qryndel-0.3.0/qryndel.egg-info/entry_points.txt +2 -0
- qryndel-0.3.0/qryndel.egg-info/requires.txt +4 -0
- qryndel-0.3.0/qryndel.egg-info/top_level.txt +1 -0
- qryndel-0.3.0/setup.cfg +4 -0
- qryndel-0.3.0/setup_db.py +101 -0
- qryndel-0.3.0/tests/__init__.py +0 -0
- qryndel-0.3.0/tests/conftest.py +20 -0
- qryndel-0.3.0/tests/test_aggregates.py +51 -0
- qryndel-0.3.0/tests/test_budgets.py +40 -0
- qryndel-0.3.0/tests/test_capabilities.py +14 -0
- qryndel-0.3.0/tests/test_concurrency.py +23 -0
- qryndel-0.3.0/tests/test_contracts.py +53 -0
- qryndel-0.3.0/tests/test_errors.py +37 -0
- qryndel-0.3.0/tests/test_executor.py +173 -0
- qryndel-0.3.0/tests/test_explain.py +17 -0
- qryndel-0.3.0/tests/test_fault_injection.py +55 -0
- qryndel-0.3.0/tests/test_language_semantics.py +76 -0
- qryndel-0.3.0/tests/test_logical_plan.py +169 -0
- qryndel-0.3.0/tests/test_metrics.py +36 -0
- qryndel-0.3.0/tests/test_null_predicates.py +44 -0
- qryndel-0.3.0/tests/test_optimizer.py +49 -0
- qryndel-0.3.0/tests/test_parameters.py +39 -0
- qryndel-0.3.0/tests/test_parser.py +270 -0
- qryndel-0.3.0/tests/test_rules.py +495 -0
- qryndel-0.3.0/tests/test_safety.py +101 -0
- qryndel-0.3.0/tests/test_schema_drift.py +50 -0
- qryndel-0.3.0/tests/test_sdk.py +26 -0
- qryndel-0.3.0/tests/test_semantic.py +248 -0
- qryndel-0.3.0/tests/test_sql_compiler.py +296 -0
- qryndel-0.3.0/tests/test_streaming_contracts.py +53 -0
- qryndel-0.3.0/tests/test_transactions.py +70 -0
- qryndel-0.3.0/tests/test_types.py +78 -0
- qryndel-0.3.0/tests/test_v01_compatibility.py +161 -0
- qryndel-0.3.0/tests/test_v02_features.py +321 -0
- qryndel-0.3.0/tests/test_v03_features.py +350 -0
- qryndel-0.3.0/tests/test_v03_hardening.py +262 -0
- qryndel-0.3.0/tests/test_write_budgets.py +25 -0
- qryndel-0.3.0/tests/test_writes.py +530 -0
qryndel-0.3.0/AUTHORS.md
ADDED
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable public changes to Qryndel are recorded here.
|
|
4
|
+
|
|
5
|
+
## [0.3.0] - 2026-11-17
|
|
6
|
+
|
|
7
|
+
Expressions, aliases, schema checks against the real database, and result
|
|
8
|
+
contracts. Still SQLite-only.
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **Column-to-column comparisons:** either side of a comparison can be a
|
|
13
|
+
column or an expression, e.g.
|
|
14
|
+
`WHERE l.current_stock != p.master_stock` or `WHERE price < cost * 1.2`.
|
|
15
|
+
Rules can compare columns too (`RULE underpriced(x) = x.price < x.cost`).
|
|
16
|
+
- **Arithmetic:** `+`, `-`, `*`, `/`, unary minus and parentheses in
|
|
17
|
+
`RETURN`, `WHERE`, `HAVING`, `ORDER BY`, inside aggregates
|
|
18
|
+
(`SUM(qty * unit_cost)`), and in `UPDATE ... SET stock = stock - $sold`.
|
|
19
|
+
`/` always divides as decimals (`7 / 2` is `3.5`). Literal values in
|
|
20
|
+
expressions are still bound parameters.
|
|
21
|
+
- **`AS` aliases in `RETURN`:** `RETURN SUM(fees) / SUM(gross) * 100 AS fee_pct`.
|
|
22
|
+
Aliases can be used in `ORDER BY`. A computed column without `AS` is named
|
|
23
|
+
after its UDL text, such as `"qty * unit_cost"`. Two result columns with
|
|
24
|
+
the same name are an error, because one would silently overwrite the other.
|
|
25
|
+
- **Schema loading from the database:** `Client(path, schema="auto")` reads
|
|
26
|
+
every table and view, so an unknown table or column is reported before any
|
|
27
|
+
SQL runs, with a hint: `Unknown field 'platfrom' in source 'orders'. Did
|
|
28
|
+
you mean 'platform'?`. TEXT/JSON columns stay open for nested paths.
|
|
29
|
+
`client.refresh_schema()` re-reads it. The CLI checks the schema by
|
|
30
|
+
default (`--no-schema-check` turns it off) and `--show-schema` prints it.
|
|
31
|
+
- **Schema drift checks:** `client.check_schema(program)` (CLI:
|
|
32
|
+
`--check-schema FILE`) compares a program's `TYPE` declarations with the
|
|
33
|
+
real tables and reports removed, added, retyped and nullable columns, and
|
|
34
|
+
missing tables. Report-only; nothing is changed. A program may now consist
|
|
35
|
+
of declarations only.
|
|
36
|
+
- **Result contracts:** `client.execute(query, contracts=[...])` checks the
|
|
37
|
+
rows before returning them: `NonNull`, `NoMissing`, `Unique`, `Compare`,
|
|
38
|
+
`RowCount`. A failure raises `ContractViolation` (`UDL_CONTRACT_VIOLATION`)
|
|
39
|
+
with redacted samples. `iter_verified_results` checks results chunk by
|
|
40
|
+
chunk.
|
|
41
|
+
- New capability flags `computed_expressions` and `column_comparison`, so a
|
|
42
|
+
backend that cannot do these fails before compiling.
|
|
43
|
+
- **`NUMBER(x)` and `TEXT(x)` conversions** for data imported as text:
|
|
44
|
+
`WHERE NUMBER(price) > 1000`, `ORDER BY NUMBER(price) DESC`.
|
|
45
|
+
- **`TYPE ... price: Number` now converts the column** wherever the program
|
|
46
|
+
uses it, so comparisons, sorting, `MIN`/`MAX` and results are numeric even
|
|
47
|
+
when the column is stored as TEXT. With `ALLOW extra fields`, a TYPE block
|
|
48
|
+
adds to a schema loaded from the database instead of replacing it.
|
|
49
|
+
- **`NonEmpty(field)` contract**: like `NonNull`, but also rejects `''` and
|
|
50
|
+
blank strings.
|
|
51
|
+
- `Client(default_budget=...)` applies a budget to every `execute` that
|
|
52
|
+
passes none, and `Client(busy_timeout_ms=...)` sets how long to wait for
|
|
53
|
+
another connection's lock (default 5000 ms).
|
|
54
|
+
- `DatabaseLockedError` (`UDL_DATABASE_LOCKED`) with a suggestion, instead of
|
|
55
|
+
a generic "database is locked" execution error.
|
|
56
|
+
- `examples/agent_guardrails.py`: a provider-neutral tool function that gives
|
|
57
|
+
an AI agent read-only, schema-checked, budgeted database access.
|
|
58
|
+
|
|
59
|
+
### Changed
|
|
60
|
+
|
|
61
|
+
- A bare word on the right of a comparison is now a column:
|
|
62
|
+
`WHERE city = Singapore` compares two columns. Quote strings:
|
|
63
|
+
`WHERE city = 'Singapore'`. `INSERT { city: Singapore }` still stores the
|
|
64
|
+
string, as before.
|
|
65
|
+
- `Program.statement` is `None` for a declaration-only program; running one
|
|
66
|
+
raises a `SemanticError`.
|
|
67
|
+
- `-5` is parsed as unary minus applied to `5`; results are unchanged.
|
|
68
|
+
- `SUM(*)`, `AVG(*)`, `MIN(*)` and `MAX(*)` are parse errors; only `COUNT(*)`
|
|
69
|
+
takes `*`.
|
|
70
|
+
- `ExecutionMetrics.result_bytes` is `None` unless a `max_result_bytes`
|
|
71
|
+
budget is set.
|
|
72
|
+
- A parameter set to `None` still follows SQL semantics and matches nothing
|
|
73
|
+
in `x = $p`; only a written `NULL` means `IS NULL`. This is deliberate:
|
|
74
|
+
`WHERE owner_id = $user` with `user=None` must not match every unowned row.
|
|
75
|
+
It is now documented.
|
|
76
|
+
|
|
77
|
+
### Safety
|
|
78
|
+
|
|
79
|
+
- **Comparing a text column with a number is an error when the schema is
|
|
80
|
+
known** (`schema="auto"`, or the CLI default). In SQLite `price > 1000` on
|
|
81
|
+
a TEXT column compares text, so `'999.99' > '1000'` is true; on a
|
|
82
|
+
real-world import this returned 112,081 rows instead of 844. The message
|
|
83
|
+
explains both fixes (`NUMBER(price)` or a TYPE declaration).
|
|
84
|
+
- **`UPDATE`/`DELETE` reject WHERE clauses that can never be false**: no
|
|
85
|
+
column at all (`1 = 1`), a column compared with itself (`price = price`),
|
|
86
|
+
`x IS NULL OR x IS NOT NULL`, and `p OR NOT p`. These used to delete every
|
|
87
|
+
row despite the "WHERE required" rule. This catches common mistakes, not
|
|
88
|
+
every possible tautology, so keep `max_affected_rows` as the backstop.
|
|
89
|
+
|
|
90
|
+
### Fixed
|
|
91
|
+
|
|
92
|
+
- The optimizer could push a predicate that compares columns from two
|
|
93
|
+
joined tables into one side of the join.
|
|
94
|
+
- The statements inside a transaction are now included in the backend
|
|
95
|
+
capability check (it used to stop at the transaction itself).
|
|
96
|
+
- Schema inspection no longer creates an empty database file when the path
|
|
97
|
+
does not exist, and an `INTEGER PRIMARY KEY` is no longer reported as
|
|
98
|
+
nullable.
|
|
99
|
+
- Deeply nested or very long queries crashed with `RecursionError` (from 200
|
|
100
|
+
nested parentheses or a 1,000-term `OR`), and 500 `OR` terms overflowed
|
|
101
|
+
SQLite's own parser. The AST is now built inside the LALR parser without
|
|
102
|
+
recursion, `AND`/`OR` chains become balanced trees, and nesting deeper than
|
|
103
|
+
200 levels is a clear `ParseError`.
|
|
104
|
+
- An integer parameter outside SQLite's 64-bit range raised a raw
|
|
105
|
+
`OverflowError`; it is now a `ParameterError`. Integer literals that large
|
|
106
|
+
become decimals, as in SQLite.
|
|
107
|
+
- `max_duration_ms` now also bounds waiting for another connection's lock
|
|
108
|
+
(it used to wait SQLite's fixed 5 s).
|
|
109
|
+
- Writes start with `BEGIN IMMEDIATE`, so concurrent writers wait for each
|
|
110
|
+
other instead of risking a deadlock error mid-transaction.
|
|
111
|
+
- Large reads were about twice as slow as plain SQLite because every result
|
|
112
|
+
was JSON-encoded to fill the `result_bytes` metric. It is now measured only
|
|
113
|
+
under a `max_result_bytes` budget (`None` otherwise); a 1M-row read went
|
|
114
|
+
from 2.1x to about 1.3x native time.
|
|
115
|
+
- `max_result_bytes` read the whole result before checking it (10 s and over
|
|
116
|
+
1 GB of memory to reject a 1M-row read); it now checks while fetching and
|
|
117
|
+
stops early.
|
|
118
|
+
|
|
119
|
+
## [0.2.0] - 2026-11-06
|
|
120
|
+
|
|
121
|
+
The second public release. Qryndel is still SQLite-only; this release fills in
|
|
122
|
+
the rest of the language on that backend.
|
|
123
|
+
|
|
124
|
+
### Added
|
|
125
|
+
|
|
126
|
+
- **Sorting and paging:** `ORDER BY field [ASC|DESC] [NULLS FIRST|LAST]`,
|
|
127
|
+
`LIMIT n`, and `RETURN DISTINCT`.
|
|
128
|
+
- **Joins:** `JOIN` / `INNER JOIN`, `LEFT JOIN`, and (on SQLite 3.39+)
|
|
129
|
+
`RIGHT JOIN` and `FULL JOIN`, with table aliases and qualified fields such
|
|
130
|
+
as `u.name`.
|
|
131
|
+
- **Aggregation:** `COUNT(*)`, `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, with
|
|
132
|
+
`GROUP BY` and `HAVING`. Aggregates can be used in `ORDER BY`.
|
|
133
|
+
- **Nested fields:** dotted paths into JSON columns (`profile.address.city`)
|
|
134
|
+
compile to `json_extract`. `IS MISSING`, `IS NOT MISSING`, and `EXISTS`
|
|
135
|
+
tell an absent key apart from a JSON `null`.
|
|
136
|
+
- **Rules:** `RULE name(x) = <condition>` declares a reusable predicate that
|
|
137
|
+
can be called in `WHERE`, including from other rules and inside
|
|
138
|
+
transactions.
|
|
139
|
+
- **Schemas in the language:** `TYPE table { field: Type [required|optional] }`
|
|
140
|
+
turns on field checking and required-field checks for `INSERT`.
|
|
141
|
+
`ALLOW extra fields` relaxes it.
|
|
142
|
+
- **Writes:** `INSERT INTO t { field: value, ... }`,
|
|
143
|
+
`UPDATE t SET f = v WHERE ...`, `DELETE FROM t WHERE ...`. `UPDATE` and
|
|
144
|
+
`DELETE` without `WHERE` are rejected.
|
|
145
|
+
- **Transactions:** `BEGIN; <write>; <write>; COMMIT` (or `ROLLBACK`). Every
|
|
146
|
+
statement commits together or not at all.
|
|
147
|
+
- **Comments:** `-- like this` to the end of a line.
|
|
148
|
+
- **Safety controls:** `Client(read_only=True)`, `Client(allowed_tables=[...])`,
|
|
149
|
+
and execution budgets (`max_result_rows`, `max_result_bytes`,
|
|
150
|
+
`max_affected_rows`, `max_duration_ms`). A write that goes over budget is
|
|
151
|
+
rolled back.
|
|
152
|
+
- **Diagnostics:** `Client.explain()` shows the logical plan and SQL with
|
|
153
|
+
parameter values redacted. `Client.preview()` counts the rows a write would
|
|
154
|
+
affect without changing data. `QueryResult.metrics` reports timing and
|
|
155
|
+
row counts.
|
|
156
|
+
- **CLI flags:** `--explain`, `--preview`, `--read-only`, `--max-rows`,
|
|
157
|
+
`--max-affected-rows`, `--timeout-ms`, and `--json`. Errors are printed as
|
|
158
|
+
`error[CODE]: message` with exit status 1 instead of a traceback.
|
|
159
|
+
|
|
160
|
+
### Changed
|
|
161
|
+
|
|
162
|
+
- `parse_program()` now returns a `Program` (types, rules, statement).
|
|
163
|
+
`parse()` still returns the statement directly.
|
|
164
|
+
- `semantic.validate()` returns the validated statement (rules expanded,
|
|
165
|
+
fields resolved). It used to return `None`.
|
|
166
|
+
- `SqliteBackend.capabilities` is now a `Capabilities` dataclass instead of a
|
|
167
|
+
`frozenset` of names.
|
|
168
|
+
- `QueryResult` gained `rows_affected`, `last_insert_id`, `transaction`,
|
|
169
|
+
`statements`, `metrics`, and `is_write`. Reads behave as before.
|
|
170
|
+
- Missing parameters raise `ParameterError`, which is both a `UdlError`
|
|
171
|
+
(code `UDL_PARAMETER_ERROR`) and a `ValueError`. The message is unchanged:
|
|
172
|
+
`missing parameter: $name`.
|
|
173
|
+
- Executing against a database file that does not exist raises
|
|
174
|
+
`ExecutionError` instead of silently creating an empty file.
|
|
175
|
+
- The test suite creates `test.db` automatically; running `setup_db.py` first
|
|
176
|
+
is no longer required.
|
|
177
|
+
|
|
178
|
+
### Kept from 0.1.0
|
|
179
|
+
|
|
180
|
+
- `Client("path.db")`, `client.compile(...)`, `client.execute(...)`, and
|
|
181
|
+
`result.rows`.
|
|
182
|
+
- `WHERE x = NULL` still means `IS NULL`, and `!= NULL` means `IS NOT NULL`.
|
|
183
|
+
- CLI output for reads (`header`, then one row per line, ` | ` separated).
|
|
184
|
+
- Raw SQL strings given to the executor are limited to `SELECT`.
|
|
185
|
+
|
|
186
|
+
### Still not included
|
|
187
|
+
|
|
188
|
+
PostgreSQL, MongoDB, Neo4j, graph `MATCH` queries, and non-SQLite backends.
|
|
189
|
+
|
|
190
|
+
## [0.1.0] - 2026-10-18
|
|
191
|
+
|
|
192
|
+
First public release. Includes the UDL parser, AST, semantic validation,
|
|
193
|
+
logical planning, SQLite compilation and execution, named parameters, a
|
|
194
|
+
Python API, a CLI, and reproducible tests and examples.
|
qryndel-0.3.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Manveer Singh
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
include AUTHORS.md
|
|
2
|
+
include CHANGELOG.md
|
|
3
|
+
include LICENSE
|
|
4
|
+
include README.md
|
|
5
|
+
include SECURITY.md
|
|
6
|
+
include pyproject.toml
|
|
7
|
+
include setup_db.py
|
|
8
|
+
recursive-include qryndel *.py *.lark
|
|
9
|
+
recursive-include tests *.py
|
|
10
|
+
recursive-include examples *.qryndel *.py
|
|
11
|
+
recursive-include docs *.md
|
|
12
|
+
prune build
|
|
13
|
+
prune dist
|
|
14
|
+
prune .pytest_cache
|
|
15
|
+
global-exclude *.py[cod]
|
|
16
|
+
global-exclude __pycache__
|
|
17
|
+
global-exclude *.egg-info
|
|
18
|
+
global-exclude test.db
|
qryndel-0.3.0/PKG-INFO
ADDED
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: qryndel
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: A safe, schema-checked query language for SQLite: bound parameters, write guards, budgets and guardrails for AI agents
|
|
5
|
+
Author: Manveer Singh
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Manveer04/qryndel
|
|
8
|
+
Project-URL: Repository, https://github.com/Manveer04/qryndel
|
|
9
|
+
Project-URL: Issues, https://github.com/Manveer04/qryndel/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/Manveer04/qryndel/blob/main/docs/language-reference.md
|
|
11
|
+
Project-URL: Changelog, https://github.com/Manveer04/qryndel/blob/main/CHANGELOG.md
|
|
12
|
+
Keywords: sqlite,sql,query-language,dsl,udl,safe-sql,sql-injection,query-builder,query-validation,schema-validation,data-contracts,llm,ai-agents,guardrails,database
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Database
|
|
23
|
+
Classifier: Topic :: Database :: Front-Ends
|
|
24
|
+
Classifier: Topic :: Security
|
|
25
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
License-File: AUTHORS.md
|
|
30
|
+
Requires-Dist: lark>=1.1.0
|
|
31
|
+
Provides-Extra: test
|
|
32
|
+
Requires-Dist: pytest>=7.0; extra == "test"
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# Qryndel
|
|
36
|
+
|
|
37
|
+
[](https://github.com/Manveer04/qryndel/actions/workflows/tests.yml)
|
|
38
|
+
[](pyproject.toml)
|
|
39
|
+
[](LICENSE)
|
|
40
|
+
[](https://github.com/Manveer04/qryndel/releases)
|
|
41
|
+
|
|
42
|
+
**A safe query language for SQLite.** Qryndel checks every query before it
|
|
43
|
+
runs: unknown columns, `DELETE` without a real `WHERE`, text compared with
|
|
44
|
+
numbers, runaway result sets. Values are always bound parameters, so SQL
|
|
45
|
+
injection is ruled out by design. Useful anywhere a query comes from somewhere
|
|
46
|
+
you don't fully trust: an app's users, a script, or an AI agent.
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
$ udl "FROM users RETURN nmae"
|
|
50
|
+
error[UDL_SEMANTIC_ERROR]: Unknown field 'nmae' in source 'users'. Did you mean 'name'?
|
|
51
|
+
|
|
52
|
+
$ udl "DELETE FROM orders WHERE 1 = 1"
|
|
53
|
+
error[UDL_SEMANTIC_ERROR]: DELETE on 'orders' would change every row: the WHERE clause can never be false ...
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Qryndel is an experimental implementation of Unified Data Language (UDL), a
|
|
57
|
+
small query language that separates how a query is written from how it is
|
|
58
|
+
executed. It is SQLite-first: reads, joins, aggregation, arithmetic, safe
|
|
59
|
+
writes and transactions, checked against the real database schema. It was
|
|
60
|
+
tested against a 1.5-million-row real-world dataset
|
|
61
|
+
([results](docs/real-world-testing.md)). The language may still change.
|
|
62
|
+
|
|
63
|
+
## Why UDL?
|
|
64
|
+
|
|
65
|
+
Applications often couple query text directly to one database engine, and
|
|
66
|
+
leave safety to code review. UDL parses each query, checks its meaning
|
|
67
|
+
against the schema, builds a logical plan, and compiles that plan to
|
|
68
|
+
parameterized SQLite. Safety rules, such as "no `DELETE` without `WHERE`",
|
|
69
|
+
are part of the language.
|
|
70
|
+
|
|
71
|
+
| You want to... | Qryndel gives you |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| Let an AI agent or end user query a database | Read-only clients, table allow-lists, row/time budgets, no SQL injection |
|
|
74
|
+
| Catch mistakes before they reach the database | Schema checks with "did you mean", text-vs-number checks, always-true `WHERE` checks |
|
|
75
|
+
| See what a query will do | `explain` (values redacted) and `preview` for writes |
|
|
76
|
+
| Trust the result | Result contracts: `Unique`, `NonNull`, `NonEmpty`, `RowCount`, `Compare` |
|
|
77
|
+
| Keep schemas honest | `TYPE` declarations and `--check-schema` drift reports for CI |
|
|
78
|
+
|
|
79
|
+
## Example
|
|
80
|
+
|
|
81
|
+
```udl
|
|
82
|
+
RULE is_adult(x) = x.age >= $minimum
|
|
83
|
+
|
|
84
|
+
FROM users AS u
|
|
85
|
+
JOIN orders AS o ON u.id = o.user_id
|
|
86
|
+
WHERE is_adult(u) AND (u.city = "Singapore" OR u.city = "Jakarta")
|
|
87
|
+
RETURN u.name AS customer,
|
|
88
|
+
COUNT(*) AS orders,
|
|
89
|
+
SUM(o.amount * o.quantity) AS spent
|
|
90
|
+
GROUP BY u.name
|
|
91
|
+
HAVING COUNT(*) >= 2
|
|
92
|
+
ORDER BY spent DESC
|
|
93
|
+
LIMIT 10
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Comparisons can use columns on both sides, which is how you find stock that
|
|
97
|
+
has drifted between a marketplace and your master record:
|
|
98
|
+
|
|
99
|
+
```udl
|
|
100
|
+
FROM platform_listings AS l
|
|
101
|
+
JOIN products AS p ON l.product_id = p.id
|
|
102
|
+
WHERE l.current_stock != p.master_stock
|
|
103
|
+
RETURN p.master_sku AS sku, l.current_stock - p.master_stock AS difference
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Values are passed as named parameters (`$minimum`) and bound by SQLite. They
|
|
107
|
+
are never concatenated into SQL text.
|
|
108
|
+
|
|
109
|
+
## Installation
|
|
110
|
+
|
|
111
|
+
Qryndel is distributed from the source repository. From a checkout:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
python -m venv .venv
|
|
115
|
+
# Activate .venv using the command for your shell.
|
|
116
|
+
python -m pip install --upgrade pip
|
|
117
|
+
python -m pip install .
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Python 3.10 or newer is required. `RIGHT JOIN` and `FULL JOIN` need SQLite
|
|
121
|
+
3.39 or newer, and `NULLS FIRST`/`NULLS LAST` need SQLite 3.30 or newer. On
|
|
122
|
+
older SQLite versions Qryndel reports a clear capability error before running
|
|
123
|
+
the query.
|
|
124
|
+
|
|
125
|
+
## Getting Started
|
|
126
|
+
|
|
127
|
+
Create the example database and run a query through the CLI:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
python setup_db.py
|
|
131
|
+
udl "FROM users WHERE age >= $minimum RETURN name, age ORDER BY age DESC" --param '$minimum=18'
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The same query through the Python API:
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
from qryndel import Client
|
|
138
|
+
|
|
139
|
+
client = Client("test.db")
|
|
140
|
+
result = client.execute(
|
|
141
|
+
"FROM users WHERE age >= $minimum RETURN name, age ORDER BY age DESC",
|
|
142
|
+
params={"minimum": 18},
|
|
143
|
+
)
|
|
144
|
+
print(result.rows)
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The fixture created by `setup_db.py` contains `users` (including JSON
|
|
148
|
+
`profile` and `settings` columns) and `orders` tables. Runnable programs are
|
|
149
|
+
in [`examples/`](examples).
|
|
150
|
+
|
|
151
|
+
## Catching Mistakes Before They Run
|
|
152
|
+
|
|
153
|
+
The CLI reads the database's tables and columns first, and
|
|
154
|
+
`Client(path, schema="auto")` does the same in Python:
|
|
155
|
+
|
|
156
|
+
```text
|
|
157
|
+
$ udl "FROM users RETURN nmae"
|
|
158
|
+
error[UDL_SEMANTIC_ERROR]: Unknown field 'nmae' in source 'users'. Did you mean 'name'?
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
`TYPE` declarations can be checked against the real tables, which is useful
|
|
162
|
+
in CI to notice that a migration changed a column the application relies on:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
udl --check-schema examples/checks/fixture_types.qryndel # exit 1 on drift
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Data imported from CSV often stores numbers as TEXT, where SQLite compares
|
|
169
|
+
them as text (`'999.99' > '1000'`). When the schema is known, Qryndel refuses
|
|
170
|
+
that comparison and tells you how to fix it:
|
|
171
|
+
|
|
172
|
+
```text
|
|
173
|
+
$ udl "FROM order_items WHERE price > 1000 RETURN COUNT(*)"
|
|
174
|
+
error[UDL_SEMANTIC_ERROR]: Column 'price' is stored as text, so `price > 1000` would
|
|
175
|
+
compare text, not numbers ... Write NUMBER(price) to compare as numbers, or declare
|
|
176
|
+
`price: Number` in a TYPE block.
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Results can be checked before your code uses them:
|
|
180
|
+
|
|
181
|
+
```python
|
|
182
|
+
from qryndel import Client, NonEmpty, NonNull, RowCount, Unique
|
|
183
|
+
|
|
184
|
+
client.execute(
|
|
185
|
+
"FROM orders WHERE amount > 0 RETURN id, amount, product",
|
|
186
|
+
contracts=[Unique("id"), NonNull("amount"), NonEmpty("product"), RowCount(minimum=1)],
|
|
187
|
+
) # raises ContractViolation if any check fails
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
`NonNull` accepts `''`; `NonEmpty` also rejects empty and blank strings.
|
|
191
|
+
Other contracts: `NoMissing` (the field must exist) and `Compare`
|
|
192
|
+
(`Compare("amount", ">=", 0)`).
|
|
193
|
+
|
|
194
|
+
## Writing Data
|
|
195
|
+
|
|
196
|
+
```python
|
|
197
|
+
client.execute(
|
|
198
|
+
"INSERT INTO users { name: $name, age: 22, email: $email, city: 'Singapore' }",
|
|
199
|
+
params={"name": "Hana", "email": "hana@example.com"},
|
|
200
|
+
)
|
|
201
|
+
client.execute("UPDATE users SET city = 'Jakarta' WHERE name = 'Hana'")
|
|
202
|
+
|
|
203
|
+
# UPDATE or DELETE without WHERE is rejected before any SQL runs.
|
|
204
|
+
client.execute("DELETE FROM users") # raises SemanticError
|
|
205
|
+
|
|
206
|
+
# Several writes commit together, or not at all.
|
|
207
|
+
client.execute("""
|
|
208
|
+
BEGIN
|
|
209
|
+
UPDATE users SET city = "Jakarta" WHERE name = "Eve";
|
|
210
|
+
DELETE FROM orders WHERE user_id = 5;
|
|
211
|
+
COMMIT
|
|
212
|
+
""")
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Writes return `rows_affected` (and `last_insert_id` for `INSERT`) on the
|
|
216
|
+
result.
|
|
217
|
+
|
|
218
|
+
## Safety Controls
|
|
219
|
+
|
|
220
|
+
| Control | Python API | CLI |
|
|
221
|
+
| --- | --- | --- |
|
|
222
|
+
| Reject all writes | `Client(path, read_only=True)` | `--read-only` |
|
|
223
|
+
| Limit which tables writes touch | `Client(path, allowed_tables=["orders"])` | — |
|
|
224
|
+
| Cap rows returned | `budget={"max_result_rows": 1000}` | `--max-rows N` |
|
|
225
|
+
| Cap rows a write changes (rolls back) | `budget={"max_affected_rows": 10}` | `--max-affected-rows N` |
|
|
226
|
+
| Time limit | `budget={"max_duration_ms": 500}` | `--timeout-ms MS` |
|
|
227
|
+
| See the SQL without running it | `client.explain(query)` | `--explain` |
|
|
228
|
+
| Check tables and columns first | `Client(path, schema="auto")` | on by default (`--no-schema-check` to skip) |
|
|
229
|
+
| Check results before using them | `execute(..., contracts=[...])` | — |
|
|
230
|
+
| One budget for every query | `Client(path, default_budget={...})` | — |
|
|
231
|
+
| Lock wait limit | `Client(path, busy_timeout_ms=5000)` | capped by `--timeout-ms` |
|
|
232
|
+
| Count rows a write would change | `client.preview(query)` | `--preview` |
|
|
233
|
+
|
|
234
|
+
`explain` output never includes parameter values. See
|
|
235
|
+
[SECURITY.md](SECURITY.md) for the full security model.
|
|
236
|
+
|
|
237
|
+
## Safe Database Access For AI Agents
|
|
238
|
+
|
|
239
|
+
Give a model a tool that runs UDL instead of raw SQL. Qryndel checks each
|
|
240
|
+
query against the live schema, refuses writes, caps rows and time, and
|
|
241
|
+
returns short errors the model can act on:
|
|
242
|
+
|
|
243
|
+
```python
|
|
244
|
+
from qryndel import Client, UdlError
|
|
245
|
+
|
|
246
|
+
agent_db = Client("shop.db", schema="auto", read_only=True,
|
|
247
|
+
default_budget={"max_result_rows": 200, "max_duration_ms": 2000})
|
|
248
|
+
|
|
249
|
+
def query_database(udl: str) -> dict:
|
|
250
|
+
try:
|
|
251
|
+
return {"rows": agent_db.execute(udl).rows}
|
|
252
|
+
except UdlError as error:
|
|
253
|
+
return {"error": error.code, "message": error.message} # e.g. "Did you mean 'name'?"
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
The full runnable version, with a tool description generated from the schema,
|
|
257
|
+
is [examples/agent_guardrails.py](examples/agent_guardrails.py)
|
|
258
|
+
(`python -m examples.agent_guardrails`). It does not depend on any particular
|
|
259
|
+
LLM provider.
|
|
260
|
+
|
|
261
|
+
## Supported In v0.3.0
|
|
262
|
+
|
|
263
|
+
- `FROM`, `WHERE`, `RETURN [DISTINCT]`, `ORDER BY ... [ASC|DESC] [NULLS FIRST|LAST]`, `LIMIT`.
|
|
264
|
+
- `AND`, `OR`, `NOT`, parentheses, and `=`, `!=`, `>`, `<`, `>=`, `<=`, with
|
|
265
|
+
columns or expressions on either side.
|
|
266
|
+
- Arithmetic (`+ - * /`, unary minus), `NUMBER(x)` / `TEXT(x)` conversions,
|
|
267
|
+
and `AS` names in `RETURN`.
|
|
268
|
+
- `JOIN`, `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN` with aliases.
|
|
269
|
+
- `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` (over expressions), `GROUP BY`, `HAVING`.
|
|
270
|
+
- Nested JSON fields (`profile.address.city`) and `IS [NOT] NULL`,
|
|
271
|
+
`IS [NOT] MISSING`, `EXISTS`.
|
|
272
|
+
- `RULE` reusable predicates and `TYPE` schema declarations.
|
|
273
|
+
- `INSERT`, `UPDATE` (including `SET stock = stock - $sold`), `DELETE`, and
|
|
274
|
+
`BEGIN ... COMMIT|ROLLBACK` transactions.
|
|
275
|
+
- Schema checks against the live database, schema-drift reports, and result
|
|
276
|
+
contracts.
|
|
277
|
+
- Named parameters (`$name`) and `--` line comments.
|
|
278
|
+
- Source-aware parse errors and structured `UdlError` codes.
|
|
279
|
+
- A Python API and the `udl` command-line tool.
|
|
280
|
+
|
|
281
|
+
The full syntax is in the [language reference](docs/language-reference.md).
|
|
282
|
+
Upgrading? See the [changelog](CHANGELOG.md). The one behaviour change in
|
|
283
|
+
0.3.0: an unquoted word on the right of a comparison is now a column name, so
|
|
284
|
+
write `city = 'Singapore'`, not `city = Singapore`.
|
|
285
|
+
|
|
286
|
+
## Tested On Real Data
|
|
287
|
+
|
|
288
|
+
v0.3.0 was tested against a 1.5-million-row public e-commerce dataset:
|
|
289
|
+
native-SQL comparisons, 3,000 generated queries, 15,000 fuzzed inputs,
|
|
290
|
+
rollback, concurrency and 1M-row workloads. See
|
|
291
|
+
[docs/real-world-testing.md](docs/real-world-testing.md) for what was found
|
|
292
|
+
and fixed.
|
|
293
|
+
|
|
294
|
+
## Current Limitations
|
|
295
|
+
|
|
296
|
+
PostgreSQL, MongoDB, Neo4j and graph `MATCH` queries are not part of v0.3.0.
|
|
297
|
+
UDL does not yet promise that a query gives identical results on engines
|
|
298
|
+
other than SQLite.
|
|
299
|
+
|
|
300
|
+
## Implementation Overview
|
|
301
|
+
|
|
302
|
+
```text
|
|
303
|
+
UDL text -> parser -> AST -> rule expansion + semantic validation
|
|
304
|
+
-> logical plan -> optimizer -> safety policy -> SQLite SQL -> executor
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
See [docs/architecture.md](docs/architecture.md).
|
|
308
|
+
|
|
309
|
+
## Development And Testing
|
|
310
|
+
|
|
311
|
+
```bash
|
|
312
|
+
python -m pip install -e ".[test]"
|
|
313
|
+
python -m pytest -q
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
The test suite creates its own SQLite fixtures and needs no external
|
|
317
|
+
database service.
|
|
318
|
+
|
|
319
|
+
## Roadmap
|
|
320
|
+
|
|
321
|
+
See [docs/ROADMAP.md](docs/ROADMAP.md). These are plans, not compatibility
|
|
322
|
+
promises.
|
|
323
|
+
|
|
324
|
+
## Contributing
|
|
325
|
+
|
|
326
|
+
Bug reports, focused feature proposals, tests, and documentation improvements
|
|
327
|
+
are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull
|
|
328
|
+
request. Major language changes should start with an RFC in
|
|
329
|
+
[docs/rfcs](docs/rfcs/README.md).
|
|
330
|
+
|
|
331
|
+
## License
|
|
332
|
+
|
|
333
|
+
Qryndel is released under the [MIT License](LICENSE).
|
|
334
|
+
|
|
335
|
+
## Original Author
|
|
336
|
+
|
|
337
|
+
Qryndel was initiated by **Manveer Singh**, Original Creator and Founding
|
|
338
|
+
Maintainer.
|
|
339
|
+
|
|
340
|
+
AI-assisted development disclosure: [docs/AI_ASSISTED_DEVELOPMENT.md](docs/AI_ASSISTED_DEVELOPMENT.md).
|