feat: support mounting a persistent data directory (#11)

* feat: support mounting a persistent data directory
* fix: use host uid/gid

Author: mnahkies

.env.example.sh

@@ -9,3 +9,10 @@ export POSTGRES_EXTENSIONS="ltree postgis"
 
 export EPHEMERAL_POSTGRES_AUTO_UPDATE="1"
 export EPHEMERAL_POSTGRES_FORCE_BUILD="0"
+
+# Set to empty string to use a tmpfs / ram disk instead
+export EPHEMERAL_POSTGRES_DATA_DIR="./data"
+
+# Defaults to uid:gid of current user, set to empty to use upstream default user
+EPHEMERAL_POSTGRES_LINUX_USER=$(id -u)
+export EPHEMERAL_POSTGRES_LINUX_USER

.github/workflows/cd.yaml

@@ -41,6 +41,7 @@ jobs:
 
       - name: Test ephemeral-postgres ${{ matrix.postgres-version }}
         run: ./bin/test-image.sh "${{ matrix.postgres-version }}"
+        timeout-minutes: 2
 
       - name: Push ephemeral-postgres ${{ matrix.postgres-version }}
         if: github.ref_name == 'main'

README.md

@@ -3,9 +3,12 @@
 
 A bash script that starts an ephemeral postgres locally in docker for **development purposes**.
 
-**Data is destroyed** between runs, on Linux the data is stored on a `tmpfs` / ramdisk
+By default, **Data is destroyed** between runs, and on Linux the data is stored on a `tmpfs` (ramdisk)
 for faster startup.
 
+For persistent data, configure `EPHEMERAL_POSTGRES_DATA_DIR` to be a path you wish to 
+store the data on your host machine.
+
 The container loads a `ClientAuthentication` hook `ensure_role_and_database_exists` that
 automatically creates roles & databases that don't exist when connections are made.
 
@@ -23,6 +26,12 @@ Prebuild images are pulled from dockerhub automatically for recent postgres vers
 - Clone the repo
 - (Optionally) add the repo to your `$PATH`
 
+```shell
+git clone git@github.com:mnahkies/ephemeral-postgres.git ~/.local/share/ephemeral-postgres
+ln -s ~/.local/share/ephemeral-postgres/start-ephemeral-postgres.sh ~/.local/bin/start-postgres
+ln -s ~/.local/share/ephemeral-postgres/connect-ephemeral-postgres.sh ~/.local/bin/connect-postgres
+```
+
 ## Usage
 
 Start the `postgres` server:
@@ -40,8 +49,11 @@ start-ephemeral-postgres.sh
 - `POSTGRES_EXTENSIONS=` - could be `postgis ltree` / etc
 - `EPHEMERAL_POSTGRES_FORCE_BUILD=0` - force building the docker image locally instead of pulling a prebuilt image
 - `EPHEMERAL_POSTGRES_AUTO_UPDATE=1` - whether to automatically check for updates to `ephemeral-postgres`
+- `EPHEMERAL_POSTGRES_DATA_DIR=` - when empty, use a tmpfs / ram disk, otherwise a path to bind mount to the postgres data directory
+- `EPHEMERAL_POSTGRES_LINUX_USER=$(id -u)` - linux `uid` / `gid` to run postgres as, defaulting to current users
+- `EPHEMERAL_POSTGRES_DOCKER_RUN_ARGS` - used internally, but you can pass arbitrary flags for `docker run` here, eg: `--network=foo`
 
-You can also create a `.env.sh` file and this will be automatically loaded by `start-postgres.sh
+You can also create a `.env.sh` file and this will be automatically loaded by `start-ephemeral-postgres.sh`
 
 Connect using `psql`:
 

bin/build-image.sh

@@ -2,8 +2,7 @@
 
 set -xeo pipefail
 
-__dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
+__dir="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
 pushd "$__dir"
 trap popd EXIT
 

bin/push-image.sh

@@ -2,8 +2,7 @@
 
 set -xeo pipefail
 
-__dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
+__dir="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
 pushd "$__dir"
 trap popd EXIT
 

bin/test-image.sh

@@ -2,8 +2,7 @@
 
 set -xeo pipefail
 
-__dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
+__dir="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
 pushd "$__dir"
 trap popd EXIT
 

connect-ephemeral-postgres.sh

@@ -2,4 +2,10 @@
 
 set -eo pipefail
 
+__dir="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+pushd "$__dir"
+trap popd EXIT
+
+source ./ephemeral-postgres-config.sh
+
 docker exec -it postgres psql -U postgres

ephemeral-postgres-config.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+set -eo pipefail
+
+: "${POSTGRES_VERSION:=17}"
+: "${POSTGRES_USER:=postgres}"
+: "${POSTGRES_PASSWORD:=postgres}"
+: "${POSTGRES_HOST_AUTH_METHOD:=trust}"
+: "${POSTGRES_ROLE_ATTRIBUTES:=LOGIN CREATEDB}"
+: "${POSTGRES_EXTENSIONS:=}"
+
+: "${EPHEMERAL_POSTGRES_AUTO_UPDATE:=1}"
+: "${EPHEMERAL_POSTGRES_FORCE_BUILD:=0}"
+: "${EPHEMERAL_POSTGRES_DATA_DIR:=}"
+: "${EPHEMERAL_POSTGRES_LINUX_USER:=$(id -u)}"
+: "${EPHEMERAL_POSTGRES_DOCKER_RUN_ARGS:=}"
+
+if [ -f .env.sh ]; then
+  echo "loading config from '.env.sh'"
+  source .env.sh
+fi
+
+export POSTGRES_VERSION
+export POSTGRES_USER
+export POSTGRES_PASSWORD
+export POSTGRES_HOST_AUTH_METHOD
+export POSTGRES_ROLE_ATTRIBUTES
+export POSTGRES_EXTENSIONS
+
+export EPHEMERAL_POSTGRES_AUTO_UPDATE
+export EPHEMERAL_POSTGRES_FORCE_BUILD
+export EPHEMERAL_POSTGRES_DATA_DIR
+export EPHEMERAL_POSTGRES_LINUX_USER
+export EPHEMERAL_POSTGRES_DOCKER_RUN_ARGS

start-ephemeral-postgres.sh

@@ -2,25 +2,11 @@
 
 set -eo pipefail
 
-__dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-pushd $__dir
+__dir="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+pushd "$__dir"
 trap popd EXIT
 
-: "${POSTGRES_VERSION:=17}"
-: "${POSTGRES_USER:=postgres}"
-: "${POSTGRES_PASSWORD:=postgres}"
-: "${POSTGRES_HOST_AUTH_METHOD:=trust}"
-: "${POSTGRES_ROLE_ATTRIBUTES:=LOGIN CREATEDB}"
-: "${POSTGRES_EXTENSIONS:=}"
-
-: "${EPHEMERAL_POSTGRES_AUTO_UPDATE:=1}"
-: "${EPHEMERAL_POSTGRES_FORCE_BUILD:=0}"
-
-if [ -f .env.sh ]; then
-  echo "loading config from '.env.sh'"
-  source .env.sh
-fi
+source ./ephemeral-postgres-config.sh
 
 if [[ "${EPHEMERAL_POSTGRES_AUTO_UPDATE}" -eq 1 ]]; then
   if git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
@@ -37,8 +23,8 @@ fi
 
 IMAGE=mnahkies/ephemeral-postgres:$POSTGRES_VERSION
 
-docker stop postgres || echo 'already stopped'
-docker rm postgres || echo 'already removed'
+docker stop postgres > /dev/null 2>&1 || echo 'already stopped'
+docker rm postgres > /dev/null 2>&1 || echo 'already removed'
 
 if [[ "${EPHEMERAL_POSTGRES_FORCE_BUILD}" -ne 0 ]]; then
   echo "Force build enabled. Skipping pull and building Docker image with POSTGRES_VERSION=$POSTGRES_VERSION"
@@ -51,13 +37,31 @@ else
   fi
 fi
 
-if [[ "$OSTYPE" =~ ^linux ]]; then
-  MNT='--mount type=tmpfs,destination=/var/lib/postgresql/data'
+if [ -n "$EPHEMERAL_POSTGRES_DATA_DIR" ]; then
+  EPHEMERAL_POSTGRES_DATA_DIR=$(realpath "$EPHEMERAL_POSTGRES_DATA_DIR")
+
+  if [ ! -d "$EPHEMERAL_POSTGRES_DATA_DIR" ]; then
+    echo "Creating $EPHEMERAL_POSTGRES_DATA_DIR"
+    mkdir -p "$EPHEMERAL_POSTGRES_DATA_DIR"
+  fi
+
+  EPHEMERAL_POSTGRES_DOCKER_RUN_ARGS+=" -v $EPHEMERAL_POSTGRES_DATA_DIR:/var/lib/postgresql/data"
+  echo "Using data directory $EPHEMERAL_POSTGRES_DATA_DIR"
 else
-  MNT=''
+  if [[ "$OSTYPE" =~ ^linux ]]; then
+    echo "Using ram disk"
+    EPHEMERAL_POSTGRES_DOCKER_RUN_ARGS+='--mount type=tmpfs,destination=/var/lib/postgresql/data'
+    # Postgres encounters permission issues when using the ram disk unless run as its default linux user
+    EPHEMERAL_POSTGRES_LINUX_USER=''
+  fi
+fi
+
+if [ -n "$EPHEMERAL_POSTGRES_LINUX_USER" ]; then
+  EPHEMERAL_POSTGRES_DOCKER_RUN_ARGS+=" --user $EPHEMERAL_POSTGRES_LINUX_USER"
 fi
 
-docker run -d --rm --name postgres $MNT \
+# shellcheck disable=SC2086
+docker run -d --name postgres $EPHEMERAL_POSTGRES_DOCKER_RUN_ARGS \
   -e POSTGRES_USER="${POSTGRES_USER}" \
   -e POSTGRES_PASSWORD="${POSTGRES_PASSWORD}" \
   -e POSTGRES_HOST_AUTH_METHOD="${POSTGRES_HOST_AUTH_METHOD}" \