chore(scripts): add pg backup & restore scripts for dev

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Oct 25, 2025 9:22am
rivet-inspector	Ignored	Preview		Oct 25, 2025 9:22am
rivet-site	Ignored	Preview		Oct 25, 2025 9:22am

[NathanFlurry]

• fix(fe): invalid types #3260
• fix: make inspector working again #3229
• fix(fe): bring back ts type check #3259
• ci: fix release scripts for engine #3258
• chore(scripts): add pg backup & restore scripts for dev #3251 👈 (View in Graphite)
• feat(examples): cursors with raw websockets example #3245
• feat(examples-cursors): cursors example #3244
• feat(core): allow routing traffic to actors via path #3250
• fix: fix biome ignore path #3249
• chore: fix rivetkit release script #3242 : 1 other dependent PR (#3243 )
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Code Review

Thanks for adding these PostgreSQL backup and restore scripts! This is a useful addition for development workflows. Here's my feedback:

✅ Strengths

1. Good error handling: Proper use of set -euo pipefail across all scripts
2. Clear user feedback: Informative echo messages guide users through operations
3. Validation: Input validation for backup paths and file existence
4. Auto-start improvement: The enhancement to engine-postgres.sh to auto-start postgres is a nice UX improvement

🐛 Potential Issues

1. Volume persistence issue in postgres.sh (Critical)

The base postgres.sh script doesn't use a named volume, which means:

• Data is lost when the container is removed (which happens on every restart)
• Backups/restores won't work as expected since they rely on named volumes

Location: scripts/run/postgres.sh:14-21

Recommendation: Add a volume mount like:

VOLUME_NAME="rivet-engine-postgres-data"

docker run \
  --detach \
  --name "${CONTAINER_NAME}" \
  --publish 5432:5432 \
  --env POSTGRES_PASSWORD=postgres \
  --env POSTGRES_USER=postgres \
  --env POSTGRES_DB=postgres \
  -v "${VOLUME_NAME}":/var/lib/postgresql/data \
  "${POSTGRES_IMAGE}"

2. Race condition in restore script

In scripts/run/restore-postgres.sh:44-52, the container is started but there's no wait for postgres to be ready before declaring success.

Recommendation: Add a readiness check similar to engine-postgres.sh:18-27:

echo "Waiting for postgres to be ready..."
for i in {1..30}; do
  if docker exec "${CONTAINER_NAME}" pg_isready -U postgres >/dev/null 2>&1; then
    echo "Postgres is ready!"
    break
  fi
  if [ $i -eq 30 ]; then
    echo "warning: postgres may not be ready yet"
  fi
  sleep 1
done

3. Inconsistent volume handling

nuke-postgres.sh tries to clean up volumes, but postgres.sh doesn't create named volumes. This creates confusion about volume lifecycle.

Recommendation: Ensure all scripts use the same volume naming convention.

🔒 Security Considerations

1. Hardcoded credentials: Using POSTGRES_PASSWORD=postgres is fine for local dev, but consider documenting this is dev-only
2. Backup file permissions: Backups may contain sensitive data - consider adding a note about secure storage

🎯 Best Practices & Improvements

1. DRY principle: The CONTAINER_NAME and POSTGRES_IMAGE constants are duplicated across multiple scripts. Consider sourcing from a shared config file:

# scripts/run/postgres-config.sh
export CONTAINER_NAME="rivet-engine-postgres"
export POSTGRES_IMAGE="postgres:17"
export VOLUME_NAME="rivet-engine-postgres-data"

2. Backup naming: Consider adding timestamps to backup filenames for better organization:

# In backup-postgres.sh
if [ $# -eq 0 ]; then
  BACKUP_PATH="./postgres-backup-$(date +%Y%m%d-%H%M%S).tar.gz"
fi

3. Graceful shutdown: In nuke-postgres.sh:17, consider using docker stop -t 10 to allow postgres to shut down gracefully

4. Documentation: Consider adding a README or inline documentation explaining:

   • When to use each script
   • Backup/restore workflow
   • Volume management strategy

📊 Test Coverage

No tests are included for these bash scripts. Consider:

• Adding basic smoke tests using bats-core or similar
• At minimum, documenting manual test procedures

Minor Nitpicks

1. In backup-postgres.sh:14, BACKUP_PATH="$1" could validate the path format
2. In engine-postgres.sh:14, the echo message references old path scripts/dev/run-postgres.sh (outdated comment removed, but worth noting)
3. Error messages use lowercase "error:" - consider using "Error:" for consistency with typical CLI tools (though this is stylistic)

Summary

Priority Fixes:

1. ⚠️ Fix volume persistence in postgres.sh - otherwise backup/restore won't work correctly
2. ⚠️ Add readiness check to restore script
3. ⚠️ Align volume naming across all scripts

Nice to have:

• Shared configuration file
• Better documentation
• Graceful shutdown handling

Overall, this is a solid addition once the volume persistence issue is addressed. The scripts are well-structured and handle edge cases appropriately.

[claude]

Code Review

Overall, this is a solid addition to the development tooling! The backup and restore scripts will be very useful for managing local development databases. Here's my detailed feedback:

✅ Strengths

1. Good error handling - Proper use of set -euo pipefail in all scripts
2. Clear usage messages - Helpful examples for backup/restore scripts
3. Smart automation - The engine-postgres.sh enhancement to auto-start postgres is a nice DX improvement
4. Consistent naming - All scripts follow the same container name convention

🐛 Potential Issues

Critical: Volume Handling in restore-postgres.sh

Issue: restore-postgres.sh always creates a new volume instead of reusing the existing one from the removed container. This means the old volume is orphaned and not cleaned up.

Location: scripts/run/restore-postgres.sh:30-31

# Creates a brand new volume every time
VOLUME_NAME=$(docker volume create)

Recommendation: Extract the volume name before removing the container (like nuke-postgres.sh does), then either:

1. Reuse the same volume name if it exists
2. Or explicitly remove the old volume first

Suggested fix:

# Get the old volume name if container exists
OLD_VOLUME_NAME=""
if docker ps --all --format '{{.Names}}' | grep -qw "${CONTAINER_NAME}"; then
	OLD_VOLUME_NAME=$(docker inspect "${CONTAINER_NAME}" --format '{{range .Mounts}}{{if eq .Destination "/var/lib/postgresql/data"}}{{.Name}}{{end}}{{end}}' 2>/dev/null || true)
fi

# Stop and remove existing container
# ... existing code ...

# Remove old volume if it exists
if [ -n "${OLD_VOLUME_NAME}" ]; then
	echo "Removing old volume '${OLD_VOLUME_NAME}'..."
	docker volume rm "${OLD_VOLUME_NAME}" >/dev/null 2>&1 || true
fi

# Create a new volume
VOLUME_NAME=$(docker volume create)

Missing Volume Handling in postgres.sh

Issue: The base postgres.sh script doesn't mount a volume, so data is ephemeral. This differs from the restore script which uses a named volume.

Location: scripts/run/postgres.sh:14-21

Recommendation: Consider whether postgres.sh should also use a named volume for data persistence. This would make the behavior consistent with restore operations.

🔒 Security Considerations

1. Hardcoded credentials - All scripts use POSTGRES_PASSWORD=postgres. This is fine for local development but worth documenting clearly.
2. Volume permissions - The Alpine container runs as root by default when accessing volumes, which is acceptable for dev scripts.

⚡ Performance Considerations

1. Compression - Using tar czf (gzip) is good. Consider documenting backup size implications.
2. Backup timing - No check if postgres is in a consistent state during backup. For dev use this is probably fine, but consider adding a note that for production-like backups, you'd want to:
   • Stop the container first, or
   • Use pg_dump instead of volume-level backup

📝 Code Quality & Best Practices

1. Consistent style - All scripts follow the same patterns, good!
2. Variable quoting - Proper quoting throughout (e.g., "${CONTAINER_NAME}")
3. Error messages - Clear lowercase messages following the codebase conventions

🧪 Testing Suggestions

Consider testing these scenarios:

1. Backup when container doesn't exist (should fail clearly)
2. Restore with invalid backup path (already handled ✅)
3. Multiple backup/restore cycles to verify volume cleanup
4. Restore while container is running (appears handled ✅)

📖 Documentation

Consider adding a README in scripts/run/ documenting:

• The typical workflow (backup -> nuke -> restore)
• When to use each script
• Backup file format and location recommendations

Minor Suggestions

1. backup-postgres.sh:14 - Consider also checking if container is running (not just exists)
2. engine-postgres.sh:18 - The 30-second timeout is good, maybe make it configurable via env var
3. All scripts could benefit from a --help flag for consistency

---

Summary: The implementation is solid, but please address the volume cleanup issue in restore-postgres.sh to prevent accumulating orphaned volumes. Everything else is minor polish.

Great work on improving the dev tooling! 🚀

[claude]

PR Review: chore(scripts): add pg backup & restore scripts for dev

Summary

This PR adds helpful developer tooling for managing PostgreSQL backups and data lifecycle. The changes include backup, restore, and nuke scripts, plus an enhancement to auto-start postgres when needed.

Code Quality & Best Practices

Strengths:

• Consistent error handling with set -euo pipefail across all scripts
• Clear usage messages and validation
• Good naming conventions matching existing scripts
• Proper directory creation and file existence checks
• Follows existing patterns in the codebase

Issues & Suggestions:

1. Volume naming in postgres.sh (scripts/run/postgres.sh:14-21)

The original postgres.sh doesn't create a named volume, which makes the backup scripts rely on inspecting the container to find the anonymous volume. Consider using a named volume for consistency - this would simplify the backup scripts and make the volume easier to manage.

2. Race condition in engine-postgres.sh (scripts/run/engine-postgres.sh:19-27)

The postgres readiness check uses nc to test port connectivity, but this doesn't guarantee postgres is ready to accept queries. PostgreSQL may accept connections before it's fully initialized. Consider using pg_isready via docker exec instead.

3. Error handling in backup-postgres.sh (scripts/run/backup-postgres.sh:34-39)

The backup operation could fail silently. Consider checking the exit status and verifying the backup file was created with proper error messages.

Potential Bugs

4. Missing container name constant (scripts/run/engine-postgres.sh:14) - CRITICAL

The script references CONTAINER_NAME on line 14 but this variable is not defined in the script. It should be added after REPO_ROOT definition.

5. Docker volume inspect edge case (scripts/run/nuke-postgres.sh:11)

The volume name extraction could return multiple values if there are multiple mounts to /var/lib/postgresql/data. Adding head -1 would make it more robust.

Security Concerns

6. Hardcoded credentials (scripts/run/restore-postgres.sh:49)

The postgres password is hardcoded as postgres. While this is for local development, consider adding a comment noting this is for dev only.

7. Path injection (all scripts)

Using user-provided paths directly in docker commands could be risky. Consider adding path validation to reject dangerous characters.

Overall Assessment

Verdict: Approve with suggestions

This is a useful addition for developer productivity. The code is generally well-written and follows existing patterns. The main concerns are:

1. CRITICAL: Missing CONTAINER_NAME variable in engine-postgres.sh (bug 4)
2. IMPORTANT: Consider named volumes for consistency
3. NICE TO HAVE: Better error handling and documentation

Action Items

Must fix before merge:

• Add CONTAINER_NAME variable to engine-postgres.sh

Recommended:

• Use named volume in postgres.sh
• Add error handling to backup operation
• Use pg_isready for postgres readiness check
• Add usage documentation to PR description

Nice to have:

• Add script header comments
• Add path validation
• Create integration test script

[claude]

Code Review

Thank you for adding these PostgreSQL backup and restore scripts! This is a useful addition for local development. Here's my review:

✅ Strengths

1. Good error handling: The scripts use set -euo pipefail consistently, which is excellent for catching errors early
2. Clear user feedback: Good echo messages throughout to inform users of progress
3. Validation: Proper checks for file/container existence before operations
4. Consistent naming: Uses the same CONTAINER_NAME constant across all scripts

🔍 Code Quality & Best Practices

backup-postgres.sh (lines 1-41):

• ✅ Good: Validates backup path argument
• ✅ Good: Creates backup directory if needed
• ✅ Good: Uses Alpine container for lightweight operations
• ⚠️ Consideration: The backup is performed while the database may be running. For production-like backups, you might want to document that this is a filesystem-level backup and may not be consistent if writes are happening

restore-postgres.sh (lines 1-56):

• ✅ Good: Validates backup file exists
• ✅ Good: Stops existing container before restore
• ⚠️ Issue: Creates a volume with auto-generated name but doesn't associate it with the container properly - see bug section below
• ℹ️ Minor: Missing wait/readiness check after starting the container (unlike engine-postgres.sh)

nuke-postgres.sh (lines 1-33):

• ✅ Good: Safe handling of missing containers/volumes
• ✅ Good: Comprehensive cleanup of both container and volume
• ✅ Good: Informative messages about what was found/removed

engine-postgres.sh (changes):

• ✅ Good: Auto-starts postgres if not running (better DX)
• ✅ Good: Proper wait loop with timeout
• ⚠️ Consideration: Changed behavior from "error and tell user to start manually" to "auto-start" - this is probably better but is a behavior change

🐛 Potential Bugs

Critical issue in restore-postgres.sh (line 51):
The -v flag uses ${VOLUME_NAME} which is an auto-generated name from docker volume create, but this breaks the association with the original postgres.sh script. The original postgres.sh doesn't specify a volume name, so Docker creates an anonymous volume. After restore, you'll have a named volume that won't be reused by postgres.sh.

Suggested fix: Either:

1. Make postgres.sh use a named volume consistently (e.g., rivet-engine-postgres-data), OR
2. Update restore-postgres.sh to create a container with the same volume naming strategy

Minor issue in backup-postgres.sh (line 20):
If the container has no volume mounted at /var/lib/postgresql/data, VOLUME_NAME will be empty, but this is correctly caught at line 22. However, this could happen if postgres.sh changes its mount strategy. Consider documenting the expected mount structure.

🔒 Security Concerns

• ✅ Good: No hardcoded sensitive data (credentials are same as postgres.sh)
• ✅ Good: Scripts validate inputs before operations
• ℹ️ Note: These are dev scripts, so security is less critical, but backups may contain sensitive development data

⚡ Performance Considerations

• ✅ Good: Uses Alpine image for backup/restore operations (minimal overhead)
• ℹ️ Note: Backup is a simple tar.gz which is fine for dev use. For large databases, this might be slow but that's acceptable for development
• ℹ️ Minor: The wait loop in engine-postgres.sh checks every 1 second for 30 seconds. Could add postgres-specific readiness check (e.g., pg_isready) for more reliable detection

🧪 Test Coverage

• ℹ️ These are shell scripts, so traditional unit tests don't apply
• ℹ️ Recommendation: Consider adding integration tests or at least manual testing steps in the PR description to verify:
  • Backup of running database
  • Restore to clean state
  • Nuke and restart
  • Engine-postgres auto-start behavior

📝 Additional Recommendations

1. Documentation: Consider adding a comment block at the top of each script explaining its purpose and any prerequisites
2. Consistency: The restore script shows the container ID at the end - consider doing this in postgres.sh too for consistency
3. Volume naming: Address the volume naming issue mentioned in the bugs section
4. Error messages: Consider adding more context to error messages (e.g., which command failed if a docker command fails)

Example Usage Documentation

Consider adding to the PR description or a doc file:

# Backup current postgres state
./scripts/run/backup-postgres.sh /tmp/my-backup.tar.gz

# Nuke existing postgres
./scripts/run/nuke-postgres.sh

# Restore from backup
./scripts/run/restore-postgres.sh /tmp/my-backup.tar.gz

Summary

Overall, this is a solid addition that improves the development workflow. The main issue to address is the volume naming inconsistency between postgres.sh and restore-postgres.sh. The other items are minor improvements or considerations.

Recommendation: Address the volume naming issue, then this should be good to merge! 👍

[claude]

PR Review

Thank you for adding these helpful development scripts! Overall, this is a solid addition that will make it easier for developers to manage their local Postgres instances. Here's my detailed feedback:

✅ Strengths

1. Good error handling: All scripts use set -euo pipefail for robust error handling
2. Clear user feedback: Good use of echo statements to keep users informed
3. Consistent naming: All scripts follow the same container/volume naming conventions
4. Useful functionality: Backup, restore, and nuke operations are valuable for development workflows

---

🐛 Potential Issues

1. Volume persistence issue in restore-postgres.sh

Location: scripts/run/restore-postgres.sh:31

The script creates a new volume every time but never removes the old one, which could lead to orphaned volume accumulation over time.

Recommendation: Use a named volume for consistency (like rivet-engine-postgres-data) and remove the old volume before creating a new one.

2. Missing volume persistence in postgres.sh

Location: scripts/run/postgres.sh:14-21

The original postgres.sh script doesn't use a named volume, which means data is lost when the container is removed. This is inconsistent with the backup/restore scripts that expect persistent volumes.

Recommendation: Update postgres.sh to use a named volume with -v rivet-engine-postgres-data:/var/lib/postgresql/data

3. Race condition in engine-postgres.sh

Location: scripts/run/engine-postgres.sh:17-23

The script waits for port 5432 to be open, but this doesn't guarantee Postgres is ready to accept connections. The port might be open while Postgres is still initializing.

Recommendation: Use docker exec rivet-engine-postgres pg_isready -U postgres for a more reliable check, or add a small sleep after the port check.

---

🔒 Security Considerations

1. Hardcoded credentials: The scripts use hardcoded credentials (postgres:postgres). This is acceptable for local development but should be clearly documented as dev-only.

2. No backup validation: restore-postgres.sh doesn't verify the backup file is a valid tar.gz before attempting to restore. Consider adding validation with tar tzf.

---

🎯 Best Practices & Style

1. Error messages: Using lowercase "error:" prefix is good and consistent ✅
2. Variable quoting: Good use of quotes around variables to handle paths with spaces ✅
3. Shebang: Using #\!/usr/bin/env bash is portable and correct ✅
4. Documentation: Consider adding comment blocks at the top explaining usage

---

🧪 Testing Recommendations

1. Test the full backup → nuke → restore workflow to ensure data integrity
2. Test restore with a non-existent backup file (error handling)
3. Test restore with an invalid tar file (error handling)
4. Test behavior when container is running vs. stopped
5. Verify volume cleanup works correctly in nuke-postgres.sh

---

📝 Minor Suggestions

1. Consistency in output redirection: Some commands use >/dev/null 2>&1 || true and others don't
2. Container name variable: Consider extracting to a shared constants file since used across multiple scripts
3. Add usage examples in comments at the top of each script

---

🎉 Summary

This is a valuable addition to the development tooling. The main issues to address are:

1. ✋ Critical: Fix volume persistence in restore-postgres.sh to avoid accumulating orphaned volumes
2. ⚠️ Important: Update postgres.sh to use named volumes for consistency
3. 💡 Nice to have: Improve Postgres readiness check in engine-postgres.sh

The scripts are well-structured and follow good bash practices. With these fixes, they'll be production-ready for development use!

[claude]

PR Review: PostgreSQL Backup & Restore Scripts

Overall, this is a solid addition that provides useful development tooling for managing PostgreSQL data. The scripts are well-structured and follow good bash practices. Below are my findings:

✅ Strengths

1. Good Error Handling: All scripts use set -euo pipefail which is excellent for catching errors early
2. Clear Separation of Concerns: Each script has a single, well-defined purpose
3. Helpful User Feedback: Clear error messages and usage instructions
4. Consistent Naming: Uses the same container name across all scripts
5. Safe Docker Operations: Uses || true to prevent failures when containers don't exist

🔍 Issues & Concerns

Critical: Data Loss Risk in restore-postgres.sh

Location: scripts/run/restore-postgres.sh:20-27

The restore script stops and removes the existing container without warning the user about potential data loss. This is dangerous for a development workflow.

Recommendation: Add a confirmation prompt before destroying existing data

Bug: Volume Not Persisted in postgres.sh

Location: scripts/run/postgres.sh:14-21

The postgres.sh script creates a container without a named volume, which means data won't persist if the container is removed. This is inconsistent with the backup/restore scripts which expect named volumes.

Recommendation: Add a named volume to postgres.sh like: -v rivet-engine-postgres-data:/var/lib/postgresql/data

Enhancement: Container State Check in backup-postgres.sh

Location: scripts/run/backup-postgres.sh:14-18

The backup script checks if the container exists but doesn't verify it's running. A stopped container could still have a valid volume to backup, so this check might be too restrictive.

Minor: Biome.json Fix

Location: biome.json:8-11

Good catch fixing the missing comma - this was a syntax error.

Security: Hardcoded Credentials

Location: Multiple files (postgres.sh, restore-postgres.sh)

The scripts use hardcoded credentials (postgres/postgres). While acceptable for local development, it would be better to make these configurable via environment variables.

📝 Style & Best Practices

1. Consistent Error Messages: Good use of lowercase "error:" prefix
2. Path Handling: Proper use of dirname and basename for path manipulation
3. Tab Indentation: Scripts use tabs consistently

🧪 Testing Recommendations

Consider testing these scenarios:

1. Backup when container is stopped
2. Restore with invalid backup file path
3. Restore when disk is full
4. Backup/restore cycle to verify data integrity
5. Concurrent operations (e.g., backup while container is being modified)

🎯 Summary

Approve with Changes Required

The scripts provide valuable functionality but need the following critical fixes:

1. Add confirmation prompt in restore-postgres.sh to prevent accidental data loss
2. Fix postgres.sh to use a named volume for data persistence
3. Consider making credentials configurable

The enhancement to engine-postgres.sh to auto-start postgres is a nice quality-of-life improvement for developers.

[pkg-pr-new]

More templates

• example-ai-agent
• example-background-jobs
• example-better-auth-external-db
• example-bots
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-counter
• example-counter-serverless
• example-crdt
• example-cursors
• example-cursors-raw-websocket
• example-database
• example-deno
• example-sqlite
• example-elysia
• example-express
• example-freestyle
• example-game
• example-hono
• example-hono-bun
• example-hono-react
• example-kitchen-sink
• example-next-js
• example-rate
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• example-smoke-test
• starter
• example-stream
• example-sync
• example-tenant
• example-trpc
• example-workflows

@rivetkit/actor

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/actor@3251

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3251

@rivetkit/core

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/core@3251

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3251

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3251

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3251

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3251

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3251

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3251

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3251

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3251

commit: 0d3238b

[claude]

PR Review: PostgreSQL Backup & Restore Scripts

Summary

This PR adds development utilities for PostgreSQL container management including backup, restore, and nuke functionality, plus auto-start capability in engine-postgres.sh. Overall the implementation is solid and follows good bash practices.

Code Quality & Best Practices

Strengths:

• Consistent use of set -euo pipefail for robust error handling
• Good validation and error messages throughout
• Proper quoting of variables to prevent word splitting
• Clean, readable code with appropriate comments
• Consistent naming conventions across all scripts

Minor Issues:

1. biome.json formatting fix - Good catch fixing the missing comma
2. pnpm-lock.yaml changes - These appear unrelated to the postgres scripts. Should they be in a separate PR?

Potential Issues

1. Race condition in restore script (scripts/run/restore-postgres.sh:45-53)

The script creates and starts the postgres container but doesn't wait for postgres to be ready before reporting success. Consider adding a readiness check similar to the one in engine-postgres.sh.

2. Volume persistence in postgres.sh (scripts/run/postgres.sh:14-21)

The existing postgres.sh doesn't specify a named volume, which means Docker will create an anonymous volume. The restore script creates a named volume, but the standard postgres startup doesn't. Consider using a named volume for consistency.

3. Backup script doesn't check if postgres is running (scripts/run/backup-postgres.sh:15-18)

The script only checks if the container exists, not if it's running. Backing up while postgres is actively writing could lead to inconsistent backups. Consider adding a warning or check.

Security Considerations

1. Hardcoded credentials - The postgres password is hardcoded as postgres throughout. This is acceptable for local development but should be clearly documented.
2. Path injection risk - User-supplied paths are used without sanitization. Document that these scripts should only be used in trusted development environments.

Performance Considerations

1. Backup/restore performance - Using tar with gzip compression is good for file size but can be slow for large databases.
2. Alpine image choice - Good choice! Alpine is minimal and perfect for these utility operations.

Additional Recommendations

1. Add usage documentation - Consider documenting when to use each script and example workflows
2. Add confirmation for destructive operations - The nuke-postgres.sh script could benefit from a confirmation prompt
3. Consider adding a --force flag - For automation/CI purposes

Verdict

Status: Approve with minor suggestions

The core functionality is well-implemented and follows good practices. The suggested improvements are mostly about edge cases and enhanced safety, not critical bugs. The scripts will work well for their intended development use case.

The changes to engine-postgres.sh are particularly nice - auto-starting postgres when needed is a great developer experience improvement!

[claude]

Code Review

Overview

This PR adds three new development scripts for managing PostgreSQL backup/restore operations and improves the engine-postgres.sh script to auto-start postgres. Overall, this is a solid addition for development workflow, but there are several improvements to consider.

---

Critical Issues

1. Data Loss Risk in restore-postgres.sh (Lines 20-27)

The restore script automatically stops and removes the existing container without confirmation. This could lead to accidental data loss if a developer runs the wrong command.

Recommendation: Add a confirmation prompt or at minimum a warning message before destructing the existing container.

2. Security: Hardcoded Credentials (restore-postgres.sh:49-51)

Hardcoded postgres credentials (postgres/postgres) are exposed in the script. While this is for dev purposes, it is a pattern that could accidentally propagate to production configs.

Recommendation: Consider using environment variables with defaults.

---

Bugs and Issues

3. Race Condition in restore-postgres.sh (Line 44-56)

The script starts the postgres container immediately after restoring data, but does not verify the container actually started successfully or wait for postgres to be ready. This could cause subsequent operations to fail.

Recommendation: Add health check similar to what is in engine-postgres.sh:18-28

4. Error Handling: Silent Failures (nuke-postgres.sh:29)

The script uses || true when removing the volume, which masks actual errors that might be important (e.g., volume in use by another container).

Recommendation: Capture and display the error, or at least log why the removal failed.

5. Incomplete Validation in backup-postgres.sh (Line 15-17)

The script checks if the container exists but does not check if it is running. Backing up a stopped container might result in inconsistent data.

Recommendation: Add a check to ensure the container is running or warn the user.

---

Code Quality and Best Practices

6. Inconsistent Error Message Style

Error messages use different formatting across scripts. Use consistent formatting (lowercase error:, no trailing periods) across all scripts.

7. Missing Dependency Check

All scripts assume docker is available but do not verify. The engine-postgres.sh checks for nc (line 7), but new scripts do not check for docker.

Recommendation: Add docker availability check at the top of each script.

8. Path Handling Edge Case (backup-postgres.sh:12)

Using the first argument directly without validation could cause issues with paths containing special characters or spaces. Already quoted properly, but consider validating the path does not contain newlines or other problematic characters.

---

Performance Considerations

9. Backup Performance: Missing Compression Options

The backup uses default tar compression (czf) which is gzip. For large databases, this could be slow. Consider adding an optional compression method argument or document expected backup times for large datasets.

10. Volume Creation Strategy (restore-postgres.sh:31)

Creates an anonymous volume that may be harder to manage/debug later. Consider creating a named volume for better tracking.

---

Minor Issues and Suggestions

11. biome.json Fix (Line 11)

Good catch fixing the missing comma! This was a syntax error.

12. pnpm-lock.yaml Changes

These appear to be from a merge/rebase from the base branch. Verify these are intentional.

13. Documentation

Consider adding a README or comments in CLAUDE.md explaining when to use each script: When to backup vs. restore, What nuke-postgres does (destructive!), Example workflows

14. engine-postgres.sh Enhancement is Good

The auto-start functionality (lines 12-28) is a nice UX improvement. However, it references postgres.sh which should be checked into the repo.

---

Test Coverage

Scripts have basic error handling but no automated tests, no validation of backup file integrity, and no test for restore correctness.

Recommendation: Consider adding a simple test script that starts postgres, inserts test data, backs up, nukes, restores, and verifies test data exists.

---

Security Assessment

Hardcoded credentials (dev only, but still a pattern concern). No injection vulnerabilities detected (good use of quoting). Appropriate use of set -euo pipefail. No backup encryption (consider for sensitive dev data).

---

Summary

Approval Status: Approve with recommendations

This PR adds valuable development tooling. The scripts are well-structured and follow bash best practices (set -euo pipefail, proper quoting). However, implementing the safety checks (especially the confirmation prompt in restore) would prevent potential foot-guns.

Priority Fixes:

1. Add confirmation prompt to restore-postgres.sh (Critical - prevents data loss)
2. Add health check after restore (High - prevents confusing errors)
3. Check for docker command availability (Medium - better error messages)
4. Consistent error message formatting (Low - polish)

Nice to Have:

• Documentation in CLAUDE.md or a README
• Backup integrity validation
• Named volumes for better tracking

Great work on improving the developer experience!

[claude]

Code Review

This PR adds useful PostgreSQL backup/restore scripts for local development. Overall the implementation is solid, but I have identified several issues that should be addressed before merging.

Critical Issues

1. Data Loss Risk in backup-postgres.sh (scripts/run/backup-postgres.sh:35-39)

The backup script does not stop the container before backing up, which can lead to corrupted/inconsistent backups if transactions are in progress. PostgreSQL should be stopped or you should use pg_dump instead of raw file copying.

Recommendation: Either stop the container before backup, or better yet, use pg_dump for consistent backups.

2. Volume Persistence Issue in restore-postgres.sh (scripts/run/restore-postgres.sh:31)

The restore script creates an anonymous volume with docker volume create, but the original postgres.sh does not use named volumes at all. After restore, the next run of postgres.sh will create a fresh container without the restored data.

Recommendation: Update postgres.sh to use the same named volume approach, or modify restore-postgres.sh to match postgres.sh behavior.

3. Dangerous Destructive Operation Without Confirmation

Both nuke-postgres.sh and restore-postgres.sh destroy data without asking for confirmation. This is risky for a development script.

Recommendation: Add confirmation prompts before destructive operations.

Minor Issues

4. Inconsistent Volume Management (scripts/run/backup-postgres.sh:21)

The backup script assumes the container uses a named volume, but postgres.sh does not create one. This will cause backup to fail.

5. Missing Error Handling in restore-postgres.sh (scripts/run/restore-postgres.sh:41)

The tar extraction does not check if it succeeded before starting the container. If the backup file is corrupted, you will get a container with partial/invalid data.

6. No Health Check After Restore (scripts/run/restore-postgres.sh:55-56)

The restore script does not wait for postgres to be ready after starting the container, unlike engine-postgres.sh which does wait.

7. Hardcoded Credentials (scripts/run/restore-postgres.sh:49-51)

While this is a dev script, the hardcoded credentials should match any configuration the project uses.

Positive Aspects

• Good use of set -euo pipefail for safety
• Consistent error messaging style
• Proper argument validation
• Good user feedback with echo statements
• The biome.json fix is correct (missing comma)
• engine-postgres.sh enhancement to auto-start postgres is a nice UX improvement

Test Coverage

These scripts lack any automated tests. While shell scripts are hard to test, consider adding integration tests or at minimum, document manual testing steps in the PR description.

Security Concerns

For development scripts these are acceptable, but note:

• Alpine image should be pinned to a specific version for reproducibility
• Postgres credentials are intentionally weak for local dev (acceptable)
• No sensitive data should be committed in backups (document this)

Recommendations Summary

Must Fix:

1. Fix the backup data consistency issue
2. Fix volume persistence mismatch between scripts
3. Add confirmation prompts for destructive operations

Should Fix:
4. Add error handling for tar extraction
5. Add health checks after restore
6. Pin alpine image version

Nice to Have:
7. Add manual testing documentation
8. Consider using pg_dump/pg_restore instead of raw file copying