Split pgroll latest (#861)

Split pgroll latest into
- pgroll latest migration
- pgroll latest schema

![CleanShot 2025-05-28 at 20 11
54@2x](https://github.com/user-attachments/assets/6cf28af5-0bf5-4af0-8e90-264b1d953f02)

Fix #845

Amp: https://ampcode.com/threads/T-51521447-5949-4653-bc50-d7c846a27757

Author: divyenduz

cli-definition.json

@@ -96,24 +96,44 @@
     },
     {
       "name": "latest",
-      "short": "Print the name of the latest schema version, either in the target database or a local directory",
+      "short": "Print the name of the latest schema version or migration",
       "use": "latest",
-      "example": "latest --local ./migrations",
-      "flags": [
+      "example": "",
+      "flags": [],
+      "subcommands": [
         {
-          "name": "local",
-          "shorthand": "l",
-          "description": "retrieve the latest version from a local migration directory",
-          "default": ""
+          "name": "migration",
+          "short": "Print the latest migration name (without schema prefix)",
+          "use": "migration",
+          "example": "latest migration --local ./migrations",
+          "flags": [
+            {
+              "name": "local",
+              "shorthand": "l",
+              "description": "retrieve the latest version from a local migration directory",
+              "default": ""
+            }
+          ],
+          "subcommands": [],
+          "args": []
         },
         {
-          "name": "with-schema",
-          "shorthand": "s",
-          "description": "prefix the version with the schema name",
-          "default": "false"
+          "name": "schema",
+          "short": "Print the latest schema version (migration name prefixed with schema)",
+          "use": "schema",
+          "example": "latest schema --local ./migrations",
+          "flags": [
+            {
+              "name": "local",
+              "shorthand": "l",
+              "description": "retrieve the latest version from a local migration directory",
+              "default": ""
+            }
+          ],
+          "subcommands": [],
+          "args": []
         }
       ],
-      "subcommands": [],
       "args": []
     },
     {

cmd/latest.go

@@ -13,29 +13,33 @@ import (
 )
 
 func latestCmd() *cobra.Command {
-	var withSchema bool
+	withSchema := true
+	latestCmd := &cobra.Command{
+		Use:   "latest",
+		Short: "Print the name of the latest schema version or migration",
+		Long:  "Print the name of the latest schema version or migration, either in the target database or a local directory",
+	}
+
+	latestCmd.AddCommand(latestSchemaCmd(withSchema))
+	latestCmd.AddCommand(latestMigrationCmd(!withSchema))
+
+	return latestCmd
+}
+
+func latestSchemaCmd(withSchema bool) *cobra.Command {
 	var migrationsDir string
 
-	latestCmd := &cobra.Command{
-		Use:     "latest",
-		Short:   "Print the name of the latest schema version, either in the target database or a local directory",
-		Example: "latest --local ./migrations",
+	schemaCmd := &cobra.Command{
+		Use:     "schema",
+		Short:   "Print the latest schema version (migration name prefixed with schema)",
+		Example: "latest schema --local ./migrations",
 		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
-			var latestVersion string
-			var err error
-			if migrationsDir != "" {
-				latestVersion, err = latestVersionLocal(ctx, migrationsDir, withSchema)
-				if err != nil {
-					return fmt.Errorf("failed to get latest version from directory %q: %w", migrationsDir, err)
-				}
-			} else {
-				latestVersion, err = latestVersionRemote(ctx, withSchema)
-				if err != nil {
-					return fmt.Errorf("failed to get latest version from database: %w", err)
-				}
+			latestVersion, err := getLatestVersion(ctx, migrationsDir, withSchema)
+			if err != nil {
+				return fmt.Errorf("failed to get latest version from database: %w", err)
 			}
 
 			fmt.Println(latestVersion)
@@ -44,10 +48,46 @@ func latestCmd() *cobra.Command {
 		},
 	}
 
-	latestCmd.Flags().BoolVarP(&withSchema, "with-schema", "s", false, "prefix the version with the schema name")
-	latestCmd.Flags().StringVarP(&migrationsDir, "local", "l", "", "retrieve the latest version from a local migration directory")
+	schemaCmd.Flags().StringVarP(&migrationsDir, "local", "l", "", "retrieve the latest version from a local migration directory")
 
-	return latestCmd
+	return schemaCmd
+}
+
+func latestMigrationCmd(withSchema bool) *cobra.Command {
+	var migrationsDir string
+
+	migrationCmd := &cobra.Command{
+		Use:     "migration",
+		Short:   "Print the latest migration name (without schema prefix)",
+		Example: "latest migration --local ./migrations",
+		Args:    cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+
+			latestVersion, err := getLatestVersion(ctx, migrationsDir, withSchema)
+			if err != nil {
+				return fmt.Errorf("failed to get latest version from database: %w", err)
+			}
+
+			fmt.Println(latestVersion)
+
+			return nil
+		},
+	}
+
+	migrationCmd.Flags().StringVarP(&migrationsDir, "local", "l", "", "retrieve the latest version from a local migration directory")
+
+	return migrationCmd
+}
+
+// getLatestVersion returns the latest migration version from a local
+// migrations directory or remote database, optionally prepending the schema
+// name to which the migration is applied.
+func getLatestVersion(ctx context.Context, migrationsDir string, withSchema bool) (string, error) {
+	if migrationsDir != "" {
+		return latestVersionLocal(ctx, migrationsDir, withSchema)
+	}
+	return latestVersionRemote(ctx, withSchema)
 }
 
 // latestVersionLocal returns the latest migration version from a local

docs/cli/latest.mdx

@@ -1,42 +1,75 @@
 ---
 title: Latest
-description: Prints the latest schema version in either the target database or a local directory of migration files.
+description: Prints the latest schema version or migration name in either the target database or a local directory of migration files.
 ---
 
 ## Command
 
-By default, `pgroll latest` prints the latest version in the target database. Use the `--local` flag to print the latest version in a local directory of migration files instead.
+The `pgroll latest` command has two subcommands:
 
-In both cases, the `--with-schema` flag can be used to prefix the latest version with the schema name.
+- `pgroll latest schema` - prints the latest schema version (migration name prefixed with schema name)
+- `pgroll latest migration` - prints the latest migration name (without schema prefix)
 
-### Database
+Both subcommands support the `--local` flag to retrieve the latest version from a local directory of migration files instead of the target database.
+
+### Schema Command
+
+#### Database
 
 Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) have been applied to the `public` schema in the target database, running:
 
 ```
-$ pgroll latest
+$ pgroll latest schema
 ```
 
-will print the latest version in the target database:
+will print the latest schema version in the target database:
 
 ```
-45_add_table_check_constraint
+public_55_add_primary_key_constraint_to_table
 ```
 
-The exact output will vary as the `examples/` directory is updated.
+#### Local
+
+Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) are on disk in a directory called `examples`, running:
+
+```
+$ pgroll latest schema --local examples/
+```
+
+will print the latest schema version in the directory:
+
+```
+public_55_add_primary_key_constraint_to_table
+```
+
+### Migration Command
+
+#### Database
+
+Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) have been applied to the `public` schema in the target database, running:
+
+```
+$ pgroll latest migration
+```
+
+will print the latest migration name in the target database:
+
+```
+55_add_primary_key_constraint_to_table
+```
 
-### Local
+#### Local
 
 Assuming that the [example migrations](https://github.com/xataio/pgroll/tree/main/examples) are on disk in a directory called `examples`, running:
 
 ```
-$ pgroll latest --local examples/
+$ pgroll latest migration --local examples/
 ```
 
-will print the latest migration in the directory:
+will print the latest migration name in the directory:
 
 ```
-45_add_table_check_constraint
+55_add_primary_key_constraint_to_table
 ```
 
 The exact output will vary as the `examples/` directory is updated.

docs/guides/clientapps.mdx

@@ -25,6 +25,7 @@ if err != nil {
     return nil, fmt.Errorf("failed to set search path: %s", err)
 }
 ```
+
 In practice, the `searchPath` variable would be provided to the application as an environment variable.
 
 Set `search_path` in Python using `psycopg2` with the [`Connection` class](https://www.psycopg.org/psycopg3/docs/api/connections.html#psycopg.Connection):
@@ -39,23 +40,23 @@ with psycopg2.connect('dbname=postgres user=postgres password=postgres options=-
 Another example for setting `search_path` in Node.js:
 
 ```js
-const { Client } = require('pg');
+const { Client } = require("pg");
 
 const client = new Client({
-  user: 'postgres',
-  host: 'localhost',
-  database: 'postgres',
-  password: 'postgres',
+  user: "postgres",
+  host: "localhost",
+  database: "postgres",
+  password: "postgres",
   port: 5432,
 });
 
 client.connect();
 
-client.query('SET search_path TO public_02_add_assignee_column', (err, res) => {
+client.query("SET search_path TO public_02_add_assignee_column", (err, res) => {
   if (err) {
-    console.error('Error setting search_path', err.stack);
+    console.error("Error setting search_path", err.stack);
   } else {
-    console.log('search_path set successfully');
+    console.log("search_path set successfully");
     // Perform your database operations here
   }
 
@@ -64,19 +65,17 @@ client.query('SET search_path TO public_02_add_assignee_column', (err, res) => {
 });
 ```
 
-
 ## CI/CD pipelines
 
-`pgroll` can tell you the name of the latest schema version, either in the target database or local directory using the `latest` command.
+`pgroll` can tell you the name of the latest schema version, either in the target database or local directory using the `latest schema` command.
 
 ```
-$ pgroll latest --with-schema
+$ pgroll latest schema
 public_02_add_assignee_column
 ```
 
 You can pass the `search_path` value to your application in your CI/CD pipeline, so your application can be tested against the latest database changes.
 
-
 ## What happens if the `search_path` is not set?
 
 If an application doesn't set the `search_path` for the connection, the `search_path` defaults to the `public` schema, meaning that the application will be working with the underlying tables directly rather than accessing them through the versioned views.