Ensure lex ordering of inferred migration names with respect to pgroll migrations (#899)

Ensure that inferred migrations are named appropriately with respect to
user created migrations to ensure correct lexicographical ordering of
migration files on disk.

## Reproduction

Before this PR, the problem with inferred migration naming was
reproducible as follows:

Create the following migration as `01_first_migration.yaml`:

```yaml
operations:
  - sql:
      up: SELECT 1
```

Apply the migration with `pgroll start --complete` .

On the target database, run some DDL:

```sql
CREATE TABLE foo(a int PRIMARY KEY);
```

Create another migration, `02_second_migration.yaml`:

```yaml
operations:
  - sql:
      up: SELECT 1
```

Apply the migration with `pgroll start --complete` .

Now pull the migration history into a temporary directory:

```yaml
$ pgroll pull tmp/
```

The migration history is not in the correct lexicographical order; the
inferred migration is ordered after the user-created migrations:

```
├──  01_first_migration.yaml
├──  02_second_migration.yaml
└──  sql_1fb6e25eba9678.yaml
```

## New behaviour

This PR fixes the problem by naming inferred migrations so that they
appear in the correct lexicographical order when pulled to disk with
`pgroll pull`:

The same steps as in the reproduction now result in these files on disk:

```
├──  01_first_migration.yaml
├──  01_first_migration_20250613120930931268.yaml
└──  02_second_migration.yaml
```

The inferred migration is now lex-ordered correctly between the two user
migrations by appending a fixed width timestamp suffix to the previous
migration name.

The inferred migration has its `version_schema` field set:

`cat 01_first_migration_20250613120930931268.yaml`:

``` 
version_schema: sql_e842123c
operations:
- sql:
    up: create table foo(id serial primary key)
```

This is to ensure that the version schema for the inferred migration
does not risk exceeding the Postgres 63 character limit for schema
names.

---

Fixes #882

Author: andrew-farries

pkg/state/init.sql

@@ -471,12 +471,36 @@ BEGIN
         AND migration_type = 'inferred'
         AND migration -> 'operations' -> 0 -> 'sql' ->> 'up' = current_query();
     -- Someone did a schema change without pgroll, include it in the history
-    SELECT
-        INTO migration_id pg_catalog.format('sql_%s', pg_catalog.substr(pg_catalog.md5(pg_catalog.random()::text), 0, 15));
+    -- Get the latest non-inferred migration name with microsecond timestamp for ordering
+    WITH latest_non_inferred AS (
+        SELECT
+            name
+        FROM
+            placeholder.migrations
+        WHERE
+            SCHEMA = schemaname
+            AND migration_type != 'inferred'
+        ORDER BY
+            created_at DESC
+        LIMIT 1
+)
+SELECT
+    INTO migration_id CASE WHEN EXISTS (
+        SELECT
+            1
+        FROM
+            latest_non_inferred) THEN
+        pg_catalog.format('%s_%s', (
+                SELECT
+                    name
+                FROM latest_non_inferred), pg_catalog.to_char(pg_catalog.clock_timestamp(), 'YYYYMMDDHH24MISSUS'))
+    ELSE
+        pg_catalog.format('00000_initial_%s', pg_catalog.to_char(pg_catalog.clock_timestamp(), 'YYYYMMDDHH24MISSUS'))
+    END;
     INSERT INTO placeholder.migrations (schema, name, migration, resulting_schema, done, parent, migration_type, created_at, updated_at)
-        VALUES (schemaname, migration_id, pg_catalog.json_build_object('operations', (
-                    SELECT
-                        pg_catalog.json_agg(pg_catalog.json_build_object('sql', pg_catalog.json_build_object('up', pg_catalog.current_query()))))),
+        VALUES (schemaname, migration_id, pg_catalog.json_build_object('version_schema', 'sql_' || substring(md5(random()::text), 1, 8), 'operations', (
+                SELECT
+                    pg_catalog.json_agg(pg_catalog.json_build_object('sql', pg_catalog.json_build_object('up', pg_catalog.current_query()))))),
             placeholder.read_schema (schemaname),
             TRUE,
             placeholder.latest_migration (schemaname),

pkg/state/state_test.go

@@ -15,7 +15,9 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/xataio/pgroll/internal/testutils"
+	"github.com/xataio/pgroll/pkg/backfill"
 	"github.com/xataio/pgroll/pkg/migrations"
+	"github.com/xataio/pgroll/pkg/roll"
 	"github.com/xataio/pgroll/pkg/schema"
 	"github.com/xataio/pgroll/pkg/state"
 )
@@ -263,13 +265,73 @@ func TestInferredMigration(t *testing.T) {
 				for i, wantMigration := range tt.wantMigrations {
 					gotMigration := gotMigrations[i]
 
-					assert.Equal(t, wantMigration, gotMigration)
+					// Ensure that the operations are equal; we don't care about the
+					// randomly generated `VersionSchema` field for the migration.
+					assert.Equal(t, wantMigration.Operations, gotMigration.Operations)
 				}
 			})
 		}
 	})
 }
 
+func TestInferredMigrationsHaveExpectedNamesAndVersionSchema(t *testing.T) {
+	t.Parallel()
+
+	t.Run("an inferred migration first in the history", func(t *testing.T) {
+		testutils.WithStateAndConnectionToContainer(t, func(st *state.State, db *sql.DB) {
+			ctx := context.Background()
+
+			// Execute a SQL DDL statement
+			_, err := db.ExecContext(ctx, "CREATE TABLE table1(id int)")
+			require.NoError(t, err)
+
+			// Get the migration history
+			history, err := st.SchemaHistory(ctx, "public")
+			require.NoError(t, err)
+
+			// Assert that the history contains one migration with the expected name
+			require.Len(t, history, 1)
+			require.Regexp(t, `^00000_initial_\d{20}$`, history[0].Migration.Name)
+			// Assert that the VersionSchema field matches the expected format
+			require.Regexp(t, "^sql_[0-9a-f]{8}", history[0].Migration.VersionSchema)
+		})
+	})
+
+	t.Run("an inferred migration following a pgroll migration", func(t *testing.T) {
+		testutils.WithMigratorAndConnectionToContainer(t, func(m *roll.Roll, db *sql.DB) {
+			ctx := context.Background()
+
+			// Execute a pgroll migration
+			err := m.Start(ctx, &migrations.Migration{
+				Name:       "01_initial_migration",
+				Operations: migrations.Operations{&migrations.OpRawSQL{Up: "SELECT 1"}},
+			}, backfill.NewConfig())
+			require.NoError(t, err)
+
+			// Complete the migration
+			err = m.Complete(ctx)
+			require.NoError(t, err)
+
+			// Execute a SQL DDL statement
+			_, err = db.ExecContext(ctx, "CREATE TABLE table1(id int)")
+			require.NoError(t, err)
+
+			// Get the migration history
+			history, err := m.State().SchemaHistory(ctx, "public")
+			require.NoError(t, err)
+
+			// Assert that the history contains two migrations with the expected
+			// names. The inferred migration should have a name that starts with
+			// the name of the preceding pgroll migration followed by a timestamp.
+			require.Len(t, history, 2)
+			require.Equal(t, "01_initial_migration", history[0].Migration.Name)
+			require.Regexp(t, `^01_initial_migration_\d{20}$`, history[1].Migration.Name)
+			// Assert that the VersionSchema field matches the expected format
+			require.Regexp(t, "^sql_[0-9a-f]{8}", history[1].Migration.VersionSchema)
+		})
+	})
+}
+
 func TestInferredMigrationsInTransactionHaveDifferentTimestamps(t *testing.T) {
 	ctx := context.Background()