Heroku Connect allows to connect your Salesforce Organization with a PostgreSQL database. This is an easy to use base for integrations between your application and the Salesforce ecosystem.
If the integration is a critical part of a system, it's configuration should be managed in a version control system, so that change over time is properly documented. This can also be used to move the mapping configuration between different stages of your deployment pipeline.
The generated JSON data is unfortunately not very diff friendly without further processing. This post contains a small hint about using the tool jq to transform the JSON into a very diff friendly structure.
Exporting the mapping from Heroku
Use the command line plugin for the heroku command. It can be installed with the following command:
heroku plugins:install heroku-connect-plugin
Afterwards the connect configuration can be exported with the following command:
heroku connect:export -a your-application
It will dump a JSON file into the current directory. At the time of this writing there is no way to specify an output filename yet.
Formatting the JSON with jq
The goal is to format the JSON file in a way so that we have a nice indentation, a lot of single lines and the keys should be sorted. These characteristics will turn the JSON file into something that will lead to very readable diffs when compared with a version control system or directly with the diff command.
jq -S '.mappings|=sort_by(.object_name)' < input.json > output.json
The resulting files still contain the same information, so they can be imported into Heroku Connect via calling heroku connect:import output.json.
Having good and easy to read diffs is a key feature when automating the Heroku Connect based setup. The version control system works like a time machine and it is possible to understand exactly how the mapping changed over time. This is an invaluable feature when things go wrong and one tries to understand which changes caused the problem.