Building a Geo-Spatial Application with PostGIS, Python, and TDD
How I Evolved from Notepad++ Chaos to Test-Driven Development Bliss
When I first started my journey as a geospatial application developer, my workflow was... well, let's just say it was "unique." Picture this: I’d fire up Notepad++ (yes, that was my entire development setup — caveman style) and hammer out code like a man possessed. My debugging process? Sprinkle print statements everywhere until the errors stopped screaming at me. Logging systems? Never heard of them. It was pure chaos, and somehow, I managed to scrape by.
Hellow Nodepad++!, my dear oldfriend! Source.
It wasn’t until I started collaborating with coworkers, having my code reviewed (and shredded), reviewing theirs, and diving into blogs and books on software architecture that I realized there was a better way. My code slowly started improving, becoming more maintainable, and dare I say, cleaner.
But the real game-changer? Test-Driven Development (TDD). Writing tests first transformed the way I worked. It reduced the “surprise factor” in production and helped me iterate more effectively without the looming fear of things breaking.
This blog post is my tribute to that process. Here, we’ll build a small application and walk through the workflow I typically follow for solo projects that need to be maintainable for the long haul. (If it’s just a one-off script, don’t worry — no need to roll out the TDD parade for that!)
So, let’s dive in and build something awesome.
Step:1 Defining the business ida and project's structure.
Before starting any project, I'd like to point out that good architecture begins with clearly defining the system requirements and the business problem we aim to solve.
business idea:
"We want to build a simple tool that allows users to save and manage geometries (points, lines, polygons) in a PostGIS-compatible format, along with additional information such as a descriptive name, the user who created it, and the creation date. All of this will be accessible through an intuitive command-line interface (CLI), with a PostGIS database for storage, following a test-driven development (TDD) approach and clean architecture principles."
With that definition in mind, let's move on to the first step: defining the project's architecture.
With the help of AI through Chat-GPT, I created the following project layout that we'll follow throughout this tutorial:
my_geospatial_project/
│
├── app/
│ ├── core/
│ │ ├── __init__.py
│ │ ├── entities.py # Core business objects (e.g., Geometry)
│ │ ├── use_cases.py # Business logic (e.g., add/retrieve geometries)
│ │
│ ├── infrastructure/
│ │ ├── __init__.py
│ │ ├── postgis_repository.py # PostGIS database interactions
│ │
│ ├── cli/
│ ├── __init__.py
│ ├── main.py # CLI entry point
│
├── tests/
│ ├── core/
│ │ ├── test_entities.py
│ │ ├── test_use_cases.py
│ │
│ ├── infrastructure/
│ ├── test_postgis_repository.py
│
├── Dockerfile # Docker setup for Python
├── docker-compose.yml # Multi-container setup for PostGIS and the app
├── pyproject.toml # Project dependencies and metadata
├── requirements.txt # Python dependencies (optional)
├── README.md # Project documentation
This structure emphasizes separation of concerns: core logic is isolated in core/, database interaction in infrastructure/, and CLI handling in cli/. The tests/ directory mirrors this layout to ensure modular and focused testing.
The essential project files (Dockerfile, docker-compose, pyproject.toml, and README) provide everything needed to set up and run the project, and in the future prepare the python package.
Step:2 Setting Up PostGIS with Docker compose
To store and retrieve geometries, we first need to set up the database. Instead of manually verifying the connection using tools like psql, we'll adopt a Test-Driven Development (TDD) approach to ensure the database is properly configured.
1. Create the docker-compose.yml File
Set up a PostGIS-enabled PostgreSQL database using Docker Compose:
version: '3.8'
services:
postgis:
image: postgis/postgis:15-3.3
container_name: postgis
environment:
POSTGRES_USER: admin
POSTGRES_PASSWORD: admin
POSTGRES_DB: geo_test
ports:
- "5432:5432"
volumes:
- postgis_data:/var/lib/postgresql/data
volumes:
postgis_data:
2. Start the database
Launch the database container with:
3. Test the Database Connection with Pytest
As part of TDD, it's crucial to write tests to confirm the database is operational. Here's a test script to verify the connection and PostGIS functionality: Create a file named test_database.py in the tests/infrastructure directory:
import psycopg2
import pytest
@pytest.fixture(scope="module")
def db_connection():
"""Fixture to set up and tear down the database connection."""
conn = psycopg2.connect(
host="localhost",
database="geo_test",
user="admin",
password="admin",
)
yield conn
conn.close()
def test_database_connection(db_connection):
"""Test if the database connection is successful."""
assert db_connection is not None, "Failed to connect to the database"
def test_postgis_extension(db_connection):
"""Test if the PostGIS extension is installed."""
with db_connection.cursor() as cursor:
cursor.execute("SELECT postgis_version();")
result = cursor.fetchone()
assert result is not None, "PostGIS extension is not installed"
print(f"PostGIS Version: {result[0]}")
Run the tests with:
4. Why This Matters
Adopting TDD ensures the database setup meets functional requirements and prevents surprises in later stages of development. The tests validate: * Successful database connection. * Correct installation of the PostGIS extension. * By writing tests for fundamental components early, we establish a solid foundation for the project's future development.