feat: support array format for create_index columns

[jamesvillarrubia]

Problem

Multi-column indexes require predictable column ordering for optimal query planner performance. The current OpCreateIndex implementation stores columns in a map[string]IndexField, which has non-deterministic iteration order in Go. This causes index columns to be created in random order rather than the user-specified order.

Example:

columns:
  product_id: {}
  is_active: {}
  deleted_at: {}

May generate CREATE INDEX ... (deleted_at, product_id, is_active) instead of the intended order.

Additionally, per-column settings (collation, sort order, nulls order, operator classes) were added in v0.10.0, but the map format makes it unclear which column should come first in multi-column indexes.

Solution

Support both array and map formats for the columns field:

Array Format (Recommended)

columns:
  - name: product_id
  - name: is_active
  - name: deleted_at
    sort: DESC

• Explicitly preserves column order
• Consistent with create_table operation format
• Required for multi-column indexes where order matters

Map Format (Backward Compatible)

columns:
  product_id: {}
  is_active: {}

• Still supported for single-column indexes
• YAML map key order is preserved during parsing (per YAML 1.2 spec)
• Deprecation warning logged for multi-column/partial indexes

Implementation

• OpCreateIndex.Columns internally stores []IndexColumn (array)
• Custom UnmarshalJSON/UnmarshalYAML methods detect format and convert appropriately
• Map format converted to array while preserving YAML key insertion order
• Execution pipeline uses ordered array throughout (no map conversion)
• JSON schema uses oneOf to validate both formats

Deprecation Strategy

Map format is deprecated only for:

• Multi-column indexes (2+ columns)
• Partial indexes (indexes with predicates)

Single-column indexes can continue using map format indefinitely.

Warning message:

DEPRECATION WARNING: Map format for columns is deprecated for multi-column 
and partial indexes. Use array format instead: columns: [{name: col1}, {name: col2}]. 
Map format does not preserve column order which is critical for index performance.

Changes

Component	Description
types.go	Changed OpCreateIndex.Columns from map to []IndexColumn
op_create_index_unmarshal.go	Custom unmarshalers for format detection (~174 lines)
op_create_index_format.go	Deprecation warning logic (~61 lines)
dbactions.go	Use ordered array in execution pipeline
schema.json	Added oneOf validation for both formats
create_index.go	Generate array format from SQL
Documentation	Updated create_index.mdx with examples
Tests	3 new test files (~700 lines)

Test Coverage

Unit Tests (op_create_index_execution_test.go):

• Verifies actual SQL statement column order
• Runs 10 iterations to detect non-deterministic behavior
• Tests non-alphabetical ordering (zebra, alpha, beta)
• Tests column options (DESC, NULLS LAST, collations)

Integration Tests (op_create_index_test.go):

• Creates multi-column indexes in real PostgreSQL
• Queries pg_indexes to validate column order
• Verifies non-alphabetical ordering (status, user_id, created_at)

Format Tests (op_create_index_format_test.go):

• JSON/YAML array format parsing
• JSON/YAML map format conversion
• YAML key order preservation
• Backward compatibility with existing migrations
• Mixed format support in single migration

Example

# examples/55_create_multicolumn_index.yaml
name: create_multicolumn_index
operations:
  - create_index:
      name: idx_products_lookup
      table: products
      columns:
        - name: status
        - name: category_id  
        - name: created_at
          sort: DESC

Testing

✅ All 50+ existing create_index tests pass
✅ New execution test catches column ordering bugs
✅ Integration test validates real PostgreSQL indexes
✅ Format tests verify both JSON and YAML parsing
✅ Backward compatibility with map format maintained
✅ No linter errors

Migration Path

Existing migrations continue to work unchanged. Users can adopt array format gradually:

Before:

columns:
  user_id: {}
  created_at: {sort: DESC}

After:

columns:
  - name: user_id
  - name: created_at
    sort: DESC

[andrew-farries]

Hi @jamesvillarrubia, thanks for the PR.

It looks as though the use of oneOf is causing problems with type generation. You can see this locally with make generate.

We have two choices for how to resolve #1001:

• This PR
• Fix create_index operation column ordering #1009 (which is essentially OpCreateIndex columns must be ordered reve-ai/pgroll#5)

IMO it would be better to make a clean breaking change to the migration format now (and have the automated support for rewriting migration files via pgroll update that #1009 provides).