feat: distinguish foreign key indexes from other non-unique indexes

iamralch · iamralch · commit 00775d5b34b4 · 2026-04-16T17:48:53.000+04:00
Add IsForeignKeyIndex method to detect when an index's columns match a
foreign key, enabling default generation of FK-based list queries while
keeping non-FK index queries opt-in. Update template to conditionally
include list queries based on FK index status or explicit opt-in.
diff --git a/README.md b/README.md
@@ -12,8 +12,8 @@ A CLI tool that generates [sqlc](https://sqlc.dev)-compatible SQL queries from y
 ## Features
 
 - Generate CRUD queries (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) from a database schema catalog
-- Primary key CRUD and List operations generated by default — no configuration needed
-- Opt-in to additional queries (Copy, FK joins, non-unique index queries) via `queries` allowlist
+- Primary key CRUD and FK-based List operations generated by default — no configuration needed
+- Opt-in to additional queries (Copy, FK joins, non-FK index queries) via `queries` allowlist
 - Configurable via YAML — shares the same `sqlc.yaml` configuration file
 - Works as a standalone CLI or as part of a CI/CD pipeline
 - Supports custom query templates
@@ -67,15 +67,16 @@ sql:
 
 ### Default queries (always generated)
 
-Primary key CRUD operations, List queries, and their Exec/Batch variants are
-generated automatically for every table:
+Primary key CRUD operations, List queries (including FK-index-based list
+queries), and their Exec/Batch variants are generated automatically for every
+table:
 
 | Query                     | Description                                |
 | ------------------------- | ------------------------------------------ |
 | `Get<Table>`              | Select a row by primary key                |
 | `BatchGet<Tables>`        | Batch select rows by primary key           |
 | `List<Tables>`            | Paginated list with filtering              |
-| `List<Tables>By<Columns>` | Paginated list by non-unique index         |
+| `List<Tables>By<Columns>` | Paginated list by foreign key index        |
 | `Insert<Table>`           | Insert a row                               |
 | `ExecInsert<Table>`       | Insert a row (exec, returns affected rows) |
 | `BatchInsert<Tables>`     | Batch insert rows                          |
@@ -99,6 +100,7 @@ These queries are only generated when explicitly listed in `options.queries`:
 | `Get<Table>With<Related>`       | Select with FK join                      |
 | `BatchGet<Tables>With<Related>` | Batch select with FK join                |
 | `Get<Table>By<Columns>`         | Select by non-PK unique index            |
+| `List<Tables>By<Columns>`       | Paginated list by non-FK non-unique index|
 | `Update<Tables>By<Columns>`     | Update by non-unique index               |
 | `Delete<Tables>By<Columns>`     | Delete by non-unique index               |
 
diff --git a/internal/sqlc/catalog.go b/internal/sqlc/catalog.go
@@ -143,6 +143,27 @@ func (x *Table) GetNonPrimaryKeyColumns() []Column {
 	return columns
 }
 
+// IsForeignKeyIndex checks if the given index's columns exactly match
+// any foreign key's columns on this table (order-independent).
+func (x *Table) IsForeignKeyIndex(index *Index) bool {
+	indexCols := make([]string, len(index.Parts))
+	for i, part := range index.Parts {
+		indexCols[i] = part.Column
+	}
+	slices.Sort(indexCols)
+
+	for _, fk := range x.ForeignKeys {
+		fkCols := make([]string, len(fk.Columns))
+		copy(fkCols, fk.Columns)
+		slices.Sort(fkCols)
+
+		if slices.Equal(indexCols, fkCols) {
+			return true
+		}
+	}
+	return false
+}
+
 // Column represents a table column with its name, data type, and nullability.
 type Column struct {
 	Name string `json:"name"`
diff --git a/internal/sqlc/catalog_test.go b/internal/sqlc/catalog_test.go
@@ -84,7 +84,7 @@ var _ = Describe("Catalog", func() {
 			Expect(fkAuthor.References.Columns).To(Equal([]string{"id"}))
 
 			// Verify expression-based indexes
-			Expect(postsTable.Indexes).To(HaveLen(2))
+			Expect(postsTable.Indexes).To(HaveLen(3))
 			exprIndex := postsTable.Indexes[1]
 			Expect(exprIndex.Name).To(Equal("idx_posts_title_expr"))
 			Expect(exprIndex.Parts).To(HaveLen(1))
@@ -143,9 +143,11 @@ var _ = Describe("Catalog", func() {
 
 			It("returns non-unique indexes", func() {
 				keys := postsTable.GetNonUniqueIndexes()
-				Expect(keys).To(HaveLen(1))
+				Expect(keys).To(HaveLen(2))
 				Expect(keys[0].Name).To(Equal("idx_posts_user_id"))
 				Expect(keys[0].Unique).To(BeFalse())
+				Expect(keys[1].Name).To(Equal("idx_posts_title"))
+				Expect(keys[1].Unique).To(BeFalse())
 			})
 
 			It("returns empty slice when there are no non-unique indexes", func() {
@@ -154,6 +156,34 @@ var _ = Describe("Catalog", func() {
 			})
 		})
 
+		Describe("IsForeignKeyIndex", func() {
+			var postsTable *sqlc.Table
+
+			BeforeEach(func() {
+				postsTable = &catalog.Schemas[0].Tables[1]
+			})
+
+			It("returns true when index columns match a foreign key", func() {
+				keys := postsTable.GetNonUniqueIndexes()
+				// idx_posts_user_id matches FK fk_posts_user_id
+				Expect(postsTable.IsForeignKeyIndex(keys[0])).To(BeTrue())
+			})
+
+			It("returns false when index columns do not match any foreign key", func() {
+				keys := postsTable.GetNonUniqueIndexes()
+				// idx_posts_title does not match any FK
+				Expect(postsTable.IsForeignKeyIndex(keys[1])).To(BeFalse())
+			})
+
+			It("returns false when table has no foreign keys", func() {
+				index := &sqlc.Index{
+					Name: "idx_test",
+					Parts: []sqlc.IndexPart{{Column: "email"}},
+				}
+				Expect(usersTable.IsForeignKeyIndex(index)).To(BeFalse())
+			})
+		})
+
 		Describe("GetUniqueKeys", func() {
 			It("returns primary key and unique indexes", func() {
 				keys := usersTable.GetUniqueKeys()
diff --git a/internal/sqlc/catalog_test.json b/internal/sqlc/catalog_test.json
@@ -133,6 +133,15 @@
                   "desc": false
                 }
               ]
+            },
+            {
+              "name": "idx_posts_title",
+              "unique": false,
+              "parts": [
+                {
+                  "column": "title"
+                }
+              ]
             }
           ]
         }
diff --git a/internal/sqlc/generator.go b/internal/sqlc/generator.go
@@ -150,6 +150,10 @@ func (x *Generator) Generate() error {
 			}
 			return ""
 		},
+		// Foreign key index check
+		"is_fk_index": func(table Table, index *Index) bool {
+			return table.IsForeignKeyIndex(index)
+		},
 		// Query include function for opt-in queries
 		"should_include": func(ctx Context, queryName string) bool {
 			return ctx.Queries[queryName]
diff --git a/internal/sqlc/generator_test.go b/internal/sqlc/generator_test.go
@@ -71,6 +71,18 @@ var _ = Describe("Generator", func() {
 				// Opt-in queries are not present without config
 				Expect(string(content)).NotTo(ContainSubstring("name: CopyUsers :copyfrom"))
 			}
+
+			// Verify posts.sql FK-based list queries
+			for _, config := range generator.Config.SQL {
+				path := filepath.Join(config.Queries, "posts.sql")
+				content, err := os.ReadFile(path)
+				Expect(err).NotTo(HaveOccurred())
+
+				// FK-matching index list query is present by default
+				Expect(string(content)).To(ContainSubstring("name: ListPostsByUserId :many"))
+				// Non-FK index list query is not present without opt-in
+				Expect(string(content)).NotTo(ContainSubstring("name: ListPostsByTitle :many"))
+			}
 		})
 
 		When("the queries directory does not exist", func() {
@@ -106,6 +118,7 @@ var _ = Describe("Generator", func() {
 										Options: sqlc.CodegenOptions{
 											Queries: []string{
 												"CopyUsers",
+												"ListPostsByTitle",
 											},
 										},
 									},
@@ -137,6 +150,18 @@ var _ = Describe("Generator", func() {
 					// Opt-in queries that were listed are present
 					Expect(string(content)).To(ContainSubstring("name: CopyUsers :copyfrom"))
 				}
+
+				// Verify posts.sql opt-in list queries
+				for _, config := range generator.Config.SQL {
+					path := filepath.Join(config.Queries, "posts.sql")
+					content, err := os.ReadFile(path)
+					Expect(err).NotTo(HaveOccurred())
+
+					// FK-matching index list query is present by default
+					Expect(string(content)).To(ContainSubstring("name: ListPostsByUserId :many"))
+					// Non-FK index list query is present because it was opted in
+					Expect(string(content)).To(ContainSubstring("name: ListPostsByTitle :many"))
+				}
 			})
 
 			It("only generates default queries when queries is empty", func() {
@@ -159,6 +184,16 @@ var _ = Describe("Generator", func() {
 					// Opt-in queries are not present
 					Expect(string(content)).NotTo(ContainSubstring("name: CopyUsers :copyfrom"))
 				}
+
+				// Verify posts.sql FK-based list queries
+				for _, config := range generator.Config.SQL {
+					path := filepath.Join(config.Queries, "posts.sql")
+					content, err := os.ReadFile(path)
+					Expect(err).NotTo(HaveOccurred())
+
+					Expect(string(content)).To(ContainSubstring("name: ListPostsByUserId :many"))
+					Expect(string(content)).NotTo(ContainSubstring("name: ListPostsByTitle :many"))
+				}
 			})
 
 			It("only generates default queries when codegen is nil", func() {
@@ -178,6 +213,16 @@ var _ = Describe("Generator", func() {
 					// Default List queries are present
 					Expect(string(content)).To(ContainSubstring("name: ListUsers :many"))
 				}
+
+				// Verify posts.sql FK-based list queries
+				for _, config := range generator.Config.SQL {
+					path := filepath.Join(config.Queries, "posts.sql")
+					content, err := os.ReadFile(path)
+					Expect(err).NotTo(HaveOccurred())
+
+					Expect(string(content)).To(ContainSubstring("name: ListPostsByUserId :many"))
+					Expect(string(content)).NotTo(ContainSubstring("name: ListPostsByTitle :many"))
+				}
 			})
 
 			It("handles non-existent query names gracefully", func() {
@@ -197,6 +242,16 @@ var _ = Describe("Generator", func() {
 					// Default List queries are still present
 					Expect(string(content)).To(ContainSubstring("name: ListUsers :many"))
 				}
+
+				// Verify posts.sql FK-based list queries
+				for _, config := range generator.Config.SQL {
+					path := filepath.Join(config.Queries, "posts.sql")
+					content, err := os.ReadFile(path)
+					Expect(err).NotTo(HaveOccurred())
+
+					Expect(string(content)).To(ContainSubstring("name: ListPostsByUserId :many"))
+					Expect(string(content)).NotTo(ContainSubstring("name: ListPostsByTitle :many"))
+				}
 			})
 		})
 	})
diff --git a/internal/sqlc/template/template.sql.tmpl b/internal/sqlc/template/template.sql.tmpl
@@ -299,6 +299,7 @@ OFFSET
     sqlc.narg(page_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}}.
 --
@@ -338,6 +339,7 @@ LIMIT
     sqlc.narg(page_limit)::int
 OFFSET
     sqlc.narg(page_offset)::int;
+{{- end}}
 
 {{- $query_name := printf "Update%s%s" (table_name $.Table.Name "many") (query_index $key)}}
 {{- if should_include $ $query_name}}
diff --git a/internal/sqlc/template/template_test.go b/internal/sqlc/template/template_test.go
@@ -24,6 +24,8 @@ var _ = Describe("Template", func() {
 			// Pagination Functions
 			"page_start": func(args ...any) string { return "" },
 			"page_order": func(args ...any) string { return "" },
+			// Foreign key index check
+			"is_fk_index": func(args ...any) bool { return false },
 			// Query include function
 			"should_include": func(args ...any) bool { return false },
 		}

Original file line number	Diff line number	Diff line change
`@@ -133,6 +133,15 @@`
`133`	`133`	`"desc": false`
`134`	`134`	`}`
`135`	`135`	`]`
	`136`	`+ },`
	`137`	`+ {`
	`138`	`+ "name": "idx_posts_title",`
	`139`	`+ "unique": false,`
	`140`	`+ "parts": [`
	`141`	`+ {`
	`142`	`+ "column": "title"`
	`143`	`+ }`
	`144`	`+ ]`
`136`	`145`	`}`
`137`	`146`	`]`
`138`	`147`	`}`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,8 @@ var _ = Describe("Template", func() {`
`24`	`24`	`// Pagination Functions`
`25`	`25`	`"page_start": func(args ...any) string { return "" },`
`26`	`26`	`"page_order": func(args ...any) string { return "" },`
	`27`	`+ // Foreign key index check`
	`28`	`+ "is_fk_index": func(args ...any) bool { return false },`
`27`	`29`	`// Query include function`
`28`	`30`	`"should_include": func(args ...any) bool { return false },`
`29`	`31`	`}`