This document describes the recommended, idiomatic workflow for using Skeema. There are many other ways to leverage the tool, especially in automation pipelines, but this flow is the “happy path” with the least friction.
Initial one-time setup
skeema init productionto import schemas from your master database instance. If you have multiple distinct database clusters, repeat this step for each one.
In the host directory created in step 1, use
skeema add-environment developmentto configure the connection information for your dev environment(s). This can either be a central shared dev database (e.g.
-h some.host.name, along with
-P 1234if using non-3306 port), or perhaps a separate database running locally on each engineer’s dev server reached via UNIX domain socket (
-h localhost -S /path/to/mysql.sock).
If you have additional environments such as “staging”, use
skeema add-environmentto configure connection information for them as well. Environment naming is completely arbitrary; no need to strictly use “production”, “development”, and “staging”. Just be aware that “production” is the default for all Skeema commands if no environment name is supplied as the first positional arg on the command-line.
Add all of the generated directories and files to a git repo. This can either be a new repo that you create just for schema storage, or it can be placed inside of a corresponding application repo.
Optional: if using GitHub.com for your repo’s origin, enable Skeema Cloud Linter on your repo. This provides automated safety checks on every
git push. This hosted (SaaS) system can be added to your repo with a few clicks; there’s nothing to install, and no additional configuration beyond what the Skeema CLI already uses.
Optional: if you have large tables, configure Skeema to use an external online schema change tool. Configure the
alter-wrappersetting in a
.skeemafile in the top dir of your schema repo. See the FAQ entry for more information.
Updating dev environment with changes from other engineers
If each engineer has their own localhost dev database, they can use Skeema to pull in changes made by other team members.
git checkout <branchname>to check out the shared trunk branch (typically
git pullto obtain changes made by other team members
skeema diff developmentto preview DDL corresponding to those changes
skeema push developmentto apply those schema changes to localhost dev
Schema change process
Steps 1-3 are performed by a developer. Steps 4-6 can be performed by a developer or by a DBA / SRE / devops engineer, depending on your company’s preferred policy.
Check out a new branch in your schema repo.
Test the schema change in dev, and update the corresponding files in the repo. There are a few equivalent ways of doing this:
a) If using a migration tool from an MVC framework (Rails, Django, etc): Run the migration tool on dev as usual. Then use
skeema pull developmentto update the table files in the repo.
b) If you prefer running DDL manually: Run the statement(s) in dev. Then use
skeema pull developmentto update the table files.
c) If you prefer to just change the CREATE statements directly: Modify the *.sql files as desired. Use
skeema diff developmentto confirm the auto-generated DDL looks correct, and then use
skeema push developmentto update the dev database.
Commit the change to the repo, push to origin, and open a pull request. Follow whatever review process your team uses for code changes. If using Skeema Cloud Linter, your pull request will receive automated comments with errors and warnings, as well as the generated DDL. This saves your reviewers time.
git checkout masterand
git pullto ensure your working copy of the schema repo is up-to-date.
skeema diff productionto review the list of DDL that will need to be applied to production.
skeema push productionto execute the schema change. Be sure to run this from a centralized location which prevents two engineers from pushing at the same time.