"""SQLite storage for the parts inventory. One flexible `parts` table carries the fields every kind of stock shares (name, quantity, unit, location, cost). Anything type-specific — resistance, filament diameter, thread pitch — lives in `part_specs` as key/value rows, so a 0603 resistor, a spool of PLA and a box of M3 screws coexist without a schema fork. Categories carry a `spec_template` naming the keys worth filling in for that kind of part, which is what keeps manual entry from being a blank page. """ import json import os import sqlite3 import threading from contextlib import contextmanager DB_PATH = os.environ.get("PARTS_DB", os.path.join(os.path.dirname(os.path.dirname(__file__)), "data", "parts.db")) # Photos live beside the database, inside the same volume, so one backup target # covers both. IMAGE_DIR = os.environ.get( "PARTS_IMAGE_DIR", os.path.join(os.path.dirname(os.path.abspath(DB_PATH)), "images")) _init_lock = threading.Lock() _initialised = False SCHEMA = """ CREATE TABLE IF NOT EXISTS categories ( id INTEGER PRIMARY KEY, name TEXT NOT NULL, parent_id INTEGER REFERENCES categories(id) ON DELETE SET NULL, unit TEXT NOT NULL DEFAULT 'pcs', spec_template TEXT NOT NULL DEFAULT '[]', sort_order INTEGER NOT NULL DEFAULT 0 ); CREATE UNIQUE INDEX IF NOT EXISTS categories_unique ON categories(name COLLATE NOCASE, COALESCE(parent_id, 0)); CREATE TABLE IF NOT EXISTS locations ( id INTEGER PRIMARY KEY, name TEXT NOT NULL, parent_id INTEGER REFERENCES locations(id) ON DELETE SET NULL, notes TEXT NOT NULL DEFAULT '', sort_order INTEGER NOT NULL DEFAULT 0 ); CREATE UNIQUE INDEX IF NOT EXISTS locations_unique ON locations(name COLLATE NOCASE, COALESCE(parent_id, 0)); CREATE TABLE IF NOT EXISTS parts ( id INTEGER PRIMARY KEY, name TEXT NOT NULL, description TEXT NOT NULL DEFAULT '', category_id INTEGER REFERENCES categories(id) ON DELETE SET NULL, location_id INTEGER REFERENCES locations(id) ON DELETE SET NULL, manufacturer TEXT NOT NULL DEFAULT '', mpn TEXT NOT NULL DEFAULT '', quantity REAL NOT NULL DEFAULT 0, unit TEXT NOT NULL DEFAULT 'pcs', min_quantity REAL, cost_each REAL, datasheet_url TEXT NOT NULL DEFAULT '', product_url TEXT NOT NULL DEFAULT '', notes TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL DEFAULT (datetime('now')), updated_at TEXT NOT NULL DEFAULT (datetime('now')) ); CREATE INDEX IF NOT EXISTS parts_category ON parts(category_id); CREATE INDEX IF NOT EXISTS parts_location ON parts(location_id); CREATE INDEX IF NOT EXISTS parts_name ON parts(name COLLATE NOCASE); CREATE TABLE IF NOT EXISTS part_specs ( part_id INTEGER NOT NULL REFERENCES parts(id) ON DELETE CASCADE, key TEXT NOT NULL, value TEXT NOT NULL DEFAULT '', position INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (part_id, key) ); CREATE TABLE IF NOT EXISTS tags ( id INTEGER PRIMARY KEY, name TEXT NOT NULL UNIQUE COLLATE NOCASE ); CREATE TABLE IF NOT EXISTS part_tags ( part_id INTEGER NOT NULL REFERENCES parts(id) ON DELETE CASCADE, tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE, PRIMARY KEY (part_id, tag_id) ); -- Every quantity change is recorded, so "where did those 40 headers go" has an -- answer instead of just a smaller number than you remembered. CREATE TABLE IF NOT EXISTS stock_log ( id INTEGER PRIMARY KEY, part_id INTEGER NOT NULL REFERENCES parts(id) ON DELETE CASCADE, delta REAL NOT NULL, quantity_after REAL NOT NULL, reason TEXT NOT NULL DEFAULT '', created_at TEXT NOT NULL DEFAULT (datetime('now')) ); CREATE INDEX IF NOT EXISTS stock_log_part ON stock_log(part_id, id DESC); -- Photos of a part: the bag it came in, the markings on the chip, whatever the -- datasheet doesn't tell you. Only metadata lives here; the file itself sits in -- IMAGE_DIR, because blobs in SQLite bloat the database and complicate the -- VACUUM INTO backup. CREATE TABLE IF NOT EXISTS part_images ( id INTEGER PRIMARY KEY, part_id INTEGER NOT NULL REFERENCES parts(id) ON DELETE CASCADE, token TEXT NOT NULL UNIQUE, mime TEXT NOT NULL, bytes INTEGER NOT NULL, caption TEXT NOT NULL DEFAULT '', position INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL DEFAULT (datetime('now')) ); CREATE INDEX IF NOT EXISTS part_images_part ON part_images(part_id, position, id); -- Small key/value store for things that must outlive a container rebuild and -- be changeable without editing a file on the host: the password hash and the -- session epoch live here, in the /data volume. CREATE TABLE IF NOT EXISTS settings ( key TEXT PRIMARY KEY, value TEXT NOT NULL ); CREATE VIRTUAL TABLE IF NOT EXISTS parts_fts USING fts5( name, description, manufacturer, mpn, specs, tags, category, location, tokenize='unicode61 remove_diacritics 2' ); """ # Only these are accepted and only these are ever served back. The uploaded # bytes are sniffed rather than trusted, so a file that merely claims to be a # JPEG cannot come back out as something the browser will execute. MAGIC = [ (b"\xff\xd8\xff", "image/jpeg"), (b"\x89PNG\r\n\x1a\n", "image/png"), (b"GIF87a", "image/gif"), (b"GIF89a", "image/gif"), ] EXTENSIONS = {"image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp"} def sniff_image(head: bytes) -> str | None: """The real type of an uploaded file, or None if it isn't an image we take.""" for magic, mime in MAGIC: if head.startswith(magic): return mime # WEBP is "RIFF" + 4 size bytes + "WEBP". if head[:4] == b"RIFF" and head[8:12] == b"WEBP": return "image/webp" return None def connect(): # FastAPI runs a sync `yield` dependency and its endpoint on different # threadpool threads, so the connection must not be thread-pinned. Each # request still gets its own short-lived connection. conn = sqlite3.connect(DB_PATH, timeout=15.0, check_same_thread=False) conn.row_factory = sqlite3.Row conn.execute("PRAGMA foreign_keys = ON") conn.execute("PRAGMA journal_mode = WAL") conn.execute("PRAGMA busy_timeout = 15000") return conn def init(): """Create the schema and seed starter categories/locations once.""" global _initialised with _init_lock: if _initialised: return os.makedirs(os.path.dirname(os.path.abspath(DB_PATH)), exist_ok=True) os.makedirs(IMAGE_DIR, exist_ok=True) conn = connect() try: conn.executescript(SCHEMA) conn.commit() from .seed import seed seed(conn) finally: conn.close() _initialised = True def image_path(token: str, mime: str) -> str: """Where one image file lives. The token is generated, never client-supplied.""" return os.path.join(IMAGE_DIR, token + EXTENSIONS.get(mime, ".bin")) def delete_image_files(rows): """Remove the files behind a set of part_images rows, ignoring absentees.""" for row in rows: try: os.remove(image_path(row["token"], row["mime"])) except FileNotFoundError: pass def get_setting(conn, key: str, default: str | None = None) -> str | None: row = conn.execute("SELECT value FROM settings WHERE key = ?", (key,)).fetchone() return row["value"] if row else default def set_setting(conn, key: str, value: str): conn.execute( "INSERT INTO settings(key, value) VALUES (?, ?) " "ON CONFLICT(key) DO UPDATE SET value = excluded.value", (key, str(value)), ) @contextmanager def session(): conn = connect() try: yield conn conn.commit() except Exception: conn.rollback() raise finally: conn.close() def get_db(): """FastAPI dependency yielding a per-request connection.""" with session() as conn: yield conn # --- tree helpers ----------------------------------------------------------- def tree_paths(conn, table: str) -> dict[int, str]: """Map id -> 'Parent / Child' display path for a self-referencing table.""" rows = conn.execute(f"SELECT id, name, parent_id FROM {table}").fetchall() by_id = {r["id"]: (r["name"], r["parent_id"]) for r in rows} paths: dict[int, str] = {} def resolve(node_id: int, seen: set[int]) -> str: if node_id in paths: return paths[node_id] name, parent = by_id[node_id] # `seen` guards against a cycle introduced by a bad re-parent. if parent and parent in by_id and parent not in seen: path = resolve(parent, seen | {node_id}) + " / " + name else: path = name paths[node_id] = path return path for node_id in by_id: resolve(node_id, set()) return paths def descendants(conn, table: str, root_id: int) -> list[int]: """A node id plus every id beneath it, so filtering by 'Electronics' catches parts filed under 'Electronics / Resistors'.""" rows = conn.execute(f"SELECT id, parent_id FROM {table}").fetchall() children: dict[int, list[int]] = {} for r in rows: children.setdefault(r["parent_id"], []).append(r["id"]) out, stack, seen = [], [root_id], set() while stack: node = stack.pop() if node in seen: continue seen.add(node) out.append(node) stack.extend(children.get(node, [])) return out def begin_immediate(conn): """Take SQLite's write lock up front. Anything that reads a value, computes from it and writes it back must hold the write lock across all three steps. Python's sqlite3 only begins its implicit transaction at the first *write*, which leaves the preceding read outside the transaction — two concurrent stock adjustments would then read the same starting quantity and one would overwrite the other. """ if not conn.in_transaction: conn.execute("BEGIN IMMEDIATE") # --- search index ----------------------------------------------------------- def reindex_part(conn, part_id: int, cat_paths=None, loc_paths=None): """Rebuild one part's row in the FTS index. The index is a plain (self-contained) FTS5 table rather than an external-content one: it costs a duplicate copy of some short text, and in exchange a delete is just `DELETE ... WHERE rowid = ?` instead of the contentless table's delete-with-original-values dance. Full category and location *paths* are indexed, not just the leaf names, so searching "Workshop" finds what is sitting in "Workshop / Bin A3". That is also why renaming a node has to reindex everything beneath it. """ conn.execute("DELETE FROM parts_fts WHERE rowid = ?", (part_id,)) row = conn.execute( "SELECT name, description, manufacturer, mpn, category_id, location_id " "FROM parts WHERE id = ?", (part_id,), ).fetchone() if row is None: return if cat_paths is None: cat_paths = tree_paths(conn, "categories") if loc_paths is None: loc_paths = tree_paths(conn, "locations") specs = conn.execute( "SELECT key, value FROM part_specs WHERE part_id = ?", (part_id,) ).fetchall() spec_text = " ".join(f"{s['key']} {s['value']}" for s in specs) tags = conn.execute( "SELECT t.name FROM tags t JOIN part_tags pt ON pt.tag_id = t.id WHERE pt.part_id = ?", (part_id,), ).fetchall() tag_text = " ".join(t["name"] for t in tags) conn.execute( """ INSERT INTO parts_fts(rowid, name, description, manufacturer, mpn, specs, tags, category, location) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( part_id, row["name"], row["description"], row["manufacturer"], row["mpn"], spec_text, tag_text, cat_paths.get(row["category_id"], "") if row["category_id"] else "", loc_paths.get(row["location_id"], "") if row["location_id"] else "", ), ) def parts_under(conn, table: str, node_id: int) -> list[int]: """Ids of every part filed at a node or anywhere beneath it.""" column = "category_id" if table == "categories" else "location_id" ids = descendants(conn, table, node_id) marks = ",".join("?" * len(ids)) rows = conn.execute( f"SELECT id FROM parts WHERE {column} IN ({marks})", ids ).fetchall() return [r["id"] for r in rows] def reindex_parts(conn, part_ids): """Reindex a batch, resolving the path tables only once.""" part_ids = list(part_ids) if not part_ids: return cat_paths = tree_paths(conn, "categories") loc_paths = tree_paths(conn, "locations") for part_id in part_ids: reindex_part(conn, part_id, cat_paths, loc_paths) def reindex_all(conn): conn.execute("DELETE FROM parts_fts") reindex_parts(conn, [r[0] for r in conn.execute("SELECT id FROM parts").fetchall()]) def fts_query(text: str) -> str: """Turn free-typed text into a safe FTS5 prefix query. Each whitespace-separated term is quoted (so `10k`, `0.1uF` and `M3x8` can't be read as operators) and given a `*` so search feels live while typing. """ terms = [t for t in text.replace('"', " ").split() if t] return " ".join(f'"{t}"*' for t in terms)