Address PR comments & change python version support

Author: nik-localstack

Makefile

@@ -3,8 +3,8 @@ VENV_DIR ?= .venv
 VENV_RUN = . $(VENV_DIR)/bin/activate
 PIP_CMD ?= pip
 PYTHON_CMD ?= python
-TEST_DEPS ?= pytest pytest-timeout
-LINT_DEPS ?= ruff
+TEST_REQS ?= requirements-test.txt
+LINT_REQS ?= requirements-lint.txt
 
 PG_TEST_CONTAINER ?= pg-proxy-local-tests
 PG_TEST_IMAGE ?= postgres:16
@@ -26,10 +26,10 @@ publish:           ## Publish the library to the central PyPi repository
 	($(VENV_RUN); pip install twine; python ./setup.py sdist && twine upload dist/*)
 
 install-test: install ## Install test dependencies in local virtualenv
-	($(VENV_RUN); $(PIP_CMD) install $(TEST_DEPS))
+	($(VENV_RUN); $(PIP_CMD) install -r $(TEST_REQS))
 
 install-lint: install ## Install lint dependencies in local virtualenv
-	($(VENV_RUN); $(PIP_CMD) install $(LINT_DEPS))
+	($(VENV_RUN); $(PIP_CMD) install -r $(LINT_REQS))
 
 lint: install-lint ## Format code with ruff
 	$(VENV_DIR)/bin/ruff format postgresql_proxy tests plugins

README.md

@@ -5,26 +5,30 @@ Serves as a proper server that Postgresql clients can connect to. Can modify pac
 Currently used for rewriting queries to force proper use of postgres-hll module by external proprietary software that doesn't know about that functionality
 
 ## Installing
-### Linux
-1. Make sure you have [python3 and pip3 installed on your system](https://stackoverflow.com/questions/6587507/how-to-install-pip-with-python-3#6587528). It has been tested with Python3.6 but should also run on Python3.5.
-2. Clone it locally and cd to that directory
-  ```
-  git clone git@github.com:kfzteile24/postgresql-proxy.git
-  cd postgresql-proxy
-  ```
-3. Run [setup.sh](setup.sh)
-  ```
-  ./setup.sh
-  ```
-4. Make a copy of [config.yml.example](config.yml.example) called `config.yml` and configure your proxy instances. Create the log directories if they're not there.
+
+Requires Python `3.13+`.
+
+1. Clone the repository:
+   ```bash
+   git clone git@github.com:localstack/postgresql-proxy.git
+   cd postgresql-proxy
+   ```
+2. Install dependencies into a local virtualenv:
+   ```bash
+   make install
+   ```
+3. Copy the example config and edit it for your environment:
+   ```bash
+   cp config.yml.example config.yml
+   ```
 
 ## Configuring
 In the `config.yml` file you can define the following things
 ### Plugins
 A list of dynamically loaded modules that reside in the [plugins](plugins) directory. These plugins can be used in later configuration, to intercept queries, commands, or responses. View plugin documentation for example plugins for more details on how to do that.
 ### Settings
 General application settings. Currently the following settings are used
-* `log-level` - the log level for the general log. See [python logging](https://docs.python.org/3.6/library/logging.html) for more details about the logging functionality
+* `log-level` - the log level for the general log. See [python logging](https://docs.python.org/3/library/logging.html) for more details about the logging functionality
 * `general-log` - the location for the general log. All general messages go in there.
 * `intercept-log` - the location for the intercept log. Intercepted messages and return values from various enabled plugins will be written there. This log can be quite verbose as it contains the full binary messages being circulated.
 
@@ -42,19 +46,22 @@ Make sure to manage the logs yourself, as they accumulate and take up disk space
 
   Each interceptor definition must have a `plugin`, which should also be present in the [plugins](#Plugins) configuration, and a `function`, that is found directly in that module, that will be called each time with the intercepted message as a byte string, and a context variable that is an instance of the `Proxy` class, that contains connection information and other useful stuff.
 
-## Running in testing mode
-If you want to test it, do this. Otherwise scroll down for instructions on how to install it as a service
-### Linux
-1. Activate the virtual environment
-  ```
-  source .venv/bin/activate
-  ```
-2. Run it
-  ```
-  python proxy.py
-  ```
-
-### Changelog
+## Running
+
+Activate the virtualenv and run the proxy directly:
+
+```bash
+source .venv/bin/activate
+python -m postgresql_proxy
+```
+
+Or run it without activating the venv:
+
+```bash
+.venv/bin/python -m postgresql_proxy
+```
+
+## Changelog
 - v0.3.1
   - Fix SSL COPY stalls by draining pending SSL buffer after recv [#11](https://github.com/localstack/postgresql-proxy/pull/11)
   - Fix intermittent `BlockingIOError` on macOS during SSL negotiation
@@ -84,8 +91,60 @@ If you want to test it, do this. Otherwise scroll down for instructions on how t
 
 ## Testing
 
-Run the full local test suite (starts a disposable PostgreSQL container automatically):
+All tests require a real PostgreSQL server and are organized at the top level:
+
+- `test_proxy.py`: proxy behavior tests (connection, SSL, hang regressions)
+- `test_plugins.py`: plugin integration tests (HLL rewrite behavior)
+
+### Prerequisites
+
+- Python `3.13` (same version as CI)
+- Docker (for local disposable PostgreSQL)
+- `psql` (`postgresql-client`)
+- `openssl` (SSL tests generate a temporary self-signed cert/key at runtime)
+
+Install Python deps in the project virtualenv:
+
+```bash
+make install-test
+```
+
+### Which command should I use?
+
+- Fastest full local run with disposable Postgres: `make test`
+- Run only proxy tests (using your own Postgres): `python -m pytest tests/test_proxy.py -vv`
+- Run only plugin tests: `python -m pytest tests/test_plugins.py -vv`
+
+#### 1) Full local suite (recommended)
+
+`make test` starts a temporary PostgreSQL container, waits for readiness, sets DB env vars, then runs:
+
+```bash
+python -m pytest -vv
+```
+
+Use it when you want one command that matches normal contributor workflow.
 
 ```bash
 make test
 ```
+
+#### 2) Run against an existing PostgreSQL
+
+If you already have PostgreSQL running, set connection env vars and run the tests you need:
+
+```bash
+export E2E_PG_HOST=127.0.0.1
+export E2E_PG_PORT=5432
+export E2E_PG_USER=postgres
+export E2E_PG_PASSWORD=postgres
+export E2E_PG_DB=postgres
+
+# Proxy tests only
+python -m pytest tests/test_proxy.py -vv
+
+# Plugin tests only
+python -m pytest tests/test_plugins.py -vv
+```
+
+If PostgreSQL is not reachable, tests fail fast at startup.

postgresql_proxy/__main__.py

@@ -0,0 +1,3 @@
+from postgresql_proxy.proxy import main
+
+main()

postgresql_proxy/proxy.py

@@ -329,7 +329,7 @@ def stop(self):
         self.running = False
 
 
-if __name__ == '__main__':
+def main():
     import importlib
     import yaml
     import os
@@ -370,3 +370,7 @@ def stop(self):
         logging.info("Starting proxy instance")
         proxy = Proxy(instance, plugins)
         proxy.listen()
+
+
+if __name__ == "__main__":
+    main()

requirements-lint.txt

@@ -0,0 +1 @@
+ruff==0.15.12

requirements-test.txt

@@ -0,0 +1,2 @@
+pytest==9.0.3
+pytest-timeout==2.4.0

setup.py

@@ -1,6 +1,3 @@
-import os
-import re
-import sys
 from setuptools import find_packages, setup
 
 install_requires = []
@@ -16,14 +13,8 @@
         install_requires=install_requires,
         zip_safe=False,
         classifiers=[
-            'Programming Language :: Python :: 2',
-            'Programming Language :: Python :: 2.6',
-            'Programming Language :: Python :: 2.7',
             'Programming Language :: Python :: 3',
-            'Programming Language :: Python :: 3.3',
-            'Programming Language :: Python :: 3.6',
-            'Programming Language :: Python :: 3.7',
-            'Programming Language :: Python :: 3.8',
+            'Programming Language :: Python :: 3.13',
             'License :: OSI Approved :: Apache Software License',
             'Topic :: Software Development :: Testing',
         ]

tests/README.md

@@ -30,4 +30,3 @@ def ensure_postgres_available(postgres_settings):
         pytest.fail(
             f"PostgreSQL backend is required for tests but is not reachable: {err}"
         )
-

tests/conftest.py

@@ -15,8 +15,6 @@
 from postgresql_proxy.proxy import Proxy
 
 
-
-
 def _get_free_tcp_port() -> int:
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
         sock.bind(("127.0.0.1", 0))
@@ -233,12 +231,11 @@ def test_psql_ssl_file_batch_stress_no_hang(postgres_settings, ssl_proxy_port):
     if shutil.which("psql") is None:
         pytest.fail("psql is required for this test but was not found in PATH")
 
-    sql_file_path = None
-    try:
+    with tempfile.NamedTemporaryFile("w", suffix=".sql", delete=True) as tmp_file:
         sql_content = _build_dump_like_sql(table_count=24, rows_per_table=300)
-        with tempfile.NamedTemporaryFile("w", suffix=".sql", delete=False) as tmp_file:
-            tmp_file.write(sql_content)
-            sql_file_path = tmp_file.name
+        tmp_file.write(sql_content)
+        tmp_file.flush()
+        sql_file_path = tmp_file.name
 
         for run_idx in range(3):
             started = time.time()
@@ -261,16 +258,13 @@ def test_psql_ssl_file_batch_stress_no_hang(postgres_settings, ssl_proxy_port):
                 err_tail = "\n".join((result.stderr or "").splitlines()[-20:])
                 pytest.fail(
                     "psql -f batch failed over SSL via proxy "
-                    f"(run={run_idx + 1}, rc={result.returncode}, elapsed={elapsed:.2f}s) "
+                    f"(run={run_idx + 1}, rc={result.returncode}, {elapsed=:.2f}s) "
                     f"stdout_tail={out_tail} stderr_tail={err_tail}"
                 )
 
             if "BATCH_OK" not in (result.stdout or ""):
                 out_tail = "\n".join((result.stdout or "").splitlines()[-20:])
                 pytest.fail(
                     "psql -f batch succeeded but expected marker missing "
-                    f"(run={run_idx + 1}, elapsed={elapsed:.2f}s) stdout_tail={out_tail}"
+                    f"(run={run_idx + 1}, {elapsed=:.2f}s) stdout_tail={out_tail}"
                 )
-    finally:
-        if sql_file_path and os.path.exists(sql_file_path):
-            os.unlink(sql_file_path)