Skip to content

Commit

Permalink
Merge pull request #5489 from EnterpriseDB/docs/edits_to_bganimal_pr5372
Browse files Browse the repository at this point in the history
Edits to BigAnimal PR5372
  • Loading branch information
nidhibhammar authored Jun 4, 2024
2 parents bf5bf84 + 82b4af1 commit 3227566
Showing 1 changed file with 22 additions and 25 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -7,53 +7,53 @@ deepToC: true
## Using logical replication

!!! Note
This procedure does not work with distributed high-availability BigAnimal instances.
This procedure doesn't work with distributed high-availability BigAnimal instances.
!!!

Logical replication is a common method for upgrading the Postgres major version on BigAnimal instances, enabling a transition with minimal downtime.

By replicating changes in real-time from an older version (source instance) to a newer one (target instance), this method provides a reliable upgrade path while maintaining database availability.
By replicating changes in real time from an older version (source instance) to a newer one (target instance), this method provides a reliable upgrade path while maintaining database availability.

!!! Important
Depending on where your older and newer versioned BigAnimal instances are located, this procedure may accrue ingress and egress costs from your cloud service provider (CSP) for the migrated data. Please consult your CSP's pricing documentation to see how ingress and egress fees are calculated to determine any extra costs.
Depending on where your older and newer versioned BigAnimal instances are located, this procedure can accrue ingress and egress costs from your cloud service provider (CSP) for the migrated data. Consult your CSP's pricing documentation to see how ingress and egress fees are calculated to determine any extra costs.
!!!

### Overview of upgrading

To perform a major version upgrade, use the following steps, explained in further detail below:
To perform a major version upgrade:

1. [Create a BigAnimal instance](#create-a-biganimal-instance)
1. [Gather instance information](#gather-instance-information)
1. [Confirm the Postgres versions before migration](#confirm-the-postgres-versions-before-migration)
1. [Migrate the database schema](#migrate-the-database-schema)
1. [Create a publication](#create-a-publication)
1. [Create a logical replication slot](#create-the-logical-replication-slot)
1. [Create a subscription](#create-a-subscription)
1. [Validate the migration](#validate-the-migration)
1. [Create a BigAnimal instance.](#create-a-biganimal-instance)
1. [Gather instance information.](#gather-instance-information)
1. [Confirm the Postgres versions before migration.](#confirm-the-postgres-versions-before-migration)
1. [Migrate the database schema.](#migrate-the-database-schema)
1. [Create a publication.](#create-a-publication)
1. [Create a logical replication slot.](#create-the-logical-replication-slot)
1. [Create a subscription.](#create-a-subscription)
1. [Validate the migration.](#validate-the-migration)


### Create a BigAnimal instance

To perform a major version upgrade, create a BigAnimal instance with your desired version of Postgres. This will be your target instance.
To perform a major version upgrade, create a BigAnimal instance with your desired version of Postgres. This is your target instance.

Ensure your target instance is provisioned with a storage size equal to or greater than your source instance.

For detailed steps on creating a BigAnimal instance, see [this guide](../getting_started/creating_a_cluster.mdx).
For details on creating a BigAnimal instance, see [Creating a cluster](../getting_started/creating_a_cluster.mdx).

### Gather instance information

Use the BigAnimal console to obtain the following information for your source and target instance:

- Read/write URI
- Database name
- Username
- Username
- Read/write host

Using the BigAnimal console:

1. Select the **Clusters** tab.
1. Select your source instance.
1. From the Connect tab, obtain the information from **Connection Info**.
1. From the **Connect** tab, obtain the information from **Connection Info**.

### Confirm the Postgres versions before migration

Expand All @@ -80,7 +80,7 @@ On your source instance, use the `dt` command to view the details of the schema
/dt+;
```

Here is a sample database schema for this example:
Here's a sample database schema for this example:

```
List of relations
Expand All @@ -92,7 +92,7 @@ Here is a sample database schema for this example:
public | pgbench_tellers | table | edb_admin | permanent | heap | 120 kB |
```

Use pg_dump with the `--schema-only` flag to copy the schema from your source to your target instance. For more information on using `pg_dump`, [see the Postgres documentation](https://www.postgresql.org/docs/current/app-pgdump.html).
Use pg_dump with the `--schema-only` flag to copy the schema from your source to your target instance. For more information on using pg_dump, [see the Postgres documentation](https://www.postgresql.org/docs/current/app-pgdump.html).

```
pg_dump --schema-only -h <source_biganimal_host> -U <source_biganimal_username> -d <source_biganimal_databasename> | psql -h <target_biganimal_host> -U <target_biganimal_username> -d <target_biganimal_databasename>
Expand Down Expand Up @@ -148,7 +148,7 @@ The expected output is: `ALTER PUBLICATION`.

### Create the logical replication slot

Then, on the source instance, create a replication slot using the `pgoutput` plugin:
On the source instance, create a replication slot using the `pgoutput` plugin:

```sql
SELECT pg_create_logical_replication_slot('<slot_name>','pgoutput');
Expand Down Expand Up @@ -178,15 +178,15 @@ Use the `CREATE SUBSCRIPTION` command to create a subscription on your target in
CREATE SUBSCRIPTION <name_of_subscription> CONNECTION 'user=<source_instance_username> host=<source_instance_read/write_host> sslmode=require port=<source_instance_port> dbname=<source_instance_dbname> password=<source_instance_password>' PUBLICATION <publication_name> WITH (enabled=true, copy_data = true, create_slot = false, slot_name=<slot_name>);
```

Creating a subscription on a Postgres 16 instance to a publication on a Postgres 12 instance:
This example creates a subscription on a Postgres 16 instance to a publication on a Postgres 12 instance:

```sql
CREATE SUBSCRIPTION v16_sub CONNECTION 'user=edb_admin host=p-x67kjhacc4.pg.biganimal.io sslmode=require port=5432 dbname=edb_admin password=XXX' PUBLICATION v12_pub WITH (enabled=true, copy_data = true, create_slot = false, slot_name=v12_pub);
```

The expected output is: `CREATE SUBSCRIPTION`.

In this example, the subscription uses a connection string to specify the source database and includes options to copy existing data and to follow the publication identified by 'v12_pub'.
In this example, the subscription uses a connection string to specify the source database and includes options to copy existing data and to follow the publication identified by `v12_pub`.

The subscriber pulls schema changes (with some exceptions, as noted in the PostgreSQL [documentation on Limitations of Logical Replication](https://www.postgresql.org/docs/current/logical-replication-restrictions.html)) and data from the source to the target database, effectively replicating the data.

Expand Down Expand Up @@ -214,7 +214,7 @@ To validate the progress of the data migration, use `dt+` from the source and ta
public | pgbench_tellers | table | edb_admin | permanent | heap | 0 bytes |
```

If logical replication is running correctly, each time you run `\dt+;` you see that more data has been migrated:
If logical replication is running correctly, each time you run `\dt+;` you see that more data was migrated:

```
List of relations
Expand All @@ -229,6 +229,3 @@ If logical replication is running correctly, each time you run `\dt+;` you see t
!!! Note
You can optionally use [LiveCompare](https://www.enterprisedb.com/docs/livecompare/latest/) to generate a comparison report of the source and target databases to validate that all database objects and data are consistent.
!!!



0 comments on commit 3227566

Please sign in to comment.