README.md

metadata

title: bucket-sqlite-probe-gradio
emoji: 🧪
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 5.49.0
app_file: app.py
pinned: false
tags:
  - bucket
  - sqlite
  - probe
  - reference

Bucket mount × SQLite probe — Gradio SDK Space

A minimal reference Space demonstrating how HF Storage Buckets mount into a Gradio SDK Space container, and what SQLite / fcntl.flock / file write operations look like against that mount.

This Space is half of a matched pair used to answer the question: "does the bucket-mount-with-SQLite pattern work on HF Spaces?" — and if so, under what conditions?

What it does

On startup (and on every button click), the app:

1. Prints the container's runtime identity (uid, euid, gid, HOME, SYSTEM, SPACE_ID).
2. Runs ls -lan /data, stat /data, and mount | grep /data against the mounted bucket.
3. Tries to touch a file on the mount.
4. Tries to sqlite3.connect(...).execute("CREATE TABLE ...") — both with the default journal mode and with PRAGMA journal_mode = DELETE (the mode trackio forces on Spaces).
5. Tries fcntl.flock(LOCK_EX | LOCK_NB) for POSIX advisory locking.

All output is captured into the log stream at startup (so you can read it via hf api or the Space logs tab) and surfaced via a gr.Textbox for casual browsing.

What we learned (2026-04-08)

With bucket davanstrien/search-v2-chroma attached R/W at /data:

uid=0 user=root euid=0 gid=0
SYSTEM='spaces'
SPACE_ID='davanstrien/bucket-sqlite-probe-gradio'
HOME='/root'

Access: (0755/drwxr-xr-x)  Uid: (65534/  nobody)   Gid: (65534/ nogroup)

hf-mount on /data type fuse (rw,nosuid,nodev,relatime,idmapped,user_id=0,group_id=0,default_permissions,allow_other)

OK   touch /data/gradio_probe_touch
OK   sqlite3 connect + CREATE + INSERT
OK   sqlite3 journal_mode=DELETE
OK   fcntl.flock LOCK_EX|LOCK_NB

Key facts established by this Space:

Fact	Evidence
Gradio SDK Spaces run as root (UID 0)	uid=0 user=root above
Bucket mounts land owned by nobody:nogroup (UID 65534), perms drwxr-xr-x (755)	ls -lan + stat
The FUSE mount is idmapped with user_id=0, group_id=0 — i.e. the mount provisioning layer explicitly pins the UID map to root	mount | grep /data
default_permissions is set — standard POSIX checks apply	same line
SQLite opens + writes fine from root	probe passes
SQLite with journal_mode = DELETE works (as trackio does on Spaces)	probe passes
FUSE supports fcntl.flock (advisory locking)	probe passes

What it implies: Gradio/Streamlit SDK Spaces and any container that runs as root can use bucket mounts for SQLite-style workloads today — this is what trackio does. The idmapped,user_id=0,group_id=0 mount option is the reason — it's also the reason the pattern doesn't work out of the box for Docker SDK Spaces that follow the official spaces-sdks-docker#permissions guidance to run as UID 1000 (see the matched Docker SDK probe Space, if published).

How to reproduce

1. Fork or duplicate this Space.
2. Create a Storage Bucket in your namespace (or reuse one you own).
3. Attach it R/W at /data via Space settings → Variables and secrets → Volumes (UI), or programmatically:

   from huggingface_hub import HfApi, Volume  # requires huggingface_hub >= 1.9.1
   HfApi().set_space_volumes(
       "your-namespace/bucket-sqlite-probe-gradio",
       volumes=[Volume(type="bucket", source="your-namespace/your-bucket", mount_path="/data")],
   )
   

4. Restart the Space. The startup probe output appears in the logs; the button re-runs the probe on demand.

Related

• Matched Docker SDK probe Space (failing, UID 1000): https://huggingface.co/spaces/davanstrien/bucket-sqlite-probe-docker
• gradio-app/trackio#465 — trackio's PR switching to bucket backend
• trackio/sqlite_storage.py — WAL-disable + flock pattern for SQLite on Spaces
• huggingface/huggingface_hub#4054 — set_space_volumes payload fix (required for this Space to work)
• Blog: Buckets as working layer

---

Throwaway investigative Space. Kept public as a reference example. Do not rely on for production.