directus/scripts/schema-apply.sh

#!/usr/bin/env bash
# =============================================================================
# schema-apply.sh — TRM directus schema apply (image-side, boot-time)
#
# Applies the committed Directus schema snapshot to the running Postgres so
# the database schema matches what is in git. Called from entrypoint.sh as
# part of the three-step boot sequence:
#   apply-db-init.sh → schema-apply.sh → directus start
#
# Usage
#   Called automatically by entrypoint.sh (wired in Phase 1 task 1.7).
#   Can also be run manually inside the container for debugging:
#     bash scripts/schema-apply.sh
#
# Snapshot location
#   /directus/snapshots/schema.yaml
#   This is the image-baked path.  The file is copied in by the Dockerfile.
#   For the path to be overridden (e.g. in CI), set SNAPSHOT_PATH in the
#   environment before calling this script.
#
# First-boot / no-snapshot behaviour
#   If the snapshot file does not exist, or exists but contains only a
#   .gitkeep marker (i.e. is empty or contains only whitespace), this script
#   logs a skip message and exits 0.  This is critical for Phase 1: tasks 1.4
#   and 1.5 (collection creation) have not run yet, so there is no snapshot
#   to apply.  The entrypoint must not fail in this state.
#
# Dry-run preview
#   Before applying, the script runs `directus schema apply --dry-run` and
#   prints its output.  This makes container boot logs self-explanatory:
#   an operator reading logs sees exactly what is about to change.
#   On a clean re-deploy where the DB already matches the snapshot, the diff
#   output will show "No changes to apply" (or equivalent) and the real apply
#   will be a no-op.
#
# Exit codes
#   0  Applied successfully  -OR-  snapshot not present / empty (skip).
#   1  directus schema apply failed (real apply, not dry-run).
#   2  directus CLI not found on PATH (image misconfiguration).
#
# Environment variables (all optional)
#   SNAPSHOT_PATH  Override the default /directus/snapshots/schema.yaml.
#                  Useful in CI where the path may differ.
#   DEBUG          Set to any non-empty value to enable extra verbosity.
#
# Wired into entrypoint.sh in Phase 1 task 1.7.
# =============================================================================

set -euo pipefail

# -----------------------------------------------------------------------------
# Logging helpers
# -----------------------------------------------------------------------------

log_info() {
  printf '[schema-apply] %s\n' "$*"
}

log_error() {
  printf '[schema-apply] ERROR: %s\n' "$*" >&2
}

# -----------------------------------------------------------------------------
# Configuration
# -----------------------------------------------------------------------------

SNAPSHOT_PATH="${SNAPSHOT_PATH:-/directus/snapshots/schema.yaml}"

# -----------------------------------------------------------------------------
# Step 0 — Verify the directus CLI is available
# -----------------------------------------------------------------------------
#
# Note: the upstream directus/directus image does NOT expose `directus` on
# PATH. The CLI is invoked as `node /directus/cli.js <subcommand>`, matching
# the upstream image's CMD (`node cli.js bootstrap && pm2-runtime ...`).
# We check that the cli.js entry script exists at the image-baked path.

readonly DIRECTUS_CLI=/directus/cli.js

if [[ ! -f "${DIRECTUS_CLI}" ]]; then
  log_error "directus CLI not found at ${DIRECTUS_CLI}"
  log_error "This script must run inside the directus container image."
  exit 2
fi

# -----------------------------------------------------------------------------
# Step 1 — Check for snapshot existence and non-empty content
# -----------------------------------------------------------------------------

if [[ ! -f "${SNAPSHOT_PATH}" ]]; then
  log_info "snapshot not found at ${SNAPSHOT_PATH} — no schema to apply, skipping"
  exit 0
fi

# A file containing only a .gitkeep placeholder (empty or whitespace only)
# is treated as absent.  Use `tr` to strip whitespace and check emptiness.
snapshot_content_stripped="$(tr -d '[:space:]' < "${SNAPSHOT_PATH}")"

if [[ -z "${snapshot_content_stripped}" ]]; then
  log_info "snapshot at ${SNAPSHOT_PATH} is empty (placeholder only) — no schema to apply, skipping"
  exit 0
fi

log_info "snapshot found at ${SNAPSHOT_PATH}"

if [[ -n "${DEBUG:-}" ]]; then
  snapshot_bytes="$(wc -c < "${SNAPSHOT_PATH}" | tr -d '[:space:]')"
  log_info "snapshot size: ${snapshot_bytes} bytes"
fi

# -----------------------------------------------------------------------------
# Step 2 — Dry-run preview (log the diff before applying)
# -----------------------------------------------------------------------------

log_info "--- schema diff preview (dry-run) ---"

dry_run_exit=0
# Capture output and stream it; we want each line prefixed for clarity.
while IFS= read -r line; do
  log_info "  ${line}"
done < <(node "${DIRECTUS_CLI}" schema apply --dry-run "${SNAPSHOT_PATH}" 2>&1) || dry_run_exit=$?

log_info "--- end diff preview ---"

# A non-zero dry-run exit is not fatal — some Directus versions exit non-zero
# when there are pending changes to report.  We always proceed to the real
# apply step; only the real apply exit code is authoritative.
if [[ "${dry_run_exit}" -ne 0 ]]; then
  log_info "dry-run exited ${dry_run_exit} (non-zero dry-run exit is non-fatal; proceeding to apply)"
fi

# -----------------------------------------------------------------------------
# Step 3 — Apply the snapshot
# -----------------------------------------------------------------------------

log_info "applying schema snapshot..."

apply_exit=0
apply_output=""

apply_output="$(node "${DIRECTUS_CLI}" schema apply --yes "${SNAPSHOT_PATH}" 2>&1)" || apply_exit=$?

# Always print the apply output so it appears in container logs.
while IFS= read -r line; do
  log_info "  ${line}"
done <<< "${apply_output}"

if [[ "${apply_exit}" -ne 0 ]]; then
  log_error "directus schema apply failed (exit ${apply_exit})"
  log_error "The container will not start. Fix the snapshot or the database state."
  exit 1
fi

log_info "schema apply complete"