---
title: PostgreSQL + TimescaleDB
type: entity
created: 2026-04-30
updated: 2026-04-30
sources: [gps-tracking-architecture]
tags: [infrastructure, business-plane, database]
---

# PostgreSQL + TimescaleDB

The durable storage layer. PostgreSQL with the TimescaleDB extension. Holds the positions hypertable and all business schema owned by [[directus]].

## Writers

- **[[processor]]** — sole writer for high-volume telemetry (positions hypertable) and writer for derived business entities (events, violations, alerts).
- **[[directus]]** — writes from the admin UI, custom endpoints, and Flows. Owns schema definition and migrations.

[[react-spa]] never writes (or reads) directly. [[tcp-ingestion]] does not touch the database.

## Schema authority

Schema is **defined and migrated through [[directus]]** — see that page for why. The Processor inserts rows respecting that schema; it does not create tables.

## Operational note

The database is the **only single point of failure** in the architecture. Everything else is restartable, replaceable, or naturally redundant. Operational attention concentrates here:

- Replication
- Backups
- Point-in-time recovery via TimescaleDB

## Scaling

- **Vertical** for write throughput.
- **Read replicas** for analytics workloads.

## Deployment

Internal-only container. Persistence volume. Regular backups. Accessed only by [[directus]] and [[processor]].