From 5175301a8f223b31ed623f9ce26ebac2d5e1fa8e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Sep 2025 16:09:01 +0000
Subject: [PATCH 1/8] Initial plan


From d7fcf730c8a110f882d38990a89f9053cea0cdd1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Sep 2025 16:16:25 +0000
Subject: [PATCH 2/8] Implement AsyncMemDBConnector with full async support

Co-authored-by: faizanazim11 <20454506+faizanazim11@users.noreply.github.com>
---
 src/mem_db_utils/__init__.py    |  54 ++++++++++
 tests/test_async_connector.py   | 177 ++++++++++++++++++++++++++++++++
 tests/test_async_integration.py | 173 +++++++++++++++++++++++++++++++
 3 files changed, 404 insertions(+)
 create mode 100644 tests/test_async_connector.py
 create mode 100644 tests/test_async_integration.py

diff --git a/src/mem_db_utils/__init__.py b/src/mem_db_utils/__init__.py
index d6f3f97..de22fa8 100644
--- a/src/mem_db_utils/__init__.py
+++ b/src/mem_db_utils/__init__.py
@@ -1,6 +1,7 @@
 from urllib.parse import urlparse
 
 import redis
+import redis.asyncio as aioredis
 
 from mem_db_utils.config import DBConfig, DBType
 
@@ -53,3 +54,56 @@ def _sentinel(self, db: int, **kwargs):
         connection_object = sentinel.master_for(self.service, decode_responses=kwargs.get("decode_response", True))
         connection_object.select(db)
         return connection_object
+
+
+class AsyncMemDBConnector:
+    __slots__ = ("uri", "db_type", "connection_type", "service")
+
+    def __init__(self, redis_type: str = None, master_service: str = None):
+        self.uri = DBConfig.db_url
+        self.db_type = DBConfig.db_type
+        self.service = None
+        self.connection_type = None
+        if self.db_type == DBType.REDIS:
+            self.connection_type = redis_type or DBConfig.redis_connection_type
+            self.service = master_service or DBConfig.redis_master_service
+
+    async def connect(self, db: int = 0, **kwargs):
+        """
+        The async connect function is used to connect to a MemDB instance asynchronously.
+
+        :param self: Represent the instance of the class
+        :param db: int: Specify the database number to connect to
+        :return: An async connection object
+        """
+        if self.connection_type == "sentinel":
+            return await self._sentinel(db=db, **kwargs)
+        return await aioredis.from_url(url=self.uri, db=db, decode_responses=kwargs.get("decode_response", True))
+
+    async def _sentinel(self, db: int, **kwargs):
+        """
+        The async _sentinel function is used to connect to a Redis Sentinel service asynchronously.
+
+        :param self: Bind the method to an instance of the class
+        :param db: int: Select the database to connect to
+        :return: An async connection object
+        """
+        parsed_uri = urlparse(self.uri)
+        sentinel_host = parsed_uri.hostname
+        sentinel_port = parsed_uri.port
+        redis_password = parsed_uri.password
+        sentinel_hosts = [(sentinel_host, sentinel_port)]
+
+        sentinel = aioredis.Sentinel(
+            sentinel_hosts,
+            socket_timeout=kwargs.get("timeout", DBConfig.db_timeout),
+            password=redis_password,
+        )
+
+        # Connect to the Redis Sentinel master service and select the specified database
+        connection_object = sentinel.master_for(self.service, decode_responses=kwargs.get("decode_response", True))
+        await connection_object.select(db)
+        return connection_object
+
+
+__all__ = ["MemDBConnector", "AsyncMemDBConnector"]
diff --git a/tests/test_async_connector.py b/tests/test_async_connector.py
new file mode 100644
index 0000000..be28913
--- /dev/null
+++ b/tests/test_async_connector.py
@@ -0,0 +1,177 @@
+"""Tests for AsyncMemDBConnector class."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+from urllib.parse import urlparse
+
+import pytest
+
+from mem_db_utils import AsyncMemDBConnector
+from mem_db_utils.config import DBConfig, DBType
+
+
+class TestAsyncMemDBConnector:
+    """Test the AsyncMemDBConnector class."""
+
+    def test_init_with_defaults(self):
+        """Test initialization with default values from .env file."""
+        connector = AsyncMemDBConnector()
+        assert connector.uri == DBConfig.db_url
+        assert connector.db_type == DBConfig.db_type
+
+        # For Redis databases
+        if connector.db_type == DBType.REDIS:
+            assert connector.connection_type == DBConfig.redis_connection_type
+            assert connector.service == DBConfig.redis_master_service
+        else:
+            # For non-Redis databases, these should be None
+            assert connector.connection_type is None
+            assert connector.service is None
+
+    def test_init_with_redis_type_override(self):
+        """Test initialization with Redis connection type override."""
+        connector = AsyncMemDBConnector(redis_type="sentinel")
+        assert connector.uri == DBConfig.db_url
+        assert connector.db_type == DBConfig.db_type
+
+        if connector.db_type == DBType.REDIS:
+            assert connector.connection_type == "sentinel"
+            assert connector.service == DBConfig.redis_master_service
+
+    def test_init_with_master_service_override(self):
+        """Test initialization with master service override."""
+        connector = AsyncMemDBConnector(master_service="custom_master")
+        assert connector.uri == DBConfig.db_url
+        assert connector.db_type == DBConfig.db_type
+
+        if connector.db_type == DBType.REDIS:
+            assert connector.connection_type == DBConfig.redis_connection_type
+            assert connector.service == "custom_master"
+
+    @pytest.mark.asyncio
+    @patch("redis.asyncio.from_url")
+    async def test_connect_direct_connection(self, mock_from_url):
+        """Test direct async database connection."""
+        mock_connection = AsyncMock()
+        # Mock from_url to return a coroutine
+        async def mock_coro():
+            return mock_connection
+        mock_from_url.return_value = mock_coro()
+
+        connector = AsyncMemDBConnector()
+        # Only test direct connection if not using sentinel
+        if connector.connection_type != "sentinel":
+            result = await connector.connect(db=1)
+
+            mock_from_url.assert_called_once_with(url=DBConfig.db_url, db=1, decode_responses=True)
+            assert result == mock_connection
+
+    @pytest.mark.asyncio
+    @patch("redis.asyncio.from_url")
+    async def test_connect_with_custom_kwargs(self, mock_from_url):
+        """Test async connection with custom keyword arguments."""
+        mock_connection = AsyncMock()
+        # Mock from_url to return a coroutine
+        async def mock_coro():
+            return mock_connection
+        mock_from_url.return_value = mock_coro()
+
+        connector = AsyncMemDBConnector()
+        if connector.connection_type != "sentinel":
+            result = await connector.connect(db=2, decode_response=False)
+
+            mock_from_url.assert_called_once_with(url=DBConfig.db_url, db=2, decode_responses=False)
+            assert result == mock_connection
+
+    @pytest.mark.asyncio
+    @patch("redis.asyncio.Sentinel")
+    async def test_connect_sentinel(self, mock_sentinel_class):
+        """Test async Redis Sentinel connection when configured."""
+        mock_sentinel = AsyncMock()
+        mock_master = AsyncMock()
+        mock_master.select = AsyncMock()
+        mock_sentinel.master_for.return_value = mock_master
+        mock_sentinel_class.return_value = mock_sentinel
+
+        connector = AsyncMemDBConnector()
+        if connector.connection_type == "sentinel" and connector.db_type == DBType.REDIS:
+            result = await connector.connect(db=3)
+
+            # Verify Sentinel was created with correct parameters
+            parsed_uri = urlparse(DBConfig.db_url)
+            expected_hosts = [(parsed_uri.hostname, parsed_uri.port)]
+
+            mock_sentinel_class.assert_called_once_with(
+                expected_hosts, socket_timeout=DBConfig.db_timeout, password=parsed_uri.password
+            )
+
+            # Verify master connection was requested
+            mock_sentinel.master_for.assert_called_once_with(DBConfig.redis_master_service, decode_responses=True)
+
+            # Verify database selection
+            mock_master.select.assert_called_once_with(3)
+            assert result == mock_master
+
+    @pytest.mark.asyncio
+    @patch("redis.asyncio.from_url")
+    async def test_connect_default_db(self, mock_from_url):
+        """Test async connection with default database (0)."""
+        mock_connection = AsyncMock()
+        # Mock from_url to return a coroutine
+        async def mock_coro():
+            return mock_connection
+        mock_from_url.return_value = mock_coro()
+
+        connector = AsyncMemDBConnector()
+        if connector.connection_type != "sentinel":
+            result = await connector.connect()  # No db parameter
+
+            mock_from_url.assert_called_once_with(
+                url=DBConfig.db_url,
+                db=0,  # Default value
+                decode_responses=True,
+            )
+            assert result == mock_connection
+
+    def test_slots_attribute(self):
+        """Test that the class uses __slots__ for memory efficiency."""
+        connector = AsyncMemDBConnector()
+
+        # Check that __slots__ is defined
+        assert hasattr(AsyncMemDBConnector, "__slots__")
+        expected_slots = ("uri", "db_type", "connection_type", "service")
+        assert AsyncMemDBConnector.__slots__ == expected_slots
+
+        # Verify we can't add arbitrary attributes
+        with pytest.raises(AttributeError):
+            connector.new_attribute = "test"
+
+    def test_non_redis_db_type_behavior(self):
+        """Test async connector behavior with non-Redis database types."""
+        connector = AsyncMemDBConnector()
+        if connector.db_type != DBType.REDIS:
+            # For non-Redis databases, connection_type and service should be None
+            assert connector.connection_type is None
+            assert connector.service is None
+
+    @pytest.mark.asyncio
+    async def test_error_handling_in_connect(self):
+        """Test error handling in async connect method."""
+        with patch("redis.asyncio.from_url") as mock_from_url:
+            mock_from_url.side_effect = Exception("Connection failed")
+            
+            connector = AsyncMemDBConnector()
+            if connector.connection_type != "sentinel":
+                with pytest.raises(Exception, match="Connection failed"):
+                    await connector.connect()
+
+    @pytest.mark.asyncio
+    async def test_error_handling_in_sentinel(self):
+        """Test error handling in async sentinel method."""
+        with patch("redis.asyncio.Sentinel") as mock_sentinel_class:
+            mock_sentinel_class.side_effect = Exception("Sentinel connection failed")
+            
+            connector = AsyncMemDBConnector(redis_type="sentinel")
+            if connector.db_type == DBType.REDIS:
+                with pytest.raises(Exception, match="Sentinel connection failed"):
+                    await connector.connect()
\ No newline at end of file
diff --git a/tests/test_async_integration.py b/tests/test_async_integration.py
new file mode 100644
index 0000000..06ddd83
--- /dev/null
+++ b/tests/test_async_integration.py
@@ -0,0 +1,173 @@
+"""Integration tests for AsyncMemDBConnector with real database connections.
+
+These tests use the database configuration from the .env file.
+The tests will work with Redis databases only as async support is primarily for Redis.
+"""
+
+import asyncio
+
+import pytest
+
+from mem_db_utils import AsyncMemDBConnector
+from mem_db_utils.config import DBConfig, DBType
+
+
+class TestAsyncMemDBConnectorIntegration:
+    """Integration tests with real async database connections."""
+
+    @pytest.mark.asyncio
+    async def test_async_database_connection(self):
+        """Test async connection to the configured database."""
+        connector = AsyncMemDBConnector()
+
+        try:
+            conn = await connector.connect(db=0)
+            # Test basic operations - works for Redis-compatible databases
+            if connector.db_type in [DBType.REDIS, DBType.DRAGONFLY, DBType.VALKEY]:
+                result = await conn.ping()
+                assert result is True
+
+                # Test set/get operations
+                await conn.set("test_async_key", "test_async_value")
+                value = await conn.get("test_async_key")
+                assert value == "test_async_value"
+
+                # Cleanup
+                await conn.delete("test_async_key")
+                
+                # Close the connection
+                await conn.aclose()
+            else:
+                # For other database types, just verify connection exists
+                assert conn is not None
+
+        except Exception as e:
+            pytest.skip(f"Database not available at {DBConfig.db_url}: {e}")
+
+    @pytest.mark.asyncio
+    async def test_async_database_with_different_db_number(self):
+        """Test async connection with different database number (Redis-compatible only)."""
+        connector = AsyncMemDBConnector()
+
+        # Only test for Redis-compatible databases that support db selection
+        if connector.db_type not in [DBType.REDIS, DBType.DRAGONFLY, DBType.VALKEY]:
+            pytest.skip(f"Database selection not supported for {connector.db_type}")
+
+        try:
+            conn = await connector.connect(db=1)
+            result = await conn.ping()
+            assert result is True
+            await conn.aclose()
+
+        except Exception as e:
+            pytest.skip(f"Database not available at {DBConfig.db_url}: {e}")
+
+    @pytest.mark.asyncio
+    async def test_async_auto_type_detection(self):
+        """Test automatic type detection from URL in async context."""
+        connector = AsyncMemDBConnector()
+        assert connector.db_type == DBConfig.db_type
+        assert connector.uri == DBConfig.db_url
+
+    @pytest.mark.asyncio
+    async def test_async_connection_with_decode_responses_false(self):
+        """Test async connection with decode_responses=False (Redis-compatible only)."""
+        connector = AsyncMemDBConnector()
+
+        # Only test for Redis-compatible databases
+        if connector.db_type not in [DBType.REDIS, DBType.DRAGONFLY, DBType.VALKEY]:
+            pytest.skip(f"decode_responses not supported for {connector.db_type}")
+
+        try:
+            conn = await connector.connect(db=0, decode_response=False)
+            result = await conn.ping()
+            assert result is True
+            await conn.aclose()
+
+        except Exception as e:
+            pytest.skip(f"Database not available at {DBConfig.db_url}: {e}")
+
+    @pytest.mark.asyncio
+    async def test_async_connection_timeout_configuration(self):
+        """Test async connection with configured timeout."""
+        connector = AsyncMemDBConnector()
+
+        try:
+            # This should work with the configured timeout
+            conn = await connector.connect(db=0)
+            if connector.db_type in [DBType.REDIS, DBType.DRAGONFLY, DBType.VALKEY]:
+                result = await conn.ping()
+                assert result is True
+                await conn.aclose()
+            else:
+                assert conn is not None
+
+        except Exception as e:
+            pytest.skip(f"Database not available at {DBConfig.db_url}: {e}")
+
+    @pytest.mark.skip(reason="Requires Redis Sentinel setup")
+    @pytest.mark.asyncio
+    async def test_async_sentinel_connection_integration(self):
+        """Test async Redis Sentinel connection (requires Sentinel setup)."""
+        connector = AsyncMemDBConnector()
+
+        if connector.db_type != DBType.REDIS or connector.connection_type != "sentinel":
+            pytest.skip("Test requires Redis Sentinel configuration")
+
+        try:
+            conn = await connector.connect(db=0)
+            result = await conn.ping()
+            assert result is True
+            await conn.aclose()
+
+        except Exception as e:
+            pytest.skip(f"Redis Sentinel not available: {e}")
+
+    @pytest.mark.asyncio
+    async def test_async_error_handling_with_invalid_db_number(self):
+        """Test async error handling with invalid database number."""
+        connector = AsyncMemDBConnector()
+
+        # Only test for Redis-compatible databases that support db selection
+        if connector.db_type not in [DBType.REDIS, DBType.DRAGONFLY, DBType.VALKEY]:
+            pytest.skip(f"Database selection not supported for {connector.db_type}")
+
+        try:
+            # Try to connect to a very high database number that likely doesn't exist
+            with pytest.raises(Exception):  # noqa
+                conn = await connector.connect(db=999)
+                await conn.ping()
+        except Exception as e:
+            pytest.skip(f"Database not available for error testing: {e}")
+
+    @pytest.mark.asyncio
+    async def test_async_concurrent_connections(self):
+        """Test multiple concurrent async connections."""
+        connector = AsyncMemDBConnector()
+
+        if connector.db_type not in [DBType.REDIS, DBType.DRAGONFLY, DBType.VALKEY]:
+            pytest.skip(f"Concurrent connections test not supported for {connector.db_type}")
+
+        async def test_connection(conn_id):
+            try:
+                conn = await connector.connect(db=0)
+                await conn.set(f"async_test_key_{conn_id}", f"value_{conn_id}")
+                value = await conn.get(f"async_test_key_{conn_id}")
+                assert value == f"value_{conn_id}"
+                await conn.delete(f"async_test_key_{conn_id}")
+                await conn.aclose()
+                return True
+            except Exception:
+                return False
+
+        try:
+            # Test 3 concurrent connections
+            tasks = [test_connection(i) for i in range(3)]
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            
+            # At least some connections should succeed
+            success_count = sum(1 for r in results if r is True)
+            assert success_count > 0
+
+        except Exception as e:
+            pytest.skip(f"Database not available for concurrent testing: {e}")
\ No newline at end of file

From 5703b55dccd05d877682465cabd9752112725e41 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Sep 2025 16:18:08 +0000
Subject: [PATCH 3/8] Fix code style and finalize async implementation

Co-authored-by: faizanazim11 <20454506+faizanazim11@users.noreply.github.com>
---
 tests/test_async_connector.py   | 9 ++++-----
 tests/test_async_integration.py | 6 +++---
 2 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/tests/test_async_connector.py b/tests/test_async_connector.py
index be28913..98405b0 100644
--- a/tests/test_async_connector.py
+++ b/tests/test_async_connector.py
@@ -1,7 +1,6 @@
 """Tests for AsyncMemDBConnector class."""
 
-import asyncio
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, patch
 from urllib.parse import urlparse
 
 import pytest
@@ -159,7 +158,7 @@ async def test_error_handling_in_connect(self):
         """Test error handling in async connect method."""
         with patch("redis.asyncio.from_url") as mock_from_url:
             mock_from_url.side_effect = Exception("Connection failed")
-            
+
             connector = AsyncMemDBConnector()
             if connector.connection_type != "sentinel":
                 with pytest.raises(Exception, match="Connection failed"):
@@ -170,8 +169,8 @@ async def test_error_handling_in_sentinel(self):
         """Test error handling in async sentinel method."""
         with patch("redis.asyncio.Sentinel") as mock_sentinel_class:
             mock_sentinel_class.side_effect = Exception("Sentinel connection failed")
-            
+
             connector = AsyncMemDBConnector(redis_type="sentinel")
             if connector.db_type == DBType.REDIS:
                 with pytest.raises(Exception, match="Sentinel connection failed"):
-                    await connector.connect()
\ No newline at end of file
+                    await connector.connect()
diff --git a/tests/test_async_integration.py b/tests/test_async_integration.py
index 06ddd83..8a2a58f 100644
--- a/tests/test_async_integration.py
+++ b/tests/test_async_integration.py
@@ -34,7 +34,7 @@ async def test_async_database_connection(self):
 
                 # Cleanup
                 await conn.delete("test_async_key")
-                
+
                 # Close the connection
                 await conn.aclose()
             else:
@@ -164,10 +164,10 @@ async def test_connection(conn_id):
             # Test 3 concurrent connections
             tasks = [test_connection(i) for i in range(3)]
             results = await asyncio.gather(*tasks, return_exceptions=True)
-            
+
             # At least some connections should succeed
             success_count = sum(1 for r in results if r is True)
             assert success_count > 0
 
         except Exception as e:
-            pytest.skip(f"Database not available for concurrent testing: {e}")
\ No newline at end of file
+            pytest.skip(f"Database not available for concurrent testing: {e}")

From cdd9dbb3ed26c68077b793e1a53b2221389371f5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Sep 2025 16:23:53 +0000
Subject: [PATCH 4/8] Complete GitHub Copilot instructions with validated
 commands and scenarios

Co-authored-by: faizanazim11 <20454506+faizanazim11@users.noreply.github.com>
---
 .github/copilot-instructions.md | 155 ++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..2ab6989
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,155 @@
+# mem-db-utils - GitHub Copilot Instructions
+
+**Python package for in-memory database utilities supporting Redis, Memcached, Dragonfly, and Valkey.**
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap, Build, and Test Repository:
+- `pip install -e .` -- installs the package in development mode. NEVER CANCEL: Takes 10-60 seconds, may timeout due to network issues. Set timeout to 120+ seconds.
+- `pip install coverage pre-commit pytest pytest-cov pytest-dotenv ruff` -- installs development dependencies. NEVER CANCEL: Takes 30-120 seconds. Set timeout to 180+ seconds.
+- `python -m pytest tests/ -v` -- runs unit tests (takes ~0.4 seconds, 20 passed, 5 skipped without database)
+- `ruff check .` -- runs linting (takes ~0.01 seconds)  
+- `ruff format --check .` -- checks code formatting (takes ~0.01 seconds)
+
+### Environment Configuration:
+- Create `.env` file with `DB_URL=redis://localhost:6379/0` for basic testing
+- Package requires `DB_URL` environment variable to be set at runtime
+- Supported database URLs: `redis://`, `memcached://`, `dragonfly://`, `valkey://`
+- Optional environment variables: `DB_TYPE`, `REDIS_CONNECTION_TYPE`, `REDIS_MASTER_SERVICE`, `DB_TIMEOUT`
+
+### Run Integration Tests with Real Database:
+- Start Redis: `docker run -d --name test-redis -p 6379:6379 redis:7-alpine` (NEVER CANCEL: Takes 30-60 seconds for first download)
+- Wait for startup: `sleep 5`
+- Run integration tests: `DB_URL=redis://localhost:6379/0 python -m pytest tests/test_integration.py -v` (takes ~0.4 seconds, 1 may fail on error handling test)
+- Clean up: `docker stop test-redis && docker rm test-redis`
+
+## Validation Scenarios
+
+### Always Test After Making Changes:
+1. **Import Test**: `DB_URL=redis://localhost:6379/0 python -c "from mem_db_utils import MemDBConnector; print('Import successful')"`
+2. **Basic Functionality Test** (requires Redis running):
+   ```bash
+   DB_URL=redis://localhost:6379/0 python -c "
+   from mem_db_utils import MemDBConnector
+   conn = MemDBConnector().connect(db=0)
+   conn.ping()
+   conn.set('test', 'value')
+   assert conn.get('test') == 'value'
+   conn.delete('test')
+   print('Validation PASSED')
+   "
+   ```
+3. **Run Full Test Suite**: `python -m pytest tests/ -v --cov=src --cov-report=term-missing`
+4. **Linting**: `ruff check . && ruff format --check .`
+
+### Manual Testing Requirements:
+- ALWAYS test basic database connection and operations after code changes
+- Test with different database types by changing DB_URL protocol
+- Verify configuration loading works with various environment variable combinations
+- Test error handling with invalid database URLs or unreachable servers
+
+## Common Tasks
+
+### Repository Structure:
+```
+mem-db-utils/
+├── .github/workflows/     # CI/CD pipelines
+├── src/mem_db_utils/     # Main package source
+│   ├── __init__.py       # MemDBConnector class
+│   ├── config.py         # Environment configuration
+│   └── py.typed          # Type hints marker
+├── tests/                # Test files
+├── pyproject.toml        # Project configuration
+└── README.md            # Documentation
+```
+
+### Key Files to Check After Changes:
+- Always verify `src/mem_db_utils/__init__.py` after changing MemDBConnector logic
+- Check `src/mem_db_utils/config.py` after modifying configuration handling
+- Update tests in `tests/` when adding new functionality
+- Run integration tests in `tests/test_integration.py` with real database
+
+### Development Dependencies:
+- **Testing**: pytest, pytest-cov, pytest-dotenv, coverage
+- **Linting**: ruff (replaces black, flake8, isort)
+- **Git hooks**: pre-commit
+- **Type checking**: Built into package with py.typed marker
+
+### Build and Package:
+- `python -m build` -- builds distribution packages. NEVER CANCEL: May fail due to network timeouts with uv_build backend and custom PyPI index. Consider this command unreliable in constrained network environments.
+- Package metadata in `pyproject.toml`
+- Uses standard Python packaging with uv_build backend (requires network access to custom PyPI index)
+- **Note**: Package installation works fine, but building from source may be problematic due to external dependencies
+
+## Database Types and Testing
+
+### Supported Database Types:
+- **Redis**: `redis://localhost:6379/0` (most common, full functionality)
+- **Memcached**: `memcached://localhost:11211` (basic key-value operations)
+- **Dragonfly**: `dragonfly://localhost:6380` (Redis-compatible)
+- **Valkey**: `valkey://localhost:6381` (Redis-compatible)
+
+### Database-Specific Testing:
+- **Redis/Dragonfly/Valkey**: Support database selection (`db` parameter), ping, set/get/delete
+- **Memcached**: Basic connection only, no database selection
+- **Redis Sentinel**: Requires `REDIS_CONNECTION_TYPE=sentinel` and `REDIS_MASTER_SERVICE` environment variables
+
+### Setting up Test Databases with Docker:
+- Redis: `docker run -d --name test-redis -p 6379:6379 redis:7-alpine`
+- Memcached: `docker run -d --name test-memcached -p 11211:11211 memcached:1.6-alpine`
+- Dragonfly: `docker run -d --name test-dragonfly -p 6380:6380 docker.dragonflydb.io/dragonflydb/dragonfly`
+
+## CI/CD Pipeline (.github/workflows)
+
+### Linter Pipeline (linter.yaml):
+- Runs on pull requests
+- Uses `chartboost/ruff-action@v1` for linting and format checking
+- ALWAYS run `ruff check .` and `ruff format --check .` before committing
+
+### Package Publishing (publish_package.yaml):
+- Triggers on git tags
+- Builds with `python -m build`
+- Publishes to PyPI
+- Creates GitHub releases with sigstore signatures
+
+## Critical Notes
+
+### Environment Variable Loading:
+- Package uses `pydantic-settings` with `python-dotenv` integration
+- Environment variables are loaded from `.env` files automatically
+- Configuration is validated at import time, not lazily
+- Missing `DB_URL` will cause import failure with ValidationError
+
+### Error Handling:
+- Import failures occur when `DB_URL` is missing or invalid protocol
+- Connection failures in integration tests are skipped (pytest.skip)
+- Invalid database numbers may or may not raise exceptions depending on database type
+
+### Memory and Performance:
+- MemDBConnector uses `__slots__` for memory efficiency
+- Connection objects are created per call to `connect()`
+- No connection pooling implemented in base connector
+- Timeouts configurable via `DB_TIMEOUT` environment variable (default: 30 seconds)
+
+## Troubleshooting
+
+### Common Issues:
+1. **Import Error**: Ensure `DB_URL` environment variable is set
+2. **Test Failures**: Start appropriate database container first
+3. **Linting Failures**: Run `ruff format .` to auto-fix formatting issues
+4. **Missing Dependencies**: Run `pip install -e .` to reinstall package
+5. **Network Timeouts**: Package uses custom PyPI index (pypi.prismatica.in) which may be unreachable. pip install and python -m build commands may timeout.
+
+### Network Dependencies:
+- Package depends on custom PyPI index at pypi.prismatica.in
+- Build commands may fail with network timeouts in restricted environments
+- Runtime functionality works fine once dependencies are installed
+- Consider using pre-installed environments or alternative package sources if network issues persist
+
+### Database Connection Issues:
+- Check if database container is running: `docker ps`
+- Test connection manually: `docker exec -it test-redis redis-cli ping`
+- Verify port availability: `netstat -tlnp | grep 6379`
+- Check firewall settings if running on remote host
\ No newline at end of file

From 827fb7f3c39a70b45b3c50cadae3b4e889c243e3 Mon Sep 17 00:00:00 2001
From: Faizan Azim <faizanazim11@gmail.com>
Date: Wed, 17 Sep 2025 22:01:29 +0530
Subject: [PATCH 5/8] Update .github/copilot-instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .github/copilot-instructions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 2ab6989..5266730 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -7,8 +7,8 @@ Always reference these instructions first and fallback to search or bash command
 ## Working Effectively
 
 ### Bootstrap, Build, and Test Repository:
-- `pip install -e .` -- installs the package in development mode. NEVER CANCEL: Takes 10-60 seconds, may timeout due to network issues. Set timeout to 120+ seconds.
-- `pip install coverage pre-commit pytest pytest-cov pytest-dotenv ruff` -- installs development dependencies. NEVER CANCEL: Takes 30-120 seconds. Set timeout to 180+ seconds.
+- `pip install -e .` -- installs the package in development mode. NEVER CANCEL: Takes 10-60 seconds, may timeout due to network issues. Set timeout to 120+ seconds (extra margin for slow mirrors or network issues).
+- `pip install coverage pre-commit pytest pytest-cov pytest-dotenv ruff` -- installs development dependencies. NEVER CANCEL: Takes 30-120 seconds. Set timeout to 180+ seconds (extra margin for slow mirrors or network issues).
 - `python -m pytest tests/ -v` -- runs unit tests (takes ~0.4 seconds, 20 passed, 5 skipped without database)
 - `ruff check .` -- runs linting (takes ~0.01 seconds)  
 - `ruff format --check .` -- checks code formatting (takes ~0.01 seconds)

From f207ef292139889a565b04aa0a8436b748bbb8db Mon Sep 17 00:00:00 2001
From: Faizan Azim <faizanazim11@gmail.com>
Date: Wed, 17 Sep 2025 22:01:40 +0530
Subject: [PATCH 6/8] Update .github/copilot-instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .github/copilot-instructions.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 5266730..72d43e8 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -78,9 +78,9 @@ mem-db-utils/
 - **Type checking**: Built into package with py.typed marker
 
 ### Build and Package:
-- `python -m build` -- builds distribution packages. NEVER CANCEL: May fail due to network timeouts with uv_build backend and custom PyPI index. Consider this command unreliable in constrained network environments.
+- `python -m build` -- builds distribution packages. NEVER CANCEL: May fail due to network timeouts depending on the configured build backend and network environment (see `pyproject.toml` for the backend in use). Consider this command unreliable in constrained network environments.
 - Package metadata in `pyproject.toml`
-- Uses standard Python packaging with uv_build backend (requires network access to custom PyPI index)
+- Uses standard Python packaging; the build backend is specified in `pyproject.toml` (may require network access to a custom PyPI index depending on backend).
 - **Note**: Package installation works fine, but building from source may be problematic due to external dependencies
 
 ## Database Types and Testing

From 36f586371ae0a0b52a3c232068c9297ca9dabd70 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 17 Sep 2025 17:00:43 +0000
Subject: [PATCH 7/8] Restructure async implementation to use asyncio submodule

Co-authored-by: faizanazim11 <20454506+faizanazim11@users.noreply.github.com>
---
 src/mem_db_utils/__init__.py         | 54 --------------------------
 src/mem_db_utils/asyncio/__init__.py | 58 ++++++++++++++++++++++++++++
 tests/test_async_connector.py        |  4 +-
 tests/test_async_integration.py      |  4 +-
 4 files changed, 62 insertions(+), 58 deletions(-)
 create mode 100644 src/mem_db_utils/asyncio/__init__.py

diff --git a/src/mem_db_utils/__init__.py b/src/mem_db_utils/__init__.py
index de22fa8..d6f3f97 100644
--- a/src/mem_db_utils/__init__.py
+++ b/src/mem_db_utils/__init__.py
@@ -1,7 +1,6 @@
 from urllib.parse import urlparse
 
 import redis
-import redis.asyncio as aioredis
 
 from mem_db_utils.config import DBConfig, DBType
 
@@ -54,56 +53,3 @@ def _sentinel(self, db: int, **kwargs):
         connection_object = sentinel.master_for(self.service, decode_responses=kwargs.get("decode_response", True))
         connection_object.select(db)
         return connection_object
-
-
-class AsyncMemDBConnector:
-    __slots__ = ("uri", "db_type", "connection_type", "service")
-
-    def __init__(self, redis_type: str = None, master_service: str = None):
-        self.uri = DBConfig.db_url
-        self.db_type = DBConfig.db_type
-        self.service = None
-        self.connection_type = None
-        if self.db_type == DBType.REDIS:
-            self.connection_type = redis_type or DBConfig.redis_connection_type
-            self.service = master_service or DBConfig.redis_master_service
-
-    async def connect(self, db: int = 0, **kwargs):
-        """
-        The async connect function is used to connect to a MemDB instance asynchronously.
-
-        :param self: Represent the instance of the class
-        :param db: int: Specify the database number to connect to
-        :return: An async connection object
-        """
-        if self.connection_type == "sentinel":
-            return await self._sentinel(db=db, **kwargs)
-        return await aioredis.from_url(url=self.uri, db=db, decode_responses=kwargs.get("decode_response", True))
-
-    async def _sentinel(self, db: int, **kwargs):
-        """
-        The async _sentinel function is used to connect to a Redis Sentinel service asynchronously.
-
-        :param self: Bind the method to an instance of the class
-        :param db: int: Select the database to connect to
-        :return: An async connection object
-        """
-        parsed_uri = urlparse(self.uri)
-        sentinel_host = parsed_uri.hostname
-        sentinel_port = parsed_uri.port
-        redis_password = parsed_uri.password
-        sentinel_hosts = [(sentinel_host, sentinel_port)]
-
-        sentinel = aioredis.Sentinel(
-            sentinel_hosts,
-            socket_timeout=kwargs.get("timeout", DBConfig.db_timeout),
-            password=redis_password,
-        )
-
-        # Connect to the Redis Sentinel master service and select the specified database
-        connection_object = sentinel.master_for(self.service, decode_responses=kwargs.get("decode_response", True))
-        await connection_object.select(db)
-        return connection_object
-
-
-__all__ = ["MemDBConnector", "AsyncMemDBConnector"]
diff --git a/src/mem_db_utils/asyncio/__init__.py b/src/mem_db_utils/asyncio/__init__.py
new file mode 100644
index 0000000..2301ca1
--- /dev/null
+++ b/src/mem_db_utils/asyncio/__init__.py
@@ -0,0 +1,58 @@
+from urllib.parse import urlparse
+
+import redis.asyncio as aioredis
+
+from mem_db_utils.config import DBConfig, DBType
+
+
+class MemDBConnector:
+    __slots__ = ("uri", "db_type", "connection_type", "service")
+
+    def __init__(self, redis_type: str = None, master_service: str = None):
+        self.uri = DBConfig.db_url
+        self.db_type = DBConfig.db_type
+        self.service = None
+        self.connection_type = None
+        if self.db_type == DBType.REDIS:
+            self.connection_type = redis_type or DBConfig.redis_connection_type
+            self.service = master_service or DBConfig.redis_master_service
+
+    async def connect(self, db: int = 0, **kwargs):
+        """
+        The async connect function is used to connect to a MemDB instance asynchronously.
+
+        :param self: Represent the instance of the class
+        :param db: int: Specify the database number to connect to
+        :return: An async connection object
+        """
+        if self.connection_type == "sentinel":
+            return await self._sentinel(db=db, **kwargs)
+        return await aioredis.from_url(url=self.uri, db=db, decode_responses=kwargs.get("decode_response", True))
+
+    async def _sentinel(self, db: int, **kwargs):
+        """
+        The async _sentinel function is used to connect to a Redis Sentinel service asynchronously.
+
+        :param self: Bind the method to an instance of the class
+        :param db: int: Select the database to connect to
+        :return: An async connection object
+        """
+        parsed_uri = urlparse(self.uri)
+        sentinel_host = parsed_uri.hostname
+        sentinel_port = parsed_uri.port
+        redis_password = parsed_uri.password
+        sentinel_hosts = [(sentinel_host, sentinel_port)]
+
+        sentinel = aioredis.Sentinel(
+            sentinel_hosts,
+            socket_timeout=kwargs.get("timeout", DBConfig.db_timeout),
+            password=redis_password,
+        )
+
+        # Connect to the Redis Sentinel master service and select the specified database
+        connection_object = sentinel.master_for(self.service, decode_responses=kwargs.get("decode_response", True))
+        await connection_object.select(db)
+        return connection_object
+
+
+__all__ = ["MemDBConnector"]
\ No newline at end of file
diff --git a/tests/test_async_connector.py b/tests/test_async_connector.py
index 98405b0..6aa34a8 100644
--- a/tests/test_async_connector.py
+++ b/tests/test_async_connector.py
@@ -1,11 +1,11 @@
-"""Tests for AsyncMemDBConnector class."""
+"""Tests for async MemDBConnector class."""
 
 from unittest.mock import AsyncMock, patch
 from urllib.parse import urlparse
 
 import pytest
 
-from mem_db_utils import AsyncMemDBConnector
+from mem_db_utils.asyncio import MemDBConnector as AsyncMemDBConnector
 from mem_db_utils.config import DBConfig, DBType
 
 
diff --git a/tests/test_async_integration.py b/tests/test_async_integration.py
index 8a2a58f..1e3ee96 100644
--- a/tests/test_async_integration.py
+++ b/tests/test_async_integration.py
@@ -1,4 +1,4 @@
-"""Integration tests for AsyncMemDBConnector with real database connections.
+"""Integration tests for async MemDBConnector with real database connections.
 
 These tests use the database configuration from the .env file.
 The tests will work with Redis databases only as async support is primarily for Redis.
@@ -8,7 +8,7 @@
 
 import pytest
 
-from mem_db_utils import AsyncMemDBConnector
+from mem_db_utils.asyncio import MemDBConnector as AsyncMemDBConnector
 from mem_db_utils.config import DBConfig, DBType
 
 

From 16760eb91d6ade6b37c69db6a3190e5ede76ffd9 Mon Sep 17 00:00:00 2001
From: Faizan Azim <faizanazim11@gmail.com>
Date: Wed, 17 Sep 2025 17:08:54 +0000
Subject: [PATCH 8/8] fix: :arrow_up: add pytest-asyncio & format code

---
 .github/copilot-instructions.md      |  4 ++--
 pyproject.toml                       |  1 +
 src/mem_db_utils/asyncio/__init__.py |  2 +-
 tests/test_async_connector.py        |  6 ++++++
 uv.lock                              | 15 +++++++++++++++
 5 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 72d43e8..5a885a0 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -10,7 +10,7 @@ Always reference these instructions first and fallback to search or bash command
 - `pip install -e .` -- installs the package in development mode. NEVER CANCEL: Takes 10-60 seconds, may timeout due to network issues. Set timeout to 120+ seconds (extra margin for slow mirrors or network issues).
 - `pip install coverage pre-commit pytest pytest-cov pytest-dotenv ruff` -- installs development dependencies. NEVER CANCEL: Takes 30-120 seconds. Set timeout to 180+ seconds (extra margin for slow mirrors or network issues).
 - `python -m pytest tests/ -v` -- runs unit tests (takes ~0.4 seconds, 20 passed, 5 skipped without database)
-- `ruff check .` -- runs linting (takes ~0.01 seconds)  
+- `ruff check .` -- runs linting (takes ~0.01 seconds)
 - `ruff format --check .` -- checks code formatting (takes ~0.01 seconds)
 
 ### Environment Configuration:
@@ -152,4 +152,4 @@ mem-db-utils/
 - Check if database container is running: `docker ps`
 - Test connection manually: `docker exec -it test-redis redis-cli ping`
 - Verify port availability: `netstat -tlnp | grep 6379`
-- Check firewall settings if running on remote host
\ No newline at end of file
+- Check firewall settings if running on remote host
diff --git a/pyproject.toml b/pyproject.toml
index 719966a..15cef48 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,6 +25,7 @@ dev = [
     "coverage>=7.10.2",
     "pre-commit>=4.2.0",
     "pytest>=8.4.1",
+    "pytest-asyncio>=1.2.0",
     "pytest-cov>=6.2.1",
     "pytest-dotenv>=0.5.2",
 ]
diff --git a/src/mem_db_utils/asyncio/__init__.py b/src/mem_db_utils/asyncio/__init__.py
index 2301ca1..792c15e 100644
--- a/src/mem_db_utils/asyncio/__init__.py
+++ b/src/mem_db_utils/asyncio/__init__.py
@@ -55,4 +55,4 @@ async def _sentinel(self, db: int, **kwargs):
         return connection_object
 
 
-__all__ = ["MemDBConnector"]
\ No newline at end of file
+__all__ = ["MemDBConnector"]
diff --git a/tests/test_async_connector.py b/tests/test_async_connector.py
index 6aa34a8..1679918 100644
--- a/tests/test_async_connector.py
+++ b/tests/test_async_connector.py
@@ -52,9 +52,11 @@ def test_init_with_master_service_override(self):
     async def test_connect_direct_connection(self, mock_from_url):
         """Test direct async database connection."""
         mock_connection = AsyncMock()
+
         # Mock from_url to return a coroutine
         async def mock_coro():
             return mock_connection
+
         mock_from_url.return_value = mock_coro()
 
         connector = AsyncMemDBConnector()
@@ -70,9 +72,11 @@ async def mock_coro():
     async def test_connect_with_custom_kwargs(self, mock_from_url):
         """Test async connection with custom keyword arguments."""
         mock_connection = AsyncMock()
+
         # Mock from_url to return a coroutine
         async def mock_coro():
             return mock_connection
+
         mock_from_url.return_value = mock_coro()
 
         connector = AsyncMemDBConnector()
@@ -116,9 +120,11 @@ async def test_connect_sentinel(self, mock_sentinel_class):
     async def test_connect_default_db(self, mock_from_url):
         """Test async connection with default database (0)."""
         mock_connection = AsyncMock()
+
         # Mock from_url to return a coroutine
         async def mock_coro():
             return mock_connection
+
         mock_from_url.return_value = mock_coro()
 
         connector = AsyncMemDBConnector()
diff --git a/uv.lock b/uv.lock
index 2bbd458..b3973c6 100644
--- a/uv.lock
+++ b/uv.lock
@@ -145,6 +145,7 @@ dev = [
     { name = "coverage" },
     { name = "pre-commit" },
     { name = "pytest" },
+    { name = "pytest-asyncio" },
     { name = "pytest-cov" },
     { name = "pytest-dotenv" },
 ]
@@ -162,6 +163,7 @@ dev = [
     { name = "coverage", specifier = ">=7.10.2" },
     { name = "pre-commit", specifier = ">=4.2.0" },
     { name = "pytest", specifier = ">=8.4.1" },
+    { name = "pytest-asyncio", specifier = ">=1.2.0" },
     { name = "pytest-cov", specifier = ">=6.2.1" },
     { name = "pytest-dotenv", specifier = ">=0.5.2" },
 ]
@@ -314,6 +316,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a8/a4/20da314d277121d6534b3a980b29035dcd51e6744bd79075a6ce8fa4eb8d/pytest-8.4.2-py3-none-any.whl", hash = "sha256:872f880de3fc3a5bdc88a11b39c9710c3497a547cfa9320bc3c5e62fbf272e79", size = 365750, upload-time = "2025-09-04T14:34:20.226Z" },
 ]
 
+[[package]]
+name = "pytest-asyncio"
+version = "1.2.0"
+source = { registry = "https://pypi.prismatica.in/simple" }
+dependencies = [
+    { name = "pytest" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/42/86/9e3c5f48f7b7b638b216e4b9e645f54d199d7abbbab7a64a13b4e12ba10f/pytest_asyncio-1.2.0.tar.gz", hash = "sha256:c609a64a2a8768462d0c99811ddb8bd2583c33fd33cf7f21af1c142e824ffb57", size = 50119, upload-time = "2025-09-12T07:33:53.816Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/93/2fa34714b7a4ae72f2f8dad66ba17dd9a2c793220719e736dda28b7aec27/pytest_asyncio-1.2.0-py3-none-any.whl", hash = "sha256:8e17ae5e46d8e7efe51ab6494dd2010f4ca8dae51652aa3c8d55acf50bfb2e99", size = 15095, upload-time = "2025-09-12T07:33:52.639Z" },
+]
+
 [[package]]
 name = "pytest-cov"
 version = "7.0.0"