Database Setup

Start TimescaleDB

Polyblock uses TimescaleDB (PostgreSQL with time-series extensions) running in Docker:

# Navigate to project root
cd /path/to/Polyblock-main

# Start TimescaleDB container
docker-compose up -d timescaledb

# Wait for container to be healthy (10-15 seconds)
docker-compose ps timescaledb

Run Migrations

Apply database migrations to create required tables:

# Run migrations
docker-compose exec -T timescaledb psql -U Polyblock -d Polyblock < database/migrations/001_create_price_history.sql

# Optional: Run optimization migrations
docker-compose exec -T timescaledb psql -U Polyblock -d Polyblock < database/migrations/002_optimize_storage.sql

Migration Files

001_create_price_history.sql — Creates price_history hypertable
002_optimize_storage.sql — Adds compression and retention policies

Verify Setup

Confirm the database is running and tables exist:

# Check database is accepting connections
docker-compose exec timescaledb pg_isready -U Polyblock
# Expected: timescaledb:5432 - accepting connections

# List tables
docker-compose exec timescaledb psql -U Polyblock -d Polyblock -c "\dt"
# Expected: price_history table listed

Troubleshooting

Container won't start?

Check Docker Desktop is running and has sufficient resources allocated.

docker-compose logs timescaledb

Connection refused?

Ensure the container is healthy and port 5432 isn't in use.

lsof -i :5432

Tables missing?

Re-run migrations. Check for SQL errors in the output.

Data not persisting?

Docker volumes should preserve data. Check volume mounting:

docker volume ls | grep Polyblock

Backups and local resets

For local development, snapshot the Docker volume before risky migrations so you can roll back quickly. Never restore production dumps into shared laptops without scrubbing PII. If you need a clean slate, stop the container, remove the named volume, and rerun migrations—document this flow for teammates so nobody panics when charts look empty after a reset.