Postgres
The worker and the app run on the config’s databaseUrl, else SANOMA_DATABASE_URL (from the environment or .env; an empty value is none). A URL named is used as it is: sanoma (through sanoma serve), sanoma check and sanoma ledger export probe it first (SELECT 1 on its server’s postgres database, as its user), and stop with a message when nothing answers there or the server refuses the user. For postgresql://postgres:dbos@localhost:5433/sanoma, which earlier versions wrote into .env and started in Docker, the message says to start that container to keep its records, or to remove the line to move to the company’s own.
The tables the runtime makes (the sanoma_* tables in public, and the logins’ in better_auth and better_auth_staff) have row-level security on, with no policy. The runtime’s login makes them, so it owns them and is not affected. Any other role, even one granted SELECT, INSERT, UPDATE and DELETE on them, such as the roles a provider’s data API uses (Supabase’s anon and authenticated), reads no row and inserts, updates or deletes none. It does not stop a superuser, a role with BYPASSRLS (Supabase’s service_role), a member of the owning role, or what a role granted TRUNCATE, TRIGGER or REFERENCES does with them, which row-level security does not limit. So the runtime must connect as the login that owns its tables: one holding grants alone would read nothing, and on a database whose tables another login made, the migration that turns row-level security on fails and the worker does not start. DBOS’s tables, in the schema dbos, are DBOS’s and have none.
With none named, a company runs on its own PostgreSQL 18, from the @sanoma-ai/postgres-<platform> package installed with sanoma (macOS and Linux on arm64 and x64; Windows untested), extracted once into the OS’s cache (~/Library/Caches/sanoma/postgres/<version>-<platform>-<sha> on macOS, under $XDG_CACHE_HOME or ~/.cache on Linux, %LOCALAPPDATA% on Windows), or from SANOMA_POSTGRES_DIR, a directory holding its bin/. Its cluster is .sanoma/postgres in the company’s directory of the main checkout (beside git’s common directory, so a worktree of the repo uses the same one): data/, server.log, password (random, readable by its owner alone) and a .gitignore of its own. It listens on 127.0.0.1 alone, at a port picked when it was made (another when that one is taken), at postgresql://postgres:<password>@127.0.0.1:<port>/sanoma, which sanoma sets as its own SANOMA_DATABASE_URL for the runtime and every child it starts, never in .env. sanoma creates it on the first run (initdb, saying once where the records live), starts it on the next, and uses it as it is while another sanoma on the repo runs it; check runs its scenarios on sanoma_check beside the company’s sanoma. It runs in a process group of its own, so a terminal’s ctrl-c reaches sanoma alone, which stops it after the app and the worker when it started it and no other client is connected (another sanoma’s worker), and leaves it up otherwise. sanoma worker and sanoma app never start it: they exit 2 when it does not run. Deleting .sanoma/postgres deletes the company’s records. PostgreSQL refuses to run as root: there, set SANOMA_DATABASE_URL. A synced folder (iCloud Drive, Dropbox) may copy the files of a running database half-written: keep the repo out of one (sanoma warns in iCloud Drive).
These pages describe sanoma 0.11.24.