pgmonkey 2.1.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgmonkey
-Version: 2.1.0
+Version: 2.3.0
 Summary: A tool to assist with postgresql database connections
 Author-email: Good Boy <pythonic@rexbytes.com>
 License: MIT
@@ -52,6 +52,7 @@ Dynamic: license-file
    - [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)
    - [Normal (Synchronous) Connection](#normal-synchronous-connection)
@@ -138,10 +139,13 @@ postgresql:
   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)
@@ -152,8 +156,10 @@ postgresql:
   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
@@ -184,12 +190,14 @@ Used by `pool` connection type.
 |-----------|-------------|---------|
 | `min_size` | Minimum number of connections in the pool | `5` |
 | `max_size` | Maximum number of connections in the pool | `20` |
+| `timeout` | Seconds to wait for a connection from the pool before raising an error | `30` |
 | `max_idle` | Seconds a connection can remain idle before being closed | `300` |
 | `max_lifetime` | Seconds a connection can be reused | `3600` |
+| `check_on_checkout` | Validate connections with `SELECT 1` before handing to caller | `false` |
 
 ### Async Settings
 
-Used by `async` connection type. These are applied via SQL `SET` commands when the connection is established.
+Used by `async` and `async_pool` connection types. These are applied via SQL `SET` commands when the connection is established. For `async_pool`, they are applied to each connection via a psycopg_pool `configure` callback.
 
 | Parameter | Description | Example |
 |-----------|-------------|---------|
@@ -200,14 +208,16 @@ Used by `async` connection type. These are applied via SQL `SET` commands when t
 
 ### Async Pool Settings
 
-Used by `async_pool` connection type. Same parameters as pool settings.
+Used by `async_pool` connection type. Same parameters as pool settings. The `async_settings` section (above) is also applied to async pool connections.
 
 | Parameter | Description | Example |
 |-----------|-------------|---------|
 | `min_size` | Minimum connections in the async pool | `5` |
 | `max_size` | Maximum connections in the async pool | `20` |
+| `timeout` | Seconds to wait for a connection from the pool before raising an error | `30` |
 | `max_idle` | Seconds a connection can remain idle | `300` |
 | `max_lifetime` | Seconds a connection can be reused | `3600` |
+| `check_on_checkout` | Validate connections with `SELECT 1` before handing to caller | `false` |
 
 ## Authentication Methods
 
@@ -309,8 +319,16 @@ pgmonkey pgconfig generate-code --filepath /path/to/config.yaml
 
 # Generate code for a specific connection type
 pgmonkey pgconfig generate-code --filepath /path/to/config.yaml --connection-type async_pool
+
+# Generate code using native psycopg/psycopg_pool instead of pgmonkey
+pgmonkey pgconfig generate-code --filepath /path/to/config.yaml --connection-type pool --library psycopg
 ```
 
+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.
+
 ### Server Configuration Recommendations
 
 Generate recommended PostgreSQL server configuration entries based on your config file:
@@ -340,6 +358,36 @@ ssl_key_file = 'server.key'
 ssl_ca_file = 'ca.crt'
 ```
 
+### Auditing Live Server Settings
+
+Add `--audit` to connect to the live server and compare current settings against recommendations:
+
+```bash
+pgmonkey pgserverconfig --filepath /path/to/config.yaml --audit
+```
+
+This queries the server's `pg_settings` (read-only) and displays a comparison table:
+
+```
+1) Database type detected: PostgreSQL
+
+2) Server settings audit:
+
+   postgresql.conf:
+
+   Setting          Recommended  Current  Source              Status
+   ────────────────────────────────────────────────────────────────────
+   max_connections   22           100      configuration file  OK
+   ssl               on           on       configuration file  OK
+   ssl_cert_file     server.crt   server.crt  configuration file  OK
+   ssl_key_file      server.key   server.key  configuration file  OK
+   ssl_ca_file       ca.crt       ca.crt      configuration file  OK
+```
+
+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.
+
 ### Importing and Exporting Data
 
 **Import data** from a CSV or text file into a PostgreSQL table:
@@ -493,7 +541,8 @@ pgmonkey handles several production concerns behind the scenes so you don't have
 - **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.
+- **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)
 
@@ -725,7 +774,7 @@ Run the tests:
 pytest
 ```
 
-The test suite uses mocks and covers all connection types, the connection factory, configuration management, code generation, and server config generation.
+The test suite uses mocks and covers all connection types, the connection factory, configuration management, code generation (both pgmonkey and native psycopg), config validation, server config generation, and server settings inspection.
 
 ---
 

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

@@ -20,6 +20,7 @@
    - [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)
    - [Normal (Synchronous) Connection](#normal-synchronous-connection)
@@ -106,10 +107,13 @@ postgresql:
   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)
@@ -120,8 +124,10 @@ postgresql:
   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
@@ -152,12 +158,14 @@ Used by `pool` connection type.
 |-----------|-------------|---------|
 | `min_size` | Minimum number of connections in the pool | `5` |
 | `max_size` | Maximum number of connections in the pool | `20` |
+| `timeout` | Seconds to wait for a connection from the pool before raising an error | `30` |
 | `max_idle` | Seconds a connection can remain idle before being closed | `300` |
 | `max_lifetime` | Seconds a connection can be reused | `3600` |
+| `check_on_checkout` | Validate connections with `SELECT 1` before handing to caller | `false` |
 
 ### Async Settings
 
-Used by `async` connection type. These are applied via SQL `SET` commands when the connection is established.
+Used by `async` and `async_pool` connection types. These are applied via SQL `SET` commands when the connection is established. For `async_pool`, they are applied to each connection via a psycopg_pool `configure` callback.
 
 | Parameter | Description | Example |
 |-----------|-------------|---------|
@@ -168,14 +176,16 @@ Used by `async` connection type. These are applied via SQL `SET` commands when t
 
 ### Async Pool Settings
 
-Used by `async_pool` connection type. Same parameters as pool settings.
+Used by `async_pool` connection type. Same parameters as pool settings. The `async_settings` section (above) is also applied to async pool connections.
 
 | Parameter | Description | Example |
 |-----------|-------------|---------|
 | `min_size` | Minimum connections in the async pool | `5` |
 | `max_size` | Maximum connections in the async pool | `20` |
+| `timeout` | Seconds to wait for a connection from the pool before raising an error | `30` |
 | `max_idle` | Seconds a connection can remain idle | `300` |
 | `max_lifetime` | Seconds a connection can be reused | `3600` |
+| `check_on_checkout` | Validate connections with `SELECT 1` before handing to caller | `false` |
 
 ## Authentication Methods
 
@@ -277,8 +287,16 @@ pgmonkey pgconfig generate-code --filepath /path/to/config.yaml
 
 # Generate code for a specific connection type
 pgmonkey pgconfig generate-code --filepath /path/to/config.yaml --connection-type async_pool
+
+# Generate code using native psycopg/psycopg_pool instead of pgmonkey
+pgmonkey pgconfig generate-code --filepath /path/to/config.yaml --connection-type pool --library psycopg
 ```
 
+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.
+
 ### Server Configuration Recommendations
 
 Generate recommended PostgreSQL server configuration entries based on your config file:
@@ -308,6 +326,36 @@ ssl_key_file = 'server.key'
 ssl_ca_file = 'ca.crt'
 ```
 
+### Auditing Live Server Settings
+
+Add `--audit` to connect to the live server and compare current settings against recommendations:
+
+```bash
+pgmonkey pgserverconfig --filepath /path/to/config.yaml --audit
+```
+
+This queries the server's `pg_settings` (read-only) and displays a comparison table:
+
+```
+1) Database type detected: PostgreSQL
+
+2) Server settings audit:
+
+   postgresql.conf:
+
+   Setting          Recommended  Current  Source              Status
+   ────────────────────────────────────────────────────────────────────
+   max_connections   22           100      configuration file  OK
+   ssl               on           on       configuration file  OK
+   ssl_cert_file     server.crt   server.crt  configuration file  OK
+   ssl_key_file      server.key   server.key  configuration file  OK
+   ssl_ca_file       ca.crt       ca.crt      configuration file  OK
+```
+
+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.
+
 ### Importing and Exporting Data
 
 **Import data** from a CSV or text file into a PostgreSQL table:
@@ -461,7 +509,8 @@ pgmonkey handles several production concerns behind the scenes so you don't have
 - **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.
+- **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)
 
@@ -693,7 +742,7 @@ Run the tests:
 pytest
 ```
 
-The test suite uses mocks and covers all connection types, the connection factory, configuration management, code generation, and server config generation.
+The test suite uses mocks and covers all connection types, the connection factory, configuration management, code generation (both pgmonkey and native psycopg), config validation, server config generation, and server settings inspection.
 
 ---
 

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

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

{pgmonkey-2.1.0 → pgmonkey-2.3.0}/src/pgmonkey/cli/cli_pg_server_config_subparser.py

@@ -9,6 +9,9 @@ def cli_pg_server_config_subparser(subparsers):
 
     pg_server_config_parser.add_argument('--filepath', required=True,
                                          help='Path to the config you want settings generated.')
+    pg_server_config_parser.add_argument('--audit', action='store_true', default=False,
+                                         help='Connect to the server and compare current settings '
+                                              'against recommendations.')
     pg_server_config_parser.set_defaults(func=pg_server_config_create_handler,
                                          pg_server_config_manager=pg_server_config_manager)
 
@@ -16,5 +19,7 @@ def cli_pg_server_config_subparser(subparsers):
 def pg_server_config_create_handler(args):
     pg_server_config_manager = args.pg_server_config_manager
 
-    if args.filepath:
+    if args.audit:
+        pg_server_config_manager.audit_server_config(args.filepath)
+    else:
         pg_server_config_manager.get_server_config(args.filepath)

{pgmonkey-2.1.0 → pgmonkey-2.3.0}/src/pgmonkey/cli/cli_pgconfig_subparser.py

@@ -36,6 +36,10 @@ def cli_pgconfig_subparser(subparsers):
                              help='Path to the configuration file you want to use.')
     code_parser.add_argument('--connection-type', choices=CONNECTION_TYPE_CHOICES, default=None,
                              help='Connection type for generated code. Overrides the value in the config file.')
+    code_parser.add_argument('--library', choices=['pgmonkey', 'psycopg'], default='pgmonkey',
+                             help='Target library for generated code. '
+                                  '"pgmonkey" (default) generates code using pgmonkey. '
+                                  '"psycopg" generates code using psycopg/psycopg_pool directly.')
     code_parser.set_defaults(func=pgconfig_generate_code_handler, pgcodegen_manager=pgcodegen_manager)
 
 
@@ -58,4 +62,5 @@ def pgconfig_test_handler(args):
 def pgconfig_generate_code_handler(args):
     pgcodegen_manager = args.pgcodegen_manager
     connection_type = getattr(args, 'connection_type', None)
-    pgcodegen_manager.generate_connection_code(args.filepath, connection_type)
+    library = getattr(args, 'library', 'pgmonkey')
+    pgcodegen_manager.generate_connection_code(args.filepath, connection_type, library=library)

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

@@ -0,0 +1,66 @@
+postgresql:
+  # 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-2.1.0 → pgmonkey-2.3.0}/src/pgmonkey/connections/postgres/async_connection.py

@@ -1,28 +1,34 @@
-from psycopg import AsyncConnection, OperationalError
+import logging
+from psycopg import AsyncConnection, OperationalError, sql
 from .base_connection import PostgresBaseConnection
 from contextlib import asynccontextmanager
 from typing import Optional
 
+logger = logging.getLogger(__name__)
+
 
 class PGAsyncConnection(PostgresBaseConnection):
     def __init__(self, config, async_settings=None):
         self.config = config
         self.async_settings = async_settings or {}
+        self.autocommit = None
         self.connection: Optional[AsyncConnection] = None
 
     async def connect(self):
         """Establishes an asynchronous database connection."""
         if self.connection is None or self.connection.closed:
-            self.connection = await AsyncConnection.connect(**self.config)
+            self.connection = await AsyncConnection.connect(
+                autocommit=bool(self.autocommit), **self.config
+            )
             await self._apply_async_settings()
 
     async def _apply_async_settings(self):
         """Applies PostgreSQL GUC settings via SET commands after connection is established."""
         for setting, value in self.async_settings.items():
             try:
-                await self.connection.execute(f"SET {setting} = %s", (str(value),))
+                await self.connection.execute(sql.SQL("SET {} = %s").format(sql.Identifier(setting)), (str(value),))
             except Exception as e:
-                print(f"Warning: Could not apply setting '{setting}': {e}")
+                logger.warning("Could not apply setting '%s': %s", setting, e)
 
     async def test_connection(self):
         """Tests the asynchronous database connection."""
@@ -30,11 +36,11 @@ class PGAsyncConnection(PostgresBaseConnection):
             async with self.cursor() as cur:
                 await cur.execute('SELECT 1;')
                 result = await cur.fetchone()
-                print("Async connection successful: ", result)
+                logger.info("Async connection successful: %s", result)
         except OperationalError as e:
-            print(f"Connection failed: {e}")
+            logger.error("Connection failed: %s", e)
         except Exception as e:
-            print(f"An unexpected error occurred: {e}")
+            logger.error("An unexpected error occurred: %s", e)
 
     async def disconnect(self):
         """Closes the asynchronous database connection."""
@@ -55,7 +61,7 @@ class PGAsyncConnection(PostgresBaseConnection):
         """Creates a transaction context on the async connection."""
         if self.connection:
             async with self.connection.transaction():
-                yield
+                yield self
         else:
             raise Exception("No active connection available for transaction")
 
@@ -73,8 +79,10 @@ class PGAsyncConnection(PostgresBaseConnection):
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        if exc_type:
-            await self.rollback()
-        else:
-            await self.commit()
-        await self.disconnect()
+        try:
+            if exc_type:
+                await self.rollback()
+            else:
+                await self.commit()
+        finally:
+            await self.disconnect()

pgmonkey-2.3.0/src/pgmonkey/connections/postgres/async_pool_connection.py

@@ -0,0 +1,143 @@
+import logging
+import warnings
+import contextvars
+from psycopg_pool import AsyncConnectionPool
+from psycopg import conninfo as psycopg_conninfo, sql
+from .base_connection import PostgresBaseConnection
+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):
+        self.config = config
+        self.async_pool_settings = async_pool_settings or {}
+        self.async_settings = async_settings or {}
+        self.pool = None
+        self._pool_conn = contextvars.ContextVar(f'_pool_conn_{id(self)}', default=None)
+        self._pool_conn_ctx = contextvars.ContextVar(f'_pool_ctx_{id(self)}', default=None)
+
+    @staticmethod
+    def construct_conninfo(config):
+        """Constructs a properly escaped connection info string from the config dictionary."""
+        return psycopg_conninfo.make_conninfo(**config)
+
+    async def connect(self):
+        """Initialize the async connection pool."""
+        if self.pool is None:
+            conninfo = self.construct_conninfo(self.config)
+            kwargs = dict(self.async_pool_settings)
+
+            check_on_checkout = kwargs.pop('check_on_checkout', False)
+            if check_on_checkout:
+                async def _check(conn):
+                    await conn.execute("SELECT 1")
+                kwargs['check'] = _check
+
+            if self.async_settings:
+                async_settings = self.async_settings
+                async def _configure(conn):
+                    for setting, value in async_settings.items():
+                        try:
+                            await conn.execute(sql.SQL("SET {} = %s").format(sql.Identifier(setting)), (str(value),))
+                        except Exception as e:
+                            logger.warning("Could not apply setting '%s': %s", setting, e)
+                kwargs['configure'] = _configure
+
+            self.pool = AsyncConnectionPool(conninfo=conninfo, **kwargs)
+            await self.pool.open()
+
+    async def test_connection(self):
+        """Tests a single connection from the async pool."""
+        if not self.pool:
+            await self.connect()
+
+        try:
+            async with self.pool.connection() as conn:
+                async with conn.cursor() as cur:
+                    await cur.execute('SELECT 1;')
+                    result = await cur.fetchone()
+                    logger.info("Async pool connection successful: %s", result)
+        except Exception as e:
+            logger.error("Test connection failed: %s", e)
+
+    async def disconnect(self):
+        if self.pool:
+            await self.pool.close()
+            self.pool = None
+
+    async def commit(self):
+        """Commits the current transaction on the acquired connection."""
+        conn = self._pool_conn.get()
+        if conn:
+            await conn.commit()
+
+    async def rollback(self):
+        """Rolls back the current transaction on the acquired connection."""
+        conn = self._pool_conn.get()
+        if conn:
+            await conn.rollback()
+
+    @asynccontextmanager
+    async def transaction(self):
+        """Creates a transaction context on a pooled connection."""
+        conn = self._pool_conn.get()
+        if conn:
+            # Inside __aenter__/__aexit__ context - use the acquired connection
+            async with conn.transaction():
+                yield self
+        elif self.pool:
+            # Standalone usage - acquire connection from pool
+            async with self.pool.connection() as acquired:
+                token = self._pool_conn.set(acquired)
+                try:
+                    async with acquired.transaction():
+                        yield self
+                finally:
+                    self._pool_conn.reset(token)
+        else:
+            raise Exception("No active pool available for transaction")
+
+    @asynccontextmanager
+    async def cursor(self):
+        """Provides an async cursor from a pooled connection."""
+        conn = self._pool_conn.get()
+        if conn:
+            # Inside __aenter__/__aexit__ context - use the acquired connection
+            async with conn.cursor() as cur:
+                yield cur
+        elif self.pool:
+            # Standalone usage - acquire connection from pool
+            async with self.pool.connection() as acquired:
+                async with acquired.cursor() as cur:
+                    yield cur
+        else:
+            raise Exception("No active pool available for cursor")
+
+    async def __aenter__(self):
+        if not self.pool:
+            await self.connect()
+        pool_conn_ctx = self.pool.connection()
+        conn = await pool_conn_ctx.__aenter__()
+        self._pool_conn.set(conn)
+        self._pool_conn_ctx.set(pool_conn_ctx)
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        try:
+            conn = self._pool_conn.get()
+            if exc_type:
+                if conn:
+                    await conn.rollback()
+            else:
+                if conn:
+                    await conn.commit()
+        finally:
+            pool_conn_ctx = self._pool_conn_ctx.get()
+            if pool_conn_ctx:
+                await pool_conn_ctx.__aexit__(exc_type, exc_val, exc_tb)
+            self._pool_conn.set(None)
+            self._pool_conn_ctx.set(None)