​
Overview

When you provision a Database on Aptible, you’ll be provided with a set of Database Credentials.
The password in Database Credentials should be protected for security.
Database Credentials are presented as connection URLs. Many libraries can use those directly, but you can always break down the URL into components. The structure is:

​
Connecting to a Database using Database Credentials

There are three ways to connect to a Database using Database Credentials:
  • Direct Access: This set of credentials is usable with Network Integrations. This is also how Apps, other Databases, and Ephemeral SSH Sessions within the Stack can contact the Database. Direct Access can be achieved by running the aptible db:url command and accessing the Database Credentials from the Aptible Dashboard.
  • Database Endpoint: Database Endpoints allow users to expose Aptible Databases on the public internet. When another Database Endpoint is created, a separate set of Database Credentials is provided. Database Endpoints are useful if, for example, a third party needs to be granted access to the Aptible Database. This set of Database Credentials can be found in the Dashboard.
  • Database Tunnels: The aptible db:tunnel CLI command allows users to create a Database Tunnel, which provides a convenient, ad-hoc method for users to connect to Aptible Databases from a local workstation. Database Credentials are exposed in the terminal when you successfully tunnel and are only valid while the db:tunnel is up. Database Tunnels persist until the connection is closed or for a maximum of 24 hours.
The Database Credentials provides credentials for the aptible user, but you can also create your own users for database types that support multiple users such as PostgreSQL and MySQL. Refer to the database’s own documentation for detailed instructions. If setting up a restricted user, review our Setting Up Restriced User documentation for extra considerations.
Note that certain Supported Databases provide multiple credentials. Refer to the respective Database documentation for more information.

​
Connnecting to Mulitple Databases within your App

You can create multiple environment variables to store multiple database URLs, utilizing different variable names for each database. These can then be used in a database.yml file. The Aptible platform is agnostic as to how you store your DB configuration, as long as your are reading the added environment variables correctly. If you have additional questions regarding configuring a Database.yml file, please contact Aptible Support

​
Rotating Database Credentials

The only way to rotate Database Credentials without any downtime is to create separate Database users and update Apps to use the newly created user’s credentials. Additionally, these separate users limit the impact of security vulnerabilities because applications are not granted more permissions than they need. While using the built-in aptible user may be convenient for Databases that support it (MySQL, PostgreSQL, MongoDB, Elasticsearch 7). Aptible recommends creating a separate user that is granted only the minimum permissions required by the application. The aptible user credentials can only be rotated by contacting Aptible Support. Please note that rotating the aptible user’s credentials will involve an interruption to the app’s availability.

​
Setting Up a Restricted User

Aptible role management for the Environment is limited to what the Aptible user can do through the CLI or Dashboard; Database user management is separate. You can create other database users on the Database with CREATE USER . However, this can lead to exposing the Database so that it can be accessed by this individual without giving them access to the aptible database user’s credentials. Traditionally, you use aptible db:tunnel to access the Database locally but this command prints the tunnel URL with the aptible user credentials. This can lead to two main scenarios:

​
If you don’t mind giving this individual access to the aptible credentials

Then you can give them Manage access to the Database’s Environment so they can tunnel into the database, and use the read-only user and password to log in via the tunnel. This is relatively easy to implement and can help prevent accidental writes but doesn’t ensure that this individual doesn’t login as aptible . The user would also have to remember not to copy/paste the aptible user credentials printed every time they tunnel.

​
If this individual cannot have access to the aptible credentials

Then this user cannot have Manage access to the Database which removes db:tunnel as an option.
  • If the user only needs CLI access, you can create an App with a tool like psql installed on a different Environment on the same Stack. The user can aptible ssh into the App and use psql to access the Database using the read-only credentials. The Aptible user would require Manage access to this second Environment, but would not need any access to the Database’s Environment for this to work.
  • If the user needs access from their private system, then you’ll have to create a Database Endpoint to expose the Database over the internet. We strongly recommend using IP Filtering to restrict access to the IP addresses or address ranges that they’ll be accessing the Database from so that the Database isn’t exposed to the entire internet for anyone to attempt to connect to.