jazz-notes-db

SQLite-backed notes store. FastAPI HTTP server with full CRUD for notes with collections and tags.

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /health | Health check — returns {"status": "ok"} | | POST | /notes | Create a note | | GET | /notes | List notes (optional: ?collection=, ?tag=) | | GET | /notes/{id} | Get a note by ID | | PUT | /notes/{id} | Update a note (partial — only supplied fields are changed) | | DELETE | /notes/{id} | Delete a note |

Note object schema

{
  "id":         "string (hex UUID, assigned on creation)",
  "collection": "string or null",
  "title":      "string",
  "text":       "string",
  "tags":       ["string", "..."],
  "created":    "ISO-8601 UTC datetime",
  "updated":    "ISO-8601 UTC datetime"
}

Create / update body

- POST /notes — { "title": "...", "text": "...", "collection": "...", "tags": [] } - PUT /notes/{id} — { "title"?: "...", "text"?: "...", "tags"?: [] } (all fields optional)

---

Configuration

Configuration is driven by environment variables today. The target state for v4.x is a config.json file (see Refactor Plan in the doc-v4 notes collection).

Current environment variables

| Variable | Default | Description | |----------|---------|-------------| | DB_PATH | /data/notes.db | Absolute path to the SQLite database file. The parent directory must exist and be writable. |

Target config.json schema (not yet implemented — documents intended v4.x state)

{
  "db_path":   "/data/notes.db",
  "host":      "0.0.0.0",
  "port":      8001,
  "log_level": "info"
}

Place config.json in the working directory, at /etc/notes_db/config.json, or point to it via the NOTES_DB_CONFIG env var.

---

Install

pip install jazz-notes-db \
  --index-url https://gitlab.com/api/v4/projects/83824314/packages/pypi

---

Docker

# Pull
docker pull registry.gitlab.com/testmonkeyalpha/notes_db:4.0.0

# Run (bind-mount a local data directory so the DB persists across restarts)
mkdir -p ./data
docker run -d \
  --name notes_db \
  -p 8001:8001 \
  -v "$(pwd)/data:/data" \
  -e DB_PATH=/data/notes.db \
  registry.gitlab.com/testmonkeyalpha/notes_db:4.0.0

# Health check
curl http://localhost:8001/health

The container exposes port 8001. The /data directory must be writable by the container process.

---

Development

Prerequisites

- Python 3.11+ - pip install -e ".[test]" (installs FastAPI, uvicorn, aiosqlite, pytest, httpx)

Run locally

# From the services/notes_db directory:
DB_PATH=./local_notes.db uvicorn notes_db.server:app --reload --port 8001

Or via the installed CLI entry point:

DB_PATH=./local_notes.db jazz-notes-db

Run tests

# From services/notes_db:
pytest tests/ -v

Tests use tmp_path fixtures so they never touch a real database and can run fully in parallel.

---

Architecture

jazz-notes-db is intentionally minimal: a single-file FastAPI application backed by SQLite via aiosqlite. Each HTTP request opens its own SQLite connection — acceptable for a low-concurrency internal tool but worth revisiting for higher-load scenarios. Tags are stored as a JSON blob in the tags TEXT column rather than a normalized junction table; this keeps the schema flat and queries simple, at the cost of in-Python tag filtering (rather than indexed SQL). The /data volume convention follows standard Docker practice so the database file survives container restarts without a separate volume driver. Authentication is intentionally omitted — the service is designed to run in a private network and relies on network-layer isolation for access control.

---

Known limitations / open issues

- @app.on_event("startup") is deprecated in FastAPI ≥ 0.93 — will be replaced with a lifespan context manager in a future release. - Tag filtering (?tag=) is done in Python after fetching all rows; this is O(n) on large collections. Planned fix: use SQLite's json_each() function. - No schema migrations — CREATE TABLE IF NOT EXISTS silently leaves old schemas in place. - No full-text search endpoint (SQLite FTS5 support planned). - requirements.txt (used by Dockerfile) and pyproject.toml may drift — verify they are in sync before building images.