Heroku PostgreSQL

Heroku PostgreSQL is a managed PostgreSQL database service provided by Heroku. The Heroku PostgreSQL connector enables you to access Heroku Postgres databases via the Heroku Platform API using token-based authentication, allowing you to retrieve add-on information, provision new databases, and access database credentials programmatically. This connector is particularly useful for applications that need to manage Heroku Postgres databases, retrieve database connection information, or automate database provisioning workflows.

Power end-to-end data operations for your Heroku PostgreSQL API with Nexla. Our bi-directional Heroku PostgreSQL connector is purpose-built for Heroku PostgreSQL, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Heroku PostgreSQL or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Heroku PostgreSQL workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

Before creating a Heroku PostgreSQL credential, you'll need to obtain a Heroku API token from your Heroku account. The Heroku Platform API uses bearer token authentication, and the API token is used to authenticate all API requests.

To obtain a Heroku API token:

1. Log in to your Heroku account at https://dashboard.heroku.com or use the Heroku CLI.

2. Navigate to your account settings. You can access this by clicking on your account name in the top right corner of the Heroku dashboard and selecting Account Settings, or by visiting https://dashboard.heroku.com/account.

3. In the Account Settings page, scroll down to the API Key section.

4. Click Reveal or Show next to the API Key field to display your existing API token, or click Generate New API Key if you need to create a new one.

5. Copy the API token immediately after it's displayed. The token is a long string of characters that will be used as a Bearer token in API requests.

6. Store the API token securely, as it provides full access to your Heroku account via the Platform API.

Alternatively, you can also obtain your API token using the Heroku CLI by running the command heroku auth:token in your terminal. This will display your current API token.

For detailed information about Heroku API authentication and token management, refer to the Heroku Platform API Documentation and Heroku API Authentication Guide.

Authenticate

Credentials required

Authenticate using a Heroku API bearer token.

Field	Required	Secret	Description
Heroku API Token	Yes	Yes	Your Heroku API token.

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

New Credential Overlay – Heroku PostgreSQL

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

3. In the Heroku API Token field, enter the Heroku API token that you obtained from your Heroku account settings. This token is used as a Bearer token in the Authorization header for all Heroku Platform API requests.

   The Heroku API token is sensitive information and provides full access to your Heroku account via the Platform API. Keep it secure and do not share it publicly. If you suspect your token has been compromised, regenerate it immediately in your Heroku account settings.

4. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Heroku PostgreSQL connector tile, then select the credential that will be used to connect to the Heroku Platform API, and click Next; or, create a new Heroku PostgreSQL credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Heroku Platform API endpoints. Each template is designed specifically for the corresponding Heroku API endpoint, making data source setup easy and efficient. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

Get Add-ons

This endpoint retrieves a list of Heroku add-ons for a given Heroku application. Use this endpoint when you need to discover which add-ons (including PostgreSQL databases) are attached to a specific Heroku app, retrieve add-on metadata, or monitor add-on configurations.

• Enter the name of your Heroku application in the Heroku App Name field. This is the name of the Heroku app for which you want to retrieve add-ons. You can find your app name in the Heroku dashboard or by using the Heroku CLI command heroku apps.
• Enter a schedule in cron format in the Schedule field to specify when this endpoint should be executed. The schedule determines how frequently Nexla will retrieve add-on information. The default value is 0 * * * *, which runs the endpoint every hour. You can customize this to match your monitoring or data collection needs.

This endpoint returns all add-ons attached to the specified Heroku application, including PostgreSQL databases and other add-on services. The response includes add-on metadata such as add-on names, IDs, plans, and configuration details. For more information about the Get Add-ons endpoint, refer to the Heroku Platform API Documentation.

Create Heroku Postgres DB

This endpoint provisions a new Heroku Postgres database add-on for a specified Heroku application. Use this endpoint when you need to programmatically create new PostgreSQL databases, automate database provisioning workflows, or set up databases on a schedule.

• Enter the name of the Heroku application in the Heroku App Name field. This is the name of the Heroku app to which the new Postgres add-on will be attached. The app must exist in your Heroku account before you can attach a database to it.

• Enter the Postgres plan name in the Postgres Plan field. Available plan names include hobby-dev (free tier for development), standard-0, premium-0, and other Heroku Postgres plan tiers. The plan determines the database size, performance characteristics, and pricing. Common plan names include:

  • hobby-dev: Free tier for development and testing
  • standard-0: Standard tier for production workloads
  • premium-0: Premium tier with enhanced performance

  You can find the complete list of available plans in the Heroku dashboard or Heroku documentation.

• Enter a schedule in cron format in the Schedule field to specify when this endpoint should be executed. The schedule determines how frequently Nexla will attempt to create a new Postgres database. The default value is 0 3 * * *, which runs the endpoint once per day at 3 AM. Use this carefully, as creating databases too frequently may result in unnecessary costs.

This endpoint creates a new Heroku Postgres add-on and attaches it to the specified application. Creating databases programmatically can result in charges to your Heroku account, so ensure you understand the pricing for the selected plan. The endpoint returns information about the newly created database, including the add-on ID and configuration details. For more information about the Create Heroku Postgres DB endpoint, refer to the Heroku Platform API Documentation.

Get Credentials

This endpoint retrieves credentials for a Heroku Postgres add-on, including database connection information such as host, port, database name, username, and password. Use this endpoint when you need to programmatically access database connection strings, retrieve credentials for database connections, or monitor database configuration changes.

• Enter the name of the Heroku application in the Heroku App Name field. This is the name of the Heroku app that has the Postgres add-on attached to it.
• Enter the Postgres add-on ID in the Postgres Add-on ID field. This is the identifier for the add-on instance, which typically follows the format HEROKU_POSTGRESQL_IVORY, HEROKU_POSTGRESQL_COLOR, or similar. You can find the add-on ID by using the "Get Add-ons" endpoint first, or by checking the Heroku dashboard under your app's settings and add-ons section.
• Enter a schedule in cron format in the Schedule field to specify when this endpoint should be executed. The schedule determines how frequently Nexla will retrieve credentials. The default value is 0 6 * * *, which runs the endpoint once per day at 6 AM. You can adjust this based on how often you need to refresh or monitor database credentials.

This endpoint returns database credentials including connection strings, host information, and authentication details. The credentials are sensitive information and should be handled securely. Heroku may rotate credentials periodically, so retrieving them on a schedule ensures you have the most current connection information. For more information about the Get Credentials endpoint, refer to the Heroku Platform API Documentation.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

Heroku PostgreSQL data sources can also be manually configured to ingest data from any valid Heroku Platform API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

Heroku Platform API endpoints typically follow the pattern https://api.heroku.com/apps/{app-name}/addons or https://api.heroku.com/apps/{app-name}/addons/{addon-id}/config. Requests require the header Accept: application/vnd.heroku+json; version=3 to specify the API version and response format; the Authorization: Bearer {token} header is typically handled automatically by your credential configuration. For the response data path, use $[*] for a root-level array of objects, or $.data[*] if the response is wrapped in a data object. For complete information about Heroku Platform API endpoints and response formats, see the Heroku Platform API Documentation.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Heroku PostgreSQL data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.