Skip to content

Update docs for new versionSchema field #887

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 3 commits into from
Jun 13, 2025

Conversation

andrew-farries
Copy link
Collaborator

@andrew-farries andrew-farries commented Jun 12, 2025

Update documentation for the new versionSchema field and add an example migration.


This PR is part of a stack:

@github-actions github-actions bot temporarily deployed to Docs Preview June 12, 2025 07:11 Inactive
@andrew-farries andrew-farries marked this pull request as ready for review June 12, 2025 07:23
@andrew-farries andrew-farries requested a review from kvch June 12, 2025 07:24
@andrew-farries
Copy link
Collaborator Author

Coverage job is failing because this is a stacked PR:

fgrosse/go-coverage-report#46

@andrew-farries andrew-farries force-pushed the update-tests-for-version-schema-field branch from 575ac16 to 9f86721 Compare June 13, 2025 07:41
@andrew-farries andrew-farries force-pushed the update-docs-for-version-schema branch from d398139 to 2b1efb0 Compare June 13, 2025 07:41
@github-actions github-actions bot temporarily deployed to Docs Preview June 13, 2025 07:41 Inactive
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
@andrew-farries andrew-farries force-pushed the update-tests-for-version-schema-field branch from 9f86721 to 5cfeff8 Compare June 13, 2025 08:18
@andrew-farries andrew-farries force-pushed the update-docs-for-version-schema branch from 2b1efb0 to 6e1b432 Compare June 13, 2025 08:18
@github-actions github-actions bot temporarily deployed to Docs Preview June 13, 2025 08:18 Inactive
@andrew-farries andrew-farries changed the base branch from update-tests-for-version-schema-field to main June 13, 2025 08:19
@andrew-farries andrew-farries changed the base branch from main to update-tests-for-version-schema-field June 13, 2025 08:19
andrew-farries added a commit that referenced this pull request Jun 13, 2025
Ensure that at least one test for every operation type sets a
`VersionSchema` for the the migration.

This PR adds a `VersionSchema` field to one test for every operation
type.

--- 

This PR is part of a stack:
* #884
* #886 (this PR)
* #887
Base automatically changed from update-tests-for-version-schema-field to main June 13, 2025 08:28
Add the `versionSchema` field
Add an example migration that uses the `versionSchema` field in the
migration file.
@andrew-farries andrew-farries force-pushed the update-docs-for-version-schema branch from 6e1b432 to 43219ee Compare June 13, 2025 08:29
@github-actions github-actions bot temporarily deployed to Docs Preview June 13, 2025 08:29 Inactive
Copy link

Merging this branch will not change overall coverage

Impacted Packages Coverage Δ 🤖
github.com/xataio/pgroll/pkg/migrations 74.08% (ø)

Coverage by file

Changed files (no unit tests)

Changed File Coverage Δ Total Covered Missed 🤖
github.com/xataio/pgroll/pkg/migrations/types.go 0.00% (ø) 0 0 0

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.

@andrew-farries andrew-farries merged commit 1e4ed72 into main Jun 13, 2025
30 checks passed
@andrew-farries andrew-farries deleted the update-docs-for-version-schema branch June 13, 2025 08:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants