Add a script that waits for the DB container to be available (#194)

## Ticket

Resolves #195

## Changes

Added a shell script that uses the `pg_isready` command to check if the
DB is available rather than arbitrarily waiting 5 seconds.

Added some details for how to run with PY_RUN_APPROACH=local with some
local.env changes that occurred a while back.

## Context for reviewers

The notes regarding the PY_RUN_APPROACH and loading environment
variables was needed to unblock my development, but only amounts to some
updated documentation so should be fine to combine with this PR.

## Testing

Was able to run this locally:
![Screenshot 2023-09-13 at 2 55 49
PM](https://github.com/navapbc/template-application-flask/assets/46358556/f7fbf65f-5ba0-4f2d-8a40-f1177934f48c)

Author: chouinar

.gitignore

@@ -4,3 +4,4 @@
 
 # IDE-specific files
 .vscode/*
+.idea

app/Makefile

@@ -114,12 +114,12 @@ check: format-check lint test
 #########################
 
 # Docker starts the image for the DB but it's not quite
-# fully ready, so add a 5 second sleep so upgrade doesn't
-# fail because the DB hasn't started yet.
-init-db: start-db sleep-5 db-migrate
+# ready to accept connections so we add a brief wait script
+init-db: start-db db-migrate
 
 start-db:
 	docker-compose up --detach main-db
+	./bin/wait-for-local-db.sh
 
 ## Destroy current DB, setup new one
 db-recreate: clean-volumes init-db

app/bin/wait-for-local-db.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# wait-for-local-db
+
+set -e
+
+# Color formatting
+RED='\033[0;31m'
+NO_COLOR='\033[0m'
+
+MAX_WAIT_TIME=30 # seconds
+WAIT_TIME=0
+
+# Use pg_isready to wait for the DB to be ready to accept connections
+# We check every 3 seconds and consider it failed if it gets to 30+
+# https://www.postgresql.org/docs/current/app-pg-isready.html
+until pg_isready -h localhost -d main-db -q;
+do
+  echo "waiting on Postgres DB to initialize..."
+  sleep 3
+
+  WAIT_TIME=$(($WAIT_TIME+3))
+  if [ $WAIT_TIME -gt $MAX_WAIT_TIME ]
+  then
+    echo -e "${RED}ERROR: Database appears to not be starting up, running \"docker logs main-db\" to troubleshoot.${NO_COLOR}"
+    docker logs main-db
+    exit 1
+  fi
+done
+
+echo "Postgres DB is ready after ~${WAIT_TIME} seconds"
+
+

docs/app/README.md

@@ -64,11 +64,41 @@ Note that even with the native mode, many components like the DB and API will on
 
 Running in the native/local approach may require additional packages to be installed on your machine to get working.
 
+### Running Natively
+
+* Run `export PY_RUN_APPROACH=local`
+* Run `make setup-local`
+* Run `poetry install --all-extras --with dev` to keep your Poetry packages up to date
+* Load environment variables from the local.env file, see below for one option.
+
+One option for loading all of your local.env variables is to install direnv: https://direnv.net/
+You can configure direnv to then load the local.env file by creating an `.envrc` file in the /app directory that looks like:
+
+```sh
+#!/bin/bash
+set -o allexport
+source local.env
+set +o allexport
+
+# Set any environment variable overrides you want here
+#
+# If you are running outside of the Docker container, the DB can
+# be found on localhost:5432. Inside the container it's referenced via
+# the name of the docker container.
+export DB_HOST=localhost
+```
+And then running `direnv allow .` in the /app folder. You should see something like:
+```shell
+➜  template-application-flask git:(main) ✗ cd app
+direnv: loading ~/workspace/template-application-flask/app/.envrc
+direnv: export +API_AUTH_TOKEN +AWS_ACCESS_KEY_ID +AWS_DEFAULT_REGION +AWS_SECRET_ACCESS_KEY +DB_HOST +DB_NAME +DB_PASSWORD +DB_SCHEMA +DB_SSL_MODE +DB_USER +ENVIRONMENT +FLASK_APP +HIDE_SQL_PARAMETER_LOGS +LOG_ENABLE_AUDIT +LOG_FORMAT +PORT +PYTHONPATH
+```
+
 ## Environment Variables
 
 Most configuration options are managed by environment variables.
 
-Environment variables for local development are stored in the [local.env](/app/local.env) file. This file is automatically loaded when running. If running within Docker, this file is specified as an `env_file` in the [docker-compose](/docker-compose.yml) file, and loaded [by a script](/app/src/util/local.py) automatically when running most other components outside the container.
+Environment variables for local development are stored in the [local.env](/app/local.env) file. This file is automatically loaded when running. If running within Docker, this file is specified as an `env_file` in the [docker-compose](/docker-compose.yml) file, and loaded [by a script](/app/src/util/local.py) automatically when running unit tests (see running natively above for other cases).
 
 Any environment variables specified directly in the [docker-compose](/docker-compose.yml) file will take precedent over those specified in the [local.env](/app/local.env) file.