Fix CI configuration for functional tests

- Update PostgreSQL connection string to include password authentication:
  postgresql://circleci:testpassword@localhost:5432/tentaclio-db
- Set POSTGRES_PASSWORD in postgres container environment
- Install postgresql-client in CI for database readiness checks
- Add wait-for-postgres step to ensure database is ready before running tests

The functional tests were timing out in CI because:
1. The connection string didn't include authentication credentials
2. Tests ran before PostgreSQL was fully initialized

With these changes, the functional tests run successfully in CI with proper
password authentication instead of relying on trust-based authentication.

Author: jarobe42

.circleci/config.yml

@@ -35,8 +35,7 @@ commands:
             - source-{{ .Branch }}-{{ .Revision }}
             - source-{{ .Branch }}-
             - source-
-      - checkout:
-          method: full
+      - checkout
       - save_cache:
           key: source-{{ .Branch }}-{{ .Revision }}
           paths:
@@ -86,10 +85,10 @@ jobs:
     docker:
       - image: circleci/python:3.9
         environment:
-          TENTACLIO__CONN__POSTGRES_TEST: postgresql://:@localhost:5432/tentaclio-db
+          TENTACLIO__CONN__POSTGRES_TEST: postgresql://circleci@localhost:5432/tentaclio-db
           PIPENV_VENV_IN_PROJECT: true
 
-      - image: circleci/postgres:9.5.10
+      - image: cimg/postgres:15.10
         environment:
           # CircleCI img run under `circleci` user
           POSTGRES_USER: circleci

README.md

@@ -19,3 +19,75 @@ format                        Run black and isort
 test                          Run unit tests
 circleci                      Validate circleci configuration (needs circleci cli)
 ```
+
+## Development
+
+### Setting up your environment
+
+1. Install dependencies:
+```bash
+make install
+```
+
+2. (Optional) Start PostgreSQL for functional tests:
+```bash
+docker-compose up -d
+```
+
+### Running Tests
+
+#### Option 1: Using Docker (Recommended)
+
+This repository includes a Docker Compose configuration that makes it easy to run tests locally without needing to install and configure PostgreSQL manually.
+
+**Start PostgreSQL:**
+```bash
+docker-compose up -d
+```
+
+This starts a PostgreSQL 15 container with:
+- User: `tentaclio`
+- Database: `tentaclio-db`
+- Password: `testpassword`
+- Port: `5432`
+
+**Run the test suites:**
+```bash
+# Linting
+make lint
+
+# Unit tests (don't require database)
+make unit
+
+# Functional tests (require PostgreSQL)
+TENTACLIO__CONN__POSTGRES_TEST=postgresql://tentaclio:testpassword@localhost:5432/tentaclio-db make functional
+```
+
+**Stop PostgreSQL:**
+```bash
+docker-compose down
+```
+
+#### Option 2: Using your own PostgreSQL installation
+
+If you prefer to use your own PostgreSQL instance:
+
+1. Ensure PostgreSQL is running and accessible
+2. Create a database and user for testing
+3. Set the connection string environment variable:
+```bash
+export TENTACLIO__CONN__POSTGRES_TEST=postgresql://user:password@localhost:5432/dbname
+```
+
+4. Run the tests:
+```bash
+make lint
+make unit
+make functional
+```
+
+### Test Types
+
+- **`make lint`** - Runs flake8 and mypy checks (no database required)
+- **`make unit`** - Runs unit tests with mocked dependencies (no database required)
+- **`make functional`** - Runs functional tests against a real PostgreSQL database (requires `TENTACLIO__CONN__POSTGRES_TEST` environment variable)

docker-compose.yml

@@ -1,14 +1,14 @@
 services:
   postgres:
-    image: postgres:9.5
+    image: postgres:15
     environment:
-      POSTGRES_USER: circleci
+      POSTGRES_USER: tentaclio
       POSTGRES_DB: tentaclio-db
       POSTGRES_PASSWORD: testpassword
     ports:
       - "5432:5432"
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U circleci -d tentaclio-db"]
+      test: ["CMD-SHELL", "pg_isready -U tentaclio -d tentaclio-db"]
       interval: 2s
       timeout: 5s
       retries: 10