pgmonkey 3.2.0__tar.gz → 3.4.0__tar.gz

{pgmonkey-3.2.0/src/pgmonkey.egg-info → pgmonkey-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgmonkey
-Version: 3.2.0
+Version: 3.4.0
 Summary: A tool to assist with postgresql database connections
 Author-email: Good Boy <pythonic@rexbytes.com>
 License: MIT
@@ -47,24 +47,33 @@ Dynamic: license-file
    - [Password-Based Authentication](#password-based-authentication)
    - [SSL/TLS Encryption](#ssltls-encryption)
    - [Certificate-Based Authentication](#certificate-based-authentication)
-5. [Using the CLI](#using-the-cli)
+5. [Environment Variable Interpolation (Advanced)](#environment-variable-interpolation-advanced)
+   - [Standard YAML (Default)](#standard-yaml-default)
+   - [Inline Syntax: ${VAR}](#inline-syntax-var)
+   - [Structured Syntax: from_env / from_file](#structured-syntax-from_env--from_file)
+   - [Sensitive Key Protection](#sensitive-key-protection)
+   - [Python API](#python-api)
+   - [CLI Usage](#cli-usage)
+   - [Redacting Secrets for Logging](#redacting-secrets-for-logging)
+   - [Deployment Patterns](#deployment-patterns)
+6. [Using the CLI](#using-the-cli)
    - [Creating a Configuration Template](#creating-a-configuration-template)
    - [Testing a Connection](#testing-a-connection)
    - [Generating Python Code](#generating-python-code)
    - [Server Configuration Recommendations](#server-configuration-recommendations)
    - [Auditing Live Server Settings](#auditing-live-server-settings)
    - [Importing and Exporting Data](#importing-and-exporting-data)
-6. [Using pgmonkey in Python](#using-pgmonkey-in-python)
+7. [Using pgmonkey in Python](#using-pgmonkey-in-python)
    - [Normal (Synchronous) Connection](#normal-synchronous-connection)
    - [Pooled Connection](#pooled-connection)
    - [Async Connection](#async-connection)
    - [Async Pooled Connection](#async-pooled-connection)
    - [Using the Config File Default](#using-the-config-file-default)
    - [Transactions, Commit, and Rollback](#transactions-commit-and-rollback)
-7. [Best Practice Recipes](#best-practice-recipes)
-8. [Testing All Connection Types](#testing-all-connection-types)
-9. [Testing Pool Capacity](#testing-pool-capacity)
-10. [Running the Test Suite](#running-the-test-suite)
+8. [Best Practice Recipes](#best-practice-recipes)
+9. [Testing All Connection Types](#testing-all-connection-types)
+10. [Testing Pool Capacity](#testing-pool-capacity)
+11. [Running the Test Suite](#running-the-test-suite)
 
 ## Installation
 
@@ -272,6 +281,203 @@ connection_settings:
   sslrootcert: '/path/to/ca.crt'
 ```
 
+## Environment Variable Interpolation (Advanced)
+
+pgmonkey v3.4.0 adds opt-in support for resolving environment variables and secret file references inside YAML configuration files. This lets you keep your config files free of hardcoded credentials while staying compatible with standard deployment workflows (12-factor env vars, Docker, Kubernetes).
+
+**Interpolation is disabled by default.** If you do not enable it, pgmonkey treats every YAML value as a literal string - exactly as it always has.
+
+### Standard YAML (Default)
+
+The standard approach is to write literal values directly in the config file. This is the simplest way to get started and requires no extra flags or API parameters:
+
+```yaml
+connection_type: 'normal'
+
+connection_settings:
+  user: 'postgres'
+  password: 'my_password'
+  host: 'localhost'
+  port: '5432'
+  dbname: 'mydatabase'
+```
+
+```python
+from pgmonkey import PGConnectionManager
+
+manager = PGConnectionManager()
+conn = manager.get_database_connection('config.yaml')
+```
+
+This continues to work exactly as before. No changes needed for existing configs.
+
+### Inline Syntax: ${VAR}
+
+When interpolation is enabled, you can reference environment variables using `${VAR}` syntax. Use `${VAR:-default}` to provide a fallback value when the variable is not set:
+
+```yaml
+connection_type: 'normal'
+
+connection_settings:
+  user: '${PGUSER:-postgres}'
+  password: '${PGPASSWORD}'
+  host: '${PGHOST:-localhost}'
+  port: '${PGPORT:-5432}'
+  dbname: '${PGDATABASE:-mydb}'
+```
+
+Rules:
+- If a referenced variable is **not set** and **no default** is provided, pgmonkey raises `EnvInterpolationError` with a clear message naming the variable and the config key.
+- Multiple references can appear in a single value: `'${PGHOST}:${PGPORT}'`
+- Non-string values (integers, booleans) pass through unchanged.
+
+### Structured Syntax: from_env / from_file
+
+For secrets, pgmonkey supports a structured YAML form that makes the intent unambiguous:
+
+**Read from an environment variable:**
+
+```yaml
+connection_settings:
+  password:
+    from_env: PGMONKEY_DB_PASSWORD
+```
+
+**Read from a file (Kubernetes Secret-style):**
+
+```yaml
+connection_settings:
+  password:
+    from_file: /var/run/secrets/db/password
+```
+
+Rules:
+- `from_env` reads the named environment variable. If it is not set, pgmonkey raises `EnvInterpolationError`.
+- `from_file` reads the file contents and trims the trailing newline (matching Kubernetes Secret conventions). If the file does not exist or cannot be read, pgmonkey raises `EnvInterpolationError`.
+- A structured reference must be a dict with exactly one key (`from_env` or `from_file`). Dicts with additional keys are treated as normal nested config.
+
+### Sensitive Key Protection
+
+By default, `${VAR:-default}` fallback values are **disallowed** for sensitive keys. This prevents accidentally shipping a config with a hardcoded fallback password that silently takes over when the env var is missing.
+
+Sensitive keys: `password`, `sslkey`, `sslcert`, `sslrootcert`, and any key containing `token`, `secret`, or `credential`.
+
+```yaml
+# This will FAIL (password is a sensitive key, defaults not allowed):
+password: '${PGPASSWORD:-fallback_password}'
+
+# This is fine (host is not sensitive):
+host: '${PGHOST:-localhost}'
+```
+
+To explicitly allow sensitive defaults (e.g. for local development), pass `allow_sensitive_defaults=True`:
+
+```python
+cfg = load_config('config.yaml', resolve_env=True, allow_sensitive_defaults=True)
+```
+
+### Python API
+
+Use `load_config()` for the simplest path to a resolved config dictionary:
+
+```python
+from pgmonkey import load_config
+
+# Load without interpolation (default - same as always)
+cfg = load_config('config.yaml')
+
+# Load with env interpolation enabled
+cfg = load_config('config.yaml', resolve_env=True)
+
+# Strict mode: fail on missing vars
+cfg = load_config('config.yaml', resolve_env=True, strict=True)
+```
+
+Or pass `resolve_env=True` directly to the connection manager:
+
+```python
+from pgmonkey import PGConnectionManager
+
+manager = PGConnectionManager()
+conn = manager.get_database_connection('config.yaml', resolve_env=True)
+```
+
+Both `get_database_connection()` and `get_database_connection_from_dict()` accept the `resolve_env` parameter.
+
+### CLI Usage
+
+Add `--resolve-env` to any `pgconfig test` or `pgconfig generate-code` command:
+
+```bash
+# Test a connection with env vars resolved
+pgmonkey pgconfig test --connconfig config.yaml --resolve-env
+
+# Generate code (--resolve-env accepted for consistency)
+pgmonkey pgconfig generate-code --connconfig config.yaml --resolve-env
+```
+
+Without `--resolve-env`, the CLI works exactly as before - `${VAR}` patterns are treated as literal strings.
+
+### Redacting Secrets for Logging
+
+pgmonkey includes a `redact_config()` utility that replaces sensitive values with `***REDACTED***`, safe for logging or printing:
+
+```python
+from pgmonkey import load_config
+from pgmonkey.common.utils.redaction import redact_config
+
+cfg = load_config('config.yaml', resolve_env=True)
+print(redact_config(cfg))
+# {'connection_settings': {'password': '***REDACTED***', 'host': 'db.prod.com', ...}}
+```
+
+Redacted keys: `password`, `sslkey`, `sslcert`, `sslrootcert`, and any key containing `token`, `secret`, or `credential`. Empty strings and `None` values are left as-is (nothing to leak).
+
+### Deployment Patterns
+
+**Local development** - set env vars in your shell or a `.env` file (managed by your own tooling):
+
+```bash
+export PGPASSWORD=dev_password
+export PGHOST=localhost
+```
+
+**Docker / containers** - pass env vars via `docker run -e` or `docker-compose.yml`:
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    environment:
+      PGPASSWORD: ${DB_PASSWORD}
+      PGHOST: db
+```
+
+**Kubernetes** - mount secrets as files and use `from_file`:
+
+```yaml
+# pgmonkey config
+connection_settings:
+  password:
+    from_file: /var/run/secrets/db/password
+  host: '${PGHOST:-db-service}'
+```
+
+```yaml
+# k8s pod spec
+volumes:
+  - name: db-secret
+    secret:
+      secretName: db-credentials
+containers:
+  - volumeMounts:
+      - name: db-secret
+        mountPath: /var/run/secrets/db
+        readOnly: true
+```
+
+**Cloud secret managers** (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) - resolve secrets in your deployment pipeline and set them as env vars. pgmonkey does not integrate with cloud vaults directly.
+
 ## Using the CLI
 
 pgmonkey provides a command-line interface for managing configurations and connections.

{pgmonkey-3.2.0 → pgmonkey-3.4.0}/README.md

@@ -15,24 +15,33 @@
    - [Password-Based Authentication](#password-based-authentication)
    - [SSL/TLS Encryption](#ssltls-encryption)
    - [Certificate-Based Authentication](#certificate-based-authentication)
-5. [Using the CLI](#using-the-cli)
+5. [Environment Variable Interpolation (Advanced)](#environment-variable-interpolation-advanced)
+   - [Standard YAML (Default)](#standard-yaml-default)
+   - [Inline Syntax: ${VAR}](#inline-syntax-var)
+   - [Structured Syntax: from_env / from_file](#structured-syntax-from_env--from_file)
+   - [Sensitive Key Protection](#sensitive-key-protection)
+   - [Python API](#python-api)
+   - [CLI Usage](#cli-usage)
+   - [Redacting Secrets for Logging](#redacting-secrets-for-logging)
+   - [Deployment Patterns](#deployment-patterns)
+6. [Using the CLI](#using-the-cli)
    - [Creating a Configuration Template](#creating-a-configuration-template)
    - [Testing a Connection](#testing-a-connection)
    - [Generating Python Code](#generating-python-code)
    - [Server Configuration Recommendations](#server-configuration-recommendations)
    - [Auditing Live Server Settings](#auditing-live-server-settings)
    - [Importing and Exporting Data](#importing-and-exporting-data)
-6. [Using pgmonkey in Python](#using-pgmonkey-in-python)
+7. [Using pgmonkey in Python](#using-pgmonkey-in-python)
    - [Normal (Synchronous) Connection](#normal-synchronous-connection)
    - [Pooled Connection](#pooled-connection)
    - [Async Connection](#async-connection)
    - [Async Pooled Connection](#async-pooled-connection)
    - [Using the Config File Default](#using-the-config-file-default)
    - [Transactions, Commit, and Rollback](#transactions-commit-and-rollback)
-7. [Best Practice Recipes](#best-practice-recipes)
-8. [Testing All Connection Types](#testing-all-connection-types)
-9. [Testing Pool Capacity](#testing-pool-capacity)
-10. [Running the Test Suite](#running-the-test-suite)
+8. [Best Practice Recipes](#best-practice-recipes)
+9. [Testing All Connection Types](#testing-all-connection-types)
+10. [Testing Pool Capacity](#testing-pool-capacity)
+11. [Running the Test Suite](#running-the-test-suite)
 
 ## Installation
 
@@ -240,6 +249,203 @@ connection_settings:
   sslrootcert: '/path/to/ca.crt'
 ```
 
+## Environment Variable Interpolation (Advanced)
+
+pgmonkey v3.4.0 adds opt-in support for resolving environment variables and secret file references inside YAML configuration files. This lets you keep your config files free of hardcoded credentials while staying compatible with standard deployment workflows (12-factor env vars, Docker, Kubernetes).
+
+**Interpolation is disabled by default.** If you do not enable it, pgmonkey treats every YAML value as a literal string - exactly as it always has.
+
+### Standard YAML (Default)
+
+The standard approach is to write literal values directly in the config file. This is the simplest way to get started and requires no extra flags or API parameters:
+
+```yaml
+connection_type: 'normal'
+
+connection_settings:
+  user: 'postgres'
+  password: 'my_password'
+  host: 'localhost'
+  port: '5432'
+  dbname: 'mydatabase'
+```
+
+```python
+from pgmonkey import PGConnectionManager
+
+manager = PGConnectionManager()
+conn = manager.get_database_connection('config.yaml')
+```
+
+This continues to work exactly as before. No changes needed for existing configs.
+
+### Inline Syntax: ${VAR}
+
+When interpolation is enabled, you can reference environment variables using `${VAR}` syntax. Use `${VAR:-default}` to provide a fallback value when the variable is not set:
+
+```yaml
+connection_type: 'normal'
+
+connection_settings:
+  user: '${PGUSER:-postgres}'
+  password: '${PGPASSWORD}'
+  host: '${PGHOST:-localhost}'
+  port: '${PGPORT:-5432}'
+  dbname: '${PGDATABASE:-mydb}'
+```
+
+Rules:
+- If a referenced variable is **not set** and **no default** is provided, pgmonkey raises `EnvInterpolationError` with a clear message naming the variable and the config key.
+- Multiple references can appear in a single value: `'${PGHOST}:${PGPORT}'`
+- Non-string values (integers, booleans) pass through unchanged.
+
+### Structured Syntax: from_env / from_file
+
+For secrets, pgmonkey supports a structured YAML form that makes the intent unambiguous:
+
+**Read from an environment variable:**
+
+```yaml
+connection_settings:
+  password:
+    from_env: PGMONKEY_DB_PASSWORD
+```
+
+**Read from a file (Kubernetes Secret-style):**
+
+```yaml
+connection_settings:
+  password:
+    from_file: /var/run/secrets/db/password
+```
+
+Rules:
+- `from_env` reads the named environment variable. If it is not set, pgmonkey raises `EnvInterpolationError`.
+- `from_file` reads the file contents and trims the trailing newline (matching Kubernetes Secret conventions). If the file does not exist or cannot be read, pgmonkey raises `EnvInterpolationError`.
+- A structured reference must be a dict with exactly one key (`from_env` or `from_file`). Dicts with additional keys are treated as normal nested config.
+
+### Sensitive Key Protection
+
+By default, `${VAR:-default}` fallback values are **disallowed** for sensitive keys. This prevents accidentally shipping a config with a hardcoded fallback password that silently takes over when the env var is missing.
+
+Sensitive keys: `password`, `sslkey`, `sslcert`, `sslrootcert`, and any key containing `token`, `secret`, or `credential`.
+
+```yaml
+# This will FAIL (password is a sensitive key, defaults not allowed):
+password: '${PGPASSWORD:-fallback_password}'
+
+# This is fine (host is not sensitive):
+host: '${PGHOST:-localhost}'
+```
+
+To explicitly allow sensitive defaults (e.g. for local development), pass `allow_sensitive_defaults=True`:
+
+```python
+cfg = load_config('config.yaml', resolve_env=True, allow_sensitive_defaults=True)
+```
+
+### Python API
+
+Use `load_config()` for the simplest path to a resolved config dictionary:
+
+```python
+from pgmonkey import load_config
+
+# Load without interpolation (default - same as always)
+cfg = load_config('config.yaml')
+
+# Load with env interpolation enabled
+cfg = load_config('config.yaml', resolve_env=True)
+
+# Strict mode: fail on missing vars
+cfg = load_config('config.yaml', resolve_env=True, strict=True)
+```
+
+Or pass `resolve_env=True` directly to the connection manager:
+
+```python
+from pgmonkey import PGConnectionManager
+
+manager = PGConnectionManager()
+conn = manager.get_database_connection('config.yaml', resolve_env=True)
+```
+
+Both `get_database_connection()` and `get_database_connection_from_dict()` accept the `resolve_env` parameter.
+
+### CLI Usage
+
+Add `--resolve-env` to any `pgconfig test` or `pgconfig generate-code` command:
+
+```bash
+# Test a connection with env vars resolved
+pgmonkey pgconfig test --connconfig config.yaml --resolve-env
+
+# Generate code (--resolve-env accepted for consistency)
+pgmonkey pgconfig generate-code --connconfig config.yaml --resolve-env
+```
+
+Without `--resolve-env`, the CLI works exactly as before - `${VAR}` patterns are treated as literal strings.
+
+### Redacting Secrets for Logging
+
+pgmonkey includes a `redact_config()` utility that replaces sensitive values with `***REDACTED***`, safe for logging or printing:
+
+```python
+from pgmonkey import load_config
+from pgmonkey.common.utils.redaction import redact_config
+
+cfg = load_config('config.yaml', resolve_env=True)
+print(redact_config(cfg))
+# {'connection_settings': {'password': '***REDACTED***', 'host': 'db.prod.com', ...}}
+```
+
+Redacted keys: `password`, `sslkey`, `sslcert`, `sslrootcert`, and any key containing `token`, `secret`, or `credential`. Empty strings and `None` values are left as-is (nothing to leak).
+
+### Deployment Patterns
+
+**Local development** - set env vars in your shell or a `.env` file (managed by your own tooling):
+
+```bash
+export PGPASSWORD=dev_password
+export PGHOST=localhost
+```
+
+**Docker / containers** - pass env vars via `docker run -e` or `docker-compose.yml`:
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    environment:
+      PGPASSWORD: ${DB_PASSWORD}
+      PGHOST: db
+```
+
+**Kubernetes** - mount secrets as files and use `from_file`:
+
+```yaml
+# pgmonkey config
+connection_settings:
+  password:
+    from_file: /var/run/secrets/db/password
+  host: '${PGHOST:-db-service}'
+```
+
+```yaml
+# k8s pod spec
+volumes:
+  - name: db-secret
+    secret:
+      secretName: db-credentials
+containers:
+  - volumeMounts:
+      - name: db-secret
+        mountPath: /var/run/secrets/db
+        readOnly: true
+```
+
+**Cloud secret managers** (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) - resolve secrets in your deployment pipeline and set them as env vars. pgmonkey does not integrate with cloud vaults directly.
+
 ## Using the CLI
 
 pgmonkey provides a command-line interface for managing configurations and connections.

{pgmonkey-3.2.0 → pgmonkey-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pgmonkey"
-version = "3.2.0"
+version = "3.4.0"
 authors = [
   { name="Good Boy", email="pythonic@rexbytes.com" },
 ]

pgmonkey-3.4.0/src/pgmonkey/__init__.py

@@ -0,0 +1,3 @@
+from .managers.pgconnection_manager import PGConnectionManager
+from .common.utils.configutils import load_config
+from .common.utils.envutils import EnvInterpolationError

{pgmonkey-3.2.0 → pgmonkey-3.4.0}/src/pgmonkey/cli/cli_pgconfig_subparser.py

@@ -27,6 +27,9 @@ def cli_pgconfig_subparser(subparsers):
                              help='Path to the configuration file you want to test.')
     test_parser.add_argument('--connection-type', choices=CONNECTION_TYPE_CHOICES, default=None,
                              help='Connection type to test. Overrides the value in the config file.')
+    test_parser.add_argument('--resolve-env', action='store_true', default=False,
+                             help='Resolve ${VAR} environment variable references and '
+                                  'from_env/from_file secret references in the config file.')
     test_parser.set_defaults(func=pgconfig_test_handler, pgconfig_manager=pgconfig_manager)
 
     # The "generate-code" subcommand
@@ -40,6 +43,9 @@ def cli_pgconfig_subparser(subparsers):
                              help='Target library for generated code. '
                                   '"pgmonkey" (default) generates code using pgmonkey. '
                                   '"psycopg" generates code using psycopg/psycopg_pool directly.')
+    code_parser.add_argument('--resolve-env', action='store_true', default=False,
+                             help='Resolve ${VAR} environment variable references and '
+                                  'from_env/from_file secret references in the config file.')
     code_parser.set_defaults(func=pgconfig_generate_code_handler, pgcodegen_manager=pgcodegen_manager)
 
 
@@ -56,11 +62,15 @@ def pgconfig_create_handler(args):
 def pgconfig_test_handler(args):
     pgconfig_manager = args.pgconfig_manager
     connection_type = getattr(args, 'connection_type', None)
-    pgconfig_manager.test_connection(args.filepath, connection_type)
+    resolve_env = getattr(args, 'resolve_env', False)
+    pgconfig_manager.test_connection(args.filepath, connection_type, resolve_env=resolve_env)
 
 
 def pgconfig_generate_code_handler(args):
     pgcodegen_manager = args.pgcodegen_manager
     connection_type = getattr(args, 'connection_type', None)
     library = getattr(args, 'library', 'pgmonkey')
-    pgcodegen_manager.generate_connection_code(args.filepath, connection_type, library=library)
+    resolve_env = getattr(args, 'resolve_env', False)
+    pgcodegen_manager.generate_connection_code(
+        args.filepath, connection_type, library=library, resolve_env=resolve_env,
+    )

{pgmonkey-3.2.0 → pgmonkey-3.4.0}/src/pgmonkey/common/templates/postgres.yaml

@@ -63,3 +63,21 @@ async_pool_settings:
   # max_waiting: 0  # Max clients queued waiting for a connection (0 = unlimited)
   # reconnect_timeout: 300  # Seconds to keep trying to reconnect failed connections (0 = forever)
   # num_workers: 3  # Number of background workers maintaining pool connections
+
+# -- Advanced: environment variable interpolation (opt-in) --
+# By default, pgmonkey uses the literal values above as-is.
+# If you need to inject secrets at runtime instead of hardcoding them,
+# enable interpolation with resolve_env=True in Python or --resolve-env on the CLI.
+#
+#   Inline syntax:
+#     host: '${PGHOST:-localhost}'     # uses env var, falls back to 'localhost'
+#     password: '${PGPASSWORD}'        # required - error if not set
+#
+#   Structured syntax (recommended for secrets):
+#     password:
+#       from_env: PGMONKEY_DB_PASSWORD       # reads env var
+#     password:
+#       from_file: /var/run/secrets/db/pass   # reads file, trims trailing newline
+#
+# Sensitive keys (password, sslkey, sslcert, sslrootcert) do not allow
+# defaults in ${VAR:-default} by default, to prevent accidental fallbacks.

pgmonkey-3.4.0/src/pgmonkey/common/utils/configutils.py

@@ -0,0 +1,71 @@
+import warnings
+
+import yaml
+
+from pgmonkey.common.utils.envutils import resolve_env_vars
+
+
+def load_config(file_path, resolve_env=False, strict=False,
+                allow_sensitive_defaults=False):
+    """Load and optionally interpolate a pgmonkey YAML configuration file.
+
+    This is the recommended entry point for programmatic config loading.
+
+    Parameters
+    ----------
+    file_path : str
+        Path to the YAML configuration file.
+    resolve_env : bool
+        If True, ``${VAR}`` / ``${VAR:-default}`` patterns and
+        ``from_env`` / ``from_file`` structured references are resolved.
+    strict : bool
+        If True (and *resolve_env* is True), missing env vars with no
+        default raise immediately.  Passed through to
+        :func:`resolve_env_vars`.
+    allow_sensitive_defaults : bool
+        If True, ``${VAR:-default}`` is permitted even for sensitive keys
+        like ``password``.  Default is False for safety.
+
+    Returns
+    -------
+    dict
+        The parsed (and optionally resolved) configuration dictionary.
+    """
+    with open(file_path, 'r') as f:
+        config = yaml.safe_load(f)
+
+    config = normalize_config(config)
+
+    if resolve_env:
+        config = resolve_env_vars(
+            config,
+            strict=strict,
+            allow_sensitive_defaults=allow_sensitive_defaults,
+        )
+
+    return config
+
+
+def normalize_config(config_data):
+    """Normalize a pgmonkey configuration dictionary.
+
+    In pgmonkey v3.0.0, the top-level 'postgresql:' wrapper key was removed.
+    This function detects the old format and unwraps it with a deprecation warning.
+
+    Args:
+        config_data: Configuration dictionary (old or new format).
+
+    Returns:
+        The normalized configuration dictionary (without the 'postgresql:' wrapper).
+    """
+    if isinstance(config_data, dict) and 'postgresql' in config_data:
+        warnings.warn(
+            "The top-level 'postgresql:' key in pgmonkey config files is deprecated "
+            "since v3.0.0 and will be removed in a future version. "
+            "Remove the 'postgresql:' wrapper and dedent all settings one level. "
+            "See https://pgmonkey.net/reference.html for the new format.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return config_data['postgresql']
+    return config_data