Create enforcement.md - Encryption Enforcement topic

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

@@ -0,0 +1,62 @@
+# Encryption Enforcement
+
+For `pg_tde`, encryption enforcement ensures that only encrypted storage is allowed for specific operations, tables, or the entire database. It prevents the accidental creation of unencrypted tables or indexes in environments where encryption is required for compliance, security, or policy enforcement.
+
+## What does enforcement do?
+
+When enabled, encryption enforcement:
+
+* Prevents creation of unencrypted tables or indexes
+* Enforces consistent encryption usage across tenants, databases, or users
+* Can be scoped globally, per database, or per role
+
+## Enforce encryption usage
+
+Use the following techniques to enforce the secure use of `pg_tde`.
+
+### 1. Enforce encryption across the server
+
+To enforce encryption cluster-wide, set the [`pg_tde.enforce_encryption`](../variables.md/#pg_tdeenforce_encryption) variable in `postgresql.conf`:
+
+```ini
+pg_tde.enforce_encryption = on
+```
+
+This ensures that no user, including superusers, can create unencrypted tables unless they explicitly override the variable in a session (see below).
+
+### 2. Enforce encryption for a specific database
+
+To apply encryption enforcement only within a specific database, run:
+
+```sql
+ALTER DATABASE example_db SET pg_tde.enforce_encryption = on;
+```
+
+This ensures encryption is enforced **only** when connected to that database.
+
+### 3. Enforce encryption for a specific user
+
+You can also enforce encryption on a per-user basis, run:
+
+```sql
+ALTER USER example_user SET pg_tde.enforce_encryption = on;
+```
+
+This ensures that the user `example_user` cannot create unencrypted tables, regardless of which database they connect to.
+
+### Override enforcement for trusted sessions
+
+Superusers (such as DBAs) can override the variable at the session level:
+
+```sql
+SET pg_tde.enforce_encryption = off;
+```
+
+This allows temporary creation of unencrypted tables in special cases, such as:
+
+* Loading trusted, public reference datasets
+* Benchmarking and test environments
+* Migration staging before re-encryption
+
+!!! note
+    While superusers can disable enforcement in their session, they must do so explicitly. Enforcement defaults remain active to protect from accidental misconfiguration.

contrib/pg_tde/documentation/docs/variables.md

@@ -32,14 +32,14 @@ Similarly, `ALTER TABLE <x> SET ACCESS METHOD` is only allowed, if the access me
 
 Other DDL operations are still allowed. For example other `ALTER` commands are allowed on unencrypted tables, as long as the access method isn't changed.
 
-You can set this variable at the following levels: 
+You can set this variable at the following levels:
 
-* global - for the entire PostgreSQL cluster.
-* database - for specific databases. 
-* user - for specific users.
-* session - for the current session.
+* global - for the entire PostgreSQL cluster
+* database - for specific databases
+* user - for specific users
+* session - for the current session
 
-Setting or changing the value requires superuser permissions.
+Setting or changing the value requires superuser permissions. For examples, see the [Encryption Enforcement](how-to/enforcement.md) topic.
 
 ## pg_tde.inherit_global_providers
 
@@ -52,12 +52,12 @@ If disabled, functions that change the key providers can only work with database
 
 In this case, the default principal key, if set, is also disabled.
 
-You can set this variable at the following levels: 
+You can set this variable at the following levels:
 
-* global - for the entire PostgreSQL cluster.
-* database - for specific databases. 
-* user - for specific users.
-* session - for the current session.
+* global - for the entire PostgreSQL cluster
+* database - for specific databases
+* user - for specific users
+* session - for the current session
 
-
-Setting this variable doesn't affect existing uses of global keys. It only prevents the creation of new principal keys using global providers.
+!!! note
+    Setting this variable doesn't affect existing uses of global keys. It only prevents the creation of new principal keys using global providers.

contrib/pg_tde/documentation/mkdocs.yml

@@ -198,6 +198,7 @@ nav:
       - "pg_checksums": command-line-tools/pg-tde-checksums.md 
     - "Uninstall pg_tde": how-to/uninstall.md
     - "Configure Multi-tenancy": how-to/multi-tenant-setup.md
+    - "Encryption Enforcement": how-to/enforcement.md
     - "Decrypt an Encrypted Table": how-to/decrypt.md
   - faq.md
   - "Release Notes":