External Database Configuration


Using an external database is an option that is enabled per product license. If your license has been enabled to use this feature, IQ Server can be configured to use an external PostgreSQL (10.7 or newer) database (or a PostgreSQL-compatible service such as Amazon Aurora PostgreSQL) by adding the following section to its config.yml file:

  type: postgresql
  hostname: <database-host>
  port: <database-port-if-not-default>
  name: <database-name>
  username: <database-username>
  password: <database-password>
  # key-value pairs to be appended to the database connection URL
    #example-param-key-name: example-param-value

The database user configured for the connection must have full write permission on the specified database for IQ Server to function properly. This requirement is most easily satisfied by using the same user account who owns the database.

If you have been running IQ Server before, using its embedded database, be sure to follow the procedure regarding Data Migration to PostgreSQL.


When using an external database, it is crucial to have a low latency network connection between IQ Server and the database server. Otherwise, the performance of IQ Server will notably degrade.

Be aware that any network or service disruption of the external database equally causes failures in IQ Server. To monitor the health of the IQ Server and its configured database, you can make periodic requests to the healthcheck path on its administrative port:

GET http://localhost:8071/healthcheck

If IQ Server is completely healthy, this request responds with HTTP status 200. If any issue is detected, the request will yield HTTP status 500 instead. In either case, the payload response is a JSON object detailing the state of individual operational aspects:

  "ods-database" : {
    "healthy" : true,
    "roundTripTimeInMs" : 1
  }, ...