Chinook Postgres Starter

A base project for experimenting with the Chinook database — a digital media store with tables for artists, albums, tracks, invoices, and customers.

Use this as a starting point for any Chinook-related experiments or projects.

Stack

• PostgreSQL — Chinook database running in Docker
• Python + SQLAlchemy — ready to query and interact with the database (python/)
• Adminer — web-based DB UI at http://localhost:8080
• PgHero — Postgres performance dashboard at http://localhost:8081
• pgAdmin — full-featured Postgres UI at http://localhost:8082 (admin@admin.com / admin)
• JupyterLab — interactive notebooks for running SQLAlchemy queries (python/ dev dependency)

Make Commands

Command	Action
make up	Start all services
make down	Stop all services
make reset	Wipe volumes and restart fresh
make jupyter	Launch JupyterLab
make logs	Tail logs from all services
make psql	Open psql shell in chinook

How to Run

1. Start the database

make up

This starts PostgreSQL, Adminer (http://localhost:8080), PgHero (http://localhost:8081), and pgAdmin (http://localhost:8082).

2. Run a script

From the python/ directory:

cd python
uv run queries/revenue_report.py

Requires uv. Dependencies are installed automatically from pyproject.toml.

3. Launch JupyterLab (optional)

make jupyter

Opens at http://localhost:8888. A starter notebook is at python/notebooks/chinook_starter.ipynb.

JupyterLab

Launch with make jupyter, then open http://localhost:8888.

A starter notebook is at python/notebooks/chinook_starter.ipynb. You can also create your own — all project modules are importable directly:

import sys
sys.path.insert(0, '..')  # only needed when running from notebooks/

from db import get_session
from models import Artist, Album, Track

# ORM query
with get_session() as session:
    artists = session.query(Artist).limit(10).all()
    for a in artists:
        print(a.name)

# pandas + raw SQL
import pandas as pd
from sqlalchemy import text
from db import get_engine

df = pd.read_sql(text("SELECT * FROM track LIMIT 100"), get_engine())
df.head()

Example Scripts

Revenue report by genre

cd python
uv run queries/revenue_report.py

Prints a table with revenue, tracks sold, unique customers, and top artist per genre. Also visible in PgHero → Queries after running.

Connection Details

Parameter	Value
Host	localhost
Port	5432
Database	chinook
User	postgres
Password	postgres

psql -h localhost -U postgres -d chinook

Re-initializing the Database

The SQL init script only runs on first startup. To reset from scratch:

make reset