Add pgroll latest url command (#927)

Add a `pgroll latest url` command to the CLI. The command returns a
Postgres connection string with the `search_path` option set to the
latest version schema name. This can be used to set the connection
string for an application to work with the latest schema version.

By default, with no arguments, `pgroll latest url` will use the
connection string set via the global `--postgres-url` (or
`PGROLL_PG_URL` env var). If an argument is given to `pgroll latest
url`, the command will use that as the base connection string instead.

The resulting connection string sets the `search_path` by setting the
`options` parameter in the URL query string:

```
options=-c search_path='public_01_some_migration'
```

As described in the Postgres [libpq
documentation](https://www.postgresql.org/docs/current/libpq-connect.html).

## Examples

With no connection string argument, use the connection string used by
`pgroll` itself:

```bash
$ export PGROLL_PG_URL=postgres://postgres:postgres@localhost:5432?sslmode=disable
$ pgroll latest url

postgres://postgres:postgres@localhost:5432?options=-c%20search_path%3Dpublic_05_some_migration&sslmode=disable
```

Take the connection string as a command line argument:

```bash
$ pgroll latest url postgres://me:[email protected]:5432

postgres://me:[email protected]:5432?options=-c%20search_path%3Dpublic_05_some_migration
```

Like `pgroll latest migration` and `pgroll latest schema`, `pgroll
latest url` takes a `--local/-l` flag to take the latest version schema
name from a directory of migration files rather than the target
database. This allows for a connection string to be constructed offline,
without having to lookup the latest version schema name in the target
database.

```bash
$ pgroll latest url --local migrations/ postgres://me:mypass@localhost:5432

postgres://me:mypass@localhost:5432?options=-c%20search_path%3Dpublic_05_some_migration
```

The resulting connection string can be used directly as an argument to
tools like `psql` that accept a connection string on the command line:

```bash
psql $(pgroll . latest url)
```

Documentation for the new command is added in
#928

Closes #900

Author: andrew-farries

cli-definition.json

@@ -138,6 +138,24 @@
           ],
           "subcommands": [],
           "args": []
+        },
+        {
+          "name": "url",
+          "short": "Print a database connection URL for the latest schema version",
+          "use": "url",
+          "example": "pgroll latest url <connection-string> --local ./migrations",
+          "flags": [
+            {
+              "name": "local",
+              "shorthand": "l",
+              "description": "retrieve the latest schema version from a local migration directory",
+              "default": ""
+            }
+          ],
+          "subcommands": [],
+          "args": [
+            "connection-string"
+          ]
         }
       ],
       "args": []

cmd/latest.go

@@ -15,6 +15,7 @@ func latestCmd() *cobra.Command {
 
 	latestCmd.AddCommand(latestSchemaCmd())
 	latestCmd.AddCommand(latestMigrationCmd())
+	latestCmd.AddCommand(latestURLCmd())
 
 	return latestCmd
 }

cmd/latest_url.go

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+	"github.com/xataio/pgroll/cmd/flags"
+	"github.com/xataio/pgroll/internal/connstr"
+)
+
+func latestURLCmd() *cobra.Command {
+	var migrationsDir string
+
+	urlCmd := &cobra.Command{
+		Use:       "url",
+		Short:     "Print a database connection URL for the latest schema version",
+		Long:      "Print a database connection URL for the latest schema version, either from the target database or a local directory",
+		Example:   "pgroll latest url <connection-string> --local ./migrations",
+		Args:      cobra.MaximumNArgs(1),
+		ValidArgs: []string{"connection-string"},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+
+			// Default to the Postgres URL from flags, or use the first argument if provided
+			pgURL := flags.PostgresURL()
+			if len(args) > 0 {
+				pgURL = args[0]
+			}
+
+			// Get the latest version schema name, either from the remote database or a local directory
+			latestVersion, err := latestVersion(ctx, migrationsDir)
+			if err != nil {
+				return fmt.Errorf("failed to get latest version: %w", err)
+			}
+
+			// Append the search_path option to the connection string
+			str, err := connstr.AppendSearchPathOption(pgURL, latestVersion)
+			if err != nil {
+				return fmt.Errorf("failed to add search_path option: %w", err)
+			}
+
+			fmt.Println(str)
+
+			return nil
+		},
+	}
+
+	urlCmd.Flags().StringVarP(&migrationsDir, "local", "l", "", "retrieve the latest schema version from a local migration directory")
+
+	return urlCmd
+}

internal/connstr/connstr.go

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package connstr
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+)
+
+// AppendSearchPathOption take a Postgres connection string in URL format and
+// produces the same connection string with the search_path option set to the
+// provided schema.
+func AppendSearchPathOption(connStr, schema string) (string, error) {
+	u, err := url.Parse(connStr)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse connection string: %w", err)
+	}
+
+	if schema == "" {
+		return connStr, nil
+	}
+
+	q := u.Query()
+	q.Set("options", fmt.Sprintf("-c search_path=%s", schema))
+	encodedQuery := q.Encode()
+
+	// Replace '+' with '%20' to ensure proper encoding of spaces within the
+	// `options` query parameter.
+	encodedQuery = strings.ReplaceAll(encodedQuery, "+", "%20")
+
+	u.RawQuery = encodedQuery
+
+	return u.String(), nil
+}

internal/connstr/connstr_test.go

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package connstr_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/xataio/pgroll/internal/connstr"
+)
+
+func TestAppendSearchPathOption(t *testing.T) {
+	tests := []struct {
+		Name     string
+		ConnStr  string
+		Schema   string
+		Expected string
+	}{
+		{
+			Name:     "empty schema doesn't change connection string",
+			ConnStr:  "postgres://postgres:postgres@localhost:5432?sslmode=disable",
+			Schema:   "",
+			Expected: "postgres://postgres:postgres@localhost:5432?sslmode=disable",
+		},
+		{
+			Name:     "can set options as the only query parameter",
+			ConnStr:  "postgres://postgres:postgres@localhost:5432",
+			Schema:   "apples",
+			Expected: "postgres://postgres:postgres@localhost:5432?options=-c%20search_path%3Dapples",
+		},
+		{
+			Name:     "can set options as an additional query parameter",
+			ConnStr:  "postgres://postgres:postgres@localhost:5432?sslmode=disable",
+			Schema:   "bananas",
+			Expected: "postgres://postgres:postgres@localhost:5432?options=-c%20search_path%3Dbananas&sslmode=disable",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.Name, func(t *testing.T) {
+			result, err := connstr.AppendSearchPathOption(tt.ConnStr, tt.Schema)
+			assert.NoError(t, err)
+
+			assert.Equal(t, tt.Expected, result)
+		})
+	}
+}