From 188e9a00893d076585ba391d9cf55e982f247059 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Tue, 8 Oct 2024 20:42:39 +0200 Subject: [PATCH] PG-1012 Documented set up of the_heap access method Added How to decrypt a table --- documentation/decrypt.md | 34 ++++++++++++++++ documentation/docs/apt.md | 65 ++++++++++++++++++++++-------- documentation/docs/index.md | 6 ++- documentation/docs/install.md | 4 +- documentation/docs/test.md | 74 +++++++++++++++++++++++++---------- documentation/docs/yum.md | 74 ++++++++++++++++++++++------------- documentation/mkdocs.yml | 2 +- documentation/variables.yml | 4 +- 8 files changed, 192 insertions(+), 71 deletions(-) create mode 100644 documentation/decrypt.md diff --git a/documentation/decrypt.md b/documentation/decrypt.md new file mode 100644 index 00000000000..5d68f2f7e37 --- /dev/null +++ b/documentation/decrypt.md @@ -0,0 +1,34 @@ +# Decrypt encrypted table + +## Method 1. Change the access method + +If you encrypted a table with the `tde_heap_basic` access method and need to decrypt it, run the following command against the desired table (`mytable` in the example below): + +```sql +ALTER TABLE mytable SET access method heap; +``` + +Check that the table is not encrypted: + +```sql +SELECT pg_tde_is_encrypted('mytable'); +``` + +The output returns `f` meaning that the table is no longer encrypted. + +## Method 2. Create a new unencrypted table on the base of the encrypted one + +Alternatively, you can create a new unencrypted table with the same structure and data as the initial table. For example, the original encrypted table is `EncryptedCustomers`. Use the following command to create a new table `Customers`: + +```sql +CREATE TABLE Customers AS +SELECT * FROM EncryptedCustomers; +``` + +The new table `Customers` inherits the structure and the data from `EncryptedCustomers`. + +(Optional) If you no longer need the `EncryptedCustomers` table, you can delete it. + +```sql +DROP TABLE EncryptedCustomers; +``` \ No newline at end of file diff --git a/documentation/docs/apt.md b/documentation/docs/apt.md index 436465d4256..df7f2300cfd 100644 --- a/documentation/docs/apt.md +++ b/documentation/docs/apt.md @@ -1,6 +1,10 @@ # Install `pg_tde` on Debian or Ubuntu -In version Aplha1, `pg_tde` packages are available in the testing repository for Percona Distribution for PostgreSQL 16.2. Check the [list of supported platforms](install.md#__tabbed_1_2). +The packages for `pg_tde` {{release}} are available in the testing repository for Percona Distribution for PostgreSQL 16. + +The packages for the tech preview `pg_tde` are available in the experimental repository for Percona Distribution for PostgreSQL 17. + +Check the [list of supported platforms](install.md#__tabbed_1_2). This tutorial shows how to install `pg_tde` with [Percona Distribution for PostgreSQL](https://docs.percona.com/postgresql/latest/index.html). @@ -23,9 +27,9 @@ You need the `percona-release` repository management tool that enables the desir 2. Fetch the `percona-release` package - ```bash - sudo wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb - ``` + ```bash + sudo wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb + ``` 3. Install `percona-release` @@ -35,9 +39,17 @@ You need the `percona-release` repository management tool that enables the desir 4. Enable the Percona Distribution for PostgreSQL repository - ```bash - sudo percona-release enable-only ppg-16.2 testing - ``` + === "pg_tde Beta" + + ```bash + sudo percona-release enable-only ppg-{{pgversion16}} testing + ``` + + === "pg_tde Tech preview" + + ```bash + sudo percona-release enable-only ppg-{{pgversion17}} experimental + ``` 5. Update the local cache @@ -45,21 +57,40 @@ You need the `percona-release` repository management tool that enables the desir sudo apt-get update ``` -## Install Percona Distribution for PostgreSQL +## Install `pg_tde` + +=== "pg_tde Beta" + + 1. Install Percona Distribution for PostgreSQL. + + Run the following command to install Percona Distribution for PostgreSQL and the required packages: -To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command: + ```bash + sudo apt-get install -y percona-postgresql-16 percona-postgresql-contrib percona-postgresql-server-dev-all + ``` -```bash -sudo apt-get install -y percona-postgresql-16 percona-postgresql-contrib percona-postgresql-server-dev-all -``` + 2. Install `pg_tde` packages + + ```bash + sudo apt-get install percona-postgresql-16-pg-tde + ``` + +=== "pg_tde Tech preview" + + 1. Install Percona Distribution for PostgreSQL. + + Run the following command to install Percona Distribution for PostgreSQL and the required packages: -## Install `pg_tde` packages + ```bash + sudo apt-get install -y percona-postgresql-17 percona-postgresql-contrib percona-postgresql-server-dev-all + ``` -To install `pg_tde` packages, run the following command: + 2. Install `pg_tde` packages + + ```bash + sudo apt-get install percona-postgresql-17-pg-tde + ``` -```bash -sudo apt-get install percona-postgresql-16-pg-tde -``` ## Next step diff --git a/documentation/docs/index.md b/documentation/docs/index.md index 43cd4d57133..338ea4b38ed 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -26,7 +26,9 @@ ## Supported PostgreSQL versions -`pg_tde` is currently based on PostgreSQL 16.0 and supported for Percona Distribution for PostgreSQL 16.x and upstream PostgreSQL 16.x. +`pg_tde` is currently based on Percona Server for PostgreSQL 17.0 and upstream PostgreSQL 16.x. + +It is also supported for Percona Distribution for PostgreSQL 16.x and upstream PostgreSQL 16.x. ## Future releases @@ -34,6 +36,8 @@ The following is planned for future releases of `pg_tde`: * Encryption of indexes and `NULL` bitmaps of tuples * Logical replication support +* KMIP integration for key management +* Global principal key management diff --git a/documentation/docs/install.md b/documentation/docs/install.md index 48f1a5628d3..b87644972c2 100644 --- a/documentation/docs/install.md +++ b/documentation/docs/install.md @@ -21,12 +21,10 @@ Install `pg_tde` using one of available installation methods: Starting with Aplha1 version, you can install the extension as package from Percona repositories using the `percona-release` tool. The packages are available for the following operating systems: - - Red Hat Enterprise Linux and CentOS 7 - Red Hat Enterprise Linux 8 and compatible derivatives - Red Hat Enterprise Linux 9 and compatible derivatives - Ubuntu 20.04 (Focal Fossa) - Ubuntu 22.04 (Jammy Jellyfish) - - Debian 10 (Buster) - Debian 11 (Bullseye) - Debian 12 (Bookworm) @@ -35,6 +33,8 @@ Install `pg_tde` using one of available installation methods: === "Build from source" + The following steps apply to PostgreSQL 16. To build `pg_tde` for PostgreSQL 17, replace the version in the commands. + 1. To build `pg_tde` from source code, you require the following on Ubuntu/Debian: ```sh diff --git a/documentation/docs/test.md b/documentation/docs/test.md index a4152e69215..995481f015e 100644 --- a/documentation/docs/test.md +++ b/documentation/docs/test.md @@ -2,34 +2,66 @@ To check if the data is encrypted, do the following: -1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde` extension creates the table access method `tde_heap_basic`. To enable data encryption, create the table using this access method as follows: +=== "pg_tde Beta" - ```sql - CREATE TABLE ( ) USING tde_heap_basic; - ``` + 1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde` extension creates the table access method `tde_heap_basic`. To enable data encryption, create the table using this access method as follows: - !!! hint + ```sql + CREATE TABLE ( ) USING tde_heap_basic; + ``` + + !!! hint - You can enable data encryption by default by setting the `default_table_access_method` to `tde_heap_basic`: + You can enable data encryption by default by setting the `default_table_access_method` to `tde_heap_basic`: + + ```sql + SET default_table_access_method = tde_heap_basic; + ``` + + 2. Run the following function: ```sql - SET default_table_access_method = tde_heap_basic; + SELECT pg_tde_is_encrypted('table_name'); + ``` + + The function returns `t` if the table is encrypted and `f` - if not. + + 3. Rotate the principal key when needed: + + ```sql + SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin + -- or + SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name + -- or + SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- change provider ``` - -2. Run the following function: - ```sql - SELECT pg_tde_is_encrypted('table_name'); - ``` +=== "pg_tde Tech preview" - The function returns `t` if the table is encrypted and `f` - if not. + !!! warning -3. Rotate the principal key when needed: + This is the tech preview functionality. It is under active development and can change anytime. Use it only for testing purposes - ```sql - SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin - -- or - SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name - -- or - SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- change provider - ``` \ No newline at end of file + 1. Create a table in the database for which you have [enabled `pg_tde`](setup.md). Enabling `pg_tde` extension creates the table access method `tde_heap`. To enable data encryption, create the table using this access method as follows: + + ```sql + CREATE TABLE ( ) USING tde_heap; + ``` + + 2. Run the following function: + + ```sql + SELECT pg_tde_is_encrypted('table_name'); + ``` + + The function returns `t` if the table is encrypted and `f` - if not. + + 3. Rotate the principal key when needed: + + ```sql + SELECT pg_tde_rotate_principal_key(); -- uses automatic key versionin + -- or + SELECT pg_tde_rotate_principal_key('new-principal-key', NULL); -- specify new key name + -- or + SELECT pg_tde_rotate_principal_key('new-principal-key', 'new-provider'); -- change provider + ``` \ No newline at end of file diff --git a/documentation/docs/yum.md b/documentation/docs/yum.md index de7b6ae0a03..09234993b0b 100644 --- a/documentation/docs/yum.md +++ b/documentation/docs/yum.md @@ -1,6 +1,10 @@ # Install `pg_tde` on Red Hat Enterprise Linux and derivatives -In version Aplha1, `pg_tde` packages are available in the testing repository for Percona Distribution for PostgreSQL 16.2. Check the [list of supported platforms](install.md#__tabbed_1_2). +The packages for `pg_tde` {{release}} are available in the testing repository for Percona Distribution for PostgreSQL 16. + +The packages for the tech preview `pg_tde` are available in the experimental repository for Percona Distribution for PostgreSQL 17. + +Check the [list of supported platforms](install.md#__tabbed_1_2). This tutorial shows how to install `pg_tde` with [Percona Distribution for PostgreSQL](https://docs.percona.com/postgresql/latest/index.html). @@ -8,22 +12,11 @@ This tutorial shows how to install `pg_tde` with [Percona Distribution for Postg ### Enable / disable modules -=== "CentOS 7" - - Install the `epel-release` package: +For RHEL8/Oracle Linux 8/Rocky Linux 8, disable the ``postgresql`` and ``llvm-toolset``modules: - ```bash - sudo yum -y install epel-release - sudo yum repolist - ``` - -=== "RHEL8/Oracle Linux 8/Rocky Linux 8" - - Disable the ``postgresql`` and ``llvm-toolset``modules: - - ```bash - sudo dnf module disable postgresql llvm-toolset - ``` +```bash +sudo dnf module disable postgresql llvm-toolset +``` ### Install `percona-release` @@ -37,25 +30,50 @@ You need the `percona-release` repository management tool that enables the desir 2. Enable the repository - ```bash - sudo percona-release enable-only ppg-16.2 testing - ``` + Enable the Percona Distribution for PostgreSQL repository -## Install Percona Distribution for PostgreSQL + === "pg_tde Beta" -To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command: + ```bash + sudo percona-release enable-only ppg-{{pgversion16}} testing + ``` + + === "pg_tde Tech preview" -```bash -sudo yum -y install percona-postgresql-client-common percona-postgresql-common percona-postgresql-server-dev-all percona-postgresql16 percona-postgresql16-contrib percona-postgresql16-devel percona-postgresql16-libs -``` + ```bash + sudo percona-release enable-only ppg-{{pgversion17}} experimental + ``` ## Install `pg_tde` -To install `pg_tde` packages, run the following command: +=== "pg_tde Beta" + + 1. Install Percona Distribution for PostgreSQL 16 and the required packages, run the following command: + + ```bash + sudo yum -y install percona-postgresql-client-common percona-postgresql-common percona-postgresql-server-dev-all percona-postgresql16 percona-postgresql16-contrib percona-postgresql16-devel percona-postgresql16-libs + ``` + + 2. Install `pg_tde` packages + + ```bash + sudo yum install percona-pg_tde_16 + ``` + +=== "pg_tde Tech preview" + + 1. Install Percona Distribution for PostgreSQL 16 and the required packages, run the following command: + + ```bash + sudo yum -y install percona-postgresql-client-common percona-postgresql-common percona-postgresql-server-dev-all percona-postgresql17 percona-postgresql17-contrib percona-postgresql17-devel percona-postgresql17-libs + ``` + + 2. Install `pg_tde` packages + + ```bash + sudo yum install percona-pg_tde_17 + ``` -```bash -sudo yum install percona-pg_tde_16 -``` ## Next steps diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 1e496f93ea2..3cbee35a5b9 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -165,10 +165,10 @@ nav: - functions.md - How to: - Use reference to external parameters: external-parameters.md + - Decrypt encrypted table: decrypt.md - Release notes: - "pg_tde release notes": release-notes/release-notes.md - uninstall.md - contribute.md -# - Version Selector: "../" diff --git a/documentation/variables.yml b/documentation/variables.yml index 30dd363d688..5a87702f0a3 100644 --- a/documentation/variables.yml +++ b/documentation/variables.yml @@ -1,3 +1,5 @@ #Variables used throughout the docs -release: 'Beta' \ No newline at end of file +release: 'Beta' +pgversion16: '16.4' +pgversion17: '17.0' \ No newline at end of file