Skip to content

0003. PostgreSQL as the database

  • Status: Accepted
  • Date: 2026-10-01

Context

BizOS stores relational business data (customers, opportunities, contracts, transactions, tasks) with strict consistency needs, plus flexible data such as custom fields and AI-related records. Tenant data must be isolated, and the platform needs a control-plane store for tenants, operators, and subscriptions.

Options considered

  1. PostgreSQL: mature, open source, strong transactions and constraints, JSONB for flexible fields, full-text search, and the pgvector extension for AI embeddings; supported by every major NestJS ORM.
  2. MySQL or MariaDB: widely used, but weaker JSON and extension support.
  3. A document database (for example MongoDB): flexible schema, but weaker relational integrity for business records and reporting.

Decision

Use PostgreSQL for the control plane and for tenant data.

Consequences

  • One database engine to run, back up, monitor, and learn.
  • JSONB covers custom fields and pgvector can cover embeddings later, avoiding extra data stores early on.
  • The tenancy model (database per tenant versus schema per tenant) is a separate decision; STACK.md lists it as proposed.
  • The ORM choice must work well with PostgreSQL migrations across many tenant databases.