feat: support multiple migration sections in a single file (#620)

# Support Multiple Migrations in a Single File

## Problem
previously enforced a "one migration per file" rule, leading to file
proliferation and fragmented workflows. Related changes (e.g., table
creation followed by alterations) required separate files, complicating
organization and maintenance.

## Solution
**Group multiple migrations in a single file** using `-- migrate:up`
comments as section delimiters. Each `-- migrate:up` and `--
migrate:down` block is treated as a distinct migration, with automatic
versioning and ordered execution.

## Key Changes
- **Section-Based Parsing**:  
Files are split into migrations wherever `-- migrate:up` is encountered.
Corresponding `-- migrate:down` blocks define rollback logic.

## Backward Compatibility
Existing single-migration files remain valid. New multi-section
migrations coexist seamlessly.

## Example
**File:** `20231010120000_create_users.sql`
```sql
-- migrate:up
CREATE TABLE users (id SERIAL PRIMARY KEY);

-- migrate:down
DROP TABLE users;

-- migrate:up
ALTER TABLE users ADD COLUMN email VARCHAR;

-- migrate:down
ALTER TABLE users DROP COLUMN email;
```

Author: igorvoltaic

README.md

@@ -362,6 +362,22 @@ create table users (
 -- migrate:down
 ```
 
+For related changes, it is possible to include multiple migrations in a single file using additional `migrate:up` and `migrate:down` sections. Migration file either succeeds or fails as a whole.
+
+```sql
+-- migrate:up
+CREATE TABLE users (id SERIAL PRIMARY KEY);
+
+-- migrate:down
+DROP TABLE users;
+
+-- migrate:up
+ALTER TABLE users ADD COLUMN email VARCHAR;
+
+-- migrate:down
+ALTER TABLE users DROP COLUMN email;
+```
+
 > Note: Migration files are named in the format `[version]_[description].sql`. Only the version (defined as all leading numeric characters in the file name) is recorded in the database, so you can safely rename a migration file without having any effect on its current application state.
 
 ### Running Migrations

pkg/dbmate/db.go

@@ -384,32 +384,34 @@ func (db *DB) Migrate() error {
 			return err
 		}
 
-		execMigration := func(tx dbutil.Transaction) error {
-			// run actual migration
-			result, err := tx.Exec(parsed.Up)
-			if err != nil {
-				return drv.QueryError(parsed.Up, err)
-			} else if db.Verbose {
-				db.printVerbose(result)
+		for _, migrationSection := range parsed {
+			execMigration := func(tx dbutil.Transaction) error {
+				// run actual migration
+				result, err := tx.Exec(migrationSection.Up)
+				if err != nil {
+					return drv.QueryError(migrationSection.Up, err)
+				} else if db.Verbose {
+					db.printVerbose(result)
+				}
+
+				// record migration
+				return drv.InsertMigration(tx, migration.Version)
 			}
 
-			// record migration
-			return drv.InsertMigration(tx, migration.Version)
-		}
-
-		if parsed.UpOptions.Transaction() {
-			// begin transaction
-			err = doTransaction(sqlDB, execMigration)
-		} else {
-			// run outside of transaction
-			err = execMigration(sqlDB)
-		}
+			if migrationSection.UpOptions.Transaction() {
+				// begin transaction
+				err = doTransaction(sqlDB, execMigration)
+			} else {
+				// run outside of transaction
+				err = execMigration(sqlDB)
+			}
 
-		elapsed := time.Since(start)
-		fmt.Fprintf(db.Log, "Applied: %s in %s\n", migration.FileName, elapsed)
+			elapsed := time.Since(start)
+			fmt.Fprintf(db.Log, "Applied: %s in %s\n", migration.FileName, elapsed)
 
-		if err != nil {
-			return err
+			if err != nil {
+				return err
+			}
 		}
 	}
 
@@ -548,42 +550,44 @@ func (db *DB) Rollback() error {
 
 	start := time.Now()
 
-	parsed, err := latest.Parse()
+	parsedSections, err := latest.Parse()
 	if err != nil {
 		return err
 	}
 
-	execMigration := func(tx dbutil.Transaction) error {
-		// rollback migration
-		result, err := tx.Exec(parsed.Down)
-		if err != nil {
-			return drv.QueryError(parsed.Down, err)
-		} else if db.Verbose {
-			db.printVerbose(result)
-		}
+	for _, migrationSection := range parsedSections {
+		execMigration := func(tx dbutil.Transaction) error {
+			// rollback migration
+			result, err := tx.Exec(migrationSection.Down)
+			if err != nil {
+				return drv.QueryError(migrationSection.Down, err)
+			} else if db.Verbose {
+				db.printVerbose(result)
+			}
 
-		// remove migration record
-		return drv.DeleteMigration(tx, latest.Version)
-	}
+			// remove migration record
+			return drv.DeleteMigration(tx, latest.Version)
+		}
 
-	if parsed.DownOptions.Transaction() {
-		// begin transaction
-		err = doTransaction(sqlDB, execMigration)
-	} else {
-		// run outside of transaction
-		err = execMigration(sqlDB)
-	}
+		if migrationSection.DownOptions.Transaction() {
+			// begin transaction
+			err = doTransaction(sqlDB, execMigration)
+		} else {
+			// run outside of transaction
+			err = execMigration(sqlDB)
+		}
 
-	elapsed := time.Since(start)
-	fmt.Fprintf(db.Log, "Rolled back: %s in %s\n", latest.FileName, elapsed)
+		elapsed := time.Since(start)
+		fmt.Fprintf(db.Log, "Rolled back: %s in %s\n", latest.FileName, elapsed)
 
-	if err != nil {
-		return err
-	}
+		if err != nil {
+			return err
+		}
 
-	// automatically update schema file, silence errors
-	if db.AutoDumpSchema {
-		_ = db.DumpSchema()
+		// automatically update schema file, silence errors
+		if db.AutoDumpSchema {
+			_ = db.DumpSchema()
+		}
 	}
 
 	return nil

pkg/dbmate/db_test.go

@@ -618,8 +618,10 @@ drop table users;
 	require.Equal(t, false, actual[2].Applied)
 
 	// test parsing first migration
-	parsed, err := actual[0].Parse()
+	parsedSections, err := actual[0].Parse()
 	require.Nil(t, err)
+
+	parsed := parsedSections[0]
 	require.Equal(t, "-- migrate:up\ncreate table users (id serial, name text);\n", parsed.Up)
 	require.True(t, parsed.UpOptions.Transaction())
 	require.Equal(t, "-- migrate:down\ndrop table users;\n", parsed.Down)

pkg/dbmate/migration.go

@@ -28,7 +28,7 @@ func (m *Migration) readFile() (string, error) {
 }
 
 // Parse a migration
-func (m *Migration) Parse() (*ParsedMigration, error) {
+func (m *Migration) Parse() ([]*ParsedMigration, error) {
 	contents, err := m.readFile()
 	if err != nil {
 		return nil, err
@@ -76,14 +76,32 @@ var (
 	ErrParseUnexpectedStmt = errors.New("dbmate does not support statements preceding the '-- migrate:up' block")
 )
 
-// parseMigrationContents parses the string contents of a migration.
+func parseMigrationContents(contents string) ([]*ParsedMigration, error) {
+	sectionSubstrings, err := getMigrationSectionSubstrings(contents)
+	if err != nil {
+		return nil, err
+	}
+
+	var migrationSections []*ParsedMigration
+	for _, sectionSubstring := range sectionSubstrings {
+		migrationSection, err := parseMigrationSection(sectionSubstring)
+		if err != nil {
+			return nil, err
+		}
+		migrationSections = append(migrationSections, migrationSection)
+	}
+
+	return migrationSections, nil
+}
+
+// parseMigrationSection parses the string contents of a migration section.
 // It will return two Migration objects, the first representing the "up"
 // block and the second representing the "down" block. This function
-// requires that at least an up block was defined and will otherwise
+// requires that up and down blocks were defined and will otherwise
 // return an error.
-func parseMigrationContents(contents string) (*ParsedMigration, error) {
-	upDirectiveStart, hasDefinedUpBlock := getMatchPosition(contents, upRegExp)
-	downDirectiveStart, hasDefinedDownBlock := getMatchPosition(contents, downRegExp)
+func parseMigrationSection(section string) (*ParsedMigration, error) {
+	upDirectiveStart, hasDefinedUpBlock := getMatchPosition(section, upRegExp)
+	downDirectiveStart, hasDefinedDownBlock := getMatchPosition(section, downRegExp)
 
 	if !hasDefinedUpBlock {
 		return nil, ErrParseMissingUp
@@ -94,12 +112,9 @@ func parseMigrationContents(contents string) (*ParsedMigration, error) {
 	if upDirectiveStart > downDirectiveStart {
 		return nil, ErrParseWrongOrder
 	}
-	if statementsPrecedeMigrateBlocks(contents, upDirectiveStart) {
-		return nil, ErrParseUnexpectedStmt
-	}
 
-	upBlock := substring(contents, upDirectiveStart, downDirectiveStart)
-	downBlock := substring(contents, downDirectiveStart, len(contents))
+	upBlock := substring(section, upDirectiveStart, downDirectiveStart)
+	downBlock := substring(section, downDirectiveStart, len(section))
 
 	parsed := ParsedMigration{
 		Up:          upBlock,
@@ -117,25 +132,25 @@ func parseMigrationContents(contents string) (*ParsedMigration, error) {
 //
 //	fmt.Printf("%#v", parseMigrationOptions("-- migrate:up transaction:false"))
 //	// migrationOptions{"transaction": "false"}
-func parseMigrationOptions(contents string) ParsedMigrationOptions {
+func parseMigrationOptions(section string) ParsedMigrationOptions {
 	options := make(migrationOptions)
 
 	// remove everything after first newline
-	contents = strings.SplitN(contents, "\n", 2)[0]
+	section = strings.SplitN(section, "\n", 2)[0]
 
 	// strip away the -- migrate:[up|down] part
-	contents = blockDirectiveRegExp.ReplaceAllString(contents, "")
+	section = blockDirectiveRegExp.ReplaceAllString(section, "")
 
 	// remove leading and trailing whitespace
-	contents = strings.TrimSpace(contents)
+	section = strings.TrimSpace(section)
 
 	// return empty options if nothing is left to parse
-	if contents == "" {
+	if section == "" {
 		return options
 	}
 
 	// split the options string into pairs, e.g. "transaction:false foo:bar" -> []string{"transaction:false", "foo:bar"}
-	stringPairs := whitespaceRegExp.Split(contents, -1)
+	stringPairs := whitespaceRegExp.Split(section, -1)
 
 	for _, stringPair := range stringPairs {
 		// split stringified pair into key and value pairs, e.g. "transaction:false" -> []string{"transaction", "false"}
@@ -200,6 +215,43 @@ func getMatchPosition(s string, re *regexp.Regexp) (int, bool) {
 	return match[0], true
 }
 
+func getMigrationSectionSubstrings(contents string) ([]string, error) {
+	// Regex to match blocks starting with "-- migrate:up" and ending before the next one or EOF
+	allUpDirectives := upRegExp.FindAllStringIndex(contents, -1)
+
+	if allUpDirectives == nil {
+		return nil, ErrParseMissingUp
+	}
+
+	if statementsPrecedeMigrateBlocks(contents, allUpDirectives[0][0]) {
+		return nil, ErrParseUnexpectedStmt
+	}
+
+	var sectionBeginEndIndices [][]int
+	for i := range len(allUpDirectives) {
+		start := allUpDirectives[i][0]
+		var end int
+		if i < len(allUpDirectives)-1 {
+			end = allUpDirectives[i+1][0]
+		} else {
+			end = len(contents)
+		}
+		sectionBeginEndIndices = append(sectionBeginEndIndices, []int{start, end})
+	}
+
+	var sectionSubstrings []string
+	for _, sectionBeginEnd := range sectionBeginEndIndices {
+		begin, end := sectionBeginEnd[0], sectionBeginEnd[1]
+		contentsSubstring := substring(contents, begin, end)
+		if len(downRegExp.FindAllStringIndex(contentsSubstring, -1)) > 1 {
+			return nil, ErrParseMissingUp
+		}
+		sectionSubstrings = append(sectionSubstrings, contentsSubstring)
+	}
+
+	return sectionSubstrings, nil
+}
+
 func substring(s string, begin, end int) string {
 	if begin == -1 || end == -1 {
 		return ""