feat: rewrite list queries with comment-marker placeholders

Replaces the sqlc.narg(filter)::void and cursor machinery in List
queries with SQL comment placeholders (/* query.cursor AND */,
/* query.filter AND */, /* query.order , */) that a runtime rewriter
(e.g. sqlc-gen-template) substitutes before execution.

When left unreplaced they remain SQL comments, so the query runs as
an offset-paginated scan ordered by primary key. Removes page_start
from the generator; keeps page_order for the default ORDER BY tie-breaker.

Author: iamralch

internal/sqlc/generator.go

@@ -110,6 +110,12 @@ func (x *Generator) Generate() error {
 			}
 			return condition.String()
 		},
+		"query_argument": func(column Column) string {
+			argument := Argument{
+				Column: &column,
+			}
+			return argument.String()
+		},
 		"query_index": func(index *Index) string {
 			// Don't add suffix for primary key lookups
 			if index.Name == "primary key" {
@@ -123,32 +129,16 @@ func (x *Generator) Generate() error {
 			}
 			return "By" + strings.Join(items, "And")
 		},
-		"query_argument": func(column Column) string {
-			argument := Argument{
-				Column: &column,
-			}
-			return argument.String()
-		},
 		// Pagination functions
-		"page_start": func(table Table) string {
-			if table.PrimaryKey != nil && len(table.PrimaryKey.Parts) > 0 {
-				argument := &Argument{
-					Column: &Column{
-						Name: "page_start",
-						Type: "text",
-						Null: true,
-					},
-				}
-				column := table.PrimaryKey.Parts[0].Column
-				return fmt.Sprintf("(%v::text IS NULL OR %s::text > %v::text)", argument, column, argument)
+		"query_order": func(table Table) string {
+			if table.PrimaryKey == nil {
+				return ""
 			}
-			return ""
-		},
-		"page_order": func(table Table) string {
-			if table.PrimaryKey != nil && len(table.PrimaryKey.Parts) > 0 {
-				return table.PrimaryKey.Parts[0].Column
+			cols := make([]string, 0, len(table.PrimaryKey.Parts))
+			for _, p := range table.PrimaryKey.Parts {
+				cols = append(cols, p.Column)
 			}
-			return ""
+			return strings.Join(cols, ", ")
 		},
 		// Foreign key index check
 		"is_fk_index": func(table Table, index *Index) bool {

internal/sqlc/template/template.sql.tmpl

@@ -267,78 +267,61 @@ INSERT INTO {{.Table.Name}} (
 
 -- List{{table_name .Table.Name "many"}} retrieves a paginated list of rows from '{{$.Table.Name}}'.
 --
--- Filtering:
---   The 'filter' parameter enables dynamic WHERE clauses for flexible querying.
---   Pass NULL for no filtering, or use a query builder (e.g., pgxmql.WhereClause)
---   to construct runtime conditions. The void type cast allows query rewriting.
---   Example: filter can add conditions like "status = 'active' AND created_at > '2024-01-01'"
+-- Filtering, cursor, and ordering:
+--   The commented markers in WHERE and ORDER BY are placeholders for a runtime
+--   query rewriter (e.g. sqlc-gen-template) to substitute cursor, filter, and
+--   order expressions. When left unreplaced they remain SQL comments, so the
+--   query returns all rows ordered by primary key.
 --
--- Pagination:
---   Cursor-based: Use page_start (ID of last item from previous page) + page_limit.
---                 Returns items AFTER the cursor. Set page_start to the last item's ID from current page as next cursor.
---   Offset-based: Use page_offset + page_limit for traditional page number pagination.
+-- Offset pagination:
+--   Use offset + limit for traditional page number pagination.
 -- name: {{$query_name}} :many
 SELECT
     *
 FROM
     {{$.Table.Name}}
-{{- $page_start := page_start $.Table}}
-{{- $page_order := page_order $.Table}}
 WHERE
-    sqlc.narg(filter)::void IS NULL
-    {{- if $page_start}}
-    AND {{$page_start}}
-    {{- end}}
-{{- if $page_order}}
+    /* query.cursor AND */ /* query.filter AND */ TRUE
+{{- $query_order := query_order $.Table}}
+{{- if $query_order}}
 ORDER BY
-    {{$page_order}}
+    /* query.order , */ {{$query_order}}
 {{- end}}
 LIMIT
-    sqlc.narg(page_limit)::int
+    sqlc.narg(limit)::int
 OFFSET
-    sqlc.narg(page_offset)::int;
+    sqlc.narg(offset)::int;
 
 {{range $idx, $key := .Table.GetNonUniqueIndexes}}{{- $query_name := printf "List%s%s" (table_name $.Table.Name "many") (query_index $key)}}
 {{- if or (is_fk_index $.Table $key) (should_include $ $query_name)}}
 
 -- List{{table_name $.Table.Name "many"}}{{query_index $key}} retrieves a paginated list of rows from '{{$.Table.Name}}'{{if $key.Name}} filtered by {{$key.Name}}{{end}}.
 --
--- Filtering:
---   The 'filter' parameter enables dynamic WHERE clauses for flexible querying.
---   Pass NULL for no filtering, or use a query builder (e.g., pgxmql.WhereClause)
---   to construct runtime conditions. The void type cast allows query rewriting.
---   Example: filter can add conditions like "status = 'active' AND created_at > '2024-01-01'"
+-- Filtering, cursor, and ordering:
+--   The commented markers in WHERE and ORDER BY are placeholders for a runtime
+--   query rewriter (e.g. sqlc-gen-template) to substitute cursor, filter, and
+--   order expressions. When left unreplaced they remain SQL comments, so the
+--   query returns all matching rows ordered by primary key.
 --
--- Pagination:
---   Cursor-based: Use page_start (ID of last item from previous page) + page_limit.
---                 Returns items AFTER the cursor. Set page_start to the last item's ID from current page as next cursor.
---   Offset-based: Use page_offset + page_limit for traditional page number pagination.
+-- Offset pagination:
+--   Use offset + limit for traditional page number pagination.
 -- name: {{$query_name}} :many
 SELECT
     *
 FROM
     {{$.Table.Name}}
 {{- $condition := query_condition $.Table $key}}
-{{- $page_start := page_start $.Table}}
-{{- $page_order := page_order $.Table}}
-{{- if $condition}}
-WHERE
-    {{$condition}}
-    {{- if $page_start}}
-    AND {{$page_start}}
-    {{- end}}
-{{- else if $page_start}}
 WHERE
-    {{$page_start}}
-{{- end}}
-{{- if $page_order}}
+    /* query.cursor AND */ /* query.filter AND */ {{if $condition}}{{$condition}}{{else}}TRUE{{end}}
+{{- $query_order := query_order $.Table}}
+{{- if $query_order}}
 ORDER BY
-    {{$page_order}}
+    /* query.order , */ {{$query_order}}
 {{- end}}
 LIMIT
-    sqlc.narg(page_limit)::int
+    sqlc.narg(limit)::int
 OFFSET
-    sqlc.narg(page_offset)::int;
+    sqlc.narg(offset)::int;
 {{- end}}
 
 {{- $query_name := printf "Update%s%s" (table_name $.Table.Name "many") (query_index $key)}}

internal/sqlc/template/template_test.go

@@ -22,8 +22,7 @@ var _ = Describe("Template", func() {
 			"query_argument":  func(args ...any) string { return "" },
 			"query_index":     func(args ...any) string { return "" },
 			// Pagination Functions
-			"page_start": func(args ...any) string { return "" },
-			"page_order": func(args ...any) string { return "" },
+			"query_order": func(args ...any) string { return "" },
 			// Foreign key index check
 			"is_fk_index": func(args ...any) bool { return false },
 			// Query include function