Database Architecture

BuyWhere operates two distinct PostgreSQL databases for the product catalog API.

Production Database (Main Catalog)

Connection:

postgresql+asyncpg://buywhere:buywhere@172.18.0.4:5432/buywhere

Development Database (API Dev)

Connection:

postgresql+asyncpg://buywhere:buywhere@localhost:5432/buywhere

Internal Docker Network

Both PostgreSQL containers are on the internal Docker network 172.18.0.0/16:

• buywhere-postgres-1: 172.18.0.4
• docker-postgres-1: 172.22.0.3

The Docker Compose services connect via container name, not IP.

Paperclip Service Database

The Paperclip control plane uses its own Postgres instance:

Environment Configuration

In .env, the DATABASE_URL variable controls which database the API uses:

# Production (main catalog - 1.53M products)
DATABASE_URL=postgresql+asyncpg://buywhere:buywhere@172.18.0.4:5432/buywhere

# Development (local docker postgres - 41K products)
DATABASE_URL=postgresql+asyncpg://buywhere:buywhere@localhost:5432/buywhere

Common Issues

Ingestion Stall: If scraping/ingestion appears stuck, verify you're writing to the correct database. The main catalog at 172.18.0.4 is the production target. The dev database at localhost:5432 is isolated and won't affect production data.

Connection Confusion: Always verify DATABASE_URL before running scripts. A common mistake is running migration or ingestion scripts against the wrong database.