​
R2R Troubleshooting Guide: Incorrect Database Credentials

Database connectivity issues due to incorrect credentials are a common problem when deploying R2R. This guide will help you identify and resolve these issues.

​
Symptoms

  • Error messages containing phrases like “authentication failed”, “access denied”, or “connection refused”
  • R2R application fails to start or crashes shortly after starting
  • Database-related operations fail while other parts of the application seem to work

​
Diagnosis Steps

  1. Check Error Logs
    • Review R2R application logs for specific error messages
    • Look for database-related errors, especially those mentioning authentication or connection issues
  2. Verify Environment Variables
    • Ensure all database-related environment variables are set correctly
    • Common variables include: 
      POSTGRES_USER
POSTGRES_PASSWORD
POSTGRES_HOST
POSTGRES_PORT
POSTGRES_DBNAME
  3. Test Database Connection
    • Use a database client tool to test the connection with the same credentials
    • For PostgreSQL, you can use the psql command-line tool: 
      psql -h <host> -p <port> -U <username> -d <database_name>
  4. Check Database Server Status
    • Ensure the database server is running and accessible from the R2R container
    • Verify network connectivity between R2R and the database server
  5. Inspect Docker Compose File
    • Review the docker-compose.yml file to ensure database service configuration is correct
    • Check for any discrepancies between the database service and R2R service configurations

​
Resolution Steps

  1. Correct Environment Variables
    • Update the .env file or set environment variables with the correct database credentials
    • Ensure these variables are properly passed to the R2R container
  2. Update Docker Compose File
    • If using Docker Compose, update the docker-compose.yml file with the correct database configuration
    • Ensure the database service name matches what R2R is expecting (e.g., postgres)
  3. Rebuild and Restart Containers
    • After making changes, rebuild and restart your Docker containers: 
      docker-compose down
docker-compose up --build
  4. Check Database User Permissions
    • Ensure the database user has the necessary permissions
    • For PostgreSQL, you might need to grant permissions: 
      GRANT ALL PRIVILEGES ON DATABASE <database_name> TO <username>;
  5. Verify Database Existence
    • Ensure the specified database exists
    • Create it if necessary: 
      CREATE DATABASE <database_name>;
  6. Check Network Configuration
    • If using Docker, ensure the database and R2R services are on the same network
    • Verify firewall rules allow traffic between R2R and the database
  7. Use Secrets Management
    • Consider using Docker secrets or a secure vault for managing sensitive credentials
    • Update your Docker Compose file to use secrets instead of environment variables for passwords

​
Prevention Tips

  1. Use a .env file for local development and CI/CD pipelines for production to manage environment variables
  2. Implement a health check in your Docker Compose file to ensure the database is ready before starting R2R
  3. Use database connection pooling to manage connections efficiently
  4. Regularly audit and rotate database credentials
  5. Use least privilege principle when setting up database users for R2R

​
Debugging Commands

Here are some useful commands for debugging database connection issues:
  1. Check if PostgreSQL is running: 
    docker-compose ps postgres
  2. View PostgreSQL logs: 
    docker-compose logs postgres
  3. Check R2R logs: 
    docker-compose logs r2r
  4. Access PostgreSQL CLI within the container: 
    docker-compose exec postgres psql -U <username> -d <database_name>

​
Seeking Further Help

If you’ve tried these steps and are still experiencing issues:
  1. Check the R2R documentation for any specific database setup requirements
  2. Review the R2R GitHub issues for similar problems and solutions
  3. Reach out to the R2R community on Discord or GitHub for support
  4. Provide detailed information about your setup, including:
    • R2R version
    • Database type and version
    • Relevant parts of your Docker Compose file
    • Specific error messages you’re encountering
Remember to never share actual passwords or sensitive information when seeking help. Use placeholders instead. By following this guide, you should be able to resolve most database credential issues in your R2R deployment. If problems persist, don’t hesitate to seek help from the R2R community or support channels.