j-perm-sql 0.1.0__tar.gz → 0.2.0__tar.gz

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: j-perm-sql
-Version: 0.1.0
+Version: 0.2.0
 Summary: j-perm plugin for SQL
 Author-email: Roman <kuschanow@gmail.com>
 License: MIT
@@ -15,18 +15,23 @@ Requires-Dist: j-perm>=1.9.0
 # j-perm-sql
 
 A [j-perm](https://github.com/kuschanow/j-perm) plugin that builds and executes
-**SQL `SELECT` queries** from j-perm constructs.
+**SQL queries** from j-perm constructs.
 
 * SQL is described with a tree of `$`-constructs (`$select`, `$col`, `$val`,
   predicates, joins, …).
-* A single new top-level operation — `op: sql` — renders that tree to a
-  **parameterized** `(sql, params)` pair and hands it to a configurable
-  executor (any ORM's raw-execute function).
-* The SQL constructs live in an **isolated** named pipeline: they mean nothing
-  outside `op: sql`. `{"$select": …}` used as an ordinary value is just a dict.
-
-> v1 scope: the full standard **`SELECT`** surface (read-only). DDL/DML
-> (`CREATE`/`ALTER`/`INSERT`/`UPDATE`/`DELETE`) is intentionally out of scope.
+* A top-level operation renders that tree to a **parameterized** `(sql, params)`
+  pair and hands it to a configurable executor (any ORM's raw-execute function):
+  `op: sql` for read-only `SELECT`, and (opt-in) `op: sql_write` for
+  `INSERT`/`UPDATE`/`DELETE`.
+* The SQL constructs live in **isolated** named pipelines: they mean nothing
+  outside those operations. `{"$select": …}` used as an ordinary value is just a
+  dict.
+
+> Scope: the full standard **`SELECT`** surface (read-only) via `install_sql`,
+> plus standard **`INSERT`/`UPDATE`/`DELETE`** (row content only) via
+> `install_sql_write`. Schema DDL (`CREATE`/`ALTER`/`DROP` of tables/columns)
+> and non-universal DML (`RETURNING`, `ON CONFLICT`/upsert, `UPDATE … FROM`,
+> `DELETE … USING`) are intentionally out of scope.
 
 ## Install
 
@@ -78,12 +83,79 @@ plugins.
 * `to` — optional destination pointer (template-expanded); the executor's
   result is written there. If omitted, the result is discarded.
 
+## Writing data (`INSERT`/`UPDATE`/`DELETE`)
+
+Writing is a **separate, opt-in install** — you don't get it unless you ask for
+it, and `op: sql` stays guaranteed read-only even when both are installed:
+
+```python
+from j_perm_sql import install_sql, install_sql_write
+
+install_sql(engine, run_sql)          # read-only  op: sql      (optional)
+install_sql_write(engine, run_sql)    # write      op: sql_write
+```
+
+`install_sql_write(engine, executor, *, paramstyle="qmark", dialect=None,
+op="sql_write")` registers an isolated **write pipeline** (the full `SELECT`
+surface *plus* the DML statements, so `WHERE` predicates, `SET` expressions and
+`INSERT … SELECT` subqueries all work) and the `op: sql_write` operation. It is
+independent of `install_sql` — either may be installed alone, in any order. It
+selects the sync/async handler the same way (by `asyncio.iscoroutinefunction`).
+
+```js
+{"op": "sql_write", "query": <DML construct tree>, "to": "/dest/path"}
+```
+
+**`$insert`** — exactly one of `values` / `query`:
+
+```python
+{"$insert": {
+  "into": "users",                    # or {"table": "users", "schema": "app"}
+  "columns": ["name", "age"],         # optional
+  "values": [[{"$val": "Ann"}, {"$val": 30}], ...],   # cells are operands ($val to bind)
+  # ── OR ──
+  "query": {"$select": {...}},        # INSERT … SELECT
+}}
+# → INSERT INTO "users" ("name", "age") VALUES (?, ?)   params=["Ann", 30]
+```
+
+**`$update`** — single table:
+
+```python
+{"$update": {
+  "table": "users",                   # or {"table": "users", "schema": "app"}
+  "set": {"name": {"$val": "Bob"},
+          "visits": {"$add": [{"$col": "visits"}, {"$val": 1}]}},
+  "where": {"$eq": [{"$col": "id"}, {"$val": 5}]},      # or "all": true
+}}
+# → UPDATE "users" SET "name" = ?, "visits" = ("visits" + ?) WHERE "id" = ?
+```
+
+**`$delete`** — single table:
+
+```python
+{"$delete": {
+  "from": "sessions",                 # or {"table": "sessions", "schema": "app"}
+  "where": {"$lt": [{"$col": "last_seen"}, {"$val": "2020-01-01"}]},  # or "all": true
+}}
+# → DELETE FROM "sessions" WHERE "last_seen" < ?
+```
+
+`set` values, `$insert` cells, and `where` predicates are ordinary read
+constructs, so the full expression/predicate/subquery surface (including
+correlated subqueries) is available, and data is always bound as parameters.
+
+> **WHERE guard.** A `$update` / `$delete` **without** a `where` raises unless
+> you pass an explicit `"all": true`. This prevents an accidental full-table
+> update/delete.
+
 ## Parameterization & injection safety
 
 Data values are **always bound as parameters**, never interpolated:
 
-* `$val` (and the data sides of `$in`, `$between`, `$values`) emit a placeholder
-  and add the value to `params`.
+* `$val` (and the data sides of `$in`, `$between`, `$values`, `$update`'s `set`
+  values, and `$insert`'s row cells) emit a placeholder and add the value to
+  `params`.
 * Identifiers (table/column/alias names) are validated against a conservative
   charset and quoted.
 * Function names, CAST types, join types, sort directions, etc. are validated
@@ -94,8 +166,14 @@ Data values are **always bound as parameters**, never interpolated:
 # → '"name" = ?'   with the (possibly malicious) value safely in params
 ```
 
-Inside `$val`, the value expression is resolved with j-perm's normal value
-pipeline, so `$ref`, `${…}` templates, and `@:` dest-pointers all work.
+**Parameters come from inside j-perm — no external param source.** Inside `$val`
+the value expression is resolved with j-perm's normal value pipeline, so `$ref`,
+`${…}` templates, and `@:` dest-pointers all work. The `params` list handed to
+the executor is simply the values j-perm itself computed from the document; the
+parameter binding exists only for injection safety and the driver's paramstyle.
+The whole flow (source → SQL → bound values) is self-contained in one j-perm
+run; the executor is just the pipe to the driver. This applies equally to read
+(`op: sql`) and write (`op: sql_write`).
 
 ## Dialect / `RenderOptions`
 
@@ -114,9 +192,9 @@ install_sql(engine, run_sql, dialect=RenderOptions(
 
 ## Sync & async
 
-`install_sql` inspects the executor: a coroutine function registers the async
-handler (use with `engine.apply_async`); a regular function registers the sync
-handler (use with `engine.apply`).
+Both `install_sql` and `install_sql_write` inspect the executor: a coroutine
+function registers the async handler (use with `engine.apply_async`); a regular
+function registers the sync handler (use with `engine.apply`).
 
 ```python
 async def run_sql(sql, params): ...
@@ -134,6 +212,14 @@ await engine.apply_async(spec, source=…, dest=…)
 | `$union` / `$union_all` / `$intersect` / `$except` | `{"$union": [q1, q2, …], order_by?, limit?…}` |
 | `$values` | `{"$values": [[…row…], …]}` (table source or `IN`) |
 
+**Write (DML)** — only via `install_sql_write` / `op: sql_write`
+
+| Construct | Form |
+|---|---|
+| `$insert` | `{into, columns?, values \| query}` (exactly one of `values`/`query`) |
+| `$update` | `{table, set: {col: operand}, where? \| "all": true}` |
+| `$delete` | `{from, where? \| "all": true}` |
+
 **Projection / expressions**
 
 | Construct | Renders |

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/README.md

@@ -1,18 +1,23 @@
 # j-perm-sql
 
 A [j-perm](https://github.com/kuschanow/j-perm) plugin that builds and executes
-**SQL `SELECT` queries** from j-perm constructs.
+**SQL queries** from j-perm constructs.
 
 * SQL is described with a tree of `$`-constructs (`$select`, `$col`, `$val`,
   predicates, joins, …).
-* A single new top-level operation — `op: sql` — renders that tree to a
-  **parameterized** `(sql, params)` pair and hands it to a configurable
-  executor (any ORM's raw-execute function).
-* The SQL constructs live in an **isolated** named pipeline: they mean nothing
-  outside `op: sql`. `{"$select": …}` used as an ordinary value is just a dict.
-
-> v1 scope: the full standard **`SELECT`** surface (read-only). DDL/DML
-> (`CREATE`/`ALTER`/`INSERT`/`UPDATE`/`DELETE`) is intentionally out of scope.
+* A top-level operation renders that tree to a **parameterized** `(sql, params)`
+  pair and hands it to a configurable executor (any ORM's raw-execute function):
+  `op: sql` for read-only `SELECT`, and (opt-in) `op: sql_write` for
+  `INSERT`/`UPDATE`/`DELETE`.
+* The SQL constructs live in **isolated** named pipelines: they mean nothing
+  outside those operations. `{"$select": …}` used as an ordinary value is just a
+  dict.
+
+> Scope: the full standard **`SELECT`** surface (read-only) via `install_sql`,
+> plus standard **`INSERT`/`UPDATE`/`DELETE`** (row content only) via
+> `install_sql_write`. Schema DDL (`CREATE`/`ALTER`/`DROP` of tables/columns)
+> and non-universal DML (`RETURNING`, `ON CONFLICT`/upsert, `UPDATE … FROM`,
+> `DELETE … USING`) are intentionally out of scope.
 
 ## Install
 
@@ -64,12 +69,79 @@ plugins.
 * `to` — optional destination pointer (template-expanded); the executor's
   result is written there. If omitted, the result is discarded.
 
+## Writing data (`INSERT`/`UPDATE`/`DELETE`)
+
+Writing is a **separate, opt-in install** — you don't get it unless you ask for
+it, and `op: sql` stays guaranteed read-only even when both are installed:
+
+```python
+from j_perm_sql import install_sql, install_sql_write
+
+install_sql(engine, run_sql)          # read-only  op: sql      (optional)
+install_sql_write(engine, run_sql)    # write      op: sql_write
+```
+
+`install_sql_write(engine, executor, *, paramstyle="qmark", dialect=None,
+op="sql_write")` registers an isolated **write pipeline** (the full `SELECT`
+surface *plus* the DML statements, so `WHERE` predicates, `SET` expressions and
+`INSERT … SELECT` subqueries all work) and the `op: sql_write` operation. It is
+independent of `install_sql` — either may be installed alone, in any order. It
+selects the sync/async handler the same way (by `asyncio.iscoroutinefunction`).
+
+```js
+{"op": "sql_write", "query": <DML construct tree>, "to": "/dest/path"}
+```
+
+**`$insert`** — exactly one of `values` / `query`:
+
+```python
+{"$insert": {
+  "into": "users",                    # or {"table": "users", "schema": "app"}
+  "columns": ["name", "age"],         # optional
+  "values": [[{"$val": "Ann"}, {"$val": 30}], ...],   # cells are operands ($val to bind)
+  # ── OR ──
+  "query": {"$select": {...}},        # INSERT … SELECT
+}}
+# → INSERT INTO "users" ("name", "age") VALUES (?, ?)   params=["Ann", 30]
+```
+
+**`$update`** — single table:
+
+```python
+{"$update": {
+  "table": "users",                   # or {"table": "users", "schema": "app"}
+  "set": {"name": {"$val": "Bob"},
+          "visits": {"$add": [{"$col": "visits"}, {"$val": 1}]}},
+  "where": {"$eq": [{"$col": "id"}, {"$val": 5}]},      # or "all": true
+}}
+# → UPDATE "users" SET "name" = ?, "visits" = ("visits" + ?) WHERE "id" = ?
+```
+
+**`$delete`** — single table:
+
+```python
+{"$delete": {
+  "from": "sessions",                 # or {"table": "sessions", "schema": "app"}
+  "where": {"$lt": [{"$col": "last_seen"}, {"$val": "2020-01-01"}]},  # or "all": true
+}}
+# → DELETE FROM "sessions" WHERE "last_seen" < ?
+```
+
+`set` values, `$insert` cells, and `where` predicates are ordinary read
+constructs, so the full expression/predicate/subquery surface (including
+correlated subqueries) is available, and data is always bound as parameters.
+
+> **WHERE guard.** A `$update` / `$delete` **without** a `where` raises unless
+> you pass an explicit `"all": true`. This prevents an accidental full-table
+> update/delete.
+
 ## Parameterization & injection safety
 
 Data values are **always bound as parameters**, never interpolated:
 
-* `$val` (and the data sides of `$in`, `$between`, `$values`) emit a placeholder
-  and add the value to `params`.
+* `$val` (and the data sides of `$in`, `$between`, `$values`, `$update`'s `set`
+  values, and `$insert`'s row cells) emit a placeholder and add the value to
+  `params`.
 * Identifiers (table/column/alias names) are validated against a conservative
   charset and quoted.
 * Function names, CAST types, join types, sort directions, etc. are validated
@@ -80,8 +152,14 @@ Data values are **always bound as parameters**, never interpolated:
 # → '"name" = ?'   with the (possibly malicious) value safely in params
 ```
 
-Inside `$val`, the value expression is resolved with j-perm's normal value
-pipeline, so `$ref`, `${…}` templates, and `@:` dest-pointers all work.
+**Parameters come from inside j-perm — no external param source.** Inside `$val`
+the value expression is resolved with j-perm's normal value pipeline, so `$ref`,
+`${…}` templates, and `@:` dest-pointers all work. The `params` list handed to
+the executor is simply the values j-perm itself computed from the document; the
+parameter binding exists only for injection safety and the driver's paramstyle.
+The whole flow (source → SQL → bound values) is self-contained in one j-perm
+run; the executor is just the pipe to the driver. This applies equally to read
+(`op: sql`) and write (`op: sql_write`).
 
 ## Dialect / `RenderOptions`
 
@@ -100,9 +178,9 @@ install_sql(engine, run_sql, dialect=RenderOptions(
 
 ## Sync & async
 
-`install_sql` inspects the executor: a coroutine function registers the async
-handler (use with `engine.apply_async`); a regular function registers the sync
-handler (use with `engine.apply`).
+Both `install_sql` and `install_sql_write` inspect the executor: a coroutine
+function registers the async handler (use with `engine.apply_async`); a regular
+function registers the sync handler (use with `engine.apply`).
 
 ```python
 async def run_sql(sql, params): ...
@@ -120,6 +198,14 @@ await engine.apply_async(spec, source=…, dest=…)
 | `$union` / `$union_all` / `$intersect` / `$except` | `{"$union": [q1, q2, …], order_by?, limit?…}` |
 | `$values` | `{"$values": [[…row…], …]}` (table source or `IN`) |
 
+**Write (DML)** — only via `install_sql_write` / `op: sql_write`
+
+| Construct | Form |
+|---|---|
+| `$insert` | `{into, columns?, values \| query}` (exactly one of `values`/`query`) |
+| `$update` | `{table, set: {col: operand}, where? \| "all": true}` |
+| `$delete` | `{from, where? \| "all": true}` |
+
 **Projection / expressions**
 
 | Construct | Renders |

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "j-perm-sql"
-version = "0.1.0"
+version = "0.2.0"
 description = "j-perm plugin for SQL"
 authors = [
     { name = "Roman", email = "kuschanow@gmail.com" },

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/src/j_perm_sql/__init__.py

@@ -25,22 +25,32 @@ Quick start::
     )
 """
 from .constructs import build_sql_specials
+from .constructs_write import build_sql_write_specials
 from .dialect import PLACEHOLDER, RenderOptions
 from .handler import AsyncSqlHandler, SqlHandler, SqlRenderer
-from .install import install_sql
-from .pipeline import SQL_PIPELINE_NAME, build_sql_pipeline
+from .install import install_sql, install_sql_write
+from .pipeline import (
+    SQL_PIPELINE_NAME,
+    SQL_WRITE_PIPELINE_NAME,
+    build_sql_pipeline,
+    build_sql_write_pipeline,
+)
 from .render import fragment, is_fragment, is_query, render
 
 __all__ = [
     "install_sql",
+    "install_sql_write",
     "RenderOptions",
     "PLACEHOLDER",
     "SqlHandler",
     "AsyncSqlHandler",
     "SqlRenderer",
     "build_sql_pipeline",
+    "build_sql_write_pipeline",
     "build_sql_specials",
+    "build_sql_write_specials",
     "SQL_PIPELINE_NAME",
+    "SQL_WRITE_PIPELINE_NAME",
     "fragment",
     "is_fragment",
     "is_query",

j_perm_sql-0.2.0/src/j_perm_sql/constructs_write.py

@@ -0,0 +1,138 @@
+"""DML construct handlers — standard ``INSERT`` / ``UPDATE`` / ``DELETE``.
+
+These build on the read-only constructs in :mod:`.constructs`: a write
+statement's sub-parts (``WHERE`` predicates, ``SET`` values, ``INSERT … SELECT``
+subqueries) are ordinary read constructs that recurse through the same pipeline.
+
+Only the standard, broadly portable forms are supported.  Non-standard surface
+(``RETURNING``, ``ON CONFLICT``/upsert, ``UPDATE … FROM``, ``DELETE … USING``)
+is intentionally out of scope.
+
+Safety:
+
+* Data values are always bound as parameters (``$val`` / operands), never
+  interpolated — exactly as for ``SELECT``.
+* Table and column names are validated and quoted as identifiers.
+* ``UPDATE`` / ``DELETE`` without a ``where`` raise unless an explicit
+  ``"all": true`` flag is given, to guard against accidental full-table writes.
+"""
+from __future__ import annotations
+
+from functools import partial
+
+from .constructs import build_sql_specials
+from .dialect import RenderOptions
+from .render import (
+    fragment,
+    is_query,
+    render_construct,
+    render_operand,
+    render_operands,
+)
+
+
+def _table_target(spec, opts: RenderOptions) -> str:
+    """Quote a plain table target (``INSERT INTO`` / ``UPDATE`` / ``DELETE FROM``).
+
+    Standard DML targets a single named table (optionally schema-qualified) — no
+    alias and no subquery.  Accepts a string name or ``{"table", "schema"?}``.
+    """
+    if isinstance(spec, str):
+        return opts.quote_ref(spec)
+    if isinstance(spec, dict) and "table" in spec and not is_query(spec):
+        parts = ([spec["schema"]] if spec.get("schema") else []) + [spec["table"]]
+        return ".".join(opts.quote_identifier(p) for p in parts)
+    raise ValueError(f"invalid table target: {spec!r}")
+
+
+def _where_clause(spec, ctx) -> tuple[str, list]:
+    """Render the optional ``WHERE`` of an UPDATE/DELETE, enforcing the guard.
+
+    Returns ``(sql_suffix, params)``.  Without a ``where`` key an explicit
+    ``"all": true`` is required, else :class:`ValueError`.
+    """
+    if "where" in spec:
+        wf = render_construct(spec["where"], ctx)
+        return f" WHERE {wf['sql']}", wf["params"]
+    if spec.get("all") is True:
+        return "", []
+    raise ValueError(
+        "UPDATE/DELETE without 'where' requires an explicit \"all\": true"
+    )
+
+
+def insert(node, ctx, *, opts: RenderOptions) -> dict:
+    spec = node["$insert"]
+    sql = f"INSERT INTO {_table_target(spec['into'], opts)}"
+    if spec.get("columns"):
+        cols = ", ".join(opts.quote_identifier(c) for c in spec["columns"])
+        sql += f" ({cols})"
+    has_values = "values" in spec
+    has_query = "query" in spec
+    if has_values == has_query:
+        raise ValueError("$insert requires exactly one of 'values' or 'query'")
+    params: list = []
+    if has_values:
+        rows = spec["values"]
+        if not rows:
+            raise ValueError("$insert 'values' requires at least one row")
+        rendered_rows: list[str] = []
+        width: int | None = None
+        for row in rows:
+            if width is None:
+                width = len(row)
+            elif len(row) != width:
+                raise ValueError("all $insert rows must have the same length")
+            frag = render_operands(row, ctx, opts)
+            rendered_rows.append(f"({frag['sql']})")
+            params += frag["params"]
+        sql += " VALUES " + ", ".join(rendered_rows)
+    else:
+        if not is_query(spec["query"]):
+            raise ValueError("$insert 'query' must be a SELECT/set-op query construct")
+        q = render_construct(spec["query"], ctx)
+        sql += f" {q['sql']}"
+        params += q["params"]
+    return fragment(sql, params)
+
+
+def _render_set(spec, ctx, opts: RenderOptions) -> dict:
+    if not isinstance(spec, dict) or not spec:
+        raise ValueError("$update 'set' must be a non-empty mapping of column -> value")
+    assignments: list[str] = []
+    params: list = []
+    for col_name, value in spec.items():
+        rhs = render_operand(value, ctx, opts)
+        assignments.append(f"{opts.quote_identifier(col_name)} = {rhs['sql']}")
+        params += rhs["params"]
+    return fragment(", ".join(assignments), params)
+
+
+def update(node, ctx, *, opts: RenderOptions) -> dict:
+    spec = node["$update"]
+    set_frag = _render_set(spec["set"], ctx, opts)
+    sql = f"UPDATE {_table_target(spec['table'], opts)} SET {set_frag['sql']}"
+    params = list(set_frag["params"])
+    where_sql, where_params = _where_clause(spec, ctx)
+    return fragment(sql + where_sql, params + where_params)
+
+
+def delete(node, ctx, *, opts: RenderOptions) -> dict:
+    spec = node["$delete"]
+    sql = f"DELETE FROM {_table_target(spec['from'], opts)}"
+    where_sql, where_params = _where_clause(spec, ctx)
+    return fragment(sql + where_sql, list(where_params))
+
+
+def build_sql_write_specials(opts: RenderOptions) -> dict:
+    """Build the ``{key: handler}`` mapping for the write SQL pipeline.
+
+    The write pipeline is a superset of the read pipeline: all ``SELECT``
+    constructs plus the DML statements, so subqueries / predicates / ``SET``
+    expressions resolve in the same pipeline.
+    """
+    specials = dict(build_sql_specials(opts))
+    specials["$insert"] = partial(insert, opts=opts)
+    specials["$update"] = partial(update, opts=opts)
+    specials["$delete"] = partial(delete, opts=opts)
+    return specials

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/src/j_perm_sql/handler.py

@@ -19,24 +19,35 @@ from __future__ import annotations
 from j_perm import ActionHandler, AsyncActionHandler
 
 from .dialect import RenderOptions
-from .render import SQL_PIPELINE_NAME, is_fragment
+from .render import ACTIVE_PIPELINE_KEY, SQL_PIPELINE_NAME, is_fragment
 
 
 class SqlRenderer:
-    """Render a SQL construct tree to ``(sql, params)`` for a target dialect."""
+    """Render a SQL construct tree to ``(sql, params)`` for a target dialect.
 
-    def __init__(self, opts: RenderOptions) -> None:
+    *pipeline_name* selects which isolated pipeline the tree (and all its
+    recursion) is dispatched through — the read-only ``"sql"`` pipeline by
+    default, or the write pipeline for ``op: sql_write``.
+    """
+
+    def __init__(self, opts: RenderOptions, pipeline_name: str = SQL_PIPELINE_NAME) -> None:
         self.opts = opts
+        self.pipeline_name = pipeline_name
 
     def render(self, query, ctx) -> tuple:
         # Render against a scratch dest so the real document is never clobbered,
         # but expose the real dest under _real_dest so @: pointers inside $val
-        # can still read the document being built.
+        # can still read the document being built.  The active pipeline name is
+        # threaded through metadata so recursion stays in this pipeline.
         render_ctx = ctx.copy(
             new_dest={},
-            new_metadata={**ctx.metadata, "_real_dest": ctx.dest},
+            new_metadata={
+                **ctx.metadata,
+                "_real_dest": ctx.dest,
+                ACTIVE_PIPELINE_KEY: self.pipeline_name,
+            },
         )
-        frag = ctx.engine.run_pipeline(SQL_PIPELINE_NAME, query, render_ctx).dest
+        frag = ctx.engine.run_pipeline(self.pipeline_name, query, render_ctx).dest
         if not is_fragment(frag):
             raise ValueError("top-level SQL query must be a SQL construct")
         return self.opts.finalize(frag["sql"], frag["params"])

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/src/j_perm_sql/install.py

@@ -12,14 +12,29 @@ from j_perm import ActionNode, OpMatcher
 
 from .dialect import RenderOptions
 from .handler import AsyncSqlHandler, SqlHandler, SqlRenderer
-from .pipeline import build_sql_pipeline
-from .render import SQL_PIPELINE_NAME
+from .pipeline import (
+    SQL_PIPELINE_NAME,
+    SQL_WRITE_PIPELINE_NAME,
+    build_sql_pipeline,
+    build_sql_write_pipeline,
+)
 
-__all__ = ["install_sql"]
+__all__ = ["install_sql", "install_sql_write"]
+
+
+def _register_op(engine, executor, renderer, op):
+    """Register an ``op`` handler, choosing sync/async by the executor."""
+    if asyncio.iscoroutinefunction(executor):
+        handler = AsyncSqlHandler(executor, renderer)
+    else:
+        handler = SqlHandler(executor, renderer)
+    engine.main_pipeline.registry.register(
+        ActionNode(name=op, priority=10, matcher=OpMatcher(op), handler=handler)
+    )
 
 
 def install_sql(engine, executor, *, paramstyle: str = "qmark", dialect=None, op: str = "sql"):
-    """Install SQL support into *engine*.
+    """Install read-only SQL (``SELECT``) support into *engine*.
 
     Args:
         engine:    a built ``j_perm`` engine (e.g. from ``build_default_engine``).
@@ -36,12 +51,31 @@ def install_sql(engine, executor, *, paramstyle: str = "qmark", dialect=None, op
     """
     opts = dialect if dialect is not None else RenderOptions(paramstyle=paramstyle)
     engine.register_pipeline(SQL_PIPELINE_NAME, build_sql_pipeline(opts))
-    renderer = SqlRenderer(opts)
-    if asyncio.iscoroutinefunction(executor):
-        handler = AsyncSqlHandler(executor, renderer)
-    else:
-        handler = SqlHandler(executor, renderer)
-    engine.main_pipeline.registry.register(
-        ActionNode(name=op, priority=10, matcher=OpMatcher(op), handler=handler)
-    )
+    _register_op(engine, executor, SqlRenderer(opts, SQL_PIPELINE_NAME), op)
+    return engine
+
+
+def install_sql_write(
+    engine, executor, *, paramstyle: str = "qmark", dialect=None, op: str = "sql_write"
+):
+    """Install write (DML) SQL support — ``INSERT`` / ``UPDATE`` / ``DELETE``.
+
+    This is a separate, opt-in install: it registers an isolated write pipeline
+    (read constructs + DML) and a distinct ``op`` so that ``op: sql`` — if also
+    installed — stays guaranteed read-only.  Independent of :func:`install_sql`
+    (either may be installed alone, in any order).
+
+    Args:
+        engine:    a built ``j_perm`` engine.
+        executor:  ``executor(sql, params) -> result`` (sync or coroutine).
+        paramstyle: placeholder style when *dialect* is not given.
+        dialect:   an explicit :class:`RenderOptions`; overrides *paramstyle*.
+        op:        the operation name to register (default ``"sql_write"``).
+
+    Returns:
+        The same *engine*, for chaining.
+    """
+    opts = dialect if dialect is not None else RenderOptions(paramstyle=paramstyle)
+    engine.register_pipeline(SQL_WRITE_PIPELINE_NAME, build_sql_write_pipeline(opts))
+    _register_op(engine, executor, SqlRenderer(opts, SQL_WRITE_PIPELINE_NAME), op)
     return engine

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/src/j_perm_sql/pipeline.py

@@ -17,16 +17,23 @@ from j_perm import (
 )
 
 from .constructs import build_sql_specials
+from .constructs_write import build_sql_write_specials
 from .dialect import RenderOptions
 from .render import SQL_PIPELINE_NAME
 
-__all__ = ["build_sql_pipeline", "SQL_PIPELINE_NAME"]
+#: Name the write (DML) SQL pipeline is registered under on the engine.
+SQL_WRITE_PIPELINE_NAME = "sql_write"
 
+__all__ = [
+    "build_sql_pipeline",
+    "build_sql_write_pipeline",
+    "SQL_PIPELINE_NAME",
+    "SQL_WRITE_PIPELINE_NAME",
+]
 
-def build_sql_pipeline(opts: RenderOptions | None = None) -> Pipeline:
-    """Build the isolated SQL pipeline for the given dialect options."""
-    opts = opts if opts is not None else RenderOptions()
-    specials = build_sql_specials(opts)
+
+def _build_pipeline(specials: dict) -> Pipeline:
+    """Assemble an isolated SQL pipeline from a ``{key: handler}`` mapping."""
     registry = ActionTypeRegistry()
     registry.register(
         ActionNode(
@@ -45,3 +52,15 @@ def build_sql_pipeline(opts: RenderOptions | None = None) -> Pipeline:
         )
     )
     return Pipeline(registry=registry, track_execution=True)
+
+
+def build_sql_pipeline(opts: RenderOptions | None = None) -> Pipeline:
+    """Build the isolated read-only SQL pipeline for the given dialect options."""
+    opts = opts if opts is not None else RenderOptions()
+    return _build_pipeline(build_sql_specials(opts))
+
+
+def build_sql_write_pipeline(opts: RenderOptions | None = None) -> Pipeline:
+    """Build the isolated write (DML) SQL pipeline (read constructs + DML)."""
+    opts = opts if opts is not None else RenderOptions()
+    return _build_pipeline(build_sql_write_specials(opts))

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/src/j_perm_sql/render.py

@@ -19,9 +19,15 @@ from typing import Any
 
 from .dialect import PLACEHOLDER, RenderOptions
 
-#: Name the SQL value-pipeline is registered under on the engine.
+#: Name the read-only SQL value-pipeline is registered under on the engine.
 SQL_PIPELINE_NAME = "sql"
 
+#: Metadata key carrying the name of the pipeline that recursion should dispatch
+#: through.  Set by :class:`~j_perm_sql.handler.SqlRenderer` so a write
+#: statement's sub-parts resolve in the write pipeline; defaults to the read
+#: pipeline when absent.
+ACTIVE_PIPELINE_KEY = "_sql_pipeline"
+
 #: Keys whose presence marks a node as a *query* (must be parenthesised when
 #: used as an operand, subquery, or derived table).
 _QUERY_KEYS = frozenset(
@@ -45,8 +51,14 @@ def is_query(node: Any) -> bool:
 
 
 def render(node: Any, ctx) -> Any:
-    """Dispatch *node* through the isolated SQL pipeline and return the result."""
-    return ctx.engine.run_pipeline(SQL_PIPELINE_NAME, node, ctx).dest
+    """Dispatch *node* through the active SQL pipeline and return the result.
+
+    The active pipeline name is read from ``ctx.metadata`` (set by the renderer)
+    so recursion stays within the same pipeline the top-level operation chose;
+    it defaults to the read-only :data:`SQL_PIPELINE_NAME`.
+    """
+    name = ctx.metadata.get(ACTIVE_PIPELINE_KEY, SQL_PIPELINE_NAME)
+    return ctx.engine.run_pipeline(name, node, ctx).dest
 
 
 def render_construct(node: Any, ctx) -> dict:

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/src/j_perm_sql.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: j-perm-sql
-Version: 0.1.0
+Version: 0.2.0
 Summary: j-perm plugin for SQL
 Author-email: Roman <kuschanow@gmail.com>
 License: MIT
@@ -15,18 +15,23 @@ Requires-Dist: j-perm>=1.9.0
 # j-perm-sql
 
 A [j-perm](https://github.com/kuschanow/j-perm) plugin that builds and executes
-**SQL `SELECT` queries** from j-perm constructs.
+**SQL queries** from j-perm constructs.
 
 * SQL is described with a tree of `$`-constructs (`$select`, `$col`, `$val`,
   predicates, joins, …).
-* A single new top-level operation — `op: sql` — renders that tree to a
-  **parameterized** `(sql, params)` pair and hands it to a configurable
-  executor (any ORM's raw-execute function).
-* The SQL constructs live in an **isolated** named pipeline: they mean nothing
-  outside `op: sql`. `{"$select": …}` used as an ordinary value is just a dict.
-
-> v1 scope: the full standard **`SELECT`** surface (read-only). DDL/DML
-> (`CREATE`/`ALTER`/`INSERT`/`UPDATE`/`DELETE`) is intentionally out of scope.
+* A top-level operation renders that tree to a **parameterized** `(sql, params)`
+  pair and hands it to a configurable executor (any ORM's raw-execute function):
+  `op: sql` for read-only `SELECT`, and (opt-in) `op: sql_write` for
+  `INSERT`/`UPDATE`/`DELETE`.
+* The SQL constructs live in **isolated** named pipelines: they mean nothing
+  outside those operations. `{"$select": …}` used as an ordinary value is just a
+  dict.
+
+> Scope: the full standard **`SELECT`** surface (read-only) via `install_sql`,
+> plus standard **`INSERT`/`UPDATE`/`DELETE`** (row content only) via
+> `install_sql_write`. Schema DDL (`CREATE`/`ALTER`/`DROP` of tables/columns)
+> and non-universal DML (`RETURNING`, `ON CONFLICT`/upsert, `UPDATE … FROM`,
+> `DELETE … USING`) are intentionally out of scope.
 
 ## Install
 
@@ -78,12 +83,79 @@ plugins.
 * `to` — optional destination pointer (template-expanded); the executor's
   result is written there. If omitted, the result is discarded.
 
+## Writing data (`INSERT`/`UPDATE`/`DELETE`)
+
+Writing is a **separate, opt-in install** — you don't get it unless you ask for
+it, and `op: sql` stays guaranteed read-only even when both are installed:
+
+```python
+from j_perm_sql import install_sql, install_sql_write
+
+install_sql(engine, run_sql)          # read-only  op: sql      (optional)
+install_sql_write(engine, run_sql)    # write      op: sql_write
+```
+
+`install_sql_write(engine, executor, *, paramstyle="qmark", dialect=None,
+op="sql_write")` registers an isolated **write pipeline** (the full `SELECT`
+surface *plus* the DML statements, so `WHERE` predicates, `SET` expressions and
+`INSERT … SELECT` subqueries all work) and the `op: sql_write` operation. It is
+independent of `install_sql` — either may be installed alone, in any order. It
+selects the sync/async handler the same way (by `asyncio.iscoroutinefunction`).
+
+```js
+{"op": "sql_write", "query": <DML construct tree>, "to": "/dest/path"}
+```
+
+**`$insert`** — exactly one of `values` / `query`:
+
+```python
+{"$insert": {
+  "into": "users",                    # or {"table": "users", "schema": "app"}
+  "columns": ["name", "age"],         # optional
+  "values": [[{"$val": "Ann"}, {"$val": 30}], ...],   # cells are operands ($val to bind)
+  # ── OR ──
+  "query": {"$select": {...}},        # INSERT … SELECT
+}}
+# → INSERT INTO "users" ("name", "age") VALUES (?, ?)   params=["Ann", 30]
+```
+
+**`$update`** — single table:
+
+```python
+{"$update": {
+  "table": "users",                   # or {"table": "users", "schema": "app"}
+  "set": {"name": {"$val": "Bob"},
+          "visits": {"$add": [{"$col": "visits"}, {"$val": 1}]}},
+  "where": {"$eq": [{"$col": "id"}, {"$val": 5}]},      # or "all": true
+}}
+# → UPDATE "users" SET "name" = ?, "visits" = ("visits" + ?) WHERE "id" = ?
+```
+
+**`$delete`** — single table:
+
+```python
+{"$delete": {
+  "from": "sessions",                 # or {"table": "sessions", "schema": "app"}
+  "where": {"$lt": [{"$col": "last_seen"}, {"$val": "2020-01-01"}]},  # or "all": true
+}}
+# → DELETE FROM "sessions" WHERE "last_seen" < ?
+```
+
+`set` values, `$insert` cells, and `where` predicates are ordinary read
+constructs, so the full expression/predicate/subquery surface (including
+correlated subqueries) is available, and data is always bound as parameters.
+
+> **WHERE guard.** A `$update` / `$delete` **without** a `where` raises unless
+> you pass an explicit `"all": true`. This prevents an accidental full-table
+> update/delete.
+
 ## Parameterization & injection safety
 
 Data values are **always bound as parameters**, never interpolated:
 
-* `$val` (and the data sides of `$in`, `$between`, `$values`) emit a placeholder
-  and add the value to `params`.
+* `$val` (and the data sides of `$in`, `$between`, `$values`, `$update`'s `set`
+  values, and `$insert`'s row cells) emit a placeholder and add the value to
+  `params`.
 * Identifiers (table/column/alias names) are validated against a conservative
   charset and quoted.
 * Function names, CAST types, join types, sort directions, etc. are validated
@@ -94,8 +166,14 @@ Data values are **always bound as parameters**, never interpolated:
 # → '"name" = ?'   with the (possibly malicious) value safely in params
 ```
 
-Inside `$val`, the value expression is resolved with j-perm's normal value
-pipeline, so `$ref`, `${…}` templates, and `@:` dest-pointers all work.
+**Parameters come from inside j-perm — no external param source.** Inside `$val`
+the value expression is resolved with j-perm's normal value pipeline, so `$ref`,
+`${…}` templates, and `@:` dest-pointers all work. The `params` list handed to
+the executor is simply the values j-perm itself computed from the document; the
+parameter binding exists only for injection safety and the driver's paramstyle.
+The whole flow (source → SQL → bound values) is self-contained in one j-perm
+run; the executor is just the pipe to the driver. This applies equally to read
+(`op: sql`) and write (`op: sql_write`).
 
 ## Dialect / `RenderOptions`
 
@@ -114,9 +192,9 @@ install_sql(engine, run_sql, dialect=RenderOptions(
 
 ## Sync & async
 
-`install_sql` inspects the executor: a coroutine function registers the async
-handler (use with `engine.apply_async`); a regular function registers the sync
-handler (use with `engine.apply`).
+Both `install_sql` and `install_sql_write` inspect the executor: a coroutine
+function registers the async handler (use with `engine.apply_async`); a regular
+function registers the sync handler (use with `engine.apply`).
 
 ```python
 async def run_sql(sql, params): ...
@@ -134,6 +212,14 @@ await engine.apply_async(spec, source=…, dest=…)
 | `$union` / `$union_all` / `$intersect` / `$except` | `{"$union": [q1, q2, …], order_by?, limit?…}` |
 | `$values` | `{"$values": [[…row…], …]}` (table source or `IN`) |
 
+**Write (DML)** — only via `install_sql_write` / `op: sql_write`
+
+| Construct | Form |
+|---|---|
+| `$insert` | `{into, columns?, values \| query}` (exactly one of `values`/`query`) |
+| `$update` | `{table, set: {col: operand}, where? \| "all": true}` |
+| `$delete` | `{from, where? \| "all": true}` |
+
 **Projection / expressions**
 
 | Construct | Renders |

{j_perm_sql-0.1.0 → j_perm_sql-0.2.0}/src/j_perm_sql.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 src/j_perm_sql/__init__.py
 src/j_perm_sql/constructs.py
+src/j_perm_sql/constructs_write.py
 src/j_perm_sql/dialect.py
 src/j_perm_sql/handler.py
 src/j_perm_sql/install.py