228 lines
5.2 KiB
Markdown
228 lines
5.2 KiB
Markdown
# MyVC (MySQL Version Control)
|
|
|
|
Utilities to ease the maintenance of MySQL or MariaDB database versioning using
|
|
a Git repository.
|
|
|
|
This project is just to bring an idea to life and is still in an early stage of
|
|
development, so any help is welcomed! Feel free to contribute.
|
|
|
|
## Requirements
|
|
|
|
* Node.js >= 14.0
|
|
* Git
|
|
* Docker (Local server)
|
|
|
|
## Installation
|
|
|
|
It's recommended to install the package globally.
|
|
|
|
```text
|
|
# npm install -g myvc
|
|
$ myvc [command]
|
|
```
|
|
|
|
You can also install locally and use the *npx* command to execute it.
|
|
|
|
```text
|
|
$ npm install myvc
|
|
$ npx myvc [command]
|
|
```
|
|
|
|
## How to use
|
|
|
|
Execute *myvc* with the desired command.
|
|
|
|
```text
|
|
$ myvc [-w|--workspace] [-r|--remote] [-d|--debug] [-h|--help] command [args]
|
|
```
|
|
|
|
The default workspace directory is the current working directory and unless
|
|
otherwise indicated, the default remote is *local*.
|
|
|
|
Database versioning commands:
|
|
|
|
* **init**: Initialize an empty workspace.
|
|
* **pull**: Incorporate database routine changes into workspace.
|
|
* **push**: Apply changes into database.
|
|
* **version**: Creates a new version.
|
|
|
|
Local server management commands:
|
|
|
|
* **dump**: Export database structure and fixtures from *production*.
|
|
* **run**: Build and starts local database server container.
|
|
* **start**: Start local database server container.
|
|
|
|
Each command can have its own specific commandline options.
|
|
|
|
## Versioning commands
|
|
|
|
### init
|
|
|
|
Initializes an empty workspace.
|
|
|
|
```text
|
|
$ myvc init
|
|
```
|
|
|
|
### pull
|
|
|
|
Incorporates database routine changes into workspace.
|
|
|
|
```text
|
|
$ myvc pull [remote] [-f|--force] [-c|--checkout]
|
|
```
|
|
|
|
When *checkout* option is provided, it does the following steps:
|
|
|
|
1. Saves the current HEAD.
|
|
2. Check out to the last database push commit (saved in versioning tables).
|
|
3. Creates and checkout to a new branch.
|
|
4. Exports database routines.
|
|
5. Commits the new changes.
|
|
6. Checkout to the original HEAD.
|
|
7. Merge the new branch into.
|
|
8. Let the user deal with merge conflicts.
|
|
|
|
### push
|
|
|
|
Applies versions and routine changes into database.
|
|
|
|
```text
|
|
$ myvc push [remote] [-f|--force] [-u|--user]
|
|
```
|
|
|
|
### version
|
|
|
|
Creates a new version folder, when name is not specified it generates a random
|
|
name mixing color with plant name.
|
|
|
|
```text
|
|
$ myvc version [name]
|
|
```
|
|
|
|
## Local server commands
|
|
|
|
### dump
|
|
|
|
Exports database structure and fixtures from remote into hidden files located
|
|
in *dump* folder.
|
|
|
|
```text
|
|
$ myvc dump [remote]
|
|
```
|
|
|
|
### run
|
|
|
|
Builds and starts local database server container. It only rebuilds the image
|
|
when fixtures have been modified or when the day on which the image was built
|
|
is different to today.
|
|
|
|
```text
|
|
$ myvc run [-c|--ci] [-r|--random]
|
|
```
|
|
|
|
### start
|
|
|
|
Starts local database server container. It does the minium effort, if it
|
|
doesn't exists calls the run command, if it is started does nothing. Keep in
|
|
mind that when you do not rebuild the docker you may be using an outdated
|
|
version of it.
|
|
|
|
```text
|
|
$ myvc start
|
|
```
|
|
|
|
## Basic information
|
|
|
|
First of all you have to initalize your workspace.
|
|
|
|
```text
|
|
$ myvc init
|
|
```
|
|
|
|
Now you can configure MyVC using *myvc.config.yml* file, located at the root of
|
|
your workspace. This file should include the project codename and schemas/tables
|
|
wich are exported when you use *pull* or *dump* commands.
|
|
|
|
### Remotes
|
|
|
|
Create database connection configuration for each environment at *remotes*
|
|
folder using standard MySQL *ini* configuration files. The convention remote
|
|
names are *production* and *test*.
|
|
|
|
```text
|
|
remotes/[remote].ini
|
|
```
|
|
|
|
### Routines
|
|
|
|
Routines should be placed inside *routines* folder. All objects that have
|
|
PL/SQL code are considered routines. It includes events, functions, procedures,
|
|
triggers and views with the following structure.
|
|
|
|
```text
|
|
routines
|
|
`- schema
|
|
|- events
|
|
| `- eventName.sql
|
|
|- functions
|
|
| `- functionName.sql
|
|
|- procedures
|
|
| `- procedureName.sql
|
|
|- triggers
|
|
| `- triggerName.sql
|
|
`- views
|
|
`- viewName.sql
|
|
```
|
|
|
|
### Versions
|
|
|
|
Versions are placed inside *versions* folder with the following structure.
|
|
Don't place your PL/SQL objects here, use the routines folder!
|
|
|
|
```text
|
|
versions
|
|
|- 00001-firstVersionCodeName
|
|
| |- 00-firstExecutedScript.sql
|
|
| |- 01-secondScript.sql
|
|
| `- 99-lastScript.sql
|
|
`- 00002-secondVersion
|
|
|- 00-firstExecutedScript.sql
|
|
`- 00-sameNumbers.sql
|
|
```
|
|
|
|
### Local server
|
|
|
|
The local server is created as a MariaDB Docker container using the base dump created with the *dump* command plus pushing local versions and changed
|
|
routines.
|
|
|
|
## Dumps
|
|
|
|
You can create your local fixture and structure files.
|
|
|
|
* *dump/structure.sql*
|
|
* *dump/fixtures.sql*
|
|
|
|
## Why
|
|
|
|
The main reason for starting this project it's because there are no fully free
|
|
and opensource migration tools available that allow versioning database routines
|
|
with an standard CVS system as if they were normal application code.
|
|
|
|
Also, the existing tools are too complex and require too much knowledge to start
|
|
a small project.
|
|
|
|
## Todo
|
|
|
|
* Improve *help* option for commands.
|
|
* Allow to specify a custom workspace subdirectory inside project directory.
|
|
* Create a lock during push to avoid collisions.
|
|
* Use a custom *Dockerfile* for local database container.
|
|
|
|
## Built With
|
|
|
|
* [Git](https://git-scm.com/)
|
|
* [nodejs](https://nodejs.org/)
|
|
* [NodeGit](https://www.nodegit.org/)
|
|
* [docker](https://www.docker.com/)
|