"""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")) _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); CREATE VIRTUAL TABLE IF NOT EXISTS parts_fts USING fts5( name, description, manufacturer, mpn, specs, tags, category, location, tokenize='unicode61 remove_diacritics 2' ); """ 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) conn = connect() try: conn.executescript(SCHEMA) conn.commit() from .seed import seed seed(conn) finally: conn.close() _initialised = True @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)