Lesson 19.119.1 Why a database now

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'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 shows from zero, answers SQL, and has a feature, row-level security (19.8), 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). 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'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:

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, 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 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.