sql_querystring_builder 0.2.0__tar.gz → 0.4.0__tar.gz

{sql_querystring_builder-0.2.0/src/sql_querystring_builder.egg-info → sql_querystring_builder-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql_querystring_builder
-Version: 0.2.0
+Version: 0.4.0
 Summary: Wraps string building of MS SQL queries
 Author-email: Wael GRIBAA <g.wael@outlook.fr>
 License-Expression: GPL-3.0-only
@@ -30,24 +30,27 @@ It provides first level validation.
     - [x] Field
     - [x] Function on field
     - [x] String
+    - [x] Conditions: eq, ne, lt, le, gt, ge, like, in_, between, is_null, is_not_null, combined with & | ~
+    - [x] Values: text, numbers, booleans, None, dates and times, bytes, UUIDs, and Raw SQL
 2. Using:
     - [x] Select (with DISTINCT and TOP)
-    - [x] Update
+    - [x] Update (with typed values)
+    - [x] Insert (multi-row VALUES)
+    - [x] Delete (with joins; refused without a WHERE unless asked)
     - [x] From
-    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin, CrossJoin
-    - [x] Where
+    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin (on two fields or on any condition), CrossJoin
+    - [x] Where (with conditions)
     - [x] OrderBy (with OFFSET/FETCH paging)
 3. Handling automatically:
     - [x] Table aliases
     - [x] Field aliases
+    - [x] Escaped values: 'O''Brien', N'café'
+    - [x] Parameterized queries: build_with_params() writes ? (pyodbc) or %s (pymssql) and returns the values
 
 ## Not implemented (yet)
 In planned order:
-- [ ] Proper conditions: typed values, AND/OR/NOT, IN, BETWEEN, LIKE, IS NULL
-- [ ] Insert and Delete
 - [ ] Functions (aggregates and others), GROUP BY, HAVING, CASE
 - [ ] Compound queries (UNION, INTERSECT, EXCEPT) and sub-queries
-- [ ] Parameterized queries
 
 ## What it does not do
     Connect to a database server and run the queries by itself.
@@ -72,8 +75,8 @@ atemptable = select.to_temptable("a_temp_table")
 innerjoin = InnerJoin(accounts_table, accounts_table.fields.customerId, customers_table)
 # Defines an Order By a defined field
 orderby = OrderBy(customers_table.fields.customerId, descending=True)
-# Adds a Where filter
-where = Where(accounts_table.fields.accountId, "> 20000 AND", customers_table.fields.customerId, "LIKE 'A1C%'")
+# Adds a Where filter: conditions are methods of fields, combined with & (and_), | (or_) and ~ (not_)
+where = Where(accounts_table.fields.accountId.gt(20000) & customers_table.fields.customerId.like("A1C%"))
 ```
 2. Inspect what those elements are made of:
 ```
@@ -117,6 +120,38 @@ print(QueryBuilder(
 # > SELECT #a_temp_table.id, #a_temp_table.cid, #a_temp_table.mainPhone, #a_temp_table.accountId
 # > FROM #a_temp_table
 ```
+5. Send the values as parameters, so that they never enter the SQL text:
+```
+# Builds the same query with a placeholder for each value, and returns the values in order
+sql, params = query_builder.build_with_params()
+print(sql)
+# > SELECT Customers.id, Customers.customerId AS cid, Customers.mainPhone, acc.accountId
+# > INTO #a_temp_table
+# > FROM Customers
+# > INNER JOIN Accounts acc on acc.customerId = Customers.customerId
+# > WHERE acc.accountId > ? AND Customers.customerId LIKE ?
+# > ORDER BY cid DESC
+print(params)
+# > (20000, 'A1C%')
+# With pyodbc: cursor.execute(sql, params). For pymssql, build_with_params("format") writes %s instead.
+```
+6. Insert and delete rows:
+```
+# Inserts rows: one tuple per row, with the values in column order
+insert = Insert(customers_table.fields.customerId, customers_table.fields.mainPhone).values(
+    ("A1C42", "555-0100"), ("B7", None)
+)
+print(QueryBuilder(insert).build())
+# > INSERT INTO Customers (customerId, mainPhone)
+# > VALUES ('A1C42', '555-0100'), ('B7', NULL)
+
+# Deletes the accounts of customer B7; a DELETE needs a WHERE, unless built with where_required=False
+delete = QueryBuilder(Delete(accounts_table), From(accounts_table), Where(accounts_table.fields.customerId.eq("B7")))
+print(delete.build())
+# > DELETE acc
+# > FROM Accounts acc
+# > WHERE acc.customerId = 'B7'
+```
 
 (Find it directly in the module example.py)
 
@@ -127,6 +162,44 @@ Python 3.10 and above.
 (None)
 
 ## Changelog
+### 0.4.0
+Queries built with 0.3.0 produce the same SQL.
+- `Insert(*columns).values(*rows)` renders `INSERT INTO Customers (id, name)` and
+  `VALUES (1, 'Ann'), (2, 'O''Brien')`. The columns are fields of one table, or a whole table. Each row is a
+  tuple of values in column order, with at most 1000 rows per INSERT, as in T-SQL. Values are escaped as in
+  conditions, plain strings included, and `Raw("DEFAULT")` writes SQL. An Insert stands alone in its query.
+- `Delete(table)` renders `DELETE` and the table's alias, or its name, and works with `From`, joins and
+  `Where`: `DELETE acc FROM Accounts acc INNER JOIN ...`. A query with a DELETE but no WHERE raises
+  `IncompatibleClausesException`, unless written `Delete(table, where_required=False)`; so does a DELETE with
+  ORDER BY.
+- Both work with `build_with_params()`. SQL Server accepts about 2,100 parameters per query, so split big
+  parameterized inserts.
+
+### 0.3.0
+Queries built with 0.2.0 produce the same SQL, except for the fixed `Update` values below.
+- Conditions are methods of fields, functions on fields and strings: `eq`, `ne`, `lt`, `le`, `gt`, `ge`,
+  `like`, `in_`, `between`, `is_null` and `is_not_null`; `eq(None)` renders `IS NULL`. Combine them with
+  `&`, `|` and `~`, or with `and_()`, `or_()` and `not_()`; parentheses are added where T-SQL needs them.
+  Python's `and`, `or` and `not` raise `TypeError`, since `c1 and c2` would silently keep only `c2`.
+- Values are escaped: text becomes `'O''Brien'`, or `N'café'` when it is not ASCII (`NStr("...")` forces
+  `N'...'`). Numbers, `True`/`False` (1/0), `None` (`NULL`), dates (`'20261011'`), datetimes and times
+  (ISO), bytes (`0x...`) and UUIDs are supported; `Raw("GETDATE()")` is written verbatim.
+- `Where(condition)`, also next to raw strings, and `on=condition` on every join, for multi-column joins.
+- `QueryBuilder.build_with_params()` returns the SQL with `?` placeholders and the values, for
+  `cursor.execute(sql, params)` with pyodbc; `build_with_params("format")` writes `%s` for pymssql.
+- `Update` values: a plain string is still raw SQL (`{f: "'x'"}`), `Str("O'Brien")` is an escaped string,
+  and other values render as in conditions.
+- New top-level names: `Condition`, `Raw`, `Str` and `NStr`.
+
+Fixed:
+- `Update` values `None`, `True`/`False`, dates and fields rendered invalid or wrong SQL: `f=None`,
+  `f=True`, `f=2026-10-11` (a subtraction) or the field's description. They now render `NULL`, `1`/`0`,
+  `'20261011'` and the field's qualified name. A `Decimal` with an exponent is written in full (`1000`, not
+  `1E+3`, which T-SQL reads as a float).
+
+Breaking:
+- `Update` values of an unsupported type raise `TypeError` instead of being written with `str()`.
+
 ### 0.2.0
 Queries built with 0.1.x produce the same SQL; see "Breaking" for the few behavior changes.
 - `LeftJoin`, `RightJoin` and `FullJoin` (same arguments as `InnerJoin`), and `CrossJoin(table)`.

{sql_querystring_builder-0.2.0 → sql_querystring_builder-0.4.0}/README.md

@@ -9,24 +9,27 @@ It provides first level validation.
     - [x] Field
     - [x] Function on field
     - [x] String
+    - [x] Conditions: eq, ne, lt, le, gt, ge, like, in_, between, is_null, is_not_null, combined with & | ~
+    - [x] Values: text, numbers, booleans, None, dates and times, bytes, UUIDs, and Raw SQL
 2. Using:
     - [x] Select (with DISTINCT and TOP)
-    - [x] Update
+    - [x] Update (with typed values)
+    - [x] Insert (multi-row VALUES)
+    - [x] Delete (with joins; refused without a WHERE unless asked)
     - [x] From
-    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin, CrossJoin
-    - [x] Where
+    - [x] InnerJoin, LeftJoin, RightJoin, FullJoin (on two fields or on any condition), CrossJoin
+    - [x] Where (with conditions)
     - [x] OrderBy (with OFFSET/FETCH paging)
 3. Handling automatically:
     - [x] Table aliases
     - [x] Field aliases
+    - [x] Escaped values: 'O''Brien', N'café'
+    - [x] Parameterized queries: build_with_params() writes ? (pyodbc) or %s (pymssql) and returns the values
 
 ## Not implemented (yet)
 In planned order:
-- [ ] Proper conditions: typed values, AND/OR/NOT, IN, BETWEEN, LIKE, IS NULL
-- [ ] Insert and Delete
 - [ ] Functions (aggregates and others), GROUP BY, HAVING, CASE
 - [ ] Compound queries (UNION, INTERSECT, EXCEPT) and sub-queries
-- [ ] Parameterized queries
 
 ## What it does not do
     Connect to a database server and run the queries by itself.
@@ -51,8 +54,8 @@ atemptable = select.to_temptable("a_temp_table")
 innerjoin = InnerJoin(accounts_table, accounts_table.fields.customerId, customers_table)
 # Defines an Order By a defined field
 orderby = OrderBy(customers_table.fields.customerId, descending=True)
-# Adds a Where filter
-where = Where(accounts_table.fields.accountId, "> 20000 AND", customers_table.fields.customerId, "LIKE 'A1C%'")
+# Adds a Where filter: conditions are methods of fields, combined with & (and_), | (or_) and ~ (not_)
+where = Where(accounts_table.fields.accountId.gt(20000) & customers_table.fields.customerId.like("A1C%"))
 ```
 2. Inspect what those elements are made of:
 ```
@@ -96,6 +99,38 @@ print(QueryBuilder(
 # > SELECT #a_temp_table.id, #a_temp_table.cid, #a_temp_table.mainPhone, #a_temp_table.accountId
 # > FROM #a_temp_table
 ```
+5. Send the values as parameters, so that they never enter the SQL text:
+```
+# Builds the same query with a placeholder for each value, and returns the values in order
+sql, params = query_builder.build_with_params()
+print(sql)
+# > SELECT Customers.id, Customers.customerId AS cid, Customers.mainPhone, acc.accountId
+# > INTO #a_temp_table
+# > FROM Customers
+# > INNER JOIN Accounts acc on acc.customerId = Customers.customerId
+# > WHERE acc.accountId > ? AND Customers.customerId LIKE ?
+# > ORDER BY cid DESC
+print(params)
+# > (20000, 'A1C%')
+# With pyodbc: cursor.execute(sql, params). For pymssql, build_with_params("format") writes %s instead.
+```
+6. Insert and delete rows:
+```
+# Inserts rows: one tuple per row, with the values in column order
+insert = Insert(customers_table.fields.customerId, customers_table.fields.mainPhone).values(
+    ("A1C42", "555-0100"), ("B7", None)
+)
+print(QueryBuilder(insert).build())
+# > INSERT INTO Customers (customerId, mainPhone)
+# > VALUES ('A1C42', '555-0100'), ('B7', NULL)
+
+# Deletes the accounts of customer B7; a DELETE needs a WHERE, unless built with where_required=False
+delete = QueryBuilder(Delete(accounts_table), From(accounts_table), Where(accounts_table.fields.customerId.eq("B7")))
+print(delete.build())
+# > DELETE acc
+# > FROM Accounts acc
+# > WHERE acc.customerId = 'B7'
+```
 
 (Find it directly in the module example.py)
 
@@ -106,6 +141,44 @@ Python 3.10 and above.
 (None)
 
 ## Changelog
+### 0.4.0
+Queries built with 0.3.0 produce the same SQL.
+- `Insert(*columns).values(*rows)` renders `INSERT INTO Customers (id, name)` and
+  `VALUES (1, 'Ann'), (2, 'O''Brien')`. The columns are fields of one table, or a whole table. Each row is a
+  tuple of values in column order, with at most 1000 rows per INSERT, as in T-SQL. Values are escaped as in
+  conditions, plain strings included, and `Raw("DEFAULT")` writes SQL. An Insert stands alone in its query.
+- `Delete(table)` renders `DELETE` and the table's alias, or its name, and works with `From`, joins and
+  `Where`: `DELETE acc FROM Accounts acc INNER JOIN ...`. A query with a DELETE but no WHERE raises
+  `IncompatibleClausesException`, unless written `Delete(table, where_required=False)`; so does a DELETE with
+  ORDER BY.
+- Both work with `build_with_params()`. SQL Server accepts about 2,100 parameters per query, so split big
+  parameterized inserts.
+
+### 0.3.0
+Queries built with 0.2.0 produce the same SQL, except for the fixed `Update` values below.
+- Conditions are methods of fields, functions on fields and strings: `eq`, `ne`, `lt`, `le`, `gt`, `ge`,
+  `like`, `in_`, `between`, `is_null` and `is_not_null`; `eq(None)` renders `IS NULL`. Combine them with
+  `&`, `|` and `~`, or with `and_()`, `or_()` and `not_()`; parentheses are added where T-SQL needs them.
+  Python's `and`, `or` and `not` raise `TypeError`, since `c1 and c2` would silently keep only `c2`.
+- Values are escaped: text becomes `'O''Brien'`, or `N'café'` when it is not ASCII (`NStr("...")` forces
+  `N'...'`). Numbers, `True`/`False` (1/0), `None` (`NULL`), dates (`'20261011'`), datetimes and times
+  (ISO), bytes (`0x...`) and UUIDs are supported; `Raw("GETDATE()")` is written verbatim.
+- `Where(condition)`, also next to raw strings, and `on=condition` on every join, for multi-column joins.
+- `QueryBuilder.build_with_params()` returns the SQL with `?` placeholders and the values, for
+  `cursor.execute(sql, params)` with pyodbc; `build_with_params("format")` writes `%s` for pymssql.
+- `Update` values: a plain string is still raw SQL (`{f: "'x'"}`), `Str("O'Brien")` is an escaped string,
+  and other values render as in conditions.
+- New top-level names: `Condition`, `Raw`, `Str` and `NStr`.
+
+Fixed:
+- `Update` values `None`, `True`/`False`, dates and fields rendered invalid or wrong SQL: `f=None`,
+  `f=True`, `f=2026-10-11` (a subtraction) or the field's description. They now render `NULL`, `1`/`0`,
+  `'20261011'` and the field's qualified name. A `Decimal` with an exponent is written in full (`1000`, not
+  `1E+3`, which T-SQL reads as a float).
+
+Breaking:
+- `Update` values of an unsupported type raise `TypeError` instead of being written with `str()`.
+
 ### 0.2.0
 Queries built with 0.1.x produce the same SQL; see "Breaking" for the few behavior changes.
 - `LeftJoin`, `RightJoin` and `FullJoin` (same arguments as `InnerJoin`), and `CrossJoin(table)`.

{sql_querystring_builder-0.2.0 → sql_querystring_builder-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sql_querystring_builder"
-version = "0.2.0"
+version = "0.4.0"
 authors = [
   { name="Wael GRIBAA", email="g.wael@outlook.fr" },
 ]

{sql_querystring_builder-0.2.0 → sql_querystring_builder-0.4.0}/src/sql_querystring_builder/__init__.py

@@ -1,9 +1,11 @@
 from .clauses import (
     CrossJoin,
+    Delete,
     From,
     FullJoin,
     IncorrectUpdateException,
     InnerJoin,
+    Insert,
     LeftJoin,
     OrderBy,
     RightJoin,
@@ -11,6 +13,7 @@ from .clauses import (
     Update,
     Where,
 )
+from .conditions import Condition
 from .exceptions import SqlQueryBuilderError
 from .query_builder import IncompatibleClausesException, QueryBuilder, UnavailablePlaceException
 from .tables import (
@@ -26,3 +29,4 @@ from .tables import (
     TableException,
     TempTable,
 )
+from .values import NStr, Raw, Str

sql_querystring_builder-0.4.0/src/sql_querystring_builder/clauses.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from .abstract_clause import Clause
+from .conditions import Comparable, Condition, Junction, check_operand, render_operand
+from .exceptions import SqlQueryBuilderError
+from .tables import Aliasable, Field, Fields, Table, TempTable
+from .values import render_value
+
+
+class IncorrectUpdateException(SqlQueryBuilderError):
+    pass
+
+
+def _insert_value(value: object) -> object:
+    # VALUES cannot read columns: unlike in a condition, a field or expression is no value here.
+    if isinstance(value, Comparable):
+        raise TypeError(f"Unsupported value type: {type(value).__name__}.")
+    return check_operand(value)
+
+
+def _row_count(keyword: str, value: int, minimum: int) -> int:
+    """Validates a row count for TOP, OFFSET or FETCH."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{keyword} must be an int, got {type(value).__name__}.")
+    if value < minimum:
+        expected: str = "zero or more" if minimum == 0 else f"at least {minimum}"
+        raise ValueError(f"{keyword} must be {expected}, got {value}.")
+    return value
+
+
+class Select(Clause):
+    def __init__(self, *fields: Fields | Aliasable | Table, distinct: bool = False, top: int | None = None) -> None:
+        if top is not None:
+            _row_count("TOP", top, minimum=0)
+        self.fields: list[Aliasable] = []
+        for el in fields:
+            if isinstance(el, Fields):
+                self.fields.extend(el.as_list())
+            elif isinstance(el, Table):
+                self.fields.extend(el.fields.as_list())
+            else:
+                self.fields.append(el)
+        self.distinct: bool = distinct
+        self.top: int | None = top
+        self.temp_table: TempTable | None = None
+
+    @property
+    def place(self) -> int:
+        return 0
+
+    def build(self) -> str:
+        head: str = "SELECT"
+        if self.distinct:
+            head += " DISTINCT"
+        if self.top is not None:
+            head += f" TOP ({self.top})"
+        ret: str = f"{head} " + (", ".join([field.build(True, True) for field in self.fields]) if self.fields else "*")
+        if self.temp_table is not None:
+            ret += "\nINTO " + self.temp_table.build()
+        return ret
+
+    def to_temptable(self, name: str) -> TempTable:
+        self.temp_table = TempTable(name, *self.fields)
+        return self.temp_table
+
+    def __repr__(self) -> str:
+        options: str = (", distinct=True" if self.distinct else "") + (
+            f", top={self.top}" if self.top is not None else ""
+        )
+        return f"{self.__class__.__name__}(fields={self.fields}{options})"
+
+
+class From(Clause):
+    def __init__(self, table: Table) -> None:
+        self.table: Table = table
+
+    @property
+    def place(self) -> int:
+        return 2
+
+    def build(self) -> str:
+        return f"FROM {self.table.build(True)}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(table={self.table})"
+
+
+class Where(Clause):
+    """`WHERE` and its parts, joined by spaces: conditions, fields, and strings written as raw SQL."""
+
+    def __init__(self, *conditions: str | Aliasable | Condition) -> None:
+        self.conditions: tuple[str | Aliasable | Condition, ...] = conditions
+
+    @property
+    def place(self) -> int:
+        return 4
+
+    def build(self) -> str:
+        ret: list[str] = ["WHERE"]
+        for condition in self.conditions:
+            if isinstance(condition, Condition):
+                sql: str = condition.build()
+                # Next to raw strings, an AND or OR condition keeps its meaning only in parentheses.
+                ret.append(f"({sql})" if isinstance(condition, Junction) and len(self.conditions) > 1 else sql)
+            else:
+                ret.append(condition.build() if isinstance(condition, Aliasable) else condition)
+        return " ".join(ret)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(conditions={self.conditions})"
+
+
+class Join(Clause):
+    """A join on `on_left = on_right`, or on any condition given as `on`; each subclass only sets its `keyword`."""
+
+    keyword: str
+
+    def __init__(
+        self,
+        table: Table,
+        on_left: Field | None = None,
+        on_right: Field | Table | None = None,
+        *,
+        on: Condition | None = None,
+    ) -> None:
+        if on is None:
+            if on_left is None or on_right is None:
+                raise TypeError(f"{self.__class__.__name__} needs on_left and on_right, or on.")
+            on_right = on_right if isinstance(on_right, Aliasable) else on_right.fields[on_left.name]
+            on = on_left.eq(on_right)
+        elif on_left is not None or on_right is not None:
+            raise TypeError(f"{self.__class__.__name__} takes on_left and on_right, or on, not both.")
+        elif not isinstance(on, Condition):
+            raise TypeError(f"on must be a Condition, got {type(on).__name__}.")
+        self.table: Table = table
+        self.on_left: Field | None = on_left
+        self.on_right: Field | None = on_right
+        self.on: Condition = on
+
+    @property
+    def place(self) -> int:
+        return 3
+
+    @property
+    def is_exclusive(self) -> bool:
+        return False
+
+    def build(self) -> str:
+        return f"{self.keyword} {self.table.build(use_name=True)} on {self.on.build()}"
+
+    def __repr__(self) -> str:
+        if self.on_left is None:
+            return f"{self.__class__.__name__}(table={self.table}, on={self.on})"
+        return f"{self.__class__.__name__}(table={self.table}, on_left={self.on_left}, on_right={self.on_right})"
+
+
+class InnerJoin(Join):
+    keyword = "INNER JOIN"
+
+
+class LeftJoin(Join):
+    keyword = "LEFT JOIN"
+
+
+class RightJoin(Join):
+    keyword = "RIGHT JOIN"
+
+
+class FullJoin(Join):
+    keyword = "FULL JOIN"
+
+
+class CrossJoin(Clause):
+    def __init__(self, table: Table) -> None:
+        self.table: Table = table
+
+    @property
+    def place(self) -> int:
+        return 3
+
+    @property
+    def is_exclusive(self) -> bool:
+        return False
+
+    def build(self) -> str:
+        return f"CROSS JOIN {self.table.build(use_name=True)}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(table={self.table})"
+
+
+class Update(Clause):
+    """`UPDATE … SET field=value, …`: a plain str value is raw SQL (`"'x'"`), `Str("x")` an escaped string.
+
+    Any other value goes through `values.py`, like a value in a condition: `None` is `NULL`, a field is its
+    qualified name.
+    """
+
+    def __init__(self, updates: Mapping[Field, object]) -> None:
+        if not updates:
+            raise IncorrectUpdateException("The Update is empty.")
+        self.updates: dict[Field, object] = {}
+        first_table: Table | None = None
+        for field, value in updates.items():
+            if first_table is None:
+                first_table = field.table
+            elif (first_table.name, first_table.alias) != (field.table.name, field.table.alias):
+                # The same name under another alias is still another table in the query: show the aliases.
+                same_name: bool = first_table.name == field.table.name
+                first: str = first_table.build(use_name=True) if same_name else first_table.name
+                other: str = field.table.build(use_name=True) if same_name else field.table.name
+                raise IncorrectUpdateException(
+                    f"Two different tables cannot be updated in the same Update: '{first}' and '{other}'."
+                )
+            self.updates[field] = value if isinstance(value, str) else check_operand(value)
+        self.table: Table = field.table
+
+    @property
+    def place(self) -> int:
+        return 0
+
+    def build(self) -> str:
+        # A plain str stays raw SQL until 1.0 (D4 in ROADMAP.md): turning it into a value would quote it.
+        field_strings: list[str] = [
+            f"{field.build()}={value if isinstance(value, str) else render_operand(value)}"
+            for field, value in self.updates.items()
+        ]
+        return f"UPDATE {self.table.build(use_name=False, use_alias=True)}\nSET " + ", ".join(field_strings)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(updates={self.updates})"
+
+
+class Insert(Clause):
+    """`INSERT INTO table (columns)` and `VALUES (…), (…)`, with the rows added by `values()`.
+
+    The columns are fields of one table, or whole tables, as `Select` takes them. Unlike in `Update`, a plain
+    str is a value here. An Insert stands alone in its query (see `QueryBuilder.build()`).
+    """
+
+    def __init__(self, *columns: Field | Table) -> None:
+        tables: list[Table] = []
+        self.columns: list[Field] = []
+        for column in columns:
+            if isinstance(column, Table):
+                tables.append(column)
+                self.columns.extend(column.fields.as_list())
+            elif isinstance(column, Field):
+                tables.append(column.table)
+                self.columns.append(column)
+            else:
+                raise TypeError(f"Insert takes fields or tables, got {type(column).__name__}.")
+        if not self.columns:
+            raise ValueError("Insert needs at least one column.")
+        for table in tables[1:]:
+            if table.name != tables[0].name:
+                raise ValueError(f"Insert columns must come from one table, got '{tables[0].name}' and '{table.name}'.")
+        names: set[str] = set()
+        for column in self.columns:
+            if column.name in names:
+                raise ValueError(f"Insert column '{column.name}' appears twice.")
+            names.add(column.name)
+        self.table: Table = tables[0]
+        self.rows: list[tuple[object, ...]] = []
+
+    @property
+    def place(self) -> int:
+        return 0
+
+    def values(self, *rows: Sequence[object]) -> Insert:
+        """Adds rows, each a tuple or list of values in column order, and returns the Insert."""
+        if len(self.rows) + len(rows) > 1000:
+            raise ValueError(f"An INSERT takes at most 1000 rows, got {len(self.rows) + len(rows)}.")
+        checked: list[tuple[object, ...]] = []
+        expected: str = f"{len(self.columns)} value{'s' if len(self.columns) > 1 else ''}"
+        for number, row in enumerate(rows, start=len(self.rows) + 1):
+            if isinstance(row, (str, bytes)) or not isinstance(row, Sequence):
+                raise TypeError(f"An Insert row must be a tuple or list of values, got {type(row).__name__}.")
+            if len(row) != len(self.columns):
+                raise ValueError(f"Insert row {number} needs {expected}, got {len(row)}.")
+            checked.append(tuple(_insert_value(value) for value in row))
+        self.rows.extend(checked)
+        return self
+
+    def build(self) -> str:
+        if not self.rows:
+            raise ValueError("The Insert has no rows: add them with values().")
+        # T-SQL refuses an alias after INSERT INTO, and qualified column names.
+        columns: str = ", ".join(column.name for column in self.columns)
+        rows: str = ", ".join(f"({', '.join(render_value(value) for value in row)})" for row in self.rows)
+        return f"INSERT INTO {self.table.name} ({columns})\nVALUES {rows}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(columns={self.columns}, rows={len(self.rows)})"
+
+
+class Delete(Clause):
+    """`DELETE` and the table's alias, or its name; T-SQL reads an alias from `From(table)`, as for `Update`.
+
+    A query with a Delete needs a Where unless `where_required=False`: an empty filter would delete every row.
+    """
+
+    def __init__(self, table: Table, *, where_required: bool = True) -> None:
+        if not isinstance(table, Table):
+            raise TypeError(f"Delete takes a Table, got {type(table).__name__}.")
+        self.table: Table = table
+        self.where_required: bool = where_required
+
+    @property
+    def place(self) -> int:
+        return 0
+
+    def build(self) -> str:
+        return f"DELETE {self.table.build(use_name=False, use_alias=True)}"
+
+    def __repr__(self) -> str:
+        option: str = "" if self.where_required else ", where_required=False"
+        return f"{self.__class__.__name__}(table={self.table}{option})"
+
+
+class OrderBy(Clause):
+    def __init__(self, field: Aliasable, descending: bool = False) -> None:
+        self.ordering: list[tuple[Aliasable, bool]] = [(field, descending)]
+        self.offset_rows: int | None = None
+        self.fetch_rows: int | None = None
+
+    @property
+    def place(self) -> int:
+        return 5
+
+    @property
+    def has_paging(self) -> bool:
+        return self.offset_rows is not None or self.fetch_rows is not None
+
+    def add(self, field: Aliasable, descending: bool = False) -> OrderBy:
+        self.ordering.append((field, descending))
+        return self
+
+    def offset(self, rows: int) -> OrderBy:
+        self.offset_rows = _row_count("OFFSET", rows, minimum=0)
+        return self
+
+    def fetch(self, rows: int) -> OrderBy:
+        self.fetch_rows = _row_count("FETCH", rows, minimum=1)
+        return self
+
+    def build(self) -> str:
+        ret_list: list[str] = []
+        for field, desc in self.ordering:
+            ret_list.append(f"{field.build(use_name=False, use_alias=True)}{' DESC' if desc else ''}")
+        ret: str = "ORDER BY " + ", ".join(ret_list)
+        if self.has_paging:
+            # T-SQL requires OFFSET before FETCH: fetch() alone starts at the first row.
+            ret += f"\nOFFSET {self.offset_rows or 0} ROWS"
+            if self.fetch_rows is not None:
+                ret += f" FETCH NEXT {self.fetch_rows} ROWS ONLY"
+        return ret
+
+    def __repr__(self) -> str:
+        paging: str = (f", offset={self.offset_rows}" if self.offset_rows is not None else "") + (
+            f", fetch={self.fetch_rows}" if self.fetch_rows is not None else ""
+        )
+        return f"{self.__class__.__name__}(ordering={self.ordering}{paging})"