Can't Connect AWS RDS using Sequelize: A Troubleshooting Guide

Connecting AWS RDS with Sequelize often fails due to network misconfigurations, incorrect SSL settings, or missing security group rules. This guide resolves the most common connection errors by verifying VPC peering, adjusting security group inbound rules, and configuring Sequelize’s dialect options for secure database access.

Verify Network Connectivity and Security Groups

The most frequent cause of a "Connection Refused" error is that the EC2 instance or local machine cannot reach the RDS endpoint. AWS RDS instances are isolated within Virtual Private Clouds (VPCs) by default. If your application runs on an EC2 instance, ensure both resources are in the same VPC or that proper peering is established. You must also configure the RDS Security Group to allow incoming traffic on port 3306 for MySQL, 5432 for PostgreSQL, or 1433 for SQL Server from your application’s IP address or subnet. Check the security group attached to your RDS instance. Navigate to the EC2 console, select Security Groups, and edit the inbound rules. Add a rule allowing TCP traffic from your application server’s security group or specific CIDR block. Without this explicit permission, AWS will drop all connection attempts regardless of your Sequelize configuration. If you are connecting from a local development environment, ensure your public IP is whitelisted in the security group rules. For deeper network diagnostics, use the telnet command from your application host. Run telnet your-rds-endpoint.amazonaws.com 3306. A successful connection will clear the screen, while a failure indicates a network block. If you suspect DNS resolution issues, verify that the endpoint resolves correctly using nslookup. This step isolates whether the problem lies in routing or in the Sequelize code itself.

Configure Sequelize Dialect and Options Correctly

Sequelize requires specific dialect configurations to communicate effectively with different database engines. When initializing your database connection, ensure you specify the correct dialect corresponding to your RDS engine. For MySQL, use 'mysql'; for PostgreSQL, use 'postgres'; and for SQL Server, use 'mssql'. Incorrect dialect selection can lead to syntax errors or protocol mismatches during the handshake phase. The connection object must include the host, username, password, database name, and port. The host should be the full RDS endpoint provided in the AWS Console under the Database section. Do not use the internal private IP unless you are running within the same VPC and have configured internal DNS resolution properly. Always set the dialectOptions if you require SSL or specific authentication methods. Review the following example structure for a PostgreSQL connection:

const sequelize = new Sequelize('database', 'username', 'password', {
  host: 'your-rds-endpoint.amazonaws.com',
  dialect: 'postgres',
  port: 5432,
  dialectOptions: {
    ssl: {
      rejectUnauthorized: true
    }
  }
});

Notice the ssl option. AWS RDS enforces SSL connections by default for many configurations. If you omit this or set rejectUnauthorized incorrectly, the connection will fail with an SSL negotiation error. You may need to download the AWS RDS certificate bundle and pass it via the ca property in dialectOptions if strict verification is required.

Handle SSL and Authentication Requirements

AWS RDS increasingly mandates encrypted connections. If your Sequelize setup does not handle SSL certificates correctly, you will encounter errors like "SSL SYSCALL error: EOF detected." To resolve this, you must obtain the root CA certificate from the AWS RDS documentation page relevant to your region. Save this certificate as a file, such as rds-combined-ca-bundle.pem, and reference it in your Sequelize configuration. Update your dialectOptions to include the path to the certificate:

dialectOptions: {
  ssl: {
    ca: fs.readFileSync('/path/to/rds-combined-ca-bundle.pem')
  }
}

This ensures that the client verifies the server’s identity against the trusted AWS certificate authority. If you are developing locally, consider using a tool like sshuttle or setting up an SSH tunnel to bypass local firewall restrictions while maintaining encryption. Remember that IAM database authentication is another alternative for PostgreSQL and MySQL, which uses temporary tokens instead of static passwords. This method enhances security but requires additional library support and IAM role configuration.

Debugging Connection Timeouts

If you experience timeouts rather than immediate refusals, the issue may lie in network latency or intermediate firewalls. Increase the connectionTimeoutMS option in Sequelize to allow more time for the handshake. Set it to 30000 milliseconds (30 seconds) to give the network sufficient time to establish the link. Sometimes, aggressive firewall policies on corporate networks block long-lived TCP connections, causing intermittent failures. Check your application logs for detailed error messages. Sequelize provides verbose logging when enabled. Pass logging: console.log during initialization to see the raw SQL commands and connection attempts. Look for errors related to "ETIMEDOUT" or "ECONNRESET." These indicate network-level issues rather than database logic problems. If the connection succeeds intermittently, check for VPN interference or dynamic IP changes that might not be reflected in your security groups. For persistent issues, compare your setup against known good configurations. Ensure that the database instance status is "Available" in the AWS Console. Instances undergoing maintenance or backups may temporarily reject new connections. Also, verify that the maximum number of connections limit has not been reached. High concurrency applications can exhaust the connection pool, leading to queue delays and eventual timeouts. Adjust the pool options in Sequelize to manage concurrent connections more efficiently.

Frequently Asked Questions

Why does my connection work locally but fail on EC2?

This usually indicates a security group misconfiguration where the EC2 instance’s IP or security group ID is not allowed in the RDS inbound rules. Verify that the EC2 instance and RDS are in compatible VPCs or that peering routes are correctly established between them.

How do I disable SSL for testing purposes?

You can set rejectUnauthorized: false in the dialectOptions.ssl object, but this is strongly discouraged for production due to security risks. Disabling SSL exposes your credentials and data to interception over the network. Use this only in isolated development environments where security is not a concern.

What causes "Access Denied" errors in Sequelize?

This error typically stems from incorrect username or password credentials, or insufficient IAM permissions if using IAM authentication. Double-check the exact case-sensitive values entered in your Sequelize config and ensure the database user has the necessary privileges to connect and access the specified schema.

Can I use IAM database authentication with Sequelize?

Yes, but it requires additional setup. You must generate a temporary authentication token using the AWS SDK before creating the Sequelize instance. Replace the static password field with this generated token in your connection configuration. This approach eliminates the need to store long-term database passwords in your code.

How do I increase the connection timeout in Sequelize?

Add the connectionTimeoutMS property to your Sequelize constructor options. Setting this to a higher value, such as 30000, allows the client to wait longer for the database to respond during the initial handshake phase. This helps mitigate issues caused by high network latency or busy database servers.