Skip to content

Remove support for the name field in migrations #852

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.

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

Merged
merged 8 commits into from
May 21, 2025

Conversation

andrew-farries
Copy link
Collaborator

@andrew-farries andrew-farries commented May 21, 2025

Remove support for specifying a name field in migration files:

name: 01_some_migration # <-- no longer supported
operations:
  - create_table:
      name: products
      columns:
        - name: id
          type: serial
          pk: true
        - name: name
          type: varchar(255)

The migration filename is the source of truth for the migration name. The name field was made optional and its use discouraged in the documentation in #744. This PR removes support for it entirely.

⚠️ Warning

This is a breaking change: migration files that set the name field will not be runnable by pgroll until the name field is removed.

Because of #812 pgroll pull and pgroll migrate will still work with migration histories that contain migrations with name fields.

The easiest way to remove the name fields from all migrations in the history is to pgroll pull the migration history; this will serialize all migrations in the remote history, removing the any name fields.


Closes #715 and #850

@andrew-farries andrew-farries added the breaking-changes breaking changes to pgroll label May 21, 2025
@github-actions github-actions bot temporarily deployed to Docs Preview May 21, 2025 11:58 Inactive
Migrations need to have a name but they shouldn't be set by the user.
Migration names are no longer deserialized as part of a migration so
this hack is no longer needed.
Use the `ReadMigration` function to deserialize migrations rather than
calling json.Unmarshal directly. This ensures that the migration name
field is set correcty.
Migrations no longer set the name of the migration in the migration
JSON.
Remove mentions of the `name` field in migrations.
@andrew-farries andrew-farries force-pushed the no-user-specified-migration-names branch from f6da8b9 to 03bf2ef Compare May 21, 2025 12:26
@github-actions github-actions bot temporarily deployed to Docs Preview May 21, 2025 12:26 Inactive
@andrew-farries andrew-farries marked this pull request as ready for review May 21, 2025 12:32
@andrew-farries andrew-farries requested a review from kvch May 21, 2025 12:37
@andrew-farries andrew-farries merged commit 3160548 into main May 21, 2025
30 checks passed
@andrew-farries andrew-farries deleted the no-user-specified-migration-names branch May 21, 2025 14:01
andrew-farries added a commit that referenced this pull request May 22, 2025
The name field is no longer supported as of #852.

Follow up to #852.
andrew-farries added a commit that referenced this pull request Jun 13, 2025
#852 removed support for specifying a migration name via the `name`
field in a migration file. While having an unambiguous source of truth
for the migration name (the filename) is good, it is still often
desirable to decouple the filename from the name of the version schema
that the migration will create when applied because filenames:

* can be longer than the limit Postgres imposes on schema names
* can contain characters that are not legal in Postgres schema names
* must be named so that migration files are ordered lexicographically on
disk

This PR adds support for a new `version_schema` field in migration files
that allows the migration author to specify the name of the version
schema that the migration will create.

## Example

```yaml
# 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)
```

Running this migration:

```
$ pgroll start migrations/01_create_table.yaml --complete
```

Creates this version schema:

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

Had the `version_schema` field not been specified in the migration file
the version schema would have been:

```
+-----------------------+-------------------+
| Name                  | Owner             |
|-----------------------+-------------------|
...
| public_01_create_table | postgres         |
+-----------------------+-------------------+
```

---

This PR is part of a stack:
* #884 (this PR)
* #886
* #887

Part of #882
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
breaking-changes breaking changes to pgroll
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Remove migration name from inside the JSON and rely on filename as source of truth.
2 participants