​
Troubleshooting Guide: Database Connection Failures in R2R

Database connection issues can significantly impact the functionality of your R2R deployment. This guide will help you diagnose and resolve common database connection problems for both Postgres.

​
1. General Troubleshooting Steps

Before diving into database-specific issues, try these general troubleshooting steps:

  1. Check Database Service Status: Ensure the database service is running.

    docker ps | grep postgres

  2. Verify Network Connectivity: Ensure the R2R service can reach the database.

    docker exec r2r-container ping postgres

  3. Check Logs: Examine R2R and database container logs for error messages.

    docker logs r2r-container
docker logs postgres-container

  4. Verify Environment Variables: Ensure all necessary environment variables are correctly set in your Docker Compose file or deployment configuration.

​
2. Postgres Connection Issues

​
2.1 Common Postgres Error Messages

  • “FATAL: password authentication failed for user”
  • “FATAL: database does not exist”
  • “could not connect to server: Connection refused”

​
2.2 Troubleshooting Steps for Postgres

  1. Check Postgres Connection String:

    • Verify the POSTGRES_* environment variables in your R2R configuration.
    • Ensure the host, port, username, password, and database name are correct.

  2. Test Postgres Connection:

    docker exec postgres-container psql -U your_username -d your_database -c "SELECT 1;"

  3. Check Postgres Logs:

    docker logs postgres-container

  4. Verify Postgres User and Database:

    docker exec postgres-container psql -U postgres -c "\du"
docker exec postgres-container psql -U postgres -c "\l"

  5. Check Postgres Network Settings:

    • Ensure Postgres is configured to accept connections from other containers.
    • Verify the pg_hba.conf file allows connections from the R2R container’s IP range.

​
2.3 Common Solutions for Postgres Issues

  • Update the Postgres connection string in R2R configuration.
  • Recreate the Postgres user or database if they’re missing.
  • Modify Postgres network settings to allow connections from R2R.

​
3. Advanced Troubleshooting

​
3.1 Database Container Health Checks

Ensure your Docker Compose file includes proper health checks for database services:

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres"]
  interval: 10s
  timeout: 5s
  retries: 5

​
3.2 Network Debugging

If network issues persist:

  1. Inspect the Docker network:

    docker network inspect r2r-network

  2. Use network debugging tools within containers:

    docker exec r2r-container netstat -tuln
docker exec postgres-container netstat -tuln

​
3.3 Volume Permissions

Check if volume permissions are causing issues:

  1. Inspect volume permissions:

    docker exec postgres-container ls -l /var/lib/postgresql/data

  2. Adjust permissions if necessary:

    docker exec postgres-container chown -R postgres:postgres /var/lib/postgresql/data

​
4. Preventive Measures

To avoid future database connection issues:

  1. Use Docker secrets or environment files for sensitive information.
  2. Implement retry logic in your application for database connections.
  3. Set up monitoring and alerting for database health and connectivity.
  4. Regularly backup your database and test restoration procedures.

​
5. Seeking Further Help

If you’re still experiencing issues:

  1. Gather all relevant logs and configuration files.
  2. Check R2R documentation and community forums.
  3. Consider posting a detailed question on the R2R GitHub repository or community channels, providing:
    • Docker Compose file (with sensitive information redacted)
    • R2R and database version information
    • Detailed error messages and logs
    • Steps to reproduce the issue

By following this guide, you should be able to diagnose and resolve most database connection issues in your R2R deployment. Remember to always keep your database and R2R versions compatible and up to date.