---
title: Postgres
scope: 3dmk
type: documentation
subject: postgres
group: Systems
status: current
version: "2.1.3"
source: https://3dmk.com/documentation#postgres
author: Nick Olson
contact:
  email: 3dmk@3dmk.com
  site: https://3dmk.com
license: CC BY 4.0
license_url: https://creativecommons.org/licenses/by/4.0/
attribution: Nick Olson, 3dmk.com
---

# Postgres

Postgres is the relational database for the stack. It runs PostgreSQL, an off-the-shelf open-source database. Postgres holds the structured records that must survive a restart: users, projects, work items, history, settings, and the relationships between them. Applications read and change these records while they run.

## Role

Core manages the database for every project. A project does not create databases, run migrations, or manage roles for other services. It supplies numbered schema patches. It provisions its own application role through the Core bootstrap. A shared Core infrastructure repository owns the containers, versions, tuning, and extensions.

## Parts

Postgres has five parts across the development and production hosts.

| Part | What it does |
|---|---|
| `postgres-core` | Holds the general application databases on `core-docker-1`, on the stock PostgreSQL image |
| Seele instance | Holds Seele’s nodes and edges, with the pgvector extension for embedding similarity |
| `core-db` | Applies schema patches, refreshes grants, and provisions service roles |
| Project bootstrap | Hands each project’s patches to `core-db` at every deploy |
| Production instance | Runs on `core-docker-aws-1` under the same name as at home, so services connect the same way in both places |

`core-db` runs a discovery loop. Each cycle finds the Postgres instances in the Consul catalog. It reads their credentials from Vault. It then lists the databases on each instance. Patching never starts on its own. A deploy or an operator starts every run.

## Data

Each project gets its own database. Each service that uses the database gets its own login role. A service role may read and write table data. No service role holds superuser rights.

A schema arrives as numbered SQL patch files, applied in order, each in its own transaction. Every database starts with a required first patch that is safe to run twice.

`core-db` stores a checksum for every patch it applies. A patch edited after it ran fails that check, and `core-db` applies nothing. Each schema therefore matches its patch files. After every successful run, `core-db` refreshes the grants of each service role, so every role reaches a new table at once.

## Connections

Postgres exchanges addresses, credentials, patches, and records with the systems in this table.

| System | What passes |
|---|---|
| Consul | Each instance registers as a service. Services and `core-db` find the instances by name. |
| Vault | Vault holds the password of every role. |
| Publishing | Release deploys hand each project’s patches to `core-db`. Production runs no `core-db`, so there the deploy applies the same patches directly. |
| Applications | Python services connect through the database pool in the shared Core runtime library. |
| Redis | Redis caches data whose durable copy lives in Postgres. NervHQ reloads its cache tables from Postgres after a Redis restart. |
| Seele, Scrolls, and NervHQ | Each keeps its records in its own database. |