Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.
17. Files, transactions and what a crash can leave behind
An API response, a C++ object and bytes on disk are different kinds of state. Quinzee uses several persistence mechanisms because an uploaded Blob, a message lease and a directory permission change have different access patterns. There is no single database transaction spanning all services or a whole ARM deployment.
Follow an atomic JSON replacement
The shared document_file helper writes the complete next document to a sibling
.tmp path, using an owner-private creation mode by default. It handles short
writes and interrupted writes, flushes the file with fsync, closes it and
renames it onto the final path. It then attempts to flush the parent directory.
old state.json remains readable
-> open state.json.tmp -> write all bytes -> fsync -> close
-> rename temporary to state.json -> attempt parent-directory fsync
new opens see the new document
A same-filesystem rename switches the directory entry atomically. A reader does not see half of the new JSON merely because the writer needed several writes. The file flush and directory flush address durability at different levels: the first concerns contents; the second concerns the name-to-inode update.
There are implementation limits worth knowing. This helper uses a fixed sibling temporary name and expects its owner to serialize writes. It is not an interprocess locking service. Its parent-directory open/fsync is best effort: those failures are not reported as strictly as the temporary-file flush failure. It is therefore incorrect to describe every document update as an unconditional power-loss guarantee on every filesystem. Recovery and backups remain necessary.
The private-directory helper applies restrictive permissions when creating a directory but does not generally repair an already existing permissive directory. Likewise, a creation mode is not a recursive chmod of existing state. Specific boundaries such as the directory connection file and LDAP socket parent perform their own stricter checks. Keep the entire state tree owned and protected by the service account; do not rely on a filename extension to protect secrets.
Understand an open, deleted upload file
Large Blob uploads spool through body_file. It creates a mode-0600 temporary
file with mkostemp and close-on-exec, then immediately unlinks its name. The
open file descriptor still refers to the inode. pwrite appends bounded chunks;
pread reads by offset without changing a shared seek position.
This explains an apparent Unix puzzle: the uploads directory can look empty
while disk space is in use. The file has no directory name but is still open.
The kernel reclaims it after the last descriptor/reference closes. A process
exit also closes its descriptors. O_CLOEXEC prevents accidental inheritance
across a later exec; it is not a substitute for normal RAII closure.
Blob publication copies bounded chunks into a named generation and commits metadata. Readers keep an opened immutable generation, so replacing or deleting the Blob name does not change bytes already being downloaded. An old reader can finish while a new reader sees the replacement. This is intentional lifetime management, not evidence that deletion failed.
Separate embedded SQLite from PostgreSQL
Table Storage, Event Grid's delivery outbox and Service Bus use embedded SQLite. SQLite runs as library code inside the cloud process: there is no sqlite daemon, TCP listener or external database container for those stores.
The wrapper opens private files without following a final symlink and enables WAL, synchronous FULL, foreign keys and an untrusted schema setting. It uses a busy timeout, bound SQL parameters and a maximum page count. Provider code adds its own record/message/size limits and synchronization.
In WAL mode, a committed transaction may reside in the -wal file before a
checkpoint copies its pages into the main database. The -shm file supports
shared coordination. Copying the main .db alone while the service is live can
lose committed changes. Do not delete WAL files to “unlock” a running store.
Use a supported database backup method or a stopped, consistent instance copy.
One Table entity-group transaction either commits its changes or rolls them back. One Service Bus topic publication commits the subscription copies together. Neither transaction includes arbitrary updates to another provider or external engine. PostgreSQL-backed identity is a separate connection/session and is explained in the next chapter.
Inspect metadata, not private contents
For the standard stopped or running local instance, these commands inspect ownership and sizes without printing credentials or document bodies:
stat -c '%a %U:%G %n' .local/quinzee .local/quinzee/credentials.json
du -sh .local/quinzee
cloud_pid=12345
ls -l "/proc/$cloud_pid/fd"
cat "/proc/$cloud_pid/io"
Choose your actual lab PID. Open descriptors may show sockets, databases or
(deleted) payload files. Do not read through /proc/<pid>/fd/N: that can expose
data and can interact with a descriptor's underlying object. /proc/.../io
reports process-level counters, not a per-service audit or proof that storage
hardware has honoured every flush.
Reason about interruption at the right boundary
| Interrupted operation | What to investigate after restart |
|---|---|
| JSON replacement before rename | Old committed document; a leftover temporary file may exist |
| Blob upload before publication | No completed object from that request; unlinked spool descriptors close on exit |
| Blob replacement with an active reader | Old opened generation can outlive the name change |
| SQLite transaction | SQLite recovery and the provider's acknowledged transaction boundary |
| ARM deployment after some resources succeeded | Failed deployment history and retained completed resources; no universal rollback |
| External SQL write | Native engine transaction/WAL or redo recovery, independent of cloud metadata |
| Directory migration | PostgreSQL contents plus local destination marker and the retained legacy input |
Avoid editing live JSON or SQL to force a desired status. Those files are private implementation state; changing them bypasses locks, validation, revisions and ownership checks. A useful recovery drill restores matching state and dependencies and then exercises public APIs, rather than merely proving that an archive opens.