pgmonkey 2.3.0__tar.gz → 3.3.0__tar.gz

{pgmonkey-2.3.0/src/pgmonkey.egg-info → pgmonkey-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgmonkey
-Version: 2.3.0
+Version: 3.3.0
 Summary: A tool to assist with postgresql database connections
 Author-email: Good Boy <pythonic@rexbytes.com>
 License: MIT
@@ -15,7 +15,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: <3.14,>=3.10
+Requires-Python: <4.0,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
@@ -90,7 +90,7 @@ pip install pgmonkey[test]
 
 ## One Config File, All Connection Types
 
-In v2.0.0, pgmonkey uses a **single YAML configuration file** for all connection types. Instead of maintaining separate config files for normal, pool, async, and async_pool connections, you define everything in one file and specify the connection type when you call the API:
+pgmonkey uses a **single YAML configuration file** for all connection types. Instead of maintaining separate config files for normal, pool, async, and async_pool connections, you define everything in one file and specify the connection type when you call the API:
 
 ```python
 from pgmonkey import PGConnectionManager
@@ -111,55 +111,54 @@ The `connection_type` parameter is optional. If omitted, pgmonkey uses the `conn
 Here is the full configuration template. You only need to fill in the sections relevant to the connection types you plan to use.
 
 ```yaml
-postgresql:
-  # Default connection type when none is specified in the API call.
-  # Options: 'normal', 'pool', 'async', 'async_pool'
-  # You can override this per-call:
-  #   manager.get_database_connection('config.yaml', 'pool')
-  connection_type: 'normal'
-
-  connection_settings:
-    user: 'postgres'
-    password: 'password'
-    host: 'localhost'
-    port: '5432'
-    dbname: 'mydatabase'
-    sslmode: 'prefer'  # Options: disable, allow, prefer, require, verify-ca, verify-full
-    sslcert: ''  # Path to the client SSL certificate, if needed
-    sslkey: ''  # Path to the client SSL key, if needed
-    sslrootcert: ''  # Path to the root SSL certificate, if needed
-    connect_timeout: '10'  # Maximum wait for connection, in seconds
-    application_name: 'myapp'
-    keepalives: '1'  # Enable TCP keepalives (1=on, 0=off)
-    keepalives_idle: '60'  # Seconds before sending a keepalive probe
-    keepalives_interval: '15'  # Seconds between keepalive probes
-    keepalives_count: '5'  # Max keepalive probes before closing the connection
-
-  # Settings for 'pool' connection type
-  pool_settings:
-    min_size: 5
-    max_size: 20
-    timeout: 30  # Seconds to wait for a connection from the pool before raising an error
-    max_idle: 300  # Seconds a connection can remain idle before being closed
-    max_lifetime: 3600  # Seconds a connection can be reused
-    check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
-
-  # Settings for 'async' connection type (applied via SET commands on connection)
-  # These settings are also applied to 'async_pool' connections via a configure callback.
-  async_settings:
-    idle_in_transaction_session_timeout: '5000'  # Timeout for idle in transaction (ms)
-    statement_timeout: '30000'  # Cancel statements exceeding this time (ms)
-    lock_timeout: '10000'  # Timeout for acquiring locks (ms)
-    # work_mem: '256MB'  # Memory for sort operations and more
-
-  # Settings for 'async_pool' connection type
-  async_pool_settings:
-    min_size: 5
-    max_size: 20
-    timeout: 30  # Seconds to wait for a connection from the pool before raising an error
-    max_idle: 300
-    max_lifetime: 3600
-    check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
+# Default connection type when none is specified in the API call.
+# Options: 'normal', 'pool', 'async', 'async_pool'
+# You can override this per-call:
+#   manager.get_database_connection('config.yaml', 'pool')
+connection_type: 'normal'
+
+connection_settings:
+  user: 'postgres'
+  password: 'password'
+  host: 'localhost'
+  port: '5432'
+  dbname: 'mydatabase'
+  sslmode: 'prefer'  # Options: disable, allow, prefer, require, verify-ca, verify-full
+  sslcert: ''  # Path to the client SSL certificate, if needed
+  sslkey: ''  # Path to the client SSL key, if needed
+  sslrootcert: ''  # Path to the root SSL certificate, if needed
+  connect_timeout: '10'  # Maximum wait for connection, in seconds
+  application_name: 'myapp'
+  keepalives: '1'  # Enable TCP keepalives (1=on, 0=off)
+  keepalives_idle: '60'  # Seconds before sending a keepalive probe
+  keepalives_interval: '15'  # Seconds between keepalive probes
+  keepalives_count: '5'  # Max keepalive probes before closing the connection
+
+# Settings for 'pool' connection type
+pool_settings:
+  min_size: 5
+  max_size: 20
+  timeout: 30  # Seconds to wait for a connection from the pool before raising an error
+  max_idle: 300  # Seconds a connection can remain idle before being closed
+  max_lifetime: 3600  # Seconds a connection can be reused
+  check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
+
+# Settings for 'async' connection type (applied via SET commands on connection)
+# These settings are also applied to 'async_pool' connections via a configure callback.
+async_settings:
+  idle_in_transaction_session_timeout: '5000'  # Timeout for idle in transaction (ms)
+  statement_timeout: '30000'  # Cancel statements exceeding this time (ms)
+  lock_timeout: '10000'  # Timeout for acquiring locks (ms)
+  # work_mem: '256MB'  # Memory for sort operations and more
+
+# Settings for 'async_pool' connection type
+async_pool_settings:
+  min_size: 5
+  max_size: 20
+  timeout: 30  # Seconds to wait for a connection from the pool before raising an error
+  max_idle: 300
+  max_lifetime: 3600
+  check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
 ```
 
 ### Connection Settings
@@ -226,13 +225,12 @@ Used by `async_pool` connection type. Same parameters as pool settings. The `asy
 The most common method. Credentials are sent to the PostgreSQL server for validation.
 
 ```yaml
-postgresql:
-  connection_type: 'normal'
-  connection_settings:
-    user: 'your_user'
-    password: 'your_password'
-    host: 'localhost'
-    dbname: 'your_database'
+connection_type: 'normal'
+connection_settings:
+  user: 'your_user'
+  password: 'your_password'
+  host: 'localhost'
+  dbname: 'your_database'
 ```
 
 ### SSL/TLS Encryption
@@ -247,15 +245,14 @@ SSL/TLS encrypts the connection between your application and the PostgreSQL serv
 - `verify-full`: Require SSL, verify certificate, and ensure the hostname matches.
 
 ```yaml
-postgresql:
-  connection_type: 'normal'
-  connection_settings:
-    user: 'your_user'
-    password: 'your_password'
-    host: 'localhost'
-    dbname: 'your_database'
-    sslmode: 'require'
-    sslrootcert: '/path/to/ca.crt'
+connection_type: 'normal'
+connection_settings:
+  user: 'your_user'
+  password: 'your_password'
+  host: 'localhost'
+  dbname: 'your_database'
+  sslmode: 'require'
+  sslrootcert: '/path/to/ca.crt'
 ```
 
 ### Certificate-Based Authentication
@@ -263,17 +260,16 @@ postgresql:
 Uses SSL client certificates for authentication. Highly secure and often used in enterprise environments.
 
 ```yaml
-postgresql:
-  connection_type: 'normal'
-  connection_settings:
-    user: 'your_user'
-    password: 'your_password'
-    host: 'localhost'
-    dbname: 'your_database'
-    sslmode: 'verify-full'
-    sslcert: '/path/to/client.crt'
-    sslkey: '/path/to/client.key'
-    sslrootcert: '/path/to/ca.crt'
+connection_type: 'normal'
+connection_settings:
+  user: 'your_user'
+  password: 'your_password'
+  host: 'localhost'
+  dbname: 'your_database'
+  sslmode: 'verify-full'
+  sslcert: '/path/to/client.crt'
+  sslkey: '/path/to/client.key'
+  sslrootcert: '/path/to/ca.crt'
 ```
 
 ## Using the CLI
@@ -326,8 +322,8 @@ pgmonkey pgconfig generate-code --filepath /path/to/config.yaml --connection-typ
 
 The `--library` flag controls which library the generated code targets:
 
-- `pgmonkey` (default) — generates code using pgmonkey's `PGConnectionManager`.
-- `psycopg` — generates code using `psycopg` and `psycopg_pool` directly, reading connection settings from the same YAML config file.
+- `pgmonkey` (default) - generates code using pgmonkey's `PGConnectionManager`.
+- `psycopg` - generates code using `psycopg` and `psycopg_pool` directly, reading connection settings from the same YAML config file.
 
 ### Server Configuration Recommendations
 
@@ -386,7 +382,7 @@ This queries the server's `pg_settings` (read-only) and displays a comparison ta
 
 The audit also inspects `pg_hba_file_rules` (PostgreSQL 15+) when available, showing current HBA rules alongside recommendations.
 
-If the connected role lacks permission to query `pg_settings`, the audit fails gracefully with a message and falls back to showing recommendations only. No server settings are ever modified — the audit is entirely read-only.
+If the connected role lacks permission to query `pg_settings`, the audit fails gracefully with a message and falls back to showing recommendations only. No server settings are ever modified - the audit is entirely read-only.
 
 ### Importing and Exporting Data
 
@@ -538,11 +534,11 @@ except Exception as e:
 
 pgmonkey handles several production concerns behind the scenes so you don't have to:
 
-- **Connection caching** — Connections and pools are cached by config content (SHA-256 hash). Repeated calls with the same config return the existing instance, preventing "pool storms" where each call opens a new pool.
-- **Async pool lifecycle** — `async with pool_conn:` borrows a connection from the pool and returns it when the block exits. The pool stays open for reuse. Auto-commits on clean exit, rolls back on exception.
-- **atexit cleanup** — All cached connections are automatically closed when the process exits.
-- **Thread-safe caching** — The connection cache is protected by a threading lock with double-check locking to prevent race conditions.
-- **Config validation** — Unknown connection setting keys produce a warning log message. Pool settings are validated (e.g., `min_size` cannot exceed `max_size`).
+- **Connection caching** - Connections and pools are cached by config content (SHA-256 hash). Repeated calls with the same config return the existing instance, preventing "pool storms" where each call opens a new pool.
+- **Async pool lifecycle** - `async with pool_conn:` borrows a connection from the pool and returns it when the block exits. The pool stays open for reuse. Auto-commits on clean exit, rolls back on exception.
+- **atexit cleanup** - All cached connections are automatically closed when the process exits.
+- **Thread-safe caching** - The connection cache is protected by a threading lock with double-check locking to prevent race conditions.
+- **Config validation** - Unknown connection setting keys produce a warning log message. Pool settings are validated (e.g., `min_size` cannot exceed `max_size`).
 
 ### App-Level Pattern: Sync Database Class (Flask)
 

{pgmonkey-2.3.0 → pgmonkey-3.3.0}/README.md

@@ -58,7 +58,7 @@ pip install pgmonkey[test]
 
 ## One Config File, All Connection Types
 
-In v2.0.0, pgmonkey uses a **single YAML configuration file** for all connection types. Instead of maintaining separate config files for normal, pool, async, and async_pool connections, you define everything in one file and specify the connection type when you call the API:
+pgmonkey uses a **single YAML configuration file** for all connection types. Instead of maintaining separate config files for normal, pool, async, and async_pool connections, you define everything in one file and specify the connection type when you call the API:
 
 ```python
 from pgmonkey import PGConnectionManager
@@ -79,55 +79,54 @@ The `connection_type` parameter is optional. If omitted, pgmonkey uses the `conn
 Here is the full configuration template. You only need to fill in the sections relevant to the connection types you plan to use.
 
 ```yaml
-postgresql:
-  # Default connection type when none is specified in the API call.
-  # Options: 'normal', 'pool', 'async', 'async_pool'
-  # You can override this per-call:
-  #   manager.get_database_connection('config.yaml', 'pool')
-  connection_type: 'normal'
-
-  connection_settings:
-    user: 'postgres'
-    password: 'password'
-    host: 'localhost'
-    port: '5432'
-    dbname: 'mydatabase'
-    sslmode: 'prefer'  # Options: disable, allow, prefer, require, verify-ca, verify-full
-    sslcert: ''  # Path to the client SSL certificate, if needed
-    sslkey: ''  # Path to the client SSL key, if needed
-    sslrootcert: ''  # Path to the root SSL certificate, if needed
-    connect_timeout: '10'  # Maximum wait for connection, in seconds
-    application_name: 'myapp'
-    keepalives: '1'  # Enable TCP keepalives (1=on, 0=off)
-    keepalives_idle: '60'  # Seconds before sending a keepalive probe
-    keepalives_interval: '15'  # Seconds between keepalive probes
-    keepalives_count: '5'  # Max keepalive probes before closing the connection
-
-  # Settings for 'pool' connection type
-  pool_settings:
-    min_size: 5
-    max_size: 20
-    timeout: 30  # Seconds to wait for a connection from the pool before raising an error
-    max_idle: 300  # Seconds a connection can remain idle before being closed
-    max_lifetime: 3600  # Seconds a connection can be reused
-    check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
-
-  # Settings for 'async' connection type (applied via SET commands on connection)
-  # These settings are also applied to 'async_pool' connections via a configure callback.
-  async_settings:
-    idle_in_transaction_session_timeout: '5000'  # Timeout for idle in transaction (ms)
-    statement_timeout: '30000'  # Cancel statements exceeding this time (ms)
-    lock_timeout: '10000'  # Timeout for acquiring locks (ms)
-    # work_mem: '256MB'  # Memory for sort operations and more
-
-  # Settings for 'async_pool' connection type
-  async_pool_settings:
-    min_size: 5
-    max_size: 20
-    timeout: 30  # Seconds to wait for a connection from the pool before raising an error
-    max_idle: 300
-    max_lifetime: 3600
-    check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
+# Default connection type when none is specified in the API call.
+# Options: 'normal', 'pool', 'async', 'async_pool'
+# You can override this per-call:
+#   manager.get_database_connection('config.yaml', 'pool')
+connection_type: 'normal'
+
+connection_settings:
+  user: 'postgres'
+  password: 'password'
+  host: 'localhost'
+  port: '5432'
+  dbname: 'mydatabase'
+  sslmode: 'prefer'  # Options: disable, allow, prefer, require, verify-ca, verify-full
+  sslcert: ''  # Path to the client SSL certificate, if needed
+  sslkey: ''  # Path to the client SSL key, if needed
+  sslrootcert: ''  # Path to the root SSL certificate, if needed
+  connect_timeout: '10'  # Maximum wait for connection, in seconds
+  application_name: 'myapp'
+  keepalives: '1'  # Enable TCP keepalives (1=on, 0=off)
+  keepalives_idle: '60'  # Seconds before sending a keepalive probe
+  keepalives_interval: '15'  # Seconds between keepalive probes
+  keepalives_count: '5'  # Max keepalive probes before closing the connection
+
+# Settings for 'pool' connection type
+pool_settings:
+  min_size: 5
+  max_size: 20
+  timeout: 30  # Seconds to wait for a connection from the pool before raising an error
+  max_idle: 300  # Seconds a connection can remain idle before being closed
+  max_lifetime: 3600  # Seconds a connection can be reused
+  check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
+
+# Settings for 'async' connection type (applied via SET commands on connection)
+# These settings are also applied to 'async_pool' connections via a configure callback.
+async_settings:
+  idle_in_transaction_session_timeout: '5000'  # Timeout for idle in transaction (ms)
+  statement_timeout: '30000'  # Cancel statements exceeding this time (ms)
+  lock_timeout: '10000'  # Timeout for acquiring locks (ms)
+  # work_mem: '256MB'  # Memory for sort operations and more
+
+# Settings for 'async_pool' connection type
+async_pool_settings:
+  min_size: 5
+  max_size: 20
+  timeout: 30  # Seconds to wait for a connection from the pool before raising an error
+  max_idle: 300
+  max_lifetime: 3600
+  check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
 ```
 
 ### Connection Settings
@@ -194,13 +193,12 @@ Used by `async_pool` connection type. Same parameters as pool settings. The `asy
 The most common method. Credentials are sent to the PostgreSQL server for validation.
 
 ```yaml
-postgresql:
-  connection_type: 'normal'
-  connection_settings:
-    user: 'your_user'
-    password: 'your_password'
-    host: 'localhost'
-    dbname: 'your_database'
+connection_type: 'normal'
+connection_settings:
+  user: 'your_user'
+  password: 'your_password'
+  host: 'localhost'
+  dbname: 'your_database'
 ```
 
 ### SSL/TLS Encryption
@@ -215,15 +213,14 @@ SSL/TLS encrypts the connection between your application and the PostgreSQL serv
 - `verify-full`: Require SSL, verify certificate, and ensure the hostname matches.
 
 ```yaml
-postgresql:
-  connection_type: 'normal'
-  connection_settings:
-    user: 'your_user'
-    password: 'your_password'
-    host: 'localhost'
-    dbname: 'your_database'
-    sslmode: 'require'
-    sslrootcert: '/path/to/ca.crt'
+connection_type: 'normal'
+connection_settings:
+  user: 'your_user'
+  password: 'your_password'
+  host: 'localhost'
+  dbname: 'your_database'
+  sslmode: 'require'
+  sslrootcert: '/path/to/ca.crt'
 ```
 
 ### Certificate-Based Authentication
@@ -231,17 +228,16 @@ postgresql:
 Uses SSL client certificates for authentication. Highly secure and often used in enterprise environments.
 
 ```yaml
-postgresql:
-  connection_type: 'normal'
-  connection_settings:
-    user: 'your_user'
-    password: 'your_password'
-    host: 'localhost'
-    dbname: 'your_database'
-    sslmode: 'verify-full'
-    sslcert: '/path/to/client.crt'
-    sslkey: '/path/to/client.key'
-    sslrootcert: '/path/to/ca.crt'
+connection_type: 'normal'
+connection_settings:
+  user: 'your_user'
+  password: 'your_password'
+  host: 'localhost'
+  dbname: 'your_database'
+  sslmode: 'verify-full'
+  sslcert: '/path/to/client.crt'
+  sslkey: '/path/to/client.key'
+  sslrootcert: '/path/to/ca.crt'
 ```
 
 ## Using the CLI
@@ -294,8 +290,8 @@ pgmonkey pgconfig generate-code --filepath /path/to/config.yaml --connection-typ
 
 The `--library` flag controls which library the generated code targets:
 
-- `pgmonkey` (default) — generates code using pgmonkey's `PGConnectionManager`.
-- `psycopg` — generates code using `psycopg` and `psycopg_pool` directly, reading connection settings from the same YAML config file.
+- `pgmonkey` (default) - generates code using pgmonkey's `PGConnectionManager`.
+- `psycopg` - generates code using `psycopg` and `psycopg_pool` directly, reading connection settings from the same YAML config file.
 
 ### Server Configuration Recommendations
 
@@ -354,7 +350,7 @@ This queries the server's `pg_settings` (read-only) and displays a comparison ta
 
 The audit also inspects `pg_hba_file_rules` (PostgreSQL 15+) when available, showing current HBA rules alongside recommendations.
 
-If the connected role lacks permission to query `pg_settings`, the audit fails gracefully with a message and falls back to showing recommendations only. No server settings are ever modified — the audit is entirely read-only.
+If the connected role lacks permission to query `pg_settings`, the audit fails gracefully with a message and falls back to showing recommendations only. No server settings are ever modified - the audit is entirely read-only.
 
 ### Importing and Exporting Data
 
@@ -506,11 +502,11 @@ except Exception as e:
 
 pgmonkey handles several production concerns behind the scenes so you don't have to:
 
-- **Connection caching** — Connections and pools are cached by config content (SHA-256 hash). Repeated calls with the same config return the existing instance, preventing "pool storms" where each call opens a new pool.
-- **Async pool lifecycle** — `async with pool_conn:` borrows a connection from the pool and returns it when the block exits. The pool stays open for reuse. Auto-commits on clean exit, rolls back on exception.
-- **atexit cleanup** — All cached connections are automatically closed when the process exits.
-- **Thread-safe caching** — The connection cache is protected by a threading lock with double-check locking to prevent race conditions.
-- **Config validation** — Unknown connection setting keys produce a warning log message. Pool settings are validated (e.g., `min_size` cannot exceed `max_size`).
+- **Connection caching** - Connections and pools are cached by config content (SHA-256 hash). Repeated calls with the same config return the existing instance, preventing "pool storms" where each call opens a new pool.
+- **Async pool lifecycle** - `async with pool_conn:` borrows a connection from the pool and returns it when the block exits. The pool stays open for reuse. Auto-commits on clean exit, rolls back on exception.
+- **atexit cleanup** - All cached connections are automatically closed when the process exits.
+- **Thread-safe caching** - The connection cache is protected by a threading lock with double-check locking to prevent race conditions.
+- **Config validation** - Unknown connection setting keys produce a warning log message. Pool settings are validated (e.g., `min_size` cannot exceed `max_size`).
 
 ### App-Level Pattern: Sync Database Class (Flask)
 

{pgmonkey-2.3.0 → pgmonkey-3.3.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pgmonkey"
-version = "2.3.0"
+version = "3.3.0"
 authors = [
   { name="Good Boy", email="pythonic@rexbytes.com" },
 ]
 description = "A tool to assist with postgresql database connections"
 readme = "README.md"
 license = {text = "MIT"}
-requires-python = ">=3.10,<3.14"
+requires-python = ">=3.10,<4.0"
 classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",

{pgmonkey-2.3.0 → pgmonkey-3.3.0}/src/pgmonkey/cli/cli_export_subparser.py

@@ -1,4 +1,5 @@
 from pgmonkey.managers.pgexport_manager import PGExportManager
+from pgmonkey.common.exceptions import ConfigFileCreatedError
 from pathlib import Path
 
 
@@ -41,5 +42,8 @@ def pgexport_handler(args):
 
     # Proceed with exporting the table data to CSV (the export settings file is automatically derived)
     # print(f"Starting export of table: {table_name} to CSV file: {export_file if export_file else 'default based on table name'}")
-    pgexport_manager.export_table(table_name, connection_config, export_file)
-    print("Export complete.")
+    try:
+        pgexport_manager.export_table(table_name, connection_config, export_file)
+        print("Export complete.")
+    except ConfigFileCreatedError as e:
+        print(e)

{pgmonkey-2.3.0 → pgmonkey-3.3.0}/src/pgmonkey/cli/cli_import_subparser.py

@@ -1,4 +1,5 @@
 from pgmonkey.managers.pgimport_manager import PGImportManager
+from pgmonkey.common.exceptions import ConfigFileCreatedError
 from pathlib import Path
 
 def cli_pgimport_subparser(subparsers):
@@ -39,6 +40,9 @@ def pgimport_handler(args):
 
     # Proceed with importing the file (the settings file is automatically derived)
     # print(f"Starting import for file: {import_file} into table: {table_name}")
-    pgimport_manager.import_file(import_file, table_name, connection_config)
-    print("Import complete.")
+    try:
+        pgimport_manager.import_file(import_file, table_name, connection_config)
+        print("Import complete.")
+    except ConfigFileCreatedError as e:
+        print(e)
 

pgmonkey-3.3.0/src/pgmonkey/common/exceptions.py

@@ -0,0 +1,3 @@
+class ConfigFileCreatedError(Exception):
+    """Raised when a config file has been auto-generated and needs user review before proceeding."""
+    pass

pgmonkey-3.3.0/src/pgmonkey/common/templates/postgres.yaml

@@ -0,0 +1,65 @@
+# Default connection type used when none is specified in the API call.
+# Options: 'normal', 'pool', 'async', 'async_pool'
+# You can override this per-call:
+#   manager.get_database_connection('config.yaml', 'pool')
+connection_type: 'normal'
+
+connection_settings:
+  user: 'postgres'
+  password: 'password'
+  host: 'localhost'
+  port: '5432'
+  dbname: 'mydatabase'
+  sslmode: 'prefer'  # Options: disable, allow, prefer, require, verify-ca, verify-full
+  sslcert: ''  # Path to the client SSL certificate, if needed
+  sslkey: ''  # Path to the client SSL key, if needed
+  sslrootcert: ''  # Path to the root SSL certificate, if needed
+  connect_timeout: '10'  # Maximum wait for connection, in seconds
+  application_name: 'myapp'
+  keepalives: '1'  # Enable TCP keepalives (1=on, 0=off)
+  keepalives_idle: '60'  # Seconds before sending a keepalive probe
+  keepalives_interval: '15'  # Seconds between keepalive probes
+  keepalives_count: '5'  # Max keepalive probes before closing the connection
+  # autocommit: false  # Enable autocommit mode (required for DDL like CREATE DATABASE, VACUUM, etc.)
+
+# Session-level GUC settings for 'normal' and 'pool' connection types.
+# For 'normal': applied via SET commands after connect.
+# For 'pool': applied via psycopg_pool's configure callback on each checkout.
+sync_settings:
+  # statement_timeout: '30000'  # Cancel statements exceeding this time (ms)
+  # lock_timeout: '10000'  # Timeout for acquiring locks (ms)
+  # idle_in_transaction_session_timeout: '5000'  # Timeout for idle in transaction (ms)
+  # work_mem: '256MB'  # Memory for sort operations and more
+
+# Settings for 'pool' connection type
+pool_settings:
+  min_size: 5
+  max_size: 20
+  timeout: 30  # Seconds to wait for a connection from the pool before raising an error
+  max_idle: 300  # Seconds a connection can remain idle before being closed
+  max_lifetime: 3600  # Seconds a connection can be reused
+  check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
+  # 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
+
+# Session-level GUC settings for 'async' and 'async_pool' connection types.
+# For 'async': applied via SET commands after connect.
+# For 'async_pool': applied via psycopg_pool's configure callback on each checkout.
+async_settings:
+  idle_in_transaction_session_timeout: '5000'  # Timeout for idle in transaction (ms)
+  statement_timeout: '30000'  # Cancel statements exceeding this time (ms)
+  lock_timeout: '10000'  # Timeout for acquiring locks (ms)
+  # work_mem: '256MB'  # Memory for sort operations and more
+
+# Settings for 'async_pool' connection type
+async_pool_settings:
+  min_size: 5
+  max_size: 20
+  timeout: 30  # Seconds to wait for a connection from the pool before raising an error
+  max_idle: 300
+  max_lifetime: 3600
+  check_on_checkout: false  # Validate connections with SELECT 1 before handing to caller
+  # 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

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

@@ -0,0 +1,26 @@
+import warnings
+
+
+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

{pgmonkey-2.3.0 → pgmonkey-3.3.0}/src/pgmonkey/connections/postgres/async_pool_connection.py

@@ -8,8 +8,6 @@ from contextlib import asynccontextmanager
 
 logger = logging.getLogger(__name__)
 
-warnings.filterwarnings('ignore', category=RuntimeWarning, module='psycopg_pool')
-
 
 class PGAsyncPoolConnection(PostgresBaseConnection):
     def __init__(self, config, async_pool_settings=None, async_settings=None):
@@ -47,7 +45,12 @@ class PGAsyncPoolConnection(PostgresBaseConnection):
                             logger.warning("Could not apply setting '%s': %s", setting, e)
                 kwargs['configure'] = _configure
 
-            self.pool = AsyncConnectionPool(conninfo=conninfo, **kwargs)
+            # Suppress RuntimeWarnings that psycopg_pool may emit during
+            # pool construction. Scoped to construction only so that
+            # warnings during normal pool operation remain visible.
+            with warnings.catch_warnings():
+                warnings.filterwarnings('ignore', category=RuntimeWarning, module='psycopg_pool')
+                self.pool = AsyncConnectionPool(conninfo=conninfo, **kwargs)
             await self.pool.open()
 
     async def test_connection(self):