​

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 and Neo4j.

​

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
   docker ps | grep neo4j
   

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

   docker exec r2r-container ping postgres
   docker exec r2r-container ping neo4j
   

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

   docker logs r2r-container
   docker logs postgres-container
   docker logs neo4j-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. Neo4j Connection Issues

​

3.1 Common Neo4j Error Messages

• “Unable to connect to Neo4j at neo4j://neo4j:7687”
• “Authentication failure”
• “Connection refused”

​

3.2 Troubleshooting Steps for Neo4j

1. Check Neo4j Connection Settings:

   • Verify the NEO4J_* environment variables in your R2R configuration.
   • Ensure the bolt URL, username, and password are correct.

2. Test Neo4j Connection:

   docker exec neo4j-container cypher-shell -u neo4j -p your_password "RETURN 1;"
   

3. Check Neo4j Logs:

   docker logs neo4j-container
   

4. Verify Neo4j Authentication:

   • Ensure the Neo4j password is correctly set and matches the R2R configuration.

5. Check Neo4j Network Settings:

   • Verify that Neo4j is configured to accept connections on the correct interfaces.

​

3.3 Common Solutions for Neo4j Issues

• Update the Neo4j connection settings in R2R configuration.
• Reset the Neo4j password if authentication is failing.
• Modify Neo4j configuration to allow connections from R2R container.

​

4. Advanced Troubleshooting

​

4.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

​

4.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
   

​

4.3 Volume Permissions

Check if volume permissions are causing issues:

1. Inspect volume permissions:

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

2. Adjust permissions if necessary:

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

​

5. 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.

​

6. 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.