Add a global --use-version-schema flag to the pgroll CLI (#919)

Add a global `--use-version-schema` option to the `pgroll` CLI to
enable/disable the creation and maintenance of version schema by
`pgroll` operations.

## Usage

Apply a `migrations/` directory without creating any version schema:

```
$ pgroll migrate migrations/ --complete --use-version-schema=false
```

Start a migration without creating a version schema:

```
$ pgroll start migrations/01_some_migration.yaml --use-version-schema=false
```

The option can also be set by specifying:

```env
PGROLL_USE_VERSION_SCHEMA=false
```
as an environment variable.

---

Fixes #872

Author: andrew-farries

cli-definition.json

@@ -302,6 +302,11 @@
       "description": "Postgres schema to use for the migration",
       "default": "public"
     },
+    {
+      "name": "use-version-schema",
+      "description": "Create version schemas for each migration",
+      "default": "true"
+    },
     {
       "name": "verbose",
       "description": "Enable verbose logging",

cmd/flags/flags.go

@@ -29,3 +29,7 @@ func Role() string {
 }
 
 func Verbose() bool { return viper.GetBool("VERBOSE") }
+
+func UseVersionSchema() bool {
+	return viper.GetBool("USE_VERSION_SCHEMA")
+}

cmd/latest_migration.go

@@ -24,7 +24,7 @@ func latestMigrationCmd() *cobra.Command {
 
 			latestVersion, err := latestMigrationName(ctx, migrationsDir)
 			if err != nil {
-				return fmt.Errorf("failed to get latest migration from database: %w", err)
+				return fmt.Errorf("failed to get latest migration: %w", err)
 			}
 
 			fmt.Println(latestVersion)

cmd/latest_schema.go

@@ -25,7 +25,7 @@ func latestSchemaCmd() *cobra.Command {
 
 			latestVersion, err := latestVersion(ctx, migrationsDir)
 			if err != nil {
-				return fmt.Errorf("failed to get latest migration from database: %w", err)
+				return fmt.Errorf("failed to get latest version: %w", err)
 			}
 
 			fmt.Println(latestVersion)

cmd/root.go

@@ -24,6 +24,7 @@ func NewRoll(ctx context.Context) (*roll.Roll, error) {
 	role := flags.Role()
 	skipValidation := flags.SkipValidation()
 	verbose := flags.Verbose()
+	useVersionSchema := flags.UseVersionSchema()
 
 	state, err := state.New(ctx, pgURL, stateSchema, state.WithPgrollVersion(Version))
 	if err != nil {
@@ -35,6 +36,7 @@ func NewRoll(ctx context.Context) (*roll.Roll, error) {
 		roll.WithRole(role),
 		roll.WithSkipValidation(skipValidation),
 		roll.WithLogging(verbose),
+		roll.WithVersionSchema(useVersionSchema),
 	)
 }
 
@@ -85,13 +87,15 @@ func Prepare() *cobra.Command {
 	rootCmd.PersistentFlags().String("pgroll-schema", "pgroll", "Postgres schema to use for pgroll internal state")
 	rootCmd.PersistentFlags().Int("lock-timeout", 500, "Postgres lock timeout in milliseconds for pgroll DDL operations")
 	rootCmd.PersistentFlags().String("role", "", "Optional postgres role to set when executing migrations")
+	rootCmd.PersistentFlags().Bool("use-version-schema", true, "Create version schemas for each migration")
 	rootCmd.PersistentFlags().Bool("verbose", false, "Enable verbose logging")
 
 	viper.BindPFlag("PG_URL", rootCmd.PersistentFlags().Lookup("postgres-url"))
 	viper.BindPFlag("SCHEMA", rootCmd.PersistentFlags().Lookup("schema"))
 	viper.BindPFlag("STATE_SCHEMA", rootCmd.PersistentFlags().Lookup("pgroll-schema"))
 	viper.BindPFlag("LOCK_TIMEOUT", rootCmd.PersistentFlags().Lookup("lock-timeout"))
 	viper.BindPFlag("ROLE", rootCmd.PersistentFlags().Lookup("role"))
+	viper.BindPFlag("USE_VERSION_SCHEMA", rootCmd.PersistentFlags().Lookup("use-version-schema"))
 	viper.BindPFlag("VERBOSE", rootCmd.PersistentFlags().Lookup("verbose"))
 
 	// register subcommands

cmd/start.go

@@ -105,8 +105,14 @@ func runMigration(ctx context.Context, m *roll.Roll, migration *migrations.Migra
 		}
 	}
 
-	viewName := roll.VersionedSchemaName(flags.Schema(), migration.VersionSchemaName())
-	msg := fmt.Sprintf("New version of the schema available under the postgres %q schema", viewName)
+	var msg string
+	if m.UseVersionSchema() {
+		viewName := roll.VersionedSchemaName(flags.Schema(), migration.VersionSchemaName())
+		msg = fmt.Sprintf("New version of the schema available under the postgres %q schema", viewName)
+	} else {
+		msg = fmt.Sprintf("Migration %q started successfully", migration.Name)
+	}
+
 	sp.Success(msg)
 
 	return nil

pkg/roll/execute_test.go

@@ -84,6 +84,20 @@ func TestWithUseVersionSchemaOption(t *testing.T) {
 			require.False(t, exists)
 		})
 	})
+
+	t.Run("roll instance reports that it does not use version schema", func(t *testing.T) {
+		testutils.WithMigratorInSchemaAndConnectionToContainerWithOptions(t, "public", opts, func(mig *roll.Roll, db *sql.DB) {
+			// The roll instance correctly reports tht it does not use version schema
+			require.False(t, mig.UseVersionSchema())
+		})
+	})
+
+	t.Run("roll instance reports that it does use version schema", func(t *testing.T) {
+		testutils.WithMigratorAndConnectionToContainer(t, func(mig *roll.Roll, db *sql.DB) {
+			// The roll instance correctly reports that it uses version schema
+			require.True(t, mig.UseVersionSchema())
+		})
+	})
 }
 
 func TestPreviousVersionIsDroppedAfterMigrationCompletion(t *testing.T) {

pkg/roll/roll.go

@@ -148,6 +148,10 @@ func (m *Roll) Schema() string {
 	return m.schema
 }
 
+func (m *Roll) UseVersionSchema() bool {
+	return !m.disableVersionSchemas
+}
+
 // Status returns the current migration status
 func (m *Roll) Status(ctx context.Context, schema string) (*state.Status, error) {
 	return m.state.Status(ctx, schema)