README.md

---
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](https://github.com/gradio-app/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`](https://huggingface.co/docs/hub/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:
   ```python
   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](https://huggingface.co/blog/davanstrien/buckets-as-working-layer)

---

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