Aurora PostgreSQL Setup

This article is for general guidance. Always work with your DBA when setting up a production database. If you have any questions, contact Senzing Support . Support is 100% FREE!
When upgrading from Senzing v3 to Senzing v4, there are changes made to the entity repository database schema. See Upgrading the Senzing Repository Schema To V4

Prerequisites

  • An AWS Aurora PostgreSQL cluster

  • A <username>, <password> (or IAM role), cluster <endpoint>, and <database> from the DBA that has select, delete, update, and truncate access

  • An Aurora PostgreSQL cluster tuned for Senzing

  • libpq and psql packages installed

  • Ubuntu/Debian: typically uses libpq5 and postgresql-client-common/postgresql-client-<version> packages
  • AWS Linux 2/Red Hat: typically uses postgresql<version>-libs and postgresql<version> packages
For IAM authentication, AWS credentials must be available in the environment (for example, instance profile, environment variables, or ~/.aws/credentials). The AWS SDK is used to generate short-lived authentication tokens.

Add the Senzing schema

If applicable, the DBA should set up the database schema. If you have any questions, contact Senzing Support . Support is 100% FREE!

Connect to the Aurora PostgreSQL cluster using the cluster writer endpoint:

psql -U <user> -d <database> -h <cluster-endpoint> -W

\i <senzing_project_path>/resources/schema/szcore-schema-postgresql-create.sql
<senzing_project_path> refers to the path specified with the /opt/senzing/er/bin/sz_create_project command when creating a project.
\dt

\q

Configure the CONNECTION string

Edit the SENZING_ENGINE_CONFIGURATION_JSON environment variable or sz_engine_config.ini file :

Aurora PostgreSQL uses the aurorapostgresql:// URI scheme instead of postgresql://. This selects the Aurora-specific driver plugin, which handles IAM token authentication.

Standard password authentication

Edit the new CONNECTION aurorapostgresql://<username>:<password>@<cluster-endpoint>:5432/<database> entry where:

5432 is the default PostgreSQL port number. Change this if the port value differs.
Parameter Description
<username> Aurora PostgreSQL username
<password> Password for the above username
<cluster-endpoint> Aurora cluster writer endpoint (for example, mycluster.cluster-xxxx.us-east-1.rds.amazonaws.com)
5432 Port number of the Aurora PostgreSQL cluster
<database> Database name

IAM authentication

IAM authentication uses short-lived tokens (up to 15 minutes) generated by the AWS SDK instead of a static password. Tokens are cached process-wide and regenerated automatically when an authentication failure occurs.

aurorapostgresql://<username>@<cluster-endpoint>:5432/<database>?iam_auth=true&region=<aws-region>
Parameter Description
<username> Aurora PostgreSQL username configured for IAM authentication
<cluster-endpoint> Aurora cluster writer endpoint
iam_auth=true Enables IAM token authentication
region=<aws-region> AWS region (for example, us-east-1). Recommended.
Always specify the region= parameter. The driver attempts to auto-detect the region from the endpoint hostname, but this may not work reliably with all Aurora endpoint formats.

Example:

aurorapostgresql://[email protected]:5432/senzing?iam_auth=true&region=us-east-1

IAM authentication prerequisites

  1. The Aurora cluster must have IAM database authentication enabled.
  2. A database user must be created and granted the rds_iam role:
CREATE USER senzing_user WITH LOGIN;
GRANT rds_iam TO senzing_user;
  1. An IAM policy must allow rds-db:connect for the database user.
  2. AWS credentials must be available to the Senzing process (instance profile, environment variables, or credentials file).

Update database with the Senzing ER configuration

A Senzing instance is configured with a Senzing Entity Resolution configuration. On a fresh installation this configuration needs to be registered in the Senzing database.

See Updating Database with Senzing ER Configuration

If you have any questions, contact Senzing Support. Support is 100% FREE!