Deep-dive on the Next Gen Platform. Join the Webinar!

Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Troubleshooting Node.js Apps
      • Node.js Behavior in Heroku
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Heroku Enterprise
  • Heroku Connect (Salesforce sync)
  • Heroku Connect Administration
  • Heroku Connect Maintenance Operations

Heroku Connect Maintenance Operations

English — 日本語に切り替える

Last updated December 20, 2022

Table of Contents

  • Heroku Connect Maintenances
  • Changing the Plan of Your Heroku Postgres Database
  • Upgrading the Version of a Heroku Postgres Database
  • Recovering Synchronization After a Database Rollback
  • Pausing Synchronization
  • Recreating a Connection
  • Changing Field Definitions in Salesforce

This article covers Heroku Connect maintenances. It also covers how to change your Heroku Postgres plan or upgrade its version.

Heroku Connect Maintenances

From time to time, Heroku takes Heroku Connect offline to perform maintenance tasks. Typical tasks include updating the underlying infrastructure. This maintenance is handled automatically by Heroku. Unlike Heroku Postgres, you can’t schedule or reschedule maintenance windows for Heroku Connect.

Maintenances typically take up to 45 minutes. During maintenance, all data synchronization for Heroku Connect is unavailable. Configuring Heroku Connect is also unavailable. Existing data in the Heroku Postgres database remains accessible. Connect retains changes and resumes synchronizing after the maintenance.

Preparing for Heroku Connect Maintenances

Maintenance windows are announced roughly two weeks before they happen on status.heroku.com. You can click Subscribe on that page to get notifications.

There’s nothing you must do to prepare besides being aware of and preparing for the delay in data sync during the maintenance window. Connect resumes normal sync following the maintenance operation.

Changing the Plan of Your Heroku Postgres Database

If you want to change the plan of your Heroku Postgres Database, you can use the heroku addons:upgrade command to do so. Heroku Connect is able to handle this operation transparently since it behaves identically to an HA failover.

While not recommended, you could use the Follower Changeover method instead. If you wish to do that then you must take additional steps as those documented in the following section, omitting step 4.

If you’re upgrading from an Essential-tier database to a plan in another tier, you can’t create a follower. Instead, use the pg:copy process to copy data into the new database. Pause Heroku Connect at the same time as you put your application into maintenance mode, and resume it again when you reactivate your application.

Upgrading the Version of a Heroku Postgres Database

Heroku Connect operates continuously on a single database, which requires a few steps in order to upgrade the version of that database and allow sync operations to continue as expected. The upgrade itself is done using a follower database and pg:upgrade, and these instructions illustrate how Heroku Connect fits into that process.

These steps ensure that the new database is an exact copy of your current database. Heroku Connect doesn’t create tables or transfer data to an empty database, so be sure to follow the proper upgrade process.

 

If you’re upgrading the version on an Essential-tier database, use the pg:copy process to copy data into the new database instead. Pause Heroku Connect at the same time as you put your application into maintenance mode, and resume it again when you reactivate your application.

  1. Create your follower database and allow it to get mostly caught up with your lead database. This minimizes the amount of downtime required for the upgrade.

  2. Pause your connection for the same reason that you put your application into maintenance mode, to prevent Heroku Connect from trying to write to your database during the upgrade.

  3. Wait for your follower to catch up. Now that Heroku Connect and your application have both stopped writing to your database, the follower can get completely caught up. You can check its status using heroku pg:info.

  4. Upgrade the follower database using pg:upgrade. This has the follower unfollow the leader and perform the Postgres Version upgrade.

  5. You now must promote the follower database to become the new lead database. The steps you take depend on whether your Heroku Connect is using a standard database URL (DATABASE_URL) or a custom database URL (for example, HEROKU_POSTGRESQL_ROSE_URL).

    • If you’re using a standard database URL, Promote the follower to become the new lead database. This makes it accessible as DATABASE_URL.
    • If you’re using a custom database URL, you must update the Heroku Connect Database Settings with the new custom database URL for the promoted follower or use heroku addons:attach to attach the database to a name of your choosing.
  6. Resume Heroku Connect using the same process used to pause it in step 2, and bring your application out of maintenance mode. Heroku Connect automatically picks up the new DATABASE_URL for your application (or custom database URL, if you have that configured) and resumes synchronization using the new database.

Recovering Synchronization After a Database Rollback

Heroku Connect uses a high-water mark methodology. Rolling back a synced database causes inconsistent data. Reload mappings after a database rollback to recover data consistency.

Pausing Synchronization

When performing certain tasks, such as upgrading your database, you want to pause synchronization activity in Heroku Connect. To do this navigate to the Settings tab, Manage Connection and click the Pause button.

Heroku Connect completes any pending operations before entering the paused state. When your connection is paused then changes to data in the database continue to be added to the trigger log and changes made in Salesforce aren’t polled. Push Topic notifications from Salesforce for mappings using the streaming mode are also ignored.

Connections can only be paused when they are in the IDLE state. If your connection remains in the POLLING_DB_CHANGES status for an extended time, check your logs to debug.

To resume synchronization return to the Settings tab, Manage Connection and click the Resume button. Heroku Connect continues where it left off: entries in the trigger log are processed and pushed to Salesforce and changes made in Salesforce are retrieved using polling (including those mappings that would normally use the Streaming API).

Any changes made to data in the database or in Salesforce while your connection is paused are automatically synchronized when your connection is resumed.

Recreating a Connection

If you’ve reloaded a sandbox organization or you need to upgrade from an Essential-tier database to a plan in another tier, you must delete your existing connection and create a new one.

The following settings are manually configured:

  • Collaborators and their notifications settings
  • Beta features
  • The Write Algorithm
  • The Salesforce API version

The rest of the recreation can be automated as follows:

  1. Export your configuration from the Connect Dashboard. Click Settings, then click Import/Export Configuration, then click the Export Configuration button.
  2. If you have any read/write mappings, make sure you aren’t writing any new data to those tables, and make sure all the mappings are in DATA_SYNCED to ensure all your data is present in Salesforce. You must click Settings, Manage Connection and click the Pause button to stop activity on the connection.
  3. Destroy the Connection from the heroku CLI heroku addons:destroy -a appname herokuconnect-resource-name
  4. Create a new connection from https://elements.heroku.com or heroku addons:create herokuconnect from the command line.
  5. Authenticate your new connection, and import the config you exported from step 1.

Changing Field Definitions in Salesforce

Field definition changes can delay synchronization with Heroku Connect if not coordinated properly.

Heroku Connect doesn’t automatically change the table schema in PostgreSQL after you’ve changed the corresponding field definition in Salesforce. This is because attempting to change the field can result in data loss or corruption.

After changing a field in Salesforce, users must edit the object mapping in Heroku Connect to trigger an update to the PostgreSQL table schema by Heroku Connect. In simpler cases, all that users must do is click Edit for the mapping and then click Save. In more complex cases, users must deselect the field, save the mapping, edit the mapping again, and then re-add the field. This causes Connect to drop the column, re-add it, and load the data back into the column.

Simpler cases include extending or shortening the length of a field. More complex cases include changing the types of fields.

Keep reading

  • Heroku Connect Administration

Feedback

Log in to submit feedback.

Mapping Configuration Options Managing Heroku Connect Mappings

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices