# 19.1 Why a database now (/building-ai-workers/business-data-and-retrieval/why-a-database-now)

---
type: Document
title: "19.1 Why a database now"
description: "Why business data moves from files shipped with the code into a database server, and why it gets a different database from the sign-in data."
status: stable
order: 319.01
ksor:
  owner: team:panaversity
  audience: [ public ]
  approval:
    by: process:panaversity
    at: 2026-11-04T22:13:33Z
chapter: "19"
part: III
expert_status: co-build
concepts: [ "19.1" ]
objectives:
  - { id: CCDV-F.D8.S2, label: supporting }
last_verified: 2026-11-02
generated:
  at: 2026-11-04T22:13:33Z
  by: process:panaversity
trust_tier: unverified
build_id: sha256:e1fbcb7d9a8f8b9b7cb96875022325c02c9ba4be94cef13b301cbd39a9edad85
dirty: true
ksor_version: 0.0.60
---

**In everyday life.** A small shop keeps its customer list in a notebook by the till. With one till and one person, that works. Open a second shop across town and the notebook cannot be in both places. Make a copy for each shop and, by Friday, the two copies disagree. Every business that grows past one notebook moves its records into one place that everyone reads and writes, with rules about who may change what.

**What you will learn.** Why a connector's business data moves out of files shipped with the code, and why it gets a database of its own, apart from the sign-in data.

**Why it matters.** Files shipped with the code mean a new deploy for every changed invoice, and a second company's files inside every copy. One wrong folder name, and one company reads another's invoices.

**One request, start to finish.** Luis Moreno, Cedar Ridge Supply's AP lead, asks the builder to connect Cedar Ridge's data. In [Chapter 17](../connectors-and-mcp/overview.md)'s design, the data is files shipped inside the connector's code. So connecting Cedar Ridge would mean:

1. Adding Cedar Ridge's files to the code, beside Brightline's, in every copy of the connector.
2. Deploying again every time one invoice changes.
3. Trusting each line of code to read the right company's folder.

Every copy would carry both companies' invoices. One wrong folder name and Luis reads Brightline's.

### What replaces the files?

Files shipped with the code were right for Chapter 17: one company, sample rows, read-only. They stop working as soon as there is a second company, data that changes, or many copies that must agree. A **database server** is a program that holds the records in one place, answers questions from many copies at once, and enforces rules on every row it stores. This book uses **Postgres**, also called PostgreSQL, a free, open-source database server used by companies of every size. It keeps tables, which [19.2](tables-rows-and-keys-from-zero.md) shows from zero, answers SQL, and has a feature, row-level security ([19.8](row-level-security.md)), that keeps each company's rows apart by itself.

### Why one database for records and for meaning?

An AI worker needs two kinds of data. The first is business records: vendors, invoices, purchase orders, each linked to the others and checked by rules. The second is **embeddings**: lists of numbers that let a search find text by meaning, not by shared words ([19.13](retrieval-from-zero.md)). Many systems keep the two in two databases, one for the records and a separate "vector database" for the embeddings, and then must keep the two in step, and apply every access rule twice. Postgres, with an add-on called **pgvector**, keeps both in the same tables. One query can filter by company, join a passage to its document, and order by meaning, under one set of rules. That is why this book treats Postgres and pgvector as the data foundation for AI workers. And because both are open source and run on many hosts, the design is portable: the same tables and rules run wherever Postgres does.

### Why does the sign-in data keep its own database?

[Chapter 18](../securing-connectors/overview.md)'s sign-in data (people, companies, memberships, tokens) stays in its own database. The business data (vendors, invoices, purchase orders, policies) gets a new one, the **business database**. They are kept apart for three reasons:

| | Sign-in database | Business database |
| --- | --- | --- |
| Who changes it | The sign-in server, when people sign in or join a company | The loader, the script that brings a company's data in |
| How it changes | Constantly, a row per sign-in | In batches, when a company sends new data |
| What a leak would expose | Who works where, and their tokens | Invoices, vendors, bank details |

A leak of one must not expose the other, and a change to one must not wait for the other. No query ever reaches from one into the other. The connector reads the business database. It never reads the sign-in database: it learns the company from the token, as in Chapter 18.

**At work.** In [Lab 19](lab.md), Task 0, Claude Code creates the business database as a fresh, empty project on the hosting service (the project holds the database and its copies, which [19.6](changing-the-tables-safely.md) calls branches), with a `dev` copy for the builder's own work, and checks that no secret reached a file git tracks. The sign-in server from Chapter 18 keeps its own database, untouched.

**The operating rule:** keep business data in a database server, not in files shipped with the code, and keep it in a different database from the sign-in data.