Skip to content

Update pgroll latest to take account of migration version_schema #896

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 3 commits into from
Jun 13, 2025
Merged

Update pgroll latest to take account of migration version_schema #896

merged 3 commits into from
Jun 13, 2025

Conversation

andrew-farries
Copy link
Collaborator

#884 added support for the version_schema field in migration files, allowing a migration to specify the name of the version schema that will be created when the migration is applied:

# migration files can now specify the version schema 
# name to be created by the migration
version_schema: my_version_schema
operations:
  - create_table:
      name: items
      columns:
        - name: id
          type: serial
          pk: true
        - name: name
          type: varchar(255)

When applied as pgroll start 01_create_table.yaml, this migration will take the name of its version schema from the migration file:

+-----------------------+-------------------+
| Name                  | Owner             |
|-----------------------+-------------------|
...
| public_my_version_schema | postgres       |
+-----------------------+-------------------+

If version_schema is not specified, the name of the version schema defaults to the filename, as before.

This PR updates the pgroll latest command to take account of this new behaviour, where the version schema name can be decoupled from its filename.

Previous behaviour:

  • pgroll latest schema: would return the most recent migration name prefixed with the schema name, eg public_01_create_table.
  • pgroll latest migration: would return the most receent migration name without the schema prefix, eg 01_create_table.

New behaviour:

  • pgroll latest schema: returns the version schema name of the most recent migration prefixed with the schema name, eg public_01_set_by_version_schema_field
  • pgroll latest migration: returns the name of the most recent migration, without the schema prefix, eg, 01_create_table.

Examples

Run:

pgroll migrate examples/ --complete

to apply all example migrations. Now:

# get the **name** of the latest migration applied to the target database
$ pgroll latest migration
56_with_version_schema
# get the **version schema name** of the latest migration applied to the target database
$ pgroll latest schema
public_with_version_schema
# get the **name** of the latest migration in the migrations/ folder
$ pgroll latest migration --local examples/
56_with_version_schema
# get the **version schema name** of the latest migration in the migrations/ folder
$ pgroll latest schema --local examples/
public_with_version_schema

@github-actions github-actions bot temporarily deployed to Docs Preview June 13, 2025 09:22 Inactive
@andrew-farries andrew-farries force-pushed the update-pgroll-latest-for-version-schema branch from 20e299c to 88edd61 Compare June 13, 2025 09:24
@github-actions github-actions bot temporarily deployed to Docs Preview June 13, 2025 09:25 Inactive
@andrew-farries andrew-farries force-pushed the update-pgroll-latest-for-version-schema branch from 88edd61 to ad4a21e Compare June 13, 2025 09:33
@github-actions github-actions bot temporarily deployed to Docs Preview June 13, 2025 09:33 Inactive
@andrew-farries
Add new Latest* functions to pkg/roll`
e138384 
Add new functions to `pkg/roll` concerning retrieving latest migrations
locally and remotely:

* `LatestMigrationNameLocal`: Returns the name of the latest migration
  in a local migrations directory
* `LatestMigrationNameRemote`: Returns the name of the latest migration
  in the target database.

Add tests for both of these new functions.

Together with the existing `LatestVersionLocal` and
`LatestVersionRemote` functions, these new functions make it possible to
retrieve latest migration information, taking into account both the
version schema and the migration name.
@andrew-farries
Update pgroll latest command
465e10f 
Previous behaviour:

* `pgroll latest schema`: would return the most recent migration name
  prefixed with the schema name, eg `public_01_create_table`.
* `pgroll latest migration`: would return the most receent migration
  name without the schema prefix, eg `01_create_table`.

New behaviour:

* `pgroll latest schema`: returns the version schema name of the most
  recent migration prefixed with the schema name, eg
  `public_01_set_by_version_schema_field`
* `pgroll latest migration`: returns the name of the most recent
  migration, without the schema prefix, eg, `01_create_table`.
@andrew-farries
Update documentation
a833fb2 
* Tidy up the `latest` command documentation to clarify the difference
  between the schema version and migration name outputs.
* Add a section to the operations documentation explaining the
  difference between migration names and version schema names.
@andrew-farries andrew-farries force-pushed the update-pgroll-latest-for-version-schema branch from ad4a21e to a833fb2 Compare June 13, 2025 09:40
@github-actions github-actions bot temporarily deployed to Docs Preview June 13, 2025 09:40 Inactive
@github-actions GitHub Actions
Copy link

Merging this branch will increase overall coverage

Impacted Packages Coverage Δ 🤖
github.com/xataio/pgroll/cmd 0.00% (ø)
github.com/xataio/pgroll/pkg/roll 79.56% (+0.61%) 👍
Coverage by file

Changed files (no unit tests)

Changed File Coverage Δ Total Covered Missed 🤖
github.com/xataio/pgroll/cmd/latest.go 0.00% (ø) 4 (-45) 0 4 (-45)
github.com/xataio/pgroll/cmd/latest_migration.go 0.00% (ø) 30 (+30) 0 30 (+30)
github.com/xataio/pgroll/cmd/latest_schema.go 0.00% (ø) 30 (+30) 0 30 (+30)
github.com/xataio/pgroll/pkg/roll/latest.go 86.67% (+5.42%) 30 (+14) 26 (+13) 4 (+1) 👍

Please note that the "Total", "Covered", and "Missed" counts above refer to code statements instead of lines of code. The value in brackets refers to the test coverage of that file in the old version of the code.

Changed unit test files

  • github.com/xataio/pgroll/pkg/roll/latest_test.go
  • github.com/xataio/pgroll/pkg/roll/unapplied_test.go

@andrew-farries andrew-farries marked this pull request as ready for review June 13, 2025 09:43
@andrew-farries andrew-farries requested review from kvch and divyenduz June 13, 2025 09:43
divyenduz
divyenduz approved these changes Jun 13, 2025
View reviewed changes
Copy link
Contributor

@divyenduz divyenduz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, as I understand it, this is an internal change and not breaking in the public API correct?

@andrew-farries
Copy link
Collaborator Author

LGTM, as I understand it, this is an internal change and not breaking in the public API correct?

Yes, the command names and flags are unchanged.

@andrew-farries andrew-farries merged commit 4971378 into main Jun 13, 2025
30 checks passed
@andrew-farries andrew-farries deleted the update-pgroll-latest-for-version-schema branch June 13, 2025 12:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@divyenduz divyenduz divyenduz approved these changes

@kvch kvch kvch approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@andrew-farries @divyenduz @kvch