t-sql 4.10.0__tar.gz → 4.12.0__tar.gz

t_sql-4.10.0/README.md → t_sql-4.12.0/PKG-INFO

@@ -1,3 +1,13 @@
+Metadata-Version: 2.4
+Name: t-sql
+Version: 4.12.0
+Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
+Project-URL: Homepage, https://github.com/nhumrich/t-sql
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: alembic>=1.17.0
+Description-Content-Type: text/markdown
+
 # t-sql
 
 A lightweight SQL templating library that leverages Python 3.14's t-strings (PEP 750).
@@ -375,6 +385,14 @@ query = Users.insert(id='abc123', username='john', email='john@example.com').ret
 sql, params = query.render()
 # ('INSERT INTO users (id, username, email) VALUES (?, ?, ?) RETURNING *', [...])
 
+# INSERT with all column defaults — no values provided (Postgres/SQLite)
+# Emits `DEFAULT VALUES`; useful when every column has a DB/SA default.
+# Note: MySQL does not support `DEFAULT VALUES` syntax. For MySQL, provide at
+# least one column or use raw SQL (`INSERT INTO t () VALUES ()`).
+query = Users.insert().returning('id')
+sql, params = query.render()
+# ('INSERT INTO users DEFAULT VALUES RETURNING id', [])
+
 # INSERT IGNORE (MySQL)
 query = Users.insert(id='abc123', username='john', email='john@example.com').ignore()
 sql, params = query.render()

t_sql-4.10.0/PKG-INFO → t_sql-4.12.0/README.md

@@ -1,13 +1,3 @@
-Metadata-Version: 2.4
-Name: t-sql
-Version: 4.10.0
-Summary: Safe SQL. SQL queries for python t-strings (PEP 750)
-Project-URL: Homepage, https://github.com/nhumrich/t-sql
-License-File: LICENSE
-Requires-Python: >=3.14
-Requires-Dist: alembic>=1.17.0
-Description-Content-Type: text/markdown
-
 # t-sql
 
 A lightweight SQL templating library that leverages Python 3.14's t-strings (PEP 750).
@@ -385,6 +375,14 @@ query = Users.insert(id='abc123', username='john', email='john@example.com').ret
 sql, params = query.render()
 # ('INSERT INTO users (id, username, email) VALUES (?, ?, ?) RETURNING *', [...])
 
+# INSERT with all column defaults — no values provided (Postgres/SQLite)
+# Emits `DEFAULT VALUES`; useful when every column has a DB/SA default.
+# Note: MySQL does not support `DEFAULT VALUES` syntax. For MySQL, provide at
+# least one column or use raw SQL (`INSERT INTO t () VALUES ()`).
+query = Users.insert().returning('id')
+sql, params = query.render()
+# ('INSERT INTO users DEFAULT VALUES RETURNING id', [])
+
 # INSERT IGNORE (MySQL)
 query = Users.insert(id='abc123', username='john', email='john@example.com').ignore()
 sql, params = query.render()

{t_sql-4.10.0 → t_sql-4.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "t-sql"
-version = "4.10.0"
+version = "4.12.0"
 description = "Safe SQL. SQL queries for python t-strings (PEP 750)"
 readme = "README.md"
 requires-python = ">=3.14"

{t_sql-4.10.0 → t_sql-4.12.0}/tests/test_asyncpg_integration.py

@@ -457,4 +457,35 @@ async def test_array_with_list(conn):
         row = await conn.fetchrow("SELECT tags FROM test_array WHERE id = 1")
         assert row['tags'] == my_list
     finally:
-        await conn.execute("DROP TABLE IF EXISTS test_array")
+        await conn.execute("DROP TABLE IF EXISTS test_array")
+
+
+async def test_insert_all_defaults_with_returning(conn):
+    """Insert with empty values uses DEFAULT VALUES; all columns have defaults."""
+    from tsql.query_builder import Table, Column
+
+    await conn.execute("""
+        CREATE TABLE IF NOT EXISTS test_defaults (
+            id SERIAL PRIMARY KEY,
+            status VARCHAR(20) DEFAULT 'draft',
+            created_at TIMESTAMP DEFAULT NOW()
+        )
+    """)
+
+    try:
+        class TestDefaults(Table, table_name='test_defaults'):
+            id: Column
+            status: Column
+            created_at: Column
+
+        query, params = TestDefaults.insert().returning('id', 'status').render(
+            style=tsql.styles.NUMERIC_DOLLAR
+        )
+        assert query == 'INSERT INTO test_defaults DEFAULT VALUES RETURNING id, status'
+        assert params == []
+
+        row = await conn.fetchrow(query, *params)
+        assert row['id'] is not None
+        assert row['status'] == 'draft'
+    finally:
+        await conn.execute("DROP TABLE IF EXISTS test_defaults")

{t_sql-4.10.0 → t_sql-4.12.0}/tests/test_query_builder.py

@@ -1,5 +1,5 @@
 import tsql
-from tsql.query_builder import Table, Column, Condition, InsertBuilder, UpdateBuilder, DeleteBuilder
+from tsql.query_builder import Table, Column, Condition, InsertBuilder, UpdateBuilder, DeleteBuilder, SelectQueryBuilder
 
 
 class Users(Table):
@@ -216,6 +216,57 @@ def test_left_join():
     assert 'LEFT JOIN posts ON users.id = posts.user_id' in sql
 
 
+def test_join_raw_template():
+    """join_raw() splices a raw t-string Template verbatim as a whole JOIN clause."""
+    query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t')
+             .select(t't.*')
+             .join_raw(t'LEFT JOIN other o ON o.id = t.ref'))
+    sql, params = query.render()
+
+    assert sql == 'SELECT t.* FROM dataset.records AS t LEFT JOIN other o ON o.id = t.ref'
+    assert params == []
+
+
+def test_join_raw_lateral_no_on():
+    """join_raw() handles join shapes the typed path can't: LATERAL, no ON."""
+    query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t')
+             .select(t't.*')
+             .join_raw(t'CROSS JOIN LATERAL unnest(t.tags) AS tag'))
+    sql, params = query.render()
+
+    assert sql == 'SELECT t.* FROM dataset.records AS t CROSS JOIN LATERAL unnest(t.tags) AS tag'
+    assert params == []
+
+
+def test_join_raw_template_carries_params():
+    """A parameterized raw join Template renumbers correctly in context."""
+    query = (SelectQueryBuilder.from_table('records', schema='dataset', alias='t')
+             .select(t't.*')
+             .join_raw(t'LEFT JOIN other o ON o.id = t.ref AND o.kind = {"x"}')
+             .where(t't.active = {True}'))
+    sql, params = query.render(style=tsql.styles.NUMERIC_DOLLAR)
+
+    assert sql == (
+        'SELECT t.* FROM dataset.records AS t '
+        'LEFT JOIN other o ON o.id = t.ref AND o.kind = $1 '
+        'WHERE (t.active = $2)'
+    )
+    assert params == ['x', True]
+
+
+def test_join_raw_and_typed_mixed():
+    """Raw and typed joins compose in insertion order."""
+    query = (Posts.select(Posts.ALL)
+             .join(Users, Posts.user_id == Users.id)
+             .join_raw(t'LEFT JOIN tags tg ON tg.post_id = posts.id'))
+    sql, params = query.render()
+
+    assert 'INNER JOIN users ON posts.user_id = users.id' in sql
+    assert 'LEFT JOIN tags tg ON tg.post_id = posts.id' in sql
+    # typed join comes first (added first), raw second
+    assert sql.index('INNER JOIN users') < sql.index('LEFT JOIN tags')
+
+
 def test_order_by():
     """Test ORDER BY clause"""
     query = Users.select().order_by(Users.username)
@@ -1208,6 +1259,43 @@ def test_insert_without_metadata_ignores_defaults():
     assert params == ['1', 'test']
 
 
+class _DefaultsTable(Table, table_name='mytable'):
+    id: Column
+    name: Column
+
+
+def test_insert_all_defaults():
+    sql, params = _DefaultsTable.insert().render()
+    assert sql == 'INSERT INTO mytable DEFAULT VALUES'
+    assert params == []
+
+
+def test_insert_all_defaults_with_returning():
+    sql, params = _DefaultsTable.insert().returning('id').render()
+    assert sql == 'INSERT INTO mytable DEFAULT VALUES RETURNING id'
+    assert params == []
+
+
+def test_insert_all_defaults_with_returning_star():
+    sql, params = _DefaultsTable.insert().returning().render()
+    assert sql == 'INSERT INTO mytable DEFAULT VALUES RETURNING *'
+    assert params == []
+
+
+def test_insert_all_defaults_with_on_conflict_do_nothing():
+    sql, params = _DefaultsTable.insert().on_conflict_do_nothing().render()
+    assert sql == 'INSERT INTO mytable DEFAULT VALUES ON CONFLICT DO NOTHING'
+    assert params == []
+
+
+def test_insert_all_defaults_mysql_on_duplicate_raises():
+    import pytest
+
+    builder = _DefaultsTable.insert().on_duplicate_key_update()
+    with pytest.raises(ValueError, match='DEFAULT VALUES'):
+        builder.render()
+
+
 def test_update_with_onupdate_default():
     """Test that onupdate defaults are applied during UPDATE"""
     from sqlalchemy import MetaData, Column as SAColumn, String
@@ -1587,3 +1675,207 @@ def test_delete_where_with_bare_boolean_column():
     assert 'DELETE FROM contacts' in sql
     assert 'WHERE contacts.is_primary' in sql
     assert params == []
+
+
+# --------------------------------------------------------------------------- #
+# DISTINCT ON
+# --------------------------------------------------------------------------- #
+
+
+def test_distinct_on_string_column():
+    """distinct_on() with a string column emits SELECT DISTINCT ON (col)"""
+    query = Users.select(Users.id, Users.username).distinct_on('username')
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (username) users.id, users.username FROM users'
+    assert params == []
+
+
+def test_distinct_on_multiple_columns():
+    """distinct_on() accepts multiple columns, comma-joined inside the parens"""
+    query = Users.select(Users.id).distinct_on('username', 'email')
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (username, email) users.id FROM users'
+    assert params == []
+
+
+def test_distinct_on_column_object():
+    """distinct_on() accepts Column objects, coerced like select()"""
+    query = Users.select(Users.id).distinct_on(Users.username)
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (users.username) users.id FROM users'
+    assert params == []
+
+
+def test_distinct_on_template_fragment():
+    """distinct_on() accepts raw t-string fragments (the field-type seam)"""
+    query = Users.select(Users.id).distinct_on(t'users.username')
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (users.username) users.id FROM users'
+    assert params == []
+
+
+def test_distinct_on_select_star():
+    """distinct_on() works with SELECT * (no explicit columns)"""
+    query = Users.select().distinct_on('username')
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (username) * FROM users'
+    assert params == []
+
+
+def test_no_distinct_on_unaffected():
+    """A query without distinct_on() is unchanged"""
+    query = Users.select(Users.id)
+    sql, params = query.render()
+
+    assert sql == 'SELECT users.id FROM users'
+    assert params == []
+
+
+# --------------------------------------------------------------------------- #
+# FROM ONLY  (Postgres table inheritance)
+# --------------------------------------------------------------------------- #
+
+
+def test_from_only_flag():
+    """from_table(only=True) makes the builder emit FROM ONLY {table}"""
+    query = SelectQueryBuilder.from_table('users', only=True).select('id')
+    sql, params = query.render()
+
+    assert sql == 'SELECT id FROM ONLY users'
+    assert params == []
+
+
+def test_from_only_with_schema():
+    """FROM ONLY respects the schema-qualified table name"""
+    query = SelectQueryBuilder.from_table('records', schema='dataset', only=True)
+    sql, params = query.render()
+
+    assert sql == 'SELECT * FROM ONLY dataset.records'
+    assert params == []
+
+
+def test_from_only_default_off():
+    """Without only=True, FROM is unchanged (no ONLY keyword)"""
+    query = SelectQueryBuilder.from_table('users').select('id')
+    sql, params = query.render()
+
+    assert 'FROM ONLY' not in sql
+    assert 'FROM users' in sql
+
+
+def test_distinct_on_and_from_only_together():
+    """DISTINCT ON and FROM ONLY compose"""
+    query = (SelectQueryBuilder.from_table('records', schema='dataset', only=True)
+             .select(t't.*')
+             .distinct_on('t.id'))
+    sql, params = query.render()
+
+    assert sql == 'SELECT DISTINCT ON (t.id) t.* FROM ONLY dataset.records'
+    assert params == []
+
+
+# --------------------------------------------------------------------------- #
+# FROM table alias
+# --------------------------------------------------------------------------- #
+
+
+def test_from_table_alias():
+    """from_table(alias=...) emits FROM {table} AS {alias}"""
+    query = SelectQueryBuilder.from_table('records', schema='dataset', alias='t').select(t't.*')
+    sql, params = query.render()
+
+    assert sql == 'SELECT t.* FROM dataset.records AS t'
+    assert params == []
+
+
+def test_from_table_alias_and_only():
+    """alias and only compose: FROM ONLY {table} AS {alias}"""
+    query = SelectQueryBuilder.from_table('records', schema='dataset', alias='t', only=True).select(
+        t't.*'
+    )
+    sql, params = query.render()
+
+    assert sql == 'SELECT t.* FROM ONLY dataset.records AS t'
+    assert params == []
+
+
+def test_from_table_alias_default_none():
+    """Without alias, no AS clause is emitted"""
+    query = SelectQueryBuilder.from_table('users')
+    sql, params = query.render()
+
+    assert ' AS ' not in sql
+    assert sql == 'SELECT * FROM users'
+
+
+def test_from_table_alias_rejects_injection():
+    """alias goes through :literal and rejects a non-identifier"""
+    import pytest
+
+    query = SelectQueryBuilder.from_table('users', alias='t; DROP TABLE x')
+    with pytest.raises(ValueError):
+        query.render()
+
+
+# --------------------------------------------------------------------------- #
+# Template-aware ORDER BY / GROUP BY  (parity with where/having/select)
+# --------------------------------------------------------------------------- #
+
+
+def test_order_by_template_fragment():
+    """order_by() accepts a raw t-string fragment, emitted verbatim (no added direction)."""
+    query = Users.select(Users.id).order_by(t'lower(users.username) DESC NULLS LAST')
+    sql, params = query.render()
+
+    assert sql == 'SELECT users.id FROM users ORDER BY lower(users.username) DESC NULLS LAST'
+    assert params == []
+
+
+def test_order_by_template_carries_params():
+    """A parameterized ORDER BY fragment renumbers correctly in context."""
+    query = (Users.select(Users.id)
+             .where(Users.id > 5)
+             .order_by(t'(users.username = {"vip"}) DESC'))
+    sql, params = query.render(style=tsql.styles.NUMERIC_DOLLAR)
+
+    assert sql == 'SELECT users.id FROM users WHERE users.id > $1 ORDER BY (users.username = $2) DESC'
+    assert params == [5, 'vip']
+
+
+def test_order_by_mixed_template_and_column():
+    """Template fragments and Column/str order_by entries compose in order."""
+    query = (Users.select(Users.id)
+             .order_by(t'lower(users.username) ASC')
+             .order_by(Users.id.desc()))
+    sql, params = query.render()
+
+    assert sql == 'SELECT users.id FROM users ORDER BY lower(users.username) ASC, users.id DESC'
+    assert params == []
+
+
+def test_group_by_template_fragment():
+    """group_by() accepts a raw t-string fragment, emitted verbatim."""
+    query = Users.select(t'date_trunc({"day":unsafe}, users.created_at)').group_by(
+        t'date_trunc(day, users.created_at)'
+    )
+    sql, params = query.render()
+
+    assert sql == (
+        'SELECT date_trunc(day, users.created_at) FROM users '
+        'GROUP BY date_trunc(day, users.created_at)'
+    )
+    assert params == []
+
+
+def test_group_by_mixed_template_and_column():
+    """Template fragments and Column/str group_by entries compose in order."""
+    query = Users.select(Users.id).group_by(Users.id).group_by(t'lower(users.email)')
+    sql, params = query.render()
+
+    assert sql == 'SELECT users.id FROM users GROUP BY users.id, lower(users.email)'
+    assert params == []

{t_sql-4.10.0 → t_sql-4.12.0}/tests/test_sqlite_integration.py

@@ -429,3 +429,29 @@ async def test_like_pattern_format_specs(conn):
     # Should match john_doe
     assert len(rows) == 1
     assert rows[0][0] == 'john_doe'
+
+
+async def test_insert_all_defaults_with_returning(conn):
+    """Insert with empty values uses DEFAULT VALUES on SQLite."""
+    from tsql.query_builder import Column
+
+    await conn.execute("""
+        CREATE TABLE test_defaults (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            status TEXT DEFAULT 'draft'
+        )
+    """)
+    await conn.commit()
+
+    class TestDefaults(Table, table_name='test_defaults'):
+        id: Column
+        status: Column
+
+    sql, params = TestDefaults.insert().returning('id', 'status').render()
+    assert sql == 'INSERT INTO test_defaults DEFAULT VALUES RETURNING id, status'
+    assert params == []
+
+    cursor = await conn.execute(sql, params)
+    row = await cursor.fetchone()
+    assert row[0] is not None
+    assert row[1] == 'draft'

{t_sql-4.10.0 → t_sql-4.12.0}/tests/test_tsql.py

@@ -69,7 +69,7 @@ def test_correct_final_query_with_literals():
 def test_disallows_bad_literals():
     table = "users'"
     col = "name"
-    with pytest.raises(ValueError):  # TODO: change to appropriate error
+    with pytest.raises(ValueError):
         result = tsql.render(t'select id, {col:literal} from {table:literal}')
 
 

{t_sql-4.10.0 → t_sql-4.12.0}/tsql/query_builder.py

@@ -614,10 +614,11 @@ class QueryBuilder(ABC):
                     result_key = col.alias if col.alias else col.column_name
                     processors[result_key] = col.type_processor
         else:
-            # SELECT * - check all tables involved (base table + joins)
+            # SELECT * - check all tables involved (base table + joins).
+            # Raw-Template joins carry no introspectable table, so skip them.
             tables = [self.base_table]
             if hasattr(self, '_joins'):
-                tables.extend(join.table for join in self._joins)
+                tables.extend(join.table for join in self._joins if not isinstance(join, Template))
 
             for table in tables:
                 processors.update(table._type_processors)
@@ -759,8 +760,9 @@ class InsertBuilder(QueryBuilder):
             processor = self.base_table._type_processors.get(col_name)
             values_dict[col_name] = _process_value_for_builder(value, processor)
 
-        # MySQL INSERT IGNORE
-        if self._ignore:
+        if not values_dict:
+            parts.append(t'INSERT INTO {table_name:literal} DEFAULT VALUES')
+        elif self._ignore:
             parts.append(t'INSERT IGNORE INTO {table_name:literal} {values_dict:as_values}')
         else:
             parts.append(t'INSERT INTO {table_name:literal} {values_dict:as_values}')
@@ -821,6 +823,10 @@ class InsertBuilder(QueryBuilder):
                     update_dict[col_name] = _process_value_for_builder(value, processor)
                 parts.append(t'ON DUPLICATE KEY UPDATE {update_dict:as_set}')
             else:
+                if not self.values:
+                    raise ValueError(
+                        "ON DUPLICATE KEY UPDATE requires explicit columns when inserting DEFAULT VALUES"
+                    )
                 # Default: update all columns with alias.column (new MySQL syntax)
                 update_parts = []
                 for i, key in enumerate(self.values.keys()):
@@ -1161,32 +1167,48 @@ class SelectQueryBuilder(QueryBuilder):
         self.base_table = base_table
         self._columns: Optional[List[Union[Column, str]]] = None
         self._conditions: List[Union[Condition, Template]] = []
-        self._joins: List[Join] = []
-        self._group_by_columns: List[Union[Column, str]] = []
+        self._joins: List[Union[Join, Template]] = []
+        self._group_by_columns: List[Union[Column, Template, str]] = []
         self._having_conditions: List[Union[Condition, Template]] = []
-        self._order_by_columns: List[tuple[Union[Column, str], str]] = []
+        self._order_by_columns: List[tuple[Union[Column, Template, str], str]] = []
         self._limit_value: Optional[int] = None
         self._offset_value: Optional[int] = None
         self._ctes: List[tuple[str, Union[Template, TSQL, 'SelectQueryBuilder'], bool]] = []
+        self._distinct_on_columns: List[Union[Column, Template, str]] = []
+        self._only: bool = False
+        self._alias: Optional[str] = None
 
     @classmethod
-    def from_table(cls, table_name: str, schema: Optional[str] = None) -> 'SelectQueryBuilder':
+    def from_table(
+        cls,
+        table_name: str,
+        schema: Optional[str] = None,
+        *,
+        only: bool = False,
+        alias: Optional[str] = None,
+    ) -> 'SelectQueryBuilder':
         """Create a SelectQueryBuilder from a string table name.
 
         Args:
             table_name: Name of the table
             schema: Optional schema name
+            only: Emit ``FROM ONLY {table}`` to exclude inheriting child tables (PostgreSQL)
+            alias: Optional FROM-clause alias, emitted as ``FROM {table} AS {alias}``
+                (validated as an identifier)
 
         Returns:
             SelectQueryBuilder instance
 
         Example:
-            SelectQueryBuilder.from_table('users', schema='public') \\
-                .select('id', 'name') \\
-                .where(t'status = {status}')
+            SelectQueryBuilder.from_table('users', schema='public', alias='u') \\
+                .select('u.id', 'u.name') \\
+                .where(t'u.status = {status}')
         """
         string_table = _StringTable(table_name, schema)
-        return cls(string_table)
+        builder = cls(string_table)
+        builder._only = only
+        builder._alias = alias
+        return builder
 
     def select(self, *columns: Union[Column, Template, str]) -> 'SelectQueryBuilder':
         """Specify columns to select
@@ -1216,6 +1238,20 @@ class SelectQueryBuilder(QueryBuilder):
             self._columns = None
         return self
 
+    def distinct_on(self, *columns: Union[Column, Template, str]) -> 'SelectQueryBuilder':
+        """Add a DISTINCT ON (...) clause (PostgreSQL).
+
+        Args:
+            columns: Column objects, raw t-string Templates, or string column names,
+                coerced exactly like select().
+
+        Example:
+            SelectQueryBuilder.from_table('events').distinct_on('user_id')
+            # SELECT DISTINCT ON (user_id) * FROM events
+        """
+        self._distinct_on_columns.extend(columns)
+        return self
+
     def where(self, condition: Union[Condition, Template, Column]) -> 'SelectQueryBuilder':
         """Add a WHERE condition (multiple calls are ANDed together)
 
@@ -1229,6 +1265,23 @@ class SelectQueryBuilder(QueryBuilder):
         self._joins.append(Join(table, on, join_type))
         return self
 
+    def join_raw(self, clause: Template) -> 'SelectQueryBuilder':
+        """Splice a raw t-string Template as a complete JOIN clause, verbatim.
+
+        The Template must carry the *whole* clause including the join keyword, e.g.
+        ``t'LEFT JOIN LATERAL (SELECT ...) x ON TRUE'`` or
+        ``t'CROSS JOIN LATERAL unnest({col}) AS y'``. Unlike join(), nothing is added
+        around it — no join type, no ON.
+
+        NOT ADVISED: this is an escape hatch for join shapes the typed join() can't
+        express (LATERAL subqueries, ON-less cross joins, correlated set-returning
+        functions). It bypasses every safety/structure the builder provides. Prefer
+        join()/left_join()/right_join() with a Table + Condition. This method may be
+        removed if those typed paths grow to cover the remaining cases.
+        """
+        self._joins.append(clause)
+        return self
+
     def left_join(self, table: type['Table'], on: Condition) -> 'SelectQueryBuilder':
         """Add a LEFT JOIN clause"""
         return self.join(table, on, 'LEFT')
@@ -1237,11 +1290,13 @@ class SelectQueryBuilder(QueryBuilder):
         """Add a RIGHT JOIN clause"""
         return self.join(table, on, 'RIGHT')
 
-    def order_by(self, *columns: Union[Column, OrderByClause, str], direction: str = 'ASC') -> 'SelectQueryBuilder':
+    def order_by(self, *columns: Union[Column, OrderByClause, Template, str], direction: str = 'ASC') -> 'SelectQueryBuilder':
         """Add ORDER BY clause
 
         Args:
-            columns: Column objects, OrderByClause objects (from .asc()/.desc()), or string column names
+            columns: Column objects, OrderByClause objects (from .asc()/.desc()), raw
+                t-string Templates (emitted verbatim — bake the direction in yourself),
+                or string column names
             direction: Sort direction ('ASC' or 'DESC') for columns that don't have explicit direction
 
         Examples:
@@ -1265,15 +1320,19 @@ class SelectQueryBuilder(QueryBuilder):
                 self._order_by_columns.append((column, direction.upper()))
         return self
 
-    def group_by(self, *columns: Union[Column, str]) -> 'SelectQueryBuilder':
+    def group_by(self, *columns: Union[Column, Template, str]) -> 'SelectQueryBuilder':
         """Add GROUP BY clause
 
         Args:
-            columns: Column objects or string column names
+            columns: Column objects, raw t-string Templates (emitted verbatim), or
+                string column names
 
         Examples:
             # String-based GROUP BY
             SelectQueryBuilder.from_table('orders').select('user_id', 'COUNT(*)').group_by('user_id')
+
+            # Raw expression via t-string
+            Orders.select().group_by(t'date_trunc({"day":unsafe}, orders.created_at)')
         """
         self._group_by_columns.extend(columns)
         return self
@@ -1345,6 +1404,18 @@ class SelectQueryBuilder(QueryBuilder):
         self._ctes.append((name, query, recursive))
         return self
 
+    @staticmethod
+    def _coerce_column(col: Union['Column', Template, str]) -> Template:
+        """Coerce a SELECT/DISTINCT ON column into a t-string fragment."""
+        if isinstance(col, Template):
+            return col
+        elif isinstance(col, str):
+            # String column name, use :literal for validation
+            return t'{col:literal}'
+        else:
+            # Column object, convert to string
+            return t'{str(col):unsafe}'
+
     def to_tsql(self) -> TSQL:
         """Build the final TSQL object"""
         parts: List[Template] = []
@@ -1375,32 +1446,32 @@ class SelectQueryBuilder(QueryBuilder):
             else:
                 parts.append(t'WITH {cte_clause}')
 
-        if self._columns:
-            # Build column list, handling Column objects, Template (t-string) objects, and strings
-            column_parts = []
-            for col in self._columns:
-                if isinstance(col, Template):
-                    column_parts.append(col)
-                elif isinstance(col, str):
-                    # String column name, use :literal for validation
-                    column_parts.append(t'{col:literal}')
-                else:
-                    # Column object, convert to string
-                    column_parts.append(t'{str(col):unsafe}')
+        # DISTINCT ON (...) clause, coercing columns exactly like the SELECT list
+        if self._distinct_on_columns:
+            distinct_on_template = t_join(t', ', [self._coerce_column(c) for c in self._distinct_on_columns])
+            distinct_clause = t'DISTINCT ON ({distinct_on_template}) '
+        else:
+            distinct_clause = t''
 
+        if self._columns:
+            column_parts = [self._coerce_column(col) for col in self._columns]
             columns_template = t_join(t', ', column_parts)
-            parts.append(t'SELECT {columns_template}')
+            parts.append(t'SELECT {distinct_clause}{columns_template}')
         else:
-            parts.append(t'SELECT *')
+            parts.append(t'SELECT {distinct_clause}*')
 
         if self.base_table.schema:
             table_name = f"{self.base_table.schema}.{self.base_table.table_name}"
         else:
             table_name = self.base_table.table_name
-        parts.append(t'FROM {table_name:literal}')
+        only_kw = t'ONLY ' if self._only else t''
+        if self._alias is not None:
+            parts.append(t'FROM {only_kw}{table_name:literal} AS {self._alias:literal}')
+        else:
+            parts.append(t'FROM {only_kw}{table_name:literal}')
 
         for join in self._joins:
-            parts.append(join.to_tsql())
+            parts.append(join if isinstance(join, Template) else join.to_tsql())
 
         if self._conditions:
             where_parts = []
@@ -1418,7 +1489,9 @@ class SelectQueryBuilder(QueryBuilder):
         if self._group_by_columns:
             group_by_parts = []
             for col in self._group_by_columns:
-                if isinstance(col, str):
+                if isinstance(col, Template):
+                    group_by_parts.append(col)
+                elif isinstance(col, str):
                     group_by_parts.append(t'{col:literal}')
                 else:
                     col_str = str(col)
@@ -1439,7 +1512,10 @@ class SelectQueryBuilder(QueryBuilder):
         if self._order_by_columns:
             order_parts = []
             for col, direction in self._order_by_columns:
-                if isinstance(col, str):
+                if isinstance(col, Template):
+                    # Raw fragment is self-contained (direction baked in); emit verbatim
+                    order_parts.append(col)
+                elif isinstance(col, str):
                     # String column name - validate with :literal
                     order_parts.append(t'{col:literal} {direction:unsafe}')
                 else: