Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jonico/pscale-workflow-helper-scripts
Workflows and helper scripts around the PlanetScale DB workflow to automate database branch creation, association, update and merge directly out of your pull/merge request or favourite CI/CD. This is just a passion project, no official repository from Planetscale.
https://github.com/jonico/pscale-workflow-helper-scripts
actions automation cli credentials helper issueops planetscale pull-requests synchronous wait zerosetup
Last synced: 3 months ago
JSON representation
Workflows and helper scripts around the PlanetScale DB workflow to automate database branch creation, association, update and merge directly out of your pull/merge request or favourite CI/CD. This is just a passion project, no official repository from Planetscale.
- Host: GitHub
- URL: https://github.com/jonico/pscale-workflow-helper-scripts
- Owner: jonico
- Created: 2021-10-21T13:48:43.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-01-31T20:12:08.000Z (almost 2 years ago)
- Last Synced: 2024-05-01T21:17:35.115Z (9 months ago)
- Topics: actions, automation, cli, credentials, helper, issueops, planetscale, pull-requests, synchronous, wait, zerosetup
- Language: Shell
- Homepage: https://youtu.be/l3oe7srRUZw?t=610
- Size: 156 KB
- Stars: 77
- Watchers: 4
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
# PlanetScale Workflow Helper scripts
📺 [DevOpsPro Talk](https://youtu.be/CafDHLmHf2s)
📺 [Recording from live demo at PlanetScale Happy-Half-Hour](https://youtu.be/l3oe7srRUZw?t=610)
📺[Longer talk at WeAreDevelopers DevOps Day](https://www.youtube.com/watch?v=ojyZ2KwiXPo&t=10786s)
This is a collection of GitHub Workflows and CI/CD helper scripts around [PlanetScale's database branching workflows](https://docs.planetscale.com/concepts/branching) to:
* [attach, create, update, approve, merge and delete](#issue-ops-based-workflows) PlanetScale branches and deploy requests directly from your Pull Requests
* [wait for branch creation to be completed](.pscale/cli-helper-scripts/wait-for-branch-readiness.sh)
* [wait for deploy requests to be successfully merged](.pscale/cli-helper-scripts/wait-for-deploy-request-merged.sh) (and get an update on the current migration status)
* [DB connection string creation/parsing and extending scope of service tokens](.pscale/cli-helper-scripts/create-database.sh)
* examples on how to create branches and deploy requests ([branches](.pscale/cli-helper-scripts/add-operation-column-and-index.sh), [credentials](.pscale/cli-helper-scripts/create-database.sh), [deploy requests](.pscale/cli-helper-scripts/merge-latest-open-deploy-request.sh)) in any CI/CD environment
* [creating one-time links](.pscale/cli-helper-scripts/create-branch-connection-string.sh) with connection info for feature branches that correspond to your preview environments
* [run pscale from a Docker container](.pscale/cli-helper-scripts/use-pscale-docker-image.sh) and still use your local config files, service tokens and port forwarding
* [delete databases](.pscale/cli-helper-scripts/remove-database.sh)
### IssueOps Example
([example PR](https://github.com/jonico/pscale-cli-helper-scripts/pull/11))
## Installation
To test out the IssueOps commands and helper scripts, either work on a [copy of this repo](https://github.com/jonico/pscale-cli-helper-scripts/generate) or run the following command in the root directory of your GitHub repo's workspace and follow the suggestions of the script:
```bash
curl https://raw.githubusercontent.com/jonico/pscale-workflow-helper-scripts/main/install.sh | bash
```
## Issue-Ops based workflows
([GitHub Actions workflow source](.github/workflows/issue-ops-ps-commands.yml))
### /ps-create: Create PlanetScale Deploy Request from your PR
You can create a database branch and deploy request in an [already existing Pull Request](https://github.com/jonico/pscale-cli-helper-scripts/pull/2) using `/ps-create`:
See [configuration section](#configuration) for an explanation of the environment variables to set to specify a PlanetScale org and database different from the default settings.
### /ps-attach: Attach existing PlanetScale branch or Deploy Request to your PR
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:
### /ps-update: Refresh schema info in your PR from your attached Deploy Request
If you like to refresh the schema information of your branch or add additional DDL statements, use `/ps-update`:
### /ps-approve: Approve Deploy Request from your PR
Approvals can be done using `/ps-approve`:
### /ps-merge: Merge Deploy Request attached to your PR
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](https://docs.github.com/en/rest/guides/delivering-deployments), so that you could have other integrations and Action based workflows [hook into](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#deployment) the deployment lifecycle.
### /ps-delete: Delete PlanetScale branch attached to your PR
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 😊
## Zero-setup Action workflows included :sparkles:
In case you like to see those helper scripts in action without any further manual configuration, just
1. [Create a copy of this repo](https://github.com/jonico/pscale-cli-helper-scripts/generate) by clicking on the green 'Use this template' button or just [here](https://github.com/jonico/pscale-cli-helper-scripts/generate). Both private and public repo visibility work.
2. Create a PlanetScale account: If you have not done already, [sign up here](https://auth.planetscale.com/sign-up) 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.
3. Switch to the Actions tab in your repo
4. [Start the workflows manually](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow), in the displayed order.
See [configuration section](#configuration) for an explanation of the environment variables to set to specify a PlanetScale org and database different from the default settings.
5. 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"](https://github.com/jonico/pscale-cli-helper-scripts/actions/workflows/create-db-branch-and-pr-dr.yml) workflow, a pull request like [this one](https://github.com/jonico/pscale-cli-helper-scripts/pull/2) 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](#installation).
## Configuration
All scripts and IssueOps command in this repo have been designed to run successfully even if [zero configuration](#zero-setup-action-workflows-included-sparkles) 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](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for your GitHub Action workflows to override default behavior.
### DB_NAME
***DB_NAME*** is name of your PlanetScale database. Unless you [attach](#ps-attach-attach-existing-planetscale-branch-or-deploy-request-to-your-pr) a specific branch or deploy request to your PR, it defaults to `example-db-`. If you rather like to change the source for the default DB name, it would be [this file](.pscale/cli-helper-scripts/set-db-and-org-and-branch-name.sh).
### ORG_NAME
***ORG_NAME*** is name of your PlanetScale organization. Unless you [attach](#ps-attach-attach-existing-planetscale-branch-or-deploy-request-to-your-pr) 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](.pscale/cli-helper-scripts/set-db-and-org-and-branch-name.sh).
### PLANETSCALE_SERVICE_TOKEN_ID and PLANETSCALE_SERVICE_TOKEN
If you do not like to authorize actions by clicking on authorization links in the browser, you can [create a PlanetScale service token](https://docs.planetscale.com/reference/service-tokens#create-service-tokens-using-the-planetscale-ui). Don't forget to set the [proper scopes](https://docs.planetscale.com/reference/service-tokens#add-database-access-permissions) 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.
### CI - Runnning in CI
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](.pscale/cli-helper-scripts/) will only prompt for interactive user input if the **CI** variable is not set. In CI mode, it will output additional [workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions) 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 "::".
### Initial table
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](.pscale/cli-helper-scripts/create-database.sh).