-
-
Notifications
You must be signed in to change notification settings - Fork 999
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
ab73624
commit b91908b
Showing
1 changed file
with
50 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,53 @@ | ||
# Architecture | ||
|
||
This document describes the high-level architecture of PostgREST. | ||
|
||
## Bird's Eye View | ||
|
||
![PostgREST Architecture](docs/_static/arch.png) | ||
|
||
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 enables more complex functionality (like resource embedding) by enriching the ApiRequest. It generates intermediate Plan types | ||
that then will be used for the next step. | ||
|
||
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. |