PostgreSQL

What lives there

Everything conversational is in PostgreSQL, in a schema of ivralo's own called ivralo: sessions, the full history of every run, long-term memories, the pointer to your active session, jobs, and the knowledge index. The tables are created on first use. Nothing conversational is written to local disk, so a second machine pointed at the same database continues the same conversation.

pgvector is the extension the knowledge index needs for its embeddings. Sessions and memory do not, but every way below provides it, so the index can be switched on later without changing the database.

One store is deliberately not in PostgreSQL: a repository's code index, .ivralo/index/index.sqlite. It is a cache of what the language server and git say about the code, and deleting it costs a rebuild and nothing else.

Four ways to a database

On a developer's machine ivralo init uses Docker after a yes. On a server, ivralo init --server defaults to --postgres auto, which tries Docker first, then a PostgreSQL installed on this machine, then the one the ivralo[pg] extra carries, and says in its report which one it took.

A rerun never replaces a database that is already configured. To change it, pass --postgres <url>. Moving data from one database to another is not something ivralo does.

Docker

The home's docker-compose.yml runs the pgvector/pgvector:pg17 image, pinned by digest, as a container named ivralo-postgres with a volume named ivralo-pgdata. It publishes the port on 127.0.0.1 only:

cd ~/ivralo && docker compose up -d

The database, user and port come from IVRALO_PG_DB, IVRALO_PG_USER and IVRALO_PG_PORT (by default ivralo, ivralo and 5432). init generates an IVRALO_PG_PASSWORD into .env on a fresh machine. The shipped default password is acceptable only because the port is bound to loopback; if you publish it anywhere else, give the database a password of its own at the same time.

The compose file names one container and one volume for the whole machine, so a second home on the same machine shares the database and needs its password: copy IVRALO_PG_PASSWORD from the first home's .env.

An existing database

ivralo init --server --postgres postgresql://ivralo:secret@db.internal:5432/ivralo ...

The URL is written to .env as IVRALO_DB_URL and never printed, and Docker is not used. ivralo creates its ivralo schema in that database, so the user needs that right. With the knowledge index on, the database also needs the vector extension: run CREATE EXTENSION vector once as a superuser, or let ivralo index enable it.

A cluster ivralo makes

When there is no Docker, ivralo makes a PostgreSQL cluster of its own under <home>/pg/, with:

• initdb and pg_ctl from the PATH, or from the directory pg_config --bindir names; failing that, the PostgreSQL 18 with pgvector that the ivralo[pg] extra carries (a wheel of about 25 MB);
• a generated password, a free port on 127.0.0.1, no socket and no sudo;
• IVRALO_DB_URL written into .env, and CREATE EXTENSION vector run. A PostgreSQL without pgvector is refused, with one line saying what to install.

It is not a daemon and not a service. Every ivralo process that needs the database (a command, the session, ivralo serve, a scheduled run) holds the cluster; the first one starts it and the last one to exit stops it. A process that was killed leaves its hold behind, and the next ivralo process cleans it up.

Managed

--postgres managed makes the same cluster and leaves its start and stop to your service manager. init prints the pg_ctl lines that start and stop it, and ivralo never stops it. When the programs come from the extra, those lines point inside the tool's environment, which a reinstall on another Python moves: write them into a service file only once the install is settled, and read them again from ivralo doctor after an upgrade.

Checking it

ivralo doctor's postgres section says where the database comes from, whether it answers, and on which address its port is published. For a cluster ivralo made it reads like this:

postgres
    ok  postgres from  made by ivralo under /home/ops/ivralo/pg (PostgreSQL <major> programs in <bindir>) - stopped; it starts with the next ivralo
    ok  data directory  /home/ops/ivralo/pg/data · port <port> (loopback only) · pgvector <version>
        back it up with: PGPASSWORD=<the password in IVRALO_DB_URL> <bindir>/pg_dump -h 127.0.0.1 -p <port> -U ivralo ivralo > ivralo-backup.sql
    ok  reachable  PostgreSQL <version> on <platform>

A database that does not answer gets a fix line: start it with: docker compose up -d for Docker's, and a check of the URL for one you named. A password the database refuses is reported as exactly that. Docker's port published beyond loopback while the password is still the default is a failed row. The knowledge section checks the vector extension, and the session section shows the database URL with its password hidden and the schema.

Backups

For a cluster ivralo made, doctor prints the exact pg_dump line, with the cluster's port and the program's full path; the password is the one in IVRALO_DB_URL in the home's .env. For Docker's database or one of your own, back it up as you back up any PostgreSQL; ivralo's tables are all in the ivralo schema:

pg_dump -h 127.0.0.1 -p 5432 -U ivralo ivralo > ivralo-backup.sql

Settings