From c004851e2141b7bea22faff4cb64920231cfb470 Mon Sep 17 00:00:00 2001
From: Robin Seitz <robin@kater.ai>
Date: Mon, 5 Aug 2024 12:45:02 -0700
Subject: [PATCH] fix(docs): Add ordering warning for numeric goose migration
 (#3481)

When using Goose with numeric migrations, if the migration files aren't in
lexographic order SQLC parses them in the wrong order. This is similar to the issue that occurs
with golang-migrate. This pr documents this behaviour.
---
 docs/howto/ddl.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/howto/ddl.md b/docs/howto/ddl.md
index 0b25800365..2d51af7fad 100644
--- a/docs/howto/ddl.md
+++ b/docs/howto/ddl.md
@@ -145,6 +145,31 @@ type Post struct {
 
 ### goose
 
+**Warning:**
+sqlc parses migration files in lexicographic order. **If you are using numeric filenames for migrations in Goose and you choose to have sqlc enumerate your migration files**,
+make sure their numeric ordering matches their lexicographic ordering to avoid
+unexpected behavior. This can be done by prepending enough zeroes to the
+migration filenames.
+
+This doesn't work as intended.
+
+```
+1_initial.sql
+...
+9_foo.sql
+# this migration file will be parsed BEFORE 9_foo
+10_bar.sql
+```
+
+This worked as intended.
+
+```
+001_initial.sql
+...
+009_foo.sql
+010_bar.sql
+```
+
 ```sql
 -- +goose Up
 CREATE TABLE post (