Database Migration Safety Gate - Claude Code Hook

#!/usr/bin/env bash
set -u

# Claude Code PreToolUse hook. Inspects a pending database migration and blocks
# irreversible or lock-heavy operations (the strong_migrations safe-migration
# check classes). Exit code 2 blocks the write and feeds the reason back to
# Claude. An explicit "-- safety-gate: allow" comment in the pending write or
# edit content acknowledges the risk and lets the migration through. Fails open
# when jq is missing.

command -v jq >/dev/null 2>&1 || exit 0

INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')

# Only gate files that look like database migrations.
case "$FILE" in
  *migrations/*|*migrate/*|*/db/migrate/*|*.sql) : ;;
  *) exit 0 ;;
esac

TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""')
CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // ""')
ACK_CONTENT=$(printf '%s' "$INPUT" | jq -r '
  [ .tool_input.content,
    .tool_input.new_string,
    (.tool_input.edits[]?.new_string) ]
  | map(select(. != null)) | join("\n")
')

if [ "$TOOL_NAME" = "Edit" ] || [ "$TOOL_NAME" = "MultiEdit" ]; then
  EXISTING_FILE=""
  MAX_EXISTING_BYTES=1048576
  READ_BLOCK_REASON=""

  CANDIDATES=("$FILE")
  if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
    CANDIDATES+=("$CLAUDE_PROJECT_DIR/$FILE")
  fi

  for CANDIDATE in "${CANDIDATES[@]}"; do
    [ -n "$CANDIDATE" ] || continue
    [ -e "$CANDIDATE" ] || [ -L "$CANDIDATE" ] || continue

    if [ -L "$CANDIDATE" ]; then
      READ_BLOCK_REASON="refuses to read symlink target $CANDIDATE"
      break
    fi
    if [ ! -f "$CANDIDATE" ]; then
      READ_BLOCK_REASON="refuses to read non-regular file $CANDIDATE"
      break
    fi
    if [ ! -r "$CANDIDATE" ]; then
      READ_BLOCK_REASON="refuses to read unreadable file $CANDIDATE"
      break
    fi

    FILE_BYTES=$(wc -c < "$CANDIDATE" | tr -d '[:space:]')
    case "$FILE_BYTES" in
      ''|*[!0-9]*)
        READ_BLOCK_REASON="cannot determine size for $CANDIDATE"
        break
        ;;
    esac
    if [ "$FILE_BYTES" -gt "$MAX_EXISTING_BYTES" ]; then
      READ_BLOCK_REASON="refuses to read $CANDIDATE larger than $MAX_EXISTING_BYTES bytes"
      break
    fi

    EXISTING_FILE="$CANDIDATE"
    break
  done

  if [ -n "$READ_BLOCK_REASON" ]; then
    echo "Unable to safely inspect edited migration for ${FILE:-pending write}: $READ_BLOCK_REASON." >&2
    exit 2
  fi

  if [ -n "$EXISTING_FILE" ]; then
    if ! CONTENT=$(printf '%s' "$INPUT" | jq -r --rawfile content "$EXISTING_FILE" '
      def replace_once($old; $new):
        if ($old == "") then .
        else (index($old) as $ix
          | if $ix == null then .
            else .[0:$ix] + $new + .[($ix + ($old | length)):]
            end)
        end;
      def apply_edit($edit):
        if ($edit.replace_all == true) then split($edit.old_string) | join($edit.new_string)
        else replace_once($edit.old_string; $edit.new_string)
        end;
      . as $input
      | if $input.tool_name == "Edit" then
          $content | apply_edit($input.tool_input)
        elif $input.tool_name == "MultiEdit" then
          reduce ($input.tool_input.edits[]? // empty) as $edit ($content; apply_edit($edit))
        else
          $content
        end
    '); then
      echo "Unable to reconstruct edited migration for ${FILE:-pending write}; blocked by the safety gate." >&2
      exit 2
    fi
  else
    if ! CONTENT=$(printf '%s' "$INPUT" | jq -r '
      [ .tool_input.new_string,
        (.tool_input.edits[]?.new_string) ]
      | map(select(. != null)) | join("\n")
    '); then
      echo "Unable to inspect edited migration for ${FILE:-pending write}; blocked by the safety gate." >&2
      exit 2
    fi
  fi
fi

[ -z "$CONTENT" ] && exit 0

# Escape hatch: require the acknowledgement in the pending write/edit text so
# stale allow comments already in the file cannot suppress newly added risks.
if printf '%s' "$ACK_CONTENT" | grep -qiE 'safety-gate:[[:space:]]*allow|safety_assured|strong_migrations[[:space:]]*:[[:space:]]*disable'; then
  exit 0
fi

findings=""
flag() {
  if printf '%s' "$CONTENT" | grep -iqE "$2"; then
    findings="${findings}${1}"$'\n'
  fi
}

flag "DROP TABLE (irreversible data loss)" 'drop[[:space:]]+table'
flag "DROP COLUMN (irreversible data loss)" 'drop[[:space:]]+column'
flag "TRUNCATE (removes all rows)" '(^|[^a-z])truncate[[:space:]]'
flag "Table/column RENAME (breaks running code mid-deploy)" 'rename[[:space:]]+(table|column|to)[[:space:]]'

# CREATE INDEX without CONCURRENTLY locks writes on large tables.
if printf '%s' "$CONTENT" | grep -iE 'create[[:space:]]+(unique[[:space:]]+)?index' | grep -ivqE 'concurrently'; then
  findings="${findings}CREATE INDEX without CONCURRENTLY (locks writes on large tables)"$'\n'
fi

if [ -n "$findings" ]; then
  echo "Unsafe database migration in ${FILE:-pending write} blocked by the safety gate:" >&2
  printf '%s' "$findings" | while IFS= read -r f; do
    [ -n "$f" ] && echo "   - $f" >&2
  done
  echo "Use a safe pattern (add columns nullable then backfill, create indexes CONCURRENTLY, expand-then-contract for renames) or add a '-- safety-gate: allow' comment to acknowledge the risk and proceed." >&2
  exit 2
fi

exit 0