# Database

## Overview

Trackpull uses a single SQLite database at `/config/trackpull.db`. All access goes through `db.py`, which uses thread-local connections to stay safe under multi-threaded Gunicorn workers.

---

## Schema

### `users`

| Column | Type | Notes |
|--------|------|-------|
| `id` | TEXT PK | UUID |
| `username` | TEXT UNIQUE | Login name |
| `password_hash` | TEXT | werkzeug PBKDF2 hash |
| `role` | TEXT | `admin` or `user` |
| `created_at` | TEXT | ISO datetime |
| `last_login` | TEXT | ISO datetime, nullable |

### `jobs`

| Column | Type | Notes |
|--------|------|-------|
| `id` | TEXT PK | UUID |
| `user_id` | TEXT FK → users | Cascading delete |
| `urls` | TEXT | JSON array of download URLs |
| `options` | TEXT | JSON object of download parameters |
| `status` | TEXT | `queued`, `running`, `completed`, `failed`, `cancelled` |
| `output` | TEXT | JSON array of log lines (max 500) |
| `command` | TEXT | Full CLI command string (Votify jobs) |
| `return_code` | INTEGER | Process exit code |
| `created_at` | TEXT | ISO datetime |
| `updated_at` | TEXT | ISO datetime |

### `app_settings`

| Column | Type | Notes |
|--------|------|-------|
| `key` | TEXT PK | Setting name |
| `value` | TEXT | Setting value (always a string) |

Current settings keys: `fallback_quality`, `job_expiry_days`.

---

## Threading Model

`db.py` creates a new connection per thread using `threading.local()`. Each call opens a connection, runs the query, and closes it. This avoids SQLite's "objects created in a thread can only be used in that same thread" limitation.

Foreign keys are enabled on every connection via `PRAGMA foreign_keys = ON`.

---

## Key Functions

### Users

| Function | Purpose |
|----------|---------|
| `create_user(username, password, role)` | Hashes password and inserts row |
| `get_user_by_username(username)` | Lookup for login |
| `get_user_by_id(user_id)` | Lookup for session validation |
| `list_users()` | Admin user list |
| `delete_user(user_id)` | Cascades to jobs |
| `verify_password(username, password)` | Returns user row or None |
| `update_user_password(user_id, new_password)` | Re-hashes and saves |
| `update_last_login(user_id)` | Stamps `last_login` |

### Jobs

| Function | Purpose |
|----------|---------|
| `upsert_job(job_dict)` | Insert or replace job record |
| `get_job(job_id)` | Fetch single job |
| `list_jobs_for_user(user_id)` | All jobs for a user |
| `delete_job(job_id)` | Remove single job |
| `delete_jobs_older_than(days)` | Expiry cleanup |

### Settings

| Function | Purpose |
|----------|---------|
| `get_setting(key, default)` | Fetch value with fallback |
| `set_setting(key, value)` | Upsert a setting |
| `get_all_settings()` | Return all as dict |

---

## Initialization

`db.py` calls `init_db()` on import, which:
1. Creates all tables if they don't exist.
2. Seeds the first admin user from `ADMIN_USERNAME` / `ADMIN_PASSWORD` env vars if the `users` table is empty.

---

## Key Files

| File | Relevance |
|------|-----------|
| [db.py](../db.py) | Entire database layer |
| [app.py](../app.py) | Calls db functions for all CRUD operations |