Connect Guardian to an External Database

Every Guardian deployment, whether hosted or on-premises, relies on a PostgreSQL database server to store data, including node scans, user data, and more. This database runs alongside the actual Guardian application and can either be run in the same location as the application or externally. While you can choose either of these options, using an external database can improve performance by distributing the necessary resources across more than one location.

This topic outlines what's needed to connect Guardian to an external PostgreSQL database.

Note: The following information applies whether you are setting up a new instance of Guardian or migrating an existing instance to an external database.

Dependencies

To connect Guardian to an external database, you must have an existing external database server of your own. If you don't have an existing database, you must create one for use by Guardian. For information on recommended server size specifications, see Recommended Disk Specifications.

Note: Currently, Guardian only supports PostgreSQL version 14.

Once you have your database ready, proceed with the rest of this topic.

Required Database Details

To connect Guardian to an external PostgreSQL database, provide the following information to your Guardian Representative:

  • Database username.

  • Database password.

  • Database host/server IP.

  • Database name.

    Note: The database username and database name must be the same.

It's important the credentials you provide to your Guardian Representative are for a user with Superuser permissions to the database. If you have issues granting Superuser permissions to a user, see Troubleshooting below for server-specific commands to help.

SSL Details

To keep your data secure while using an external database, Secure Sockets Layer (SSL) is enabled by default. For proper configuration, provide your Guardian Representative with the following SSL details for your database:

Note: If you don't want to use SSL for any reason, speak with your Guardian Representative about disabling it.

If you wish to enable SSL, you must provide your Guardian Representative with additional information about your database:

  • SSL certificate.

  • SSL key.

  • CA certificate (optional for increased security).

Once you've provided the above details to your Guardian Representative, they'll do the work of connecting your Guardian instance to your external database. Your Guardian Representative will let you know once this is complete or if they need any further information.

Troubleshooting

Granting Superuser permissions to your database can be different depending on which cloud-hosting service you're using. To fix the issue, find your service below, then run the provided script to grant Superuser permissions.

Note: In each of the below scripts, replace yourname with the relevant username for your database.

Self-Hosted Servers

Copy 
ALTER ROLE youruser SUPERUSER;

AWS-Hosted Servers

Copy 
GRANT rds_superuser TO youruser;

Azure-Hosted Servers

Copy 
GRANT azure_pg_admin TO youruser;

When working with Azure, you must also enable the following extensions:

  • BTREE_GIN.

  • PG_TRGM.

For more information, see PostgreSQL Extensions.

Google Cloud SQL-Hosted Servers

Copy 
ALTER ROLE youruser REPLICATION;

## if not part of cloudsqlsuper user
GRANT cloudsqlsuperuser TO youruser;