Add db-migrate package with wiring, rationale and instructions

README.md

@@ -4,6 +4,50 @@
 
 ## - Development -
 
+### Database Migrations
+
+In order to make sure that we can keep track of the database schema, we use [db-migrate](https://db-migrate.readthedocs.io/en/latest/).
+This allows us to track the database changes along with git and provide a framework for migrating data and rolling back changes.
+So when a change to the database schema is needed, a new migration should be created instead of manually changing the database.
+To create a new migration, follow the steps below.
+
+#### Create a new migration
+
+```bash
+npm run db-migrate:create -- <migration-name>
+```
+
+This will create a new migration file in the `migrations` directory with the name `<timestamp>-<migration-name>.js` as well as 2 sql files, one for the up migration and one for the down migration.
+
+#### Fill in the down and up migration sql files with the necessary changes to the database schema.
+
+These sql commands should take care of changing the database schema as well as migrating the data if necessary.
+
+#### Run the migration to test it.
+
+```bash
+npm run db-migrate:up
+```
+
+#### Create updated mock.sql
+
+For the mock data, we always want up to date tables, so after you have done the migration on the mock data, you should re-export the database.
+You can do this with the pg_dump command in the postgres container:
+
+    ```bash
+    docker exec -it badgehub_db_1 pg_dump -U badgehub -d badgehub -a -t badgehub.badge_project > mock.sql
+    ```
+
+#### Run the down migration to test it.
+
+```bash
+npm run db-migrate:down
+```
+
+#### Commit the migration files to git.
+
+When the code is deployed, the up migrations will be run automatically before starting the server.
+
 ## Install
 
 Make sure [Docker](https://www.docker.com/get-started/) is installed and running.
@@ -99,5 +143,7 @@ docker compose --file docker-compose-production.yml down
 
 - [Express](https://expressjs.com/), a framework for Node.js
 - [tsoa](https://tsoa-community.github.io/docs/) for generating a swagger file from code
+- [sql-template-tag](https://github.com/blakeembrey/sql-template-tag) for more easily writing SQL queries
+- [db-migrate](https://db-migrate.readthedocs.io/en/latest/) for database migrations
 - [tsx](https://tsx.is/) for watching TypeScript files in Node.js
 - [PM2](https://pm2.keymetrics.io/) for managing Node.js processes

database.json

@@ -0,0 +1,12 @@
+{
+  "defaultEnv": "pg-from-env",
+  "pg-from-env": {
+    "driver": "pg",
+    "host": { "ENV": "POSTGRES_HOST" },
+    "database": { "ENV": "POSTGRES_DB" },
+    "user": { "ENV": "POSTGRES_USER" },
+    "password": { "ENV": "POSTGRES_PASSWORD" },
+    "port": "5432",
+    "schema": "badgehub"
+  }
+}

migrations/package.json

@@ -0,0 +1,4 @@
+{
+  "description": "This package.json file is picked up by db-migrate and that is needed because the js files generated by db-migrate are commonjs",
+  "type": "commonjs"
+}