53 lines
2.0 KiB
Markdown
53 lines
2.0 KiB
Markdown
# Architecture
|
|
|
|
This document describes the high-level architecture of PostgREST.
|
|
|
|
## Bird's Eye View
|
|
|
|
|
|
|
|
On the highest level, PostgREST processes the user HTTP request, if it's accepted it generates a SQL query, executes it, and produces a response.
|
|
|
|
## Code Map
|
|
|
|
This section talks briefly about various important modules.
|
|
|
|
The starting points of the program are `main/Main.hs` -> `src/PostgREST/CLI.hs` -> `src/PostgREST/App.hs`.
|
|
|
|
`App.hs` is then in charge of composing the different modules.
|
|
|
|
### Auth
|
|
|
|
It authenticates the request using JWT.
|
|
|
|
### ApiRequest
|
|
|
|
PostgREST operates over two types of resources: database relations (tables or views) and database functions; providing different representations (depending on the media type)
|
|
for them.
|
|
|
|
This module is in charge of representing the operation over an `ApiRequest` type. It parses the URL querystring following PostgREST syntax, the request headers, and the request body
|
|
(if possible it avoids parsing the body and sends it directly to the db).
|
|
|
|
A request might be rejected at this level if it's invalid. For example when providing an unknown media type to PostgREST or using an unknown HTTP method.
|
|
|
|
### Plan
|
|
|
|
Using the Schema Cache, this module fills in SQL details that the user might have not specified (like an `ON CONFLICT (pk)` clause ).
|
|
|
|
A request might be rejected at this level if it's invalid. For example when doing resource embedding on a nonexistent resource.
|
|
|
|
### Query
|
|
|
|
This module generates SQL queries that are parametrized and prepared. Only at this stage a connection from the pool might be used.
|
|
|
|
A query might fail (and be rollbacked) at this level if it doesn't comply to certain conditions, e.g. by not returning a single row when a ``Accept: application/vnd.pgrst.object``
|
|
header is specified.
|
|
|
|
### SchemaCache
|
|
|
|
This queries the PostgreSQL system catalogs and caches the results into a SchemaCache type, which then is used by the other modules.
|
|
|
|
### Admin
|
|
|
|
Admin server exposed in another port, it provides health checks.
|