Configure PostgreSQL
One PostgreSQL instance serves four kinds of consumer. Create the database, install the extensions, create the accounts, and size the connections here in one pass; the installation sections for the individual services only fill in a connection string.
← Documentation index · Previous: Install Istio · Next: Edge nginx
1. Only one database instance
FewBox does not split databases per service. Users, the credits ledger, sessions and messages, Agent definitions, jobs, and heartbeats all live in the same PostgreSQL instance, isolated by schema and table-name prefixes. The reason is simple: cross-service consistency (signup bonus, ledger and subscriptions) would become a distributed transaction if the databases were split, and single-machine POCs and mid-sized deliveries do not need that complexity at all.
| Consumer | How it connects | What it stores | Schema script |
|---|---|---|---|
themis-auth |
DATABASE_URL |
Users, organizations, credentials, OIDC clients, sessions | themis-auth-init.sql, full text in Database schema |
thia-agent |
DATABASE_URL |
Sessions and messages, attachments, memory vectors, Agent definitions, scheduled jobs | thia-agent-init-db.sql, full text in Database schema |
rhea-payment |
DATABASE_URL |
Orders, credits, transactions, packages, Stripe mappings | rhea-payment-init-db.sql, full text in Database schema |
mcp-analysis |
PG_DATABASES (JSON array) |
Creates no tables; only reads the databases above | — |
rhea-payment'sDATABASE_URLnot being set does not fail startup — it falls back to an in-memory store: the UI shows a balance, a restart resets it to zero, and the database has no row to find. This is the failure most easily mistaken for "the feature was never built"; after installation you must go into the database and confirm one real row.
2. Versions and extensions
| Requirement | Value | What happens if it is not met |
|---|---|---|
| PostgreSQL | 14 or later (15+ in the reference environment) | Syntax and index-type differences; a migration may fail halfway |
pgvector |
Required | thia-agent's vector(1024) column cannot be created, and the memory and conversation migrations fail |
| Encoding | UTF8 | Chinese content and emoji are stored incorrectly |
| Time zone | UTC | Scheduled jobs such as "every day at 9" are computed in the database time zone; once it is off, the error is hard to spot |
Install the extensions (requires a superuser or an account with the CREATE EXTENSION privilege):
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm; -- fuzzy search, optional but recommended
Verify:
SELECT extname, extversion FROM pg_extension;
3. Accounts: at least three
| Account | Privileges | Assigned to |
|---|---|---|
| Migration account | Create tables, create extensions, alter the schema | Used only during installation and upgrades; it never goes into any Deployment |
| Application account | SELECT/INSERT/UPDATE/DELETE within the target schema |
Shared by the three services (one database, separated by schema) |
| Read-only account | Only SELECT; adding statement_timeout is recommended |
mcp-analysis |
Do not write a superuser connection string into a Deployment. The application side does not need DDL privileges; grant too much and one mistaken statement can alter the table structure. Run migrations with a separate account, outside the cluster.
4. Connections: calculate first, then configure
Each service process holds one connection pool. The pool size is per Pod, so the total is a multiplication:
Peak connections ≈ Σ(replicas per service × that service's pool limit) + migration/troubleshooting overhead + headroom
In the reference environment (one replica each, pool limit 10): themis-auth 10 + thia-agent 10 + rhea-payment 10 + mcp-analysis 5 + headroom 5 ≈ 40. If your managed PG defaults to max_connections=60, that already takes two thirds —
one more replica and it can no longer connect.
Two rules of thumb:
- A managed service usually puts a connection pooler (PgBouncer and the like) in front. A transaction-mode pooler does
not support session-level prepared statements / temporary tables; if you see
prepared statement ... does not exist, confirm the pooler mode first, then decide whether to change the driver or the pooler mode — do not rush to raisemax_connections; - Before doubling the replica count, compute the total pool size once. This failure looks like intermittent 500s and
timeouts, with
too many clientsin the log — not a startup failure.
Where each service configures its pool parameters: thia-agent in the image's config/agentic.yaml (the store section) or
through environment variables; themis-auth / rhea-payment through connection-string parameters (such as ?max=10).
Restart the Pod after changing them — environment variables are not hot-reloaded.
5. Creating tables: order matters more than content
Each database has one initialisation script, and each script is complete — a new database only needs that one run, with no historical migration files to apply afterwards. The full text of all three and the exact commands are in Database schema; they do not depend on each other, but the order is required:
- Create the databases and extensions first (section 2 of this document);
- themis-auth — it has no other dependency;
- thia-agent — must come before you create scheduled jobs, otherwise the job runtime silently
degrades to off,
/jobs/*returnsdisabled, and the process does not exit; - rhea-payment — themis-auth's signup bonus writes
user_credits; when the table is missing, signup still succeeds, and the signup bonus is silently not granted.
Always run with psql -v ON_ERROR_STOP=1, otherwise a failure halfway through does not stop the run and the
remaining statements execute anyway.
A missing table raises no error. Startup succeeds, every probe is green, and pages open — until the first time a feature queries that table, when you get a 500. After installation you must run the verification command at the end of each section in manual deployment.
6. Post-install self-check
# Connectivity (run it from a Pod inside the cluster; this verifies the Service and network policies, not just the host)
kubectl -n <namespace> exec deploy/<any-stateless-service> -- \
psql "$DATABASE_URL" -c 'select version();'
# Extensions
psql "$DATABASE_URL" -c "select extname from pg_extension where extname='vector';"
# Did the tables really get created? (look at each of the three databases)
psql "$DATABASE_URL" -c '\dt' | head -20
# Connections and the limit
psql "$DATABASE_URL" -c 'show max_connections;'
psql "$DATABASE_URL" -c 'select count(*) from pg_stat_activity;'
Look at the last one after all services are running — the numbers are not meaningful at idle.
7. Backup
Only three things need a backup: PostgreSQL, the keys, and the Bundle. The database is the only one that cannot be
rebuilt; the rest are covered in upgrade, rollback and backup. Minimum requirement: one
pg_dump -Fc per day, keep 7 copies; take one extra before an upgrade. Run a restore drill at least once a year — a
backup you have never restored does not count as a backup.