Deployment guide
This guide will walk you through the process of deploying Epsio for PostgreSQL in your AWS environment.
Before you begin¶
Before proceeding with the deployment guide, ensure that you have the following:
- An EC2 instance to run epsio on with:
- Network access to your PostgreSQL instance.
docker
,docker compose
plugin andzip
installed on it
- A PostgreSQL Database with version 10+.
1. Launch Epsio in your VM¶
After you sign up, a wizard will appear and walk you through the stages of deployment.
Choose the architecture of your VM:
Run the displayed command in your VM:
Wait until Epsio is successfully deployed, and then proceed to the next step.
2. Connect Epsio to your database¶
The next step will be to configure your database and connect it to Epsio.
Open a connection to your database and follow the steps below.
Create a schema for Epsio's metadata:
Create a database user for Epsio's exclusive use:
Replace secret with a strong password
Grant user permissions
Grant the epsio_user
access to the epsio
schema:
GRANT USAGE ON SCHEMA epsio TO epsio_user;
GRANT CREATE ON SCHEMA epsio TO epsio_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA epsio TO epsio_user;
epsio_user
read-only access to all tables in your schema by running the following commands:
GRANT SELECT ON ALL TABLES IN SCHEMA public TO epsio_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO epsio_user;
GRANT CREATE, USAGE ON SCHEMA public TO epsio_user;
If you plan to access schemas other than the public schema, you'll need to run these commands for each schema.
Replace public
with the name of your schema.
Enter the credentials of the epsio user you've just created in the wizard and click connect:
You will also need to provide the hostname (or IP address), port and database name.
After connection, Epsio will check that your database is configured correctly and will create the functions under the epsio
schema.
Continue to the next step to configure logical replication.
3. Configure logical replication¶
3.1 Check if logical replication is enabled¶
Run the following command to check if your instance is already configured with logical replication:
postgres> SHOW rds.logical_replication;
rds.logical_replication
-------------------------
off
(1 row)
on
(or 1), it means that logical replication is enabled, skip to set up replication.If not, follow the steps below to enable logical replication.
postgres> SHOW rds.logical_replication;
rds.logical_replication
-------------------------
off
(1 row)
on
(or 1), it means that logical replication is enabled, skip to set up replication.If not, follow the steps below to enable logical replication.
logical
, it means that logical replication is enabled, skip to set up replication.If not, follow the steps below to enable logical replication.
3.2 Enable logical replication¶
Create a custom RDS parameter group. If your instance already uses a custom parameter group, skip to the next stage.
Edit the custom parameter group. set the rds.logical_replication
parameter to 1.
Optional: Set the max_slot_wal_keep_size
parameter to 4096 to limit the amount of WAL data that is retained for logical replication slots. (Postgres 13+)
Associate the custom parameter group with your RDS instance. Go to the RDS management console, select your instance and click on the "Modify" button.
In the "Modify DB Instance" page, select the custom parameter group you created in the previous step.
Make sure you choose "Apply Immediately" to apply the changes immediately.
Wait for the parameter group configuration to change to "Pending reboot" status.
The parameter group status can be found in the "Configuration" tab of your RDS instance.
Then, reboot the database for the changes to take effect.
You'll know that the changes have taken affect when the status of your DB instance Parameter Group changes to "In Sync".
Verify that the rds.logical_replication
parameter is set to "on" (or 1).
Create a custom Aurora parameter group. If your instance already uses a custom parameter group, skip to the next stage.
Edit the custom parameter group, set the rds.logical_replication
parameter to 1.
Optional: Set the max_slot_wal_keep_size
parameter to 4096 to limit the amount of WAL data that is retained for logical replication slots. (Postgres 13+)
Associate the custom parameter group with your Aurora cluster. Go to the RDS management console, select your instance and click on the "Modify" button.
In the "Modify DB Instance" page, select the custom parameter group you created in the previous step.
Make sure you choose "Apply Immediately" to apply the changes immediately.
Wait for the parameter group configuration to change to "Pending reboot" status.
The parameter group status can be found in the "Configuration" tab of your RDS instance.
Then, reboot the database for the changes to take effect.
You'll know that the changes have taken affect when the status of your DB instance Parameter Group changes to "In Sync".
Verify that the rds.logical_replication
parameter is set to "on" (or 1).
To enable logical replication in a PostgreSQL database, you need to set the wal_level
parameter in your database configuration to logical. For standard PostgreSQL installations, you can do this by either:
- Method 1: Adding a
wal_level = logical
line to thepostgresql.conf
file. - Method 2: Running
ALTER SYSTEM SET wal_level = logical;
;
Optional: Set the max_slot_wal_keep_size
parameter to 4096 to limit the amount of WAL data that is retained for logical replication slots. (Postgres 13+)
Restart your database for the changes to take effect.
Verify that the wal_level
parameter is set to "logical".
3.3 Set up replication¶
Next, you'll need to set up replication by running the following commands in your database:
Once finished, click on the "Validate Configuration" and Epsio will verify that logical replication is set up correctly.
Congratulations! You've successfully enabled logical replication in your database.
Once Epsio successfully connects to your database, you'll be redirected to the Epsio dashboard.
You are set to go and can create your first view. Visit the create_view for further details.