PG-1523 Rework uninstallation documentation #486

AndersAstrand · 2025-07-24T11:34:20Z

This commit rearranges the uninstallation documentation and adds instructions for disabling WAL encryption.

contrib/pg_tde/documentation/docs/how-to/uninstall.md

This commit rearranges the uninstallation documentation and adds instructions for disabling WAL encryption.

Andriciuc · 2025-07-25T12:50:18Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

 To uninstall `pg_tde`, follow these steps:

+## 1. Drop the pg_tde extension from all databases


change to ## Step 1. Drop the extension from all databases and continue with Step 2... throughout

Andriciuc · 2025-07-25T12:51:29Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

 To uninstall `pg_tde`, follow these steps:

+## 1. Drop the pg_tde extension from all databases
+
+For all databases where the extensions is loaded you need to follow these steps. This also includes the template databases, in case `pg_tde` was previously enabled there.


Before uninstalling pg_tde, you must remove the extension from every database where it is loaded. This includes template databases if pg_tde was previously enabled there.

Andriciuc · 2025-07-25T12:54:59Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

@@ -25,6 +26,8 @@ To uninstall `pg_tde`, follow these steps:
    DROP EXTENSION pg_tde;
    ```

+    If there are any encrypted objects that were not previously decrypted or deleted, this command will fail and you have to follow the step above for these objects.


!!! note

If there are any encrypted objects that were not previously decrypted or deleted, this command will fail and you have to follow the step above for these objects.

Andriciuc · 2025-07-25T13:15:22Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

+## 1. Drop the pg_tde extension from all databases
+
+For all databases where the extensions is loaded you need to follow these steps. This also includes the template databases, in case `pg_tde` was previously enabled there.
+
 1. Decrypt or drop encrypted tables:


You must clean up all encrypted tables in each database:

To decrypt a table, switch it back to the default storage method:

ALTER TABLE <table_name> SET ACCESS METHOD heap;

To discard the data**, simply drop the encrypted tables:

DROP TABLE <table_name>;

Remove the extension

Once all encrypted tables have been handled, drop the extension from the database:

DROP EXTENSION pg_tde;

Andriciuc · 2025-07-25T13:16:38Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md


-5. Modify the `shared_preload_libraries` and remove the 'pg_tde' from it. Use the `ALTER SYSTEM` command for this purpose, or edit the configuration file.
+1. Run `ALTER SYSTEM SET pg_tde.wal_encrypt=off;`


(remove the numbering format)

Disable WAL encryption by running:

ALTER SYSTEM SET pg_tde.wal_encrypt=off;

This is highly confusing to me. Why don't we want these steps to be numbered when the order in which they are run are critical?

The configuration change must be done before the restart. So numbered steps seems highly appropriate here?

Agreed! Please go ahead and edit the steps in alphabetical instead of *

Andriciuc · 2025-07-25T13:58:01Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

-    !!! warning
-        Once `pg_tde` is removed from the `shared_preload_libraries`, reading any leftover encrypted files will fail. Removing the extension from the `shared_preload_libraries` is also possible if the extension is still installed in some databases.
-        Make sure to do this only if the server has no encrypted files in its data directory.
+2. Restart the `postgresql` cluster to apply the changes.


Restart the PostgreSQL cluster to apply the change:

....

Andriciuc · 2025-07-25T13:58:12Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

+
+       ```sh
+       sudo systemctl restart postgresql-17
+


missing closing ```

Andriciuc · 2025-07-25T14:00:19Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

+!!! note
+    Encrypted WAL pages will not be decrypted, so any postgres cluster needing to read them will need the `pg_tde` library loaded, and the WAL encryption keys used available.
+
+At this point, the shared library is still loaded but inactive. Follow these steps to completely uninstall it.


At this point, the shared library is still loaded but no longer active. To fully uninstall pg_tde, complete the steps below.

Andriciuc · 2025-07-25T14:01:32Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

+
+    postgres=#
+    ```
+2. Remove `pg_tde` from the list and apply the new setting using `ALTER SYSTEM SET shared_preload_libraries=<your list of libraries>`


Remove pg_tde from the list and apply the new setting using ALTER SYSTEM SET shared_preload_libraries=<your list of libraries>. For example: ...

Andriciuc · 2025-07-25T14:01:37Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

+At this point, the shared library is still loaded but inactive. Follow these steps to completely uninstall it.
+
+1. Run `SHOW shared_preload_libraries` to view the current configuration of preloaded libraries.
+    Example:


For example: ...

Andriciuc · 2025-07-25T14:01:59Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

+    postgres=# ALTER SYSTEM SET shared_preload_libraries=pg_stat_statements,auto_explain;
+    ALTER SYSTEM
+    postgres=#
+    ```


space needed between ``` and !!!

Andriciuc · 2025-07-25T14:26:17Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

@@ -57,3 +103,16 @@ To uninstall `pg_tde`, follow these steps:
       ```sh
       sudo systemctl restart postgresql-17
       ```
+
+## 4. (optional) Cleanup


(Optional) Clean up configuration

Andriciuc · 2025-07-25T14:28:46Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

+
+    At this point it is safe to remove any configuration related to pg_tde from `postgresql.conf` and `postgresql.auto.conf`. These configuration options have the prefix `pg_tde.`
+
+## Potential issues


edit to ## Troubleshooting

with subtopic ### WAL encryption not disabled

I don't understand what you want to communicate with that? The users won't know that that was the issue, they will just see the error message and this section communicates what the issue was and how to solve it.

I understand your pov but ## Potential issues is too vague while troubleshooting might be unnecessary as you say.

Let us do this:

5. Restart error: PANIC checkpoint not found

If you see the following error when restarting the PostgreSQL cluster:

2025-04-01 17:12:50.607 CEST [496385] PANIC: could not locate a valid checkpoint record at 0/17B2580

This typically means that WAL encryption was not fully disabled before the pg_tde shared library was removed. To fix this, re-add pg_tde to shared_preload_libraries before starting the cluster, and follow the instructions for turning off WAL encryption above before uninstalling the shared library.

I believe the above version is better, it continues from the previous steps naturally and provides a specific title the user can search through the doc

Andriciuc · 2025-07-25T14:29:59Z

contrib/pg_tde/documentation/docs/how-to/uninstall.md

@@ -57,3 +103,16 @@ To uninstall `pg_tde`, follow these steps:
       ```sh
       sudo systemctl restart postgresql-17
       ```
+


for these last two steps below, please remove the spaces before of the paragraphs completely.

When you say spaces here, are you talking about spaces or about empty lines?

Yep! Just an empty line is great in between the paragraph and ```

Andriciuc

Once all the changes are made, let me have another look just to be safe, thank you very much!

AndersAstrand · 2025-07-29T09:29:33Z

Replaced by #490

AndersAstrand requested review from nastena1606 and Andriciuc as code owners July 24, 2025 11:34

dAdAbird requested changes Jul 24, 2025

View reviewed changes

contrib/pg_tde/documentation/docs/how-to/uninstall.md Outdated Show resolved Hide resolved

AndersAstrand force-pushed the tde/rework-uninstallation-instructions branch from e23d3d7 to feb9ebc Compare July 24, 2025 12:23

PG-1523 Rework uninstallation documentation

c843707

This commit rearranges the uninstallation documentation and adds instructions for disabling WAL encryption.

AndersAstrand force-pushed the tde/rework-uninstallation-instructions branch from feb9ebc to c843707 Compare July 24, 2025 12:24

Andriciuc reviewed Jul 25, 2025

View reviewed changes

contrib/pg_tde/documentation/docs/how-to/uninstall.md

```sh

sudo systemctl restart postgresql-17

Copy link

Collaborator

Andriciuc Jul 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing closing ```

Andriciuc reviewed Jul 25, 2025

View reviewed changes

Andriciuc requested changes Jul 25, 2025

View reviewed changes

nastena1606 deployed to PG-1523-uninstall-docs-cleanup - INTERNAL-pg_tde docs PR #490 July 29, 2025 09:26 — with Render View deployment

AndersAstrand closed this Jul 29, 2025

		To uninstall `pg_tde`, follow these steps:

		## 1. Drop the pg_tde extension from all databases


		5. Modify the `shared_preload_libraries` and remove the 'pg_tde' from it. Use the `ALTER SYSTEM` command for this purpose, or edit the configuration file.
		1. Run `ALTER SYSTEM SET pg_tde.wal_encrypt=off;`


		At this point it is safe to remove any configuration related to pg_tde from `postgresql.conf` and `postgresql.auto.conf`. These configuration options have the prefix `pg_tde.`

		## Potential issues

PG-1523 Rework uninstallation documentation #486

PG-1523 Rework uninstallation documentation #486

Uh oh!

Conversation

AndersAstrand commented Jul 24, 2025

Uh oh!

Uh oh!

Andriciuc Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andriciuc Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AndersAstrand Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andriciuc Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

5. Restart error: PANIC checkpoint not found

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andriciuc left a comment

Choose a reason for hiding this comment

Uh oh!

AndersAstrand commented Jul 29, 2025

Uh oh!

Uh oh!

Andriciuc Jul 25, 2025 •

edited

Loading

Andriciuc Jul 25, 2025 •

edited

Loading

AndersAstrand Jul 28, 2025 •

edited

Loading

Andriciuc Jul 25, 2025 •

edited

Loading