Skip to content

PG-1523 Rework uninstallation documentation #486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: TDE_REL_17_STABLE
Choose a base branch
from
+69 −10
Open

PG-1523 Rework uninstallation documentation #486

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 69 additions & 10 deletions contrib/pg_tde/documentation/docs/how-to/uninstall.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@

If you no longer wish to use TDE in your deployment, you can remove the `pg_tde` extension. To do so, you must have superuser privileges, or database owner privileges in case you only want to remove it from a single database.

!!! warning
This process removes the extension, but does not decrypt data automatically. Only uninstall the extension after all encrypted data **has been removed or decrypted**.

To uninstall `pg_tde`, follow these steps:

## 1. Drop the pg_tde extension from all databases
Copy link
Collaborator

@Andriciuc Andriciuc Jul 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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


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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

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.


1. Decrypt or drop encrypted tables:
Copy link
Collaborator

Choose a reason for hiding this comment

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

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>;

  1. Remove the extension

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

    DROP EXTENSION pg_tde;


Before removing the extension, you must either **decrypt** or **drop** all encrypted tables:
Expand All @@ -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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

!!! 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.


Alternatively, to remove everything at once:

```sql
Expand All @@ -34,17 +37,60 @@ To uninstall `pg_tde`, follow these steps:
!!! note
The `DROP EXTENSION` command does not delete the underlying `pg_tde`-specific data files from disk.

3. Run the `DROP EXTENSION` command against every database where you have enabled the `pg_tde` extension, if the goal is to completely remove the extension. This also includes the template databases, in case `pg_tde` was previously enabled there.
## 2. Turn off WAL encryption

4. Remove any reference to `pg_tde` GUC variables from the PostgreSQL configuration file.
If you are using WAL encryption it needs to be turned off before the pg_tde library can be uninstalled.

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;`
Copy link
Collaborator

@Andriciuc Andriciuc Jul 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

(remove the numbering format)

  • Disable WAL encryption by running:

    ALTER SYSTEM SET pg_tde.wal_encrypt=off;

Copy link
Collaborator Author

@AndersAstrand AndersAstrand Jul 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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?

Copy link
Collaborator

Choose a reason for hiding this comment

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

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


!!! 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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

  • Restart the PostgreSQL cluster to apply the change:

    • ....


* On Debian and Ubuntu:

```sh
sudo systemctl restart postgresql
```

* On RHEL and derivatives

```sh
sudo systemctl restart postgresql-17
Copy link
Collaborator

Choose a reason for hiding this comment

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

missing closing ```

## 3. Uninstall the pg_tde shared library
!!! warning
This process removes the extension, but does not decrypt data automatically. Only uninstall the shared library after all encrypted data **has been removed or decrypted** and WAL encryption **has been disabled**.
6. Start or restart the `postgresql` cluster to apply the changes.
!!! 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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

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

1. Run `SHOW shared_preload_libraries` to view the current configuration of preloaded libraries.
Example:
Copy link
Collaborator

Choose a reason for hiding this comment

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

For example: ...

```
postgres=# SHOW shared_preload_libraries;
shared_preload_libraries
-----------------------------------------
pg_stat_statements,pg_tde,auto_explain
(1 row)

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

Choose a reason for hiding this comment

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

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

Example:
```
postgres=# ALTER SYSTEM SET shared_preload_libraries=pg_stat_statements,auto_explain;
ALTER SYSTEM
postgres=#
```
Copy link
Collaborator

Choose a reason for hiding this comment

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

space needed between ``` and !!!

!!! note
Your list of libraries will most likely be different than in this example.

!!! note
If `pg_tde` is the only shared library in the list, and this is set using `postgresql.conf`, there is no way to disable it using `ALTER SYSTEM SET ...`. Instead remove the `shared_preload_libraries` line from `postgresql.conf` and then run `ALTER SYSTEM RESET shared_preload_libraries;`.

3. Restart the `postgresql` cluster to apply the changes.

* On Debian and Ubuntu:

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

Copy link
Collaborator

Choose a reason for hiding this comment

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

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

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

Copy link
Collaborator

Choose a reason for hiding this comment

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

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

## 4. (optional) Cleanup
Copy link
Collaborator

Choose a reason for hiding this comment

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

(Optional) Clean up configuration


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
Copy link
Collaborator

@Andriciuc Andriciuc Jul 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

edit to ## Troubleshooting

with subtopic ### WAL encryption not disabled

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

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.

Copy link
Collaborator

Choose a reason for hiding this comment

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

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

If WAL encryption wasn't fully disabled before the `pg_tde` library was uninstalled you may get an error message like this when trying to restart the cluster:
```
2025-04-01 17:12:50.607 CEST [496385] PANIC: could not locate a valid checkpoint record at 0/17B2580
```
If this happens, 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.