From 19af26809e3a3214054e5be9b0b13b475dd785d6 Mon Sep 17 00:00:00 2001
From: KhotSaprem <141000523+KhotSaprem@users.noreply.github.com>
Date: Fri, 12 Jun 2026 22:15:16 +0530
Subject: [PATCH] docs: add example for directory-per-migration glob pattern

---
 docs/howto/ddl.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/howto/ddl.md b/docs/howto/ddl.md
index 2d51af7fad..4a25769592 100644
--- a/docs/howto/ddl.md
+++ b/docs/howto/ddl.md
@@ -230,3 +230,39 @@ type Comment struct {
 	Text string
 }
 ```
+
+### Directory-per-migration (up/down files)
+
+Some migration tools store each migration in its own directory with separate
+`up.sql` and `down.sql` files. For example:
+migrations/
+
+├── 001_init/
+
+│   ├── up.sql
+
+│   └── down.sql
+
+├── 002_add_users/
+
+│   ├── up.sql
+
+│   └── down.sql
+
+sqlc does not walk subdirectories automatically. To handle this pattern, use a
+glob pattern in your schema configuration:
+
+```yaml
+version: "2"
+sql:
+  - engine: "postgresql"
+    queries: "query.sql"
+    schema: "migrations/*/up.sql"
+    gen:
+      go:
+        package: "store"
+        out: "internal/store"
+```
+
+sqlc will parse all matched `up.sql` files in lexicographic order and ignore
+the `down.sql` files entirely.