Data Model

Meta	Value
Repo	`xpltdco/media-rip`
Page	`Data-Model`
Audience	developers, agents
Last Updated	2026-04-04
Status	current

Overview

media-rip uses SQLite with async access via aiosqlite. The database automatically detects network filesystems and switches between WAL and DELETE journal mode. Schema is defined in backend/app/core/database.py.

Tables

`sessions`

Column	Type	Description
`id`	TEXT PK	UUID4 session identifier
`created_at`	TEXT	ISO timestamp
`last_seen`	TEXT	Updated on every request

Index: idx_sessions_last_seen on last_seen

`jobs`

Column	Type	Default	Description
`id`	TEXT PK	—	UUID4 job identifier
`session_id`	TEXT	—	FK → sessions
`url`	TEXT	—	Source URL
`status`	TEXT	`queued`	`queued`, `extracting`, `downloading`, `completed`, `failed`, `cancelled`
`format_id`	TEXT	NULL	Selected format identifier
`quality`	TEXT	NULL	Quality label
`output_template`	TEXT	NULL	Resolved output path
`filename`	TEXT	NULL	Final filename (set after download)
`filesize`	INTEGER	NULL	File size in bytes
`progress_percent`	REAL	0	Download progress (0-100)
`speed`	TEXT	NULL	Current download speed string
`eta`	TEXT	NULL	Estimated time remaining
`error_message`	TEXT	NULL	Error details (if failed)
`created_at`	TEXT	—	Job creation time
`started_at`	TEXT	NULL	Download start time
`completed_at`	TEXT	NULL	Completion/failure time

Indexes: idx_jobs_session_status on (session_id, status), idx_jobs_completed on completed_at

`config`

Admin-writable key-value settings store.

Column	Type	Description
`key`	TEXT PK	Setting key
`value`	TEXT	Setting value
`updated_at`	TEXT	Last modification time

`unsupported_urls`

Column	Type	Description
`id`	INTEGER PK	Autoincrement
`url`	TEXT	The unsupported URL
`session_id`	TEXT	Which session tried it
`error`	TEXT	Error message
`created_at`	TEXT	Timestamp

`error_log`

Column	Type	Description
`id`	INTEGER PK	Autoincrement
`url`	TEXT	Source URL
`domain`	TEXT	Extracted domain
`error`	TEXT	Error message
`format_id`	TEXT	Format that was attempted
`media_type`	TEXT	video/audio
`session_id`	TEXT	Session ID
`created_at`	TEXT	Timestamp

SQLite Pragmas

Set at initialization:

PRAGMA busy_timeout = 5000;    -- Wait 5s on lock contention
PRAGMA journal_mode = WAL;     -- Or DELETE on network filesystems
PRAGMA synchronous = NORMAL;   -- Balanced durability/speed

Network Filesystem Detection

The database module reads /proc/mounts and checks the filesystem type. If it detects CIFS, NFS, SMB, 9p, or sshfs, it switches to DELETE journal mode (WAL requires POSIX shared memory which isn't available on network mounts).