---
module: platform.data-stores
title: Data Stores — Postgres DBs & Table Ownership
tab: Overview
order: 10
audience: dev
---

> **DRAFT · internal.** Written 2026-07-01. Pairs with **platform.data-architecture** (the
> executor→Kafka→record-store pattern) and **platform.service-ownership**. Verify a table's owner
> in the owning service's code before writing to it.

## One database per service

All databases run on the **hiveiq-database VM (10.10.10.188)**, user `hiveiq`, reached via
ProxyJump (see **platform.topology**). Each service owns exactly one database — do not cross-write.

| Database | Owning service |
|----------|----------------|
| `hiveiq_config` | hiveops-config |
| `hiveiq_auth` | hiveops-auth |
| `hiveiq_mgmt` | hiveops-mgmt (users, institutions, licenses, app_modules, allocations) |
| `hiveiq_incident` | hiveops-incident |
| `hiveiq_journal` | hiveops-journal |
| `hiveiq_remote` | hiveops-remote |
| `hiveiq_messaging` | hiveops-messaging |
| `hiveiq_reports` | hiveops-reports |
| `hiveiq_analytics` | hiveops-analytics |
| `hiveiq_agent` | hiveops-agent-proxy (agent_connections, machine fingerprints) |

> Newer services (devices, fleet, recon, vault, aria, claims) each own their own DB too — confirm
> the exact name in that service's `application.yml` (the per-service guides will pin these).

## Ownership rule (non-negotiable)

Every endpoint/table belongs to **exactly one** service:
- **incident** = incidents · **fleet** = fleet tasks · **devices** = everything device-related ·
  **mgmt** = users/institutions/licenses.

Never add an endpoint or write to another service's domain. See **platform.service-ownership**.

## device_summary is MIRRORED into 4 services

Device data is mirrored into a `device_summary` table inside **incident, fleet, reports, recon**
(and now vault) via the Kafka topic **`hiveops.device.events`** (see **platform.kafka**).

- **devices is the source of truth**; it must publish on **every** device change.
- There is **no reconciler** — if devices fails to publish, all mirrors go stale independently.
- Symptom of a stale mirror: *"wrong institution / stale device in app X but correct in devices."*
  That is a missed/failed publish, not a bug in app X.

## Journal specifics

- `hiveops-journal` reads env var **`DB_URL`** (a full JDBC URL) — NOT the split
  `DB_HOST`/`DB_PORT`/`DB_NAME` other services use.
- Journal processing runs **per-institution workers** (1 upload + N institution + unassigned
  containers) with a dedup guard. Always reconcile counts after a journal deploy.

## Institution scoping

Device institution is **auto-derived from the agent token's `X-Institution-Key`**, only when
blank, and **never overwritten**. A mis-imaged box (wrong token) yields a sticky wrong
institution — diagnose via `hiveiq_agent.agent_connections` and use device LOCATION to find the
true owner.

## Do NOT
- Do not write to a table owned by another service — publish an event or call its API.
- Do not treat a stale mirror as the owner being wrong — fix the publish path in devices.
- Do not assume a service's DB name — confirm in its `application.yml`.
