Connecting to an Amazon Aurora DB cluster - Amazon Aurora

Connecting to an Amazon Aurora DB cluster

You can connect to an Aurora DB cluster using the same tools that you use to connect to a MySQL or PostgreSQL database. You specify a connection string with any script, utility, or application that connects to a MySQL or PostgreSQL DB instance. You use the same public key for Secure Sockets Layer (SSL) connections.

In the connection string, you typically use the host and port information from special endpoints associated with the DB cluster. With these endpoints, you can use the same connection parameters regardless of how many DB instances are in the cluster. You also use the host and port information from a specific DB instance in your Aurora DB cluster for specialized tasks, such as troubleshooting.

Note

For Aurora Serverless v1 DB clusters, you connect to the database endpoint rather than to the DB instance. You can find the database endpoint for an Aurora Serverless v1 DB cluster on the Connectivity & security tab of the AWS Management Console. For more information, see Using Amazon Aurora Serverless v1.

Regardless of the Aurora DB engine and specific tools you use to work with the DB cluster or instance, the endpoint must be accessible. An Amazon Aurora DB cluster can be created only in a virtual private cloud (VPC) based on the Amazon VPC service. That means that you access the endpoint from either inside the VPC or outside the VPC using one of the following approaches.

  • Access the Amazon Aurora DB cluster inside the VPC – Enable access to the Amazon Aurora DB cluster through the VPC. You do so by editing the Inbound rules on the Security group for the VPC to allow access to your specific Aurora DB cluster. To learn more, including how to configure your VPC for different Aurora DB cluster scenarios, see Amazon Virtual Private Cloud VPCs and Amazon Aurora.

  • Access the Amazon Aurora DB cluster outside the VPC – To access an Amazon Aurora DB cluster from outside the VPC, use the public endpoint address of the Amazon Aurora DB cluster. You can also connect to an Amazon Aurora DB cluster that's inside a VPC from an Amazon EC2 instance that't not in the VPC by using ClassicLink. For more information, see A DB instance in a VPC accessed by an EC2 instance not in a VPC.

For more information, see Troubleshooting Aurora connection failures.

Connecting to an Amazon Aurora MySQL DB cluster

To authenticate to your Aurora MySQL DB cluster, you can use either MySQL user name and password authentication or AWS Identity and Access Management (IAM) database authentication. For more information on using MySQL user name and password authentication, see Access control and account management in the MySQL documentation. For more information on using IAM database authentication, see IAM database authentication.

When you have a connection to your Amazon Aurora DB cluster with MySQL 5.6 compatibility, you can run SQL commands that are compatible with MySQL version 5.6. For more information about MySQL 5.6 SQL syntax, see the MySQL 5.6 reference manual.

When you have a connection to your Amazon Aurora DB cluster with MySQL 5.7 compatibility, you can run SQL commands that are compatible with MySQL version 5.7. For more information about MySQL 5.7 SQL syntax, see the MySQL 5.7 reference manual. For information about limitations that apply to Aurora MySQL 5.7, see Comparison of Aurora MySQL 5.7 and MySQL 5.7.

Note

For a helpful and detailed guide on connecting to an Amazon Aurora MySQL DB cluster, you can see the Aurora connection management handbook.

In the details view for your DB cluster, you can find the cluster endpoint, which you can use in your MySQL connection string. The endpoint is made up of the domain name and port for your DB cluster. For example, if an endpoint value is mycluster.cluster-123456789012.us-east-1.rds.amazonaws.com:3306, then you specify the following values in a MySQL connection string:

  • For host or host name, specify mycluster.cluster-123456789012.us-east-1.rds.amazonaws.com

  • For port, specify 3306 or the port value you used when you created the DB cluster

The cluster endpoint connects you to the primary instance for the DB cluster. You can perform both read and write operations using the cluster endpoint. Your DB cluster can also have up to 15 Aurora Replicas that support read-only access to the data in your DB cluster. The primary instance and each Aurora Replica has a unique endpoint that is independent of the cluster endpoint and allows you to connect to a specific DB instance in the cluster directly. The cluster endpoint always points to the primary instance. If the primary instance fails and is replaced, then the cluster endpoint points to the new primary instance.

To view the cluster endpoint (writer endpoint), choose Databases on the Amazon RDS console and choose the name of the DB cluster to show the DB cluster details.


                Amazon Aurora details

Connection utilities for Aurora MySQL

Some connection utilities you can use are the following:

  • Command line – You can connect to an Amazon Aurora DB cluster by using tools like the MySQL command line utility. For more information on using the MySQL utility, see mysql - the MySQL command line tool in the MySQL documentation.

  • GUI – You can use the MySQL Workbench utility to connect by using a UI interface. For more information, see the Download MySQL workbench page.

  • Applications – You can use the MariaDB Connector/J utility to connect your applications to your Aurora DB cluster. For more information, see the MariaDB Connector/J download page.

    Note

    If you use the MariaDB Connector/J utility with an Aurora Serverless v1 DB cluster, use the prefix jdbc:mariadb:aurora// in your connection string. The mariadb:aurora parameter avoids the automatic DNS scan for failover targets. That scanning is not needed with Aurora Serverless v1 DB clusters and causes a delay in establishing the connection.

You can use SSL encryption on connections to an Amazon Aurora DB instance. For information, see Using SSL with a MySQL DB instance.

Connecting with SSL for Aurora MySQL

To connect using SSL, use the MySQL utility as described in the following procedure. If you are using IAM database authentication, you must use an SSL connection. For information, see IAM database authentication.

Note

To connect to the cluster endpoint using SSL, your client connection utility must support Subject Alternative Names (SAN). If your client connection utility doesn't support SAN, you can connect directly to the instances in your Aurora DB cluster. For more information on Aurora endpoints, see Amazon Aurora connection management.

To connect to a DB cluster with SSL using the MySQL utility

  1. Download the public key for the Amazon RDS signing certificate.

    For information about downloading certificates, see Using SSL/TLS to encrypt a connection to a DB cluster.

  2. Type the following command at a command prompt to connect to the primary instance of a DB cluster with SSL using the MySQL utility. For the -h parameter, substitute the endpoint DNS name for your primary instance. For the --ssl_ca parameter, substitute the SSL certificate file name as appropriate. Type the master user password when prompted.

    mysql -h mycluster-primary.123456789012.us-east-1.rds.amazonaws.com --ssl-ca=[full path]rds-combined-ca-bundle.pem --ssl-verify-server-cert

You should see output similar to the following.

Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 350 Server version: 5.6.10-log MySQL Community Server (GPL) Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql>

For general instructions on constructing Amazon RDS MySQL connection strings and finding the public key for SSL connections, see Connecting to a DB instance running the MySQL database engine.

Connecting with the Amazon Web Services JDBC Driver for MySQL (preview)

This is preview documentation for Amazon Web Services JDBC Driver for MySQL. It is subject to change.

The AWS JDBC Driver for MySQL (preview) is a client driver designed for the high availability of Aurora MySQL. The AWS JDBC Driver for MySQL is drop-in compatible with the MySQL Connector/J driver.

The AWS JDBC Driver for MySQL takes full advantage of the failover capabilities of Aurora MySQL. The AWS JDBC Driver for MySQL fully maintains a cache of the DB cluster topology and each DB instance's role, either primary DB instance or Aurora Replica. It uses this topology to bypass the delays caused by DNS resolution so that a connection to the new primary DB instance is established as fast as possible.

For more information about the AWS JDBC Driver for MySQL and complete instructions for using it, see the AWS JDBC Driver for MySQL GitHub repository.

Connecting to an Amazon Aurora PostgreSQL DB cluster

You can connect to a DB instance in your Amazon Aurora PostgreSQL DB cluster using the same tools that you use to connect to a PostgreSQL database. As part of this, you use the same public key for Secure Sockets Layer (SSL) connections. You can use the endpoint and port information from the primary instance or Aurora Replicas in your Aurora PostgreSQL DB cluster in the connection string of any script, utility, or application that connects to a PostgreSQL DB instance. In the connection string, specify the DNS address from the primary instance or Aurora Replica endpoint as the host parameter. Specify the port number from the endpoint as the port parameter.

When you have a connection to a DB instance in your Amazon Aurora PostgreSQL DB cluster, you can run any SQL command that is compatible with PostgreSQL.

In the details view for your Aurora PostgreSQL DB cluster you can find the cluster endpoint. You use this endpoint in your PostgreSQL connection string. The endpoint is made up of the domain name and port for your DB cluster. For example, if an endpoint value is mycluster.cluster-123456789012.us-east-1.rds.amazonaws.com:5432, then you specify the following values in a PostgreSQL connection string:

  • For host or host name, specify mycluster.cluster-123456789012.us-east-1.rds.amazonaws.com

  • For port, specify 5432 or the port value you used when you created the DB cluster

The cluster endpoint connects you to the primary instance for the DB cluster. You can perform both read and write operations using the cluster endpoint. Your DB cluster can also have up to 15 Aurora Replicas that support read-only access to the data in your DB cluster. Each DB instance in the Aurora cluster (that is, the primary instance and each Aurora Replica) has a unique endpoint that is independent of the cluster endpoint. This unique endpoint allows you to connect to a specific DB instance in the cluster directly. The cluster endpoint always points to the primary instance. If the primary instance fails and is replaced, the cluster endpoint points to the new primary instance.

To view the cluster endpoint (writer endpoint), choose Databases on the Amazon RDS console and choose the name of the DB cluster to show the DB cluster details.


                Amazon Aurora details

Connection utilities for Aurora PostgreSQL

Some connection utilities you can use are the following:

  • Command line – You can connect to an Amazon Aurora PostgreSQL DB instance by using tools like psql, the PostgreSQL interactive terminal. For more information on using the PostgreSQL interactive terminal, see psql in the PostgreSQL documentation.

  • GUI – You can use the pgAdmin utility to connect to a PostgreSQL DB instance by using a UI interface. For more information, see the Download page from the pgAdmin website.

  • Applications – You can use the PostgreSQL JDBC driver to connect your applications to your PostgreSQL DB instance. For more information, see the Download page from the PostgreSQL JDBC driver website.

Troubleshooting Aurora connection failures

Common causes of connection failures to a new Aurora DB cluster include the following:

  • Security group in the VPC doesn't allow access – Your VPC needs to allow connections from your device or from an Amazon EC2 instance by proper configuration of the Security group in the VPC. To resolve, modify your VPC's Security group Inbound rules to allow connections. For an example, see Create a VPC and subnets.

  • Port blocked by firewall rules – Check the value of the port configured for your Aurora DB cluster. If a firewall rule blocks that port, you can re-create the instance using a different port.

  • Incomplete or incorrect IAM configuration – If you created your Aurora DB instance to use IAM–based authentication, make sure that it's properly configured. For more information, see IAM database authentication.

For more information about troubleshooting Aurora DB connection issues, see Can't connect to Amazon RDS DB instance.