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.
Files changed (112) hide show
  1. qryndel-0.3.0/AUTHORS.md +8 -0
  2. qryndel-0.3.0/CHANGELOG.md +194 -0
  3. qryndel-0.3.0/LICENSE +21 -0
  4. qryndel-0.3.0/MANIFEST.in +18 -0
  5. qryndel-0.3.0/PKG-INFO +340 -0
  6. qryndel-0.3.0/README.md +306 -0
  7. qryndel-0.3.0/SECURITY.md +52 -0
  8. qryndel-0.3.0/docs/AI_ASSISTED_DEVELOPMENT.md +10 -0
  9. qryndel-0.3.0/docs/GITHUB_RELEASE.md +57 -0
  10. qryndel-0.3.0/docs/ROADMAP.md +35 -0
  11. qryndel-0.3.0/docs/architecture.md +64 -0
  12. qryndel-0.3.0/docs/language-reference.md +252 -0
  13. qryndel-0.3.0/docs/real-world-testing.md +45 -0
  14. qryndel-0.3.0/docs/rfcs/README.md +18 -0
  15. qryndel-0.3.0/examples/__init__.py +1 -0
  16. qryndel-0.3.0/examples/agent_guardrails.py +61 -0
  17. qryndel-0.3.0/examples/basic_filter.qryndel +3 -0
  18. qryndel-0.3.0/examples/checks/fixture_types.qryndel +18 -0
  19. qryndel-0.3.0/examples/example1.qryndel +2 -0
  20. qryndel-0.3.0/examples/example10_join_where.qryndel +6 -0
  21. qryndel-0.3.0/examples/example11_nested_return.qryndel +2 -0
  22. qryndel-0.3.0/examples/example12_nested_where.qryndel +3 -0
  23. qryndel-0.3.0/examples/example13_nested_order_by.qryndel +3 -0
  24. qryndel-0.3.0/examples/example2.qryndel +3 -0
  25. qryndel-0.3.0/examples/example20_rule_basic.qryndel +2 -0
  26. qryndel-0.3.0/examples/example21_rule_nested.qryndel +3 -0
  27. qryndel-0.3.0/examples/example23_rule_multiple.qryndel +3 -0
  28. qryndel-0.3.0/examples/example24_insert.qryndel +6 -0
  29. qryndel-0.3.0/examples/example25_update.qryndel +3 -0
  30. qryndel-0.3.0/examples/example26_delete.qryndel +2 -0
  31. qryndel-0.3.0/examples/example27_rule_update.qryndel +4 -0
  32. qryndel-0.3.0/examples/example28_group_by.qryndel +6 -0
  33. qryndel-0.3.0/examples/example29_transaction.qryndel +5 -0
  34. qryndel-0.3.0/examples/example3.qryndel +3 -0
  35. qryndel-0.3.0/examples/example30_types.qryndel +10 -0
  36. qryndel-0.3.0/examples/example31_left_join.qryndel +5 -0
  37. qryndel-0.3.0/examples/example32_order_value.qryndel +5 -0
  38. qryndel-0.3.0/examples/example33_spend_per_user.qryndel +10 -0
  39. qryndel-0.3.0/examples/example34_stock_drift.qryndel +8 -0
  40. qryndel-0.3.0/examples/example35_restock.qryndel +2 -0
  41. qryndel-0.3.0/examples/example4.qryndel +3 -0
  42. qryndel-0.3.0/examples/example5_and.qryndel +3 -0
  43. qryndel-0.3.0/examples/example6_or.qryndel +3 -0
  44. qryndel-0.3.0/examples/example7_order_limit.qryndel +5 -0
  45. qryndel-0.3.0/examples/example8_distinct.qryndel +2 -0
  46. qryndel-0.3.0/examples/example9_join.qryndel +4 -0
  47. qryndel-0.3.0/pyproject.toml +54 -0
  48. qryndel-0.3.0/qryndel/__init__.py +50 -0
  49. qryndel-0.3.0/qryndel/ast_nodes.py +403 -0
  50. qryndel-0.3.0/qryndel/backends/__init__.py +40 -0
  51. qryndel-0.3.0/qryndel/backends/base.py +40 -0
  52. qryndel-0.3.0/qryndel/backends/sqlite.py +574 -0
  53. qryndel-0.3.0/qryndel/budgets.py +47 -0
  54. qryndel-0.3.0/qryndel/capabilities.py +161 -0
  55. qryndel-0.3.0/qryndel/cli.py +181 -0
  56. qryndel-0.3.0/qryndel/contracts.py +356 -0
  57. qryndel-0.3.0/qryndel/errors.py +50 -0
  58. qryndel-0.3.0/qryndel/executor.py +255 -0
  59. qryndel-0.3.0/qryndel/explain.py +85 -0
  60. qryndel-0.3.0/qryndel/expressions.py +116 -0
  61. qryndel-0.3.0/qryndel/grammar.lark +147 -0
  62. qryndel-0.3.0/qryndel/logical_plan.py +305 -0
  63. qryndel-0.3.0/qryndel/metrics.py +30 -0
  64. qryndel-0.3.0/qryndel/optimizer.py +97 -0
  65. qryndel-0.3.0/qryndel/parser.py +572 -0
  66. qryndel-0.3.0/qryndel/rules.py +249 -0
  67. qryndel-0.3.0/qryndel/safety.py +150 -0
  68. qryndel-0.3.0/qryndel/schema.py +79 -0
  69. qryndel-0.3.0/qryndel/schema_drift.py +219 -0
  70. qryndel-0.3.0/qryndel/sdk.py +212 -0
  71. qryndel-0.3.0/qryndel/semantic.py +752 -0
  72. qryndel-0.3.0/qryndel.egg-info/PKG-INFO +340 -0
  73. qryndel-0.3.0/qryndel.egg-info/SOURCES.txt +110 -0
  74. qryndel-0.3.0/qryndel.egg-info/dependency_links.txt +1 -0
  75. qryndel-0.3.0/qryndel.egg-info/entry_points.txt +2 -0
  76. qryndel-0.3.0/qryndel.egg-info/requires.txt +4 -0
  77. qryndel-0.3.0/qryndel.egg-info/top_level.txt +1 -0
  78. qryndel-0.3.0/setup.cfg +4 -0
  79. qryndel-0.3.0/setup_db.py +101 -0
  80. qryndel-0.3.0/tests/__init__.py +0 -0
  81. qryndel-0.3.0/tests/conftest.py +20 -0
  82. qryndel-0.3.0/tests/test_aggregates.py +51 -0
  83. qryndel-0.3.0/tests/test_budgets.py +40 -0
  84. qryndel-0.3.0/tests/test_capabilities.py +14 -0
  85. qryndel-0.3.0/tests/test_concurrency.py +23 -0
  86. qryndel-0.3.0/tests/test_contracts.py +53 -0
  87. qryndel-0.3.0/tests/test_errors.py +37 -0
  88. qryndel-0.3.0/tests/test_executor.py +173 -0
  89. qryndel-0.3.0/tests/test_explain.py +17 -0
  90. qryndel-0.3.0/tests/test_fault_injection.py +55 -0
  91. qryndel-0.3.0/tests/test_language_semantics.py +76 -0
  92. qryndel-0.3.0/tests/test_logical_plan.py +169 -0
  93. qryndel-0.3.0/tests/test_metrics.py +36 -0
  94. qryndel-0.3.0/tests/test_null_predicates.py +44 -0
  95. qryndel-0.3.0/tests/test_optimizer.py +49 -0
  96. qryndel-0.3.0/tests/test_parameters.py +39 -0
  97. qryndel-0.3.0/tests/test_parser.py +270 -0
  98. qryndel-0.3.0/tests/test_rules.py +495 -0
  99. qryndel-0.3.0/tests/test_safety.py +101 -0
  100. qryndel-0.3.0/tests/test_schema_drift.py +50 -0
  101. qryndel-0.3.0/tests/test_sdk.py +26 -0
  102. qryndel-0.3.0/tests/test_semantic.py +248 -0
  103. qryndel-0.3.0/tests/test_sql_compiler.py +296 -0
  104. qryndel-0.3.0/tests/test_streaming_contracts.py +53 -0
  105. qryndel-0.3.0/tests/test_transactions.py +70 -0
  106. qryndel-0.3.0/tests/test_types.py +78 -0
  107. qryndel-0.3.0/tests/test_v01_compatibility.py +161 -0
  108. qryndel-0.3.0/tests/test_v02_features.py +321 -0
  109. qryndel-0.3.0/tests/test_v03_features.py +350 -0
  110. qryndel-0.3.0/tests/test_v03_hardening.py +262 -0
  111. qryndel-0.3.0/tests/test_write_budgets.py +25 -0
  112. qryndel-0.3.0/tests/test_writes.py +530 -0
@@ -0,0 +1,8 @@
1
+ # Authors
2
+
3
+ ## Manveer Singh
4
+
5
+ **Original Creator and Founding Maintainer**
6
+
7
+ Manveer Singh initiated Qryndel and its original Unified Data Language
8
+ implementation.
@@ -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
+ [![Tests](https://github.com/Manveer04/qryndel/actions/workflows/tests.yml/badge.svg)](https://github.com/Manveer04/qryndel/actions/workflows/tests.yml)
38
+ [![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%20%E2%80%93%203.13-blue)](pyproject.toml)
39
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
40
+ [![Release](https://img.shields.io/github/v/release/Manveer04/qryndel?include_prereleases)](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).