This is a collection of GitHub Workflows and CI/CD helper scripts around PlanetScale's database branching workflows to:
- attach, create, update, approve, merge and delete PlanetScale branches and deploy requests directly from your Pull Requests
- wait for branch creation to be completed
- wait for deploy requests to be successfully merged (and get an update on the current migration status)
- DB connection string creation/parsing and extending scope of service tokens
- examples on how to create branches and deploy requests (branches, credentials, deploy requests) in any CI/CD environment
- create a branch connection string for feature branches that correspond to your preview environments
- run pscale from a Docker container and still use your local config files, service tokens and port forwarding
- delete databases
To test out the IssueOps commands and helper scripts, either work on a copy of this repo or run the following command in the root directory of your GitHub repo's workspace and follow the suggestions of the script:
curl https://raw.githubusercontent.com/planetscale/pscale-workflow-helper-scripts/main/install.sh | bashThis will download and install the latest release of the package to your repository. Alternatively, you may download the install.sh script and run it manually with the following parameters for additional flexibility:
-t {RELEASE_TAG}— This allows you to provide the specific release version tag to download and install.-s— Providing this switch will still install the helpers scripts into the.pscaledirectory of the repository, but skip installing the default workflows provided for IssueOps commands. This is helpful if you wish to use the scripts to build custom workflows.
(GitHub Actions workflow source)
You can create a database branch and deploy request in an already existing Pull Request using /ps-create:
See configuration section for an explanation of the environment variables to set to specify a PlanetScale org and database different from the default settings.
If the PlanetScale deploy request or database branch and your pull request both exist already, you can use the /ps-attach command, followed by the PlanetScale URL to your branch/DR:
If you like to refresh the schema information of your branch or add additional DDL statements, use /ps-update:
Approvals can be done using /ps-approve:
Schema changes in attached deploy requests can then be applied to production by adding a /ps-merge comment to the pull request. This IssueOps command will also create GitHub deployment events, so that you could have other integrations and Action based workflows hook into the deployment lifecycle.
Finally, you can delete the database branch associated with a Git branch using /ps-delete:
Stay tuned for updates and any feedbacks / PRs are welcome 😊
In case you like to see those helper scripts in action without any further manual configuration, just
- Create a copy of this repo by clicking on the green 'Use this template' button or just here. Both private and public repo visibility work.
-
Create a PlanetScale account: If you have not done already, sign up here for a PlanetScale account, you can have one database for free. Do not create a database yet though, this step will be automated as part of the first Action workflow.
-
Switch to the Actions tab in your repo
- Start the workflows manually, in the displayed order.
See configuration section for an explanation of the environment variables to set to specify a PlanetScale org and database different from the default settings.
- When you run the workflows, follow the output where it will ask you to authenticate to PlanetScale by clicking the displayed links.
If you start the "Create branch/PR for schema change" workflow, a pull request will be created that is associated with a PlanetScale deploy request and the desired schema changes.
If you like to install the workflows in your own repository, follow the installation steps.
All scripts and IssueOps command in this repo have been designed to run successfully even if zero configuration was provided. If the defaut values do not fit your you, or you do not like to always authorize every action with the Web UI, here are the environment variables you can override in your CI/CD or set as GitHub secrets for your GitHub Action workflows to override default behavior.
DB_NAME is name of your PlanetScale database. Unless you attach a specific branch or deploy request to your PR, it defaults to example-db-<yourgithubaccount>. If you rather like to change the source for the default DB name, it would be this file.
ORG_NAME is name of your PlanetScale organization. Unless you attach a specific branch or deploy request to your PR, it defaults to the first PlanetScale org you joined with your account. If you rather like to change the source for the default DB name, it would be this file.
If you do not like to authorize actions by clicking on authorization links in the browser, you can create a PlanetScale service token. Don't forget to set the proper scopes for the database operations you like to automate.
Note: While service tokens can be used to work with existing databases, there is currently no scope to create new databases. This is why the scripts / workflows to create entirely new databses will always prompt you to authenticate via the Web UI.
GitHub Actions and many other CI/CD platforms set the CI variable to true when they run a script. The helper scripts in the .pscale/cli-helper-scripts/ directory will only prompt for interactive user input if the CI variable is not set. In CI mode, it will output additional workflow commands to standard out to enable communication between GitHub Action workflow steps. If you are using a different CI/CD platform than GitHub Actions, you can ignore all lines starting with "::".
When you create a bew database from scratch, a default table called pixel_matrix will be created. If you like to change this behavior, modify this file.