The SQL schema
Everything the hub keeps is kept in one database, and the schema is the map of that database: which tables there are and what each row holds, and how the tables relate. You never see the schema when you use the hub, but it is underneath every page, and it decides what the API can do, because the API is made from it.
The database is PostgreSQL. The schema is written in Drizzle, a TypeScript library for describing tables, in the backend, one file for each Postgres schema. That description is the source of truth: the generated routes, the validation of what a program sends, the OpenAPI document and the SDKs are all derived from it.
Topics
- Planes: how the schemas are grouped by what they hold, and the roles that reach each group.
- Conventions: the rules every table follows, from how it is named to how one tenant's rows are kept from another's.
- The schemas: one entry per schema, with its tables.
- Exposure: which tables a program can reach directly, and which only through a hand-written route.
- Migrations: how a change to the schema is written and applied.
- Languages
- TypeScript
- APIs & protocols
- OpenAPI
The schema is the source of truth. A table is a route. A column's type is its validation. The OpenAPI document and the SDKs are derived from the schema. Nothing is described twice.
Separate planes in one database. Control, tenant and data are separate schemas with separate roles, so they can be split into separate databases later without renaming anything.
Tenancy lives in the database. A forced policy on the application role means a handler cannot leak another tenant's rows by forgetting a filter.
No foreign keys across schemas. Schemas can move between planes and databases without a web of constraints holding them together. The application owns referential integrity across the line.
Enumerations are checked strings. A new value is a migration that edits a constraint, not a type rebuild that locks a table.
Markdown is one table. Docs, notes, papers and posts all share content.markdown, so search, chunks, versions and recall exist once.