remove manual inclusion of pages on index
* drop unavailable doc pages from release notes * rename releases pages so they order in TOC
This commit is contained in:
steve-chavez
committed by
Steve Chavez
Steve Chavez
parent
36300da16d
commit
79620396ed
@@ -0,0 +1,359 @@
|
||||
.. _admin:
|
||||
|
||||
Admin
|
||||
#####
|
||||
|
||||
Hardening PostgREST
|
||||
===================
|
||||
|
||||
PostgREST is a fast way to construct a RESTful API. Its default behavior is great for scaffolding in development. When it's time to go to production it works great too, as long as you take precautions. PostgREST is a small sharp tool that focuses on performing the API-to-database mapping. We rely on a reverse proxy like Nginx for additional safeguards.
|
||||
|
||||
The first step is to create an Nginx configuration file that proxies requests to an underlying PostgREST server.
|
||||
|
||||
.. code-block:: nginx
|
||||
|
||||
http {
|
||||
# ...
|
||||
# upstream configuration
|
||||
upstream postgrest {
|
||||
server localhost:3000;
|
||||
}
|
||||
# ...
|
||||
server {
|
||||
# ...
|
||||
# expose to the outside world
|
||||
location /api/ {
|
||||
default_type application/json;
|
||||
proxy_hide_header Content-Location;
|
||||
add_header Content-Location /api/$upstream_http_content_location;
|
||||
proxy_set_header Connection "";
|
||||
proxy_http_version 1.1;
|
||||
proxy_pass http://postgrest/;
|
||||
}
|
||||
# ...
|
||||
}
|
||||
}
|
||||
|
||||
.. note::
|
||||
|
||||
For ubuntu, if you already installed nginx through :code:`apt` you can add this to the config file in
|
||||
:code:`/etc/nginx/sites-enabled/default`.
|
||||
|
||||
.. _block_fulltable:
|
||||
|
||||
Block Full-Table Operations
|
||||
---------------------------
|
||||
|
||||
Each table in the admin-selected schema gets exposed as a top level route. Client requests are executed by certain database roles depending on their authentication. All HTTP verbs are supported that correspond to actions permitted to the role. For instance if the active role can drop rows of the table then the DELETE verb is allowed for clients. Here's an API request to delete old rows from a hypothetical logs table:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. code-tab:: http
|
||||
|
||||
DELETE /logs?time=lt.1991-08-06 HTTP/1.1
|
||||
|
||||
.. code-tab:: bash Curl
|
||||
|
||||
curl "http://localhost:3000/logs?time=lt.1991-08-06" -X DELETE
|
||||
|
||||
However it's very easy to delete the **entire table** by omitting the query parameter!
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. code-tab:: http
|
||||
|
||||
DELETE /logs HTTP/1.1
|
||||
|
||||
.. code-tab:: bash Curl
|
||||
|
||||
curl "http://localhost:3000/logs" -X DELETE
|
||||
|
||||
This can happen accidentally such as by switching a request from a GET to a DELETE. To protect against accidental operations use the `pg-safeupdate <https://github.com/eradman/pg-safeupdate>`_ PostgreSQL extension. It raises an error if UPDATE or DELETE are executed without specifying conditions. To install it you can use the `PGXN <https://pgxn.org/>`_ network:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo -E pgxn install safeupdate
|
||||
|
||||
# then add this to postgresql.conf:
|
||||
# shared_preload_libraries='safeupdate';
|
||||
|
||||
This does not protect against malicious actions, since someone can add a url parameter that does not affect the result set. To prevent this you must turn to database permissions, forbidding the wrong people from deleting rows, and using `row-level security <https://www.postgresql.org/docs/current/ddl-rowsecurity.html>`_ if finer access control is required.
|
||||
|
||||
Count-Header DoS
|
||||
----------------
|
||||
|
||||
For convenience to client-side pagination controls PostgREST supports counting and reporting total table size in its response. As described in :ref:`limits`, responses ordinarily include a range but leave the total unspecified like
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Range-Unit: items
|
||||
Content-Range: 0-14/*
|
||||
|
||||
However including the request header :code:`Prefer: count=exact` calculates and includes the full count:
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
HTTP/1.1 206 Partial Content
|
||||
Range-Unit: items
|
||||
Content-Range: 0-14/3573458
|
||||
|
||||
This is fine in small tables, but count performance degrades in big tables due to the MVCC architecture of PostgreSQL. For very large tables it can take a very long time to retrieve the results which allows a denial of service attack. The solution is to strip this header from all requests:
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
-- Pending nginx config: Remove any prefer header which contains the word count
|
||||
|
||||
.. _https:
|
||||
|
||||
HTTPS
|
||||
-----
|
||||
|
||||
PostgREST aims to do one thing well: add an HTTP interface to a PostgreSQL database. To keep the code small and focused we do not implement HTTPS. Use a reverse proxy such as NGINX to add this, `here's how <https://nginx.org/en/docs/http/configuring_https_servers.html>`_. Note that some Platforms as a Service like Heroku also add SSL automatically in their load balancer.
|
||||
|
||||
Rate Limiting
|
||||
-------------
|
||||
|
||||
Nginx supports "leaky bucket" rate limiting (see `official docs <https://nginx.org/en/docs/http/ngx_http_limit_req_module.html>`_). Using standard Nginx configuration, routes can be grouped into *request zones* for rate limiting. For instance we can define a zone for login attempts:
|
||||
|
||||
.. code-block:: nginx
|
||||
|
||||
limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;
|
||||
|
||||
This creates a shared memory zone called "login" to store a log of IP addresses that access the rate limited urls. The space reserved, 10 MB (:code:`10m`) will give us enough space to store a history of 160k requests. We have chosen to allow only allow one request per second (:code:`1r/s`).
|
||||
|
||||
Next we apply the zone to certain routes, like a hypothetical stored procedure called :code:`login`.
|
||||
|
||||
.. code-block:: nginx
|
||||
|
||||
location /rpc/login/ {
|
||||
# apply rate limiting
|
||||
limit_req zone=login burst=5;
|
||||
}
|
||||
|
||||
The burst argument tells Nginx to start dropping requests if more than five queue up from a specific IP.
|
||||
|
||||
Nginx rate limiting is general and indiscriminate. To rate limit each authenticated request individually you will need to add logic in a :ref:`Custom Validation <custom_validation>` function.
|
||||
|
||||
Debugging
|
||||
=========
|
||||
|
||||
Server Version
|
||||
--------------
|
||||
|
||||
When debugging a problem it's important to verify the PostgREST version. At any time you can make a request to the running server and determine exactly which version is deployed. Look for the :code:`Server` HTTP response header, which contains the version number.
|
||||
|
||||
.. _pgrst_logging:
|
||||
|
||||
Logging
|
||||
-------
|
||||
|
||||
PostgREST logs basic request information to ``stdout``, including the authenticated user if available, the requesting IP address and user agent, the URL requested, and HTTP response status.
|
||||
|
||||
.. code::
|
||||
|
||||
127.0.0.1 - user [26/Jul/2021:01:56:38 -0500] "GET /clients HTTP/1.1" 200 - "" "curl/7.64.0"
|
||||
127.0.0.1 - anonymous [26/Jul/2021:01:56:48 -0500] "GET /unexistent HTTP/1.1" 404 - "" "curl/7.64.0"
|
||||
|
||||
For diagnostic information about the server itself, PostgREST logs to ``stderr``.
|
||||
|
||||
.. code::
|
||||
|
||||
12/Jun/2021:17:47:39 -0500: Attempting to connect to the database...
|
||||
12/Jun/2021:17:47:39 -0500: Listening on port 3000
|
||||
12/Jun/2021:17:47:39 -0500: Connection successful
|
||||
12/Jun/2021:17:47:39 -0500: Config re-loaded
|
||||
12/Jun/2021:17:47:40 -0500: Schema cache loaded
|
||||
|
||||
.. note::
|
||||
|
||||
When running it in an SSH session you must detach it from stdout or it will be terminated when the session closes. The easiest technique is redirecting the output to a log file or to the syslog:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ssh foo@example.com \
|
||||
'postgrest foo.conf </dev/null >/var/log/postgrest.log 2>&1 &'
|
||||
|
||||
# another option is to pipe the output into "logger -t postgrest"
|
||||
|
||||
PostgREST logging provides limited information for debugging server errors. It's helpful to get full information about both client requests and the corresponding SQL commands executed against the underlying database.
|
||||
|
||||
HTTP Requests
|
||||
-------------
|
||||
|
||||
A great way to inspect incoming HTTP requests including headers and query parameters is to sniff the network traffic on the port where PostgREST is running. For instance on a development server bound to port 3000 on localhost, run this:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
# sudo access is necessary for watching the network
|
||||
sudo ngrep -d lo0 port 3000
|
||||
|
||||
The options to ngrep vary depending on the address and host on which you've bound the server. The binding is described in the :ref:`configuration` section. The ngrep output isn't particularly pretty, but it's legible.
|
||||
|
||||
Database Logs
|
||||
-------------
|
||||
|
||||
Once you've verified that requests are as you expect, you can get more information about the server operations by watching the database logs. By default PostgreSQL does not keep these logs, so you'll need to make the configuration changes below. Find :code:`postgresql.conf` inside your PostgreSQL data directory (to find that, issue the command :code:`show data_directory;`). Either find the settings scattered throughout the file and change them to the following values, or append this block of code to the end of the configuration file.
|
||||
|
||||
.. code:: sql
|
||||
|
||||
# send logs where the collector can access them
|
||||
log_destination = "stderr"
|
||||
|
||||
# collect stderr output to log files
|
||||
logging_collector = on
|
||||
|
||||
# save logs in pg_log/ under the pg data directory
|
||||
log_directory = "pg_log"
|
||||
|
||||
# (optional) new log file per day
|
||||
log_filename = "postgresql-%Y-%m-%d.log"
|
||||
|
||||
# log every kind of SQL statement
|
||||
log_statement = "all"
|
||||
|
||||
Restart the database and watch the log file in real-time to understand how HTTP requests are being translated into SQL commands.
|
||||
|
||||
.. note::
|
||||
|
||||
On Docker you can enable the logs by using a custom ``init.sh``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
#!/bin/sh
|
||||
echo "log_statement = 'all'" >> /var/lib/postgresql/data/postgresql.conf
|
||||
|
||||
After that you can start the container and check the logs with ``docker logs``.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
docker run -v "$(pwd)/init.sh":"/docker-entrypoint-initdb.d/init.sh" -d postgres
|
||||
docker logs -f <container-id>
|
||||
|
||||
Schema Reloading
|
||||
----------------
|
||||
|
||||
Changing the schema while the server is running can lead to errors due to a stale schema cache. To learn how to refresh the cache see :ref:`schema_reloading`.
|
||||
|
||||
.. _health_check:
|
||||
|
||||
Health Check
|
||||
------------
|
||||
|
||||
You can enable a minimal health check to verify if PostgREST is available for client requests and to check the status of its internal state.
|
||||
|
||||
To do this, set the configuration variable :ref:`admin-server-port` to the port number of your preference. Two endpoints ``live`` and ``ready`` will then be available.
|
||||
|
||||
The ``live`` endpoint verifies if PostgREST is running on its configured port. A request will return ``200 OK`` if PostgREST is alive or ``503`` otherwise.
|
||||
|
||||
The ``ready`` endpoint also checks the state of both the Database Connection and the :ref:`schema_cache`. A request will return ``200 OK`` if it is ready or ``503`` if not.
|
||||
|
||||
For instance, to verify if PostgREST is running at ``localhost:3000`` while the ``admin-server-port`` is set to ``3001``:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. code-tab:: http
|
||||
|
||||
GET localhost:3001/live HTTP/1.1
|
||||
|
||||
.. code-tab:: bash Curl
|
||||
|
||||
curl -I "http://localhost:3001/live"
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
If you have a machine with multiple network interfaces and multiple PostgREST instances in the same port, you need to specify a unique :ref:`hostname <server-host>` in the configuration of each PostgREST instance for the health check to work correctly. Don't use the special values(``!4``, ``*``, etc) in this case because the health check could report a false positive.
|
||||
|
||||
Daemonizing
|
||||
===========
|
||||
|
||||
For Linux distributions that use **systemd** (Ubuntu, Debian, Archlinux) you can create a daemon in the following way.
|
||||
|
||||
First, create postgrest configuration in ``/etc/postgrest/config``
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
db-uri = "postgres://<your_user>:<your_password>@localhost:5432/<your_db>"
|
||||
db-schemas = "<your_exposed_schema>"
|
||||
db-anon-role = "<your_anon_role>"
|
||||
jwt-secret = "<your_secret>"
|
||||
|
||||
Then create the systemd service file in ``/etc/systemd/system/postgrest.service``
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[Unit]
|
||||
Description=REST API for any PostgreSQL database
|
||||
After=postgresql.service
|
||||
|
||||
[Service]
|
||||
ExecStart=/bin/postgrest /etc/postgrest/config
|
||||
ExecReload=/bin/kill -SIGUSR1 $MAINPID
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
After that, you can enable the service at boot time and start it with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
systemctl enable postgrest
|
||||
systemctl start postgrest
|
||||
|
||||
## For reloading the service
|
||||
## systemctl restart postgrest
|
||||
|
||||
.. _file_descriptors:
|
||||
|
||||
File Descriptors
|
||||
----------------
|
||||
|
||||
File descriptors are kernel resources that are used by HTTP connections (among others). File descriptors are limited per process. The kernel default limit is 1024, which is increased in some Linux distributions.
|
||||
When under heavy traffic, PostgREST can reach this limit and start showing ``No file descriptors available`` errors. To clear these errors, you can increase the process' file descriptor limit.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[Service]
|
||||
LimitNOFILE=10000
|
||||
|
||||
Alternate URL Structure
|
||||
=======================
|
||||
|
||||
As discussed in :ref:`singular_plural`, there are no special URL forms for singular resources in PostgREST, only operators for filtering. Thus there are no URLs like :code:`/people/1`. It would be specified instead as
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. code-tab:: http
|
||||
|
||||
GET /people?id=eq.1 HTTP/1.1
|
||||
Accept: application/vnd.pgrst.object+json
|
||||
|
||||
.. code-tab:: bash Curl
|
||||
|
||||
curl "http://localhost:3000/people?id=eq.1" \
|
||||
-H "Accept: application/vnd.pgrst.object+json"
|
||||
|
||||
This allows compound primary keys and makes the intent for singular response independent of a URL convention.
|
||||
|
||||
Nginx rewrite rules allow you to simulate the familiar URL convention. The following example adds a rewrite rule for all table endpoints, but you'll want to restrict it to those tables that have a numeric simple primary key named "id."
|
||||
|
||||
.. code-block:: nginx
|
||||
|
||||
# support /endpoint/:id url style
|
||||
location ~ ^/([a-z_]+)/([0-9]+) {
|
||||
|
||||
# make the response singular
|
||||
proxy_set_header Accept 'application/vnd.pgrst.object+json';
|
||||
|
||||
# assuming an upstream named "postgrest"
|
||||
proxy_pass http://postgrest/$1?id=eq.$2;
|
||||
|
||||
}
|
||||
|
||||
.. TODO
|
||||
.. Administration
|
||||
.. API Versioning
|
||||
.. HTTP Caching
|
||||
.. Upgrading
|
||||
@@ -0,0 +1,207 @@
|
||||
.. _db_authz:
|
||||
|
||||
Database Authorization
|
||||
######################
|
||||
|
||||
Database authorization is the process of granting and verifying database access permissions. PostgreSQL manages permissions using the concept of roles.
|
||||
|
||||
Users and Groups
|
||||
================
|
||||
|
||||
A role can be thought of as either a database user, or a group of database users, depending on how the role is set up.
|
||||
|
||||
Roles for Each Web User
|
||||
-----------------------
|
||||
|
||||
PostgREST can accommodate either viewpoint. If you treat a role as a single user then the :ref:`jwt_impersonation` does most of what you need. When an authenticated user makes a request PostgREST will switch into the database role for that user, which in addition to restricting queries, is available to SQL through the :code:`current_user` variable.
|
||||
|
||||
You can use row-level security to flexibly restrict visibility and access for the current user. Here is an `example <https://www.2ndquadrant.com/en/blog/application-users-vs-row-level-security/>`_ from Tomas Vondra, a chat table storing messages sent between users. Users can insert rows into it to send messages to other users, and query it to see messages sent to them by other users.
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
CREATE TABLE chat (
|
||||
message_uuid UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
message_time TIMESTAMP NOT NULL DEFAULT now(),
|
||||
message_from NAME NOT NULL DEFAULT current_user,
|
||||
message_to NAME NOT NULL,
|
||||
message_subject VARCHAR(64) NOT NULL,
|
||||
message_body TEXT
|
||||
);
|
||||
|
||||
ALTER TABLE chat ENABLE ROW LEVEL SECURITY;
|
||||
|
||||
We want to enforce a policy that ensures a user can see only those messages sent by them or intended for them. Also we want to prevent a user from forging the ``message_from`` column with another person's name.
|
||||
|
||||
PostgreSQL allows us to set this policy with row-level security:
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
CREATE POLICY chat_policy ON chat
|
||||
USING ((message_to = current_user) OR (message_from = current_user))
|
||||
WITH CHECK (message_from = current_user)
|
||||
|
||||
Anyone accessing the generated API endpoint for the chat table will see exactly the rows they should, without our needing custom imperative server-side coding.
|
||||
|
||||
.. warning::
|
||||
|
||||
Roles are namespaced per-cluster rather than per-database so they may be prone to collision.
|
||||
|
||||
Web Users Sharing Role
|
||||
----------------------
|
||||
|
||||
Alternately database roles can represent groups instead of (or in addition to) individual users. You may choose that all signed-in users for a web app share the role ``webuser``. You can distinguish individual users by including extra claims in the JWT such as email.
|
||||
|
||||
.. code:: json
|
||||
|
||||
{
|
||||
"role": "webuser",
|
||||
"email": "john@doe.com"
|
||||
}
|
||||
|
||||
SQL code can access claims through PostgREST :ref:`tx_settings`. For instance to get the email claim, call this function:
|
||||
|
||||
.. code:: sql
|
||||
|
||||
current_setting('request.jwt.claims', true)::json->>'email';
|
||||
|
||||
.. note::
|
||||
|
||||
For PostgreSQL < 14
|
||||
|
||||
.. code:: sql
|
||||
|
||||
current_setting('request.jwt.claim.email', true);
|
||||
|
||||
This allows JWT generation services to include extra information and your database code to react to it. For instance the RLS example could be modified to use this ``current_setting`` rather than ``current_user``. The second ``'true'`` argument tells ``current_setting`` to return NULL if the setting is missing from the current configuration.
|
||||
|
||||
Hybrid User-Group Roles
|
||||
-----------------------
|
||||
|
||||
You can mix the group and individual role policies. For instance we could still have a webuser role and individual users which inherit from it:
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
CREATE ROLE webuser NOLOGIN;
|
||||
-- grant this role access to certain tables etc
|
||||
|
||||
CREATE ROLE user000 NOLOGIN;
|
||||
GRANT webuser TO user000;
|
||||
-- now user000 can do whatever webuser can
|
||||
|
||||
GRANT user000 TO authenticator;
|
||||
-- allow authenticator to switch into user000 role
|
||||
-- (the role itself has nologin)
|
||||
|
||||
.. _schema_isolation:
|
||||
|
||||
Schemas
|
||||
=======
|
||||
|
||||
A PostgREST instance exposes all the tables, views, and stored procedures of the schemas configured in :ref:`db-schemas`. This means private data or implementation details can go inside private schemas and be invisible to HTTP clients.
|
||||
|
||||
It is recommended that you don't expose tables on the schemas you expose, instead expose views and stored procedures which insulate the internal details from the outside world.
|
||||
This allows you to change the internals of your schema and maintain backwards compatibility. It also keeps your code easier to refactor, and provides a natural way to do API versioning.
|
||||
|
||||
.. image:: ../_static/db.png
|
||||
|
||||
You must explicitly allow roles to access the exposed schemas:
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
GRANT USAGE ON SCHEMA api TO webuser;
|
||||
|
||||
Tables
|
||||
======
|
||||
|
||||
To let web users access tables you must grant them privileges for the operations you want them to do.
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
GRANT
|
||||
SELECT
|
||||
, INSERT
|
||||
, UPDATE(message_body)
|
||||
, DELETE
|
||||
ON chat TO webuser;
|
||||
|
||||
You can also choose on which table columns the operation is valid. In the above example, the web user can only update the ``message_body`` column.
|
||||
|
||||
.. _func_privs:
|
||||
|
||||
Functions
|
||||
=========
|
||||
|
||||
By default, when a function is created, the privilege to execute it is not restricted by role. The function access is ``PUBLIC`` — executable by all roles (more details at `PostgreSQL Privileges page <https://www.postgresql.org/docs/current/ddl-priv.html>`_). This is not ideal for an API schema. To disable this behavior, you can run the following SQL statement:
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
ALTER DEFAULT PRIVILEGES REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
|
||||
|
||||
This will change the privileges for all functions created in the future in all schemas. Currently there is no way to limit it to a single schema. In our opinion it's a good practice anyway.
|
||||
|
||||
.. note::
|
||||
|
||||
It is however possible to limit the effect of this clause only to functions you define. You can put the above statement at the beginning of the API schema definition, and then at the end reverse it with:
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
ALTER DEFAULT PRIVILEGES GRANT EXECUTE ON FUNCTIONS TO PUBLIC;
|
||||
|
||||
This will work because the :code:`alter default privileges` statement has effect on function created *after* it is executed. See `PostgreSQL alter default privileges <https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html>`_ for more details.
|
||||
|
||||
After that, you'll need to grant EXECUTE privileges on functions explicitly:
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
GRANT EXECUTE ON FUNCTION login TO anonymous;
|
||||
GRANT EXECUTE ON FUNCTION signup TO anonymous;
|
||||
|
||||
You can also grant execute on all functions in a schema to a higher privileged role:
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA api TO web_user;
|
||||
|
||||
Security definer
|
||||
----------------
|
||||
|
||||
A function is executed with the privileges of the user who calls it. This means that the user has to have all permissions to do the operations the procedure performs.
|
||||
If the function accesses private database objects, your :ref:`API roles <roles>` won't be able to successfully execute the function.
|
||||
|
||||
Another option is to define the function with the :code:`SECURITY DEFINER` option. Then only one permission check will take place, the permission to call the function, and the operations in the function will have the authority of the user who owns the function itself.
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
-- login as a user wich has privileges on the private schemas
|
||||
|
||||
-- create a sample function
|
||||
create or replace function login(email text, pass text) returns jwt_token as $$
|
||||
begin
|
||||
-- access to a private schema called 'auth'
|
||||
select auth.user_role(email, pass) into _role;
|
||||
-- other operations
|
||||
-- ...
|
||||
end;
|
||||
$$ language plpgsql security definer;
|
||||
|
||||
Note the ``SECURITY DEFINER`` keywords at the end of the function. See `PostgreSQL documentation <https://www.postgresql.org/docs/current/sql-createfunction.html#SQL-CREATEFUNCTION-SECURITY>`_ for more details.
|
||||
|
||||
Views
|
||||
=====
|
||||
|
||||
Views are invoked with the privileges of the view owner, much like stored procedures with the ``SECURITY DEFINER`` option. When created by a SUPERUSER role, all `row-level security <https://www.postgresql.org/docs/current/ddl-rowsecurity.html>`_ policies will be bypassed.
|
||||
|
||||
If you're on PostgreSQL >= 15, this behavior can be changed by specifying the ``security_invoker`` option.
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
CREATE VIEW sample_view WITH (security_invoker = true) AS
|
||||
SELECT * FROM sample_table;
|
||||
|
||||
On PostgreSQL < 15, you can create a non-SUPERUSER role and make this role the view's owner.
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
CREATE ROLE api_views_owner NOSUPERUSER NOBYPASSRLS;
|
||||
ALTER VIEW sample_view OWNER TO api_views_owner;
|
||||
|
||||
@@ -0,0 +1,381 @@
|
||||
.. _install:
|
||||
|
||||
Installation
|
||||
############
|
||||
|
||||
The release page has `pre-compiled binaries for Mac OS X, Windows, Linux and FreeBSD <https://github.com/PostgREST/postgrest/releases/latest>`_ .
|
||||
The Linux binary is a static executable that can be run on any Linux distribution.
|
||||
|
||||
You can also use your OS package manager.
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Mac OSX
|
||||
|
||||
You can install PostgREST from the `Homebrew official repo <https://formulae.brew.sh/formula/postgrest>`_.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
brew install postgrest
|
||||
|
||||
.. group-tab:: FreeBSD
|
||||
|
||||
You can install PostgREST from the `official ports <https://www.freshports.org/www/hs-postgrest>`_.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
pkg install hs-postgrest
|
||||
|
||||
.. group-tab:: Linux
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. tab:: Arch Linux
|
||||
|
||||
You can install PostgREST from the `community repo <https://archlinux.org/packages/community/x86_64/postgrest>`_.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
pacman -S postgrest
|
||||
|
||||
.. tab:: Nix
|
||||
|
||||
You can install PostgREST from nixpkgs.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
nix-env -i haskellPackages.postgrest
|
||||
|
||||
.. group-tab:: Windows
|
||||
|
||||
You can install PostgREST using `Chocolatey <https://community.chocolatey.org/packages/postgrest>`_ or `Scoop <https://github.com/ScoopInstaller/Scoop>`_.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
choco install postgrest
|
||||
scoop install postgrest
|
||||
|
||||
Running PostgREST
|
||||
=================
|
||||
|
||||
If you downloaded PostgREST from the release page, first extract the compressed file to obtain the executable.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# For UNIX platforms
|
||||
tar Jxf postgrest-[version]-[platform].tar.xz
|
||||
|
||||
# On Windows you should unzip the file
|
||||
|
||||
Now you can run PostgREST with the :code:`--help` flag to see usage instructions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Running postgrest binary
|
||||
./postgrest --help
|
||||
|
||||
# Running postgrest installed from a package manager
|
||||
postgrest --help
|
||||
|
||||
# You should see a usage help message
|
||||
|
||||
The PostgREST server reads a configuration file as its only argument:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
postgrest /path/to/postgrest.conf
|
||||
|
||||
# You can also generate a sample config file with
|
||||
# postgrest -e > postgrest.conf
|
||||
# You'll need to edit this file and remove the usage parts for postgrest to read it
|
||||
|
||||
For a complete reference of the configuration file, see :ref:`configuration`.
|
||||
|
||||
.. note::
|
||||
|
||||
If you see a dialog box like this on Windows, it may be that the :code:`pg_config` program is not in your system path.
|
||||
|
||||
.. image:: ../_static/win-err-dialog.png
|
||||
|
||||
It usually lives in :code:`C:\Program Files\PostgreSQL\<version>\bin`. See this `article <https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/>`_ about how to modify the system path.
|
||||
|
||||
To test that the system path is set correctly, run ``pg_config`` from the command line. You should see it output a list of paths.
|
||||
|
||||
.. _pg-dependency:
|
||||
|
||||
PostgreSQL dependency
|
||||
---------------------
|
||||
|
||||
To use PostgREST you will need an underlying database. We require PostgreSQL 9.6 or greater. You can use something like `Amazon RDS <https://aws.amazon.com/rds/>`_ but installing your own locally is cheaper and more convenient for development. You can also run PostgreSQL in a :ref:`docker container<pg-in-docker>`.
|
||||
|
||||
Docker
|
||||
======
|
||||
|
||||
You can get the `official PostgREST Docker image <https://hub.docker.com/r/postgrest/postgrest>`_ with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker pull postgrest/postgrest
|
||||
|
||||
To configure the container image, use :ref:`env_variables_config`.
|
||||
|
||||
There are two ways to run the PostgREST container: with an existing external database, or through docker-compose.
|
||||
|
||||
Containerized PostgREST with native PostgreSQL
|
||||
----------------------------------------------
|
||||
|
||||
The first way to run PostgREST in Docker is to connect it to an existing native database on the host.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Run the server
|
||||
docker run --rm --net=host \
|
||||
-e PGRST_DB_URI="postgres://app_user:password@localhost/postgres" \
|
||||
postgrest/postgrest
|
||||
|
||||
The database connection string above is just an example. Adjust the role and password as necessary. You may need to edit PostgreSQL's :code:`pg_hba.conf` to grant the user local login access.
|
||||
|
||||
.. note::
|
||||
|
||||
Docker on Mac does not support the :code:`--net=host` flag. Instead you'll need to create an IP address alias to the host. Requests for the IP address from inside the container are unable to resolve and fall back to resolution by the host.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo ifconfig lo0 10.0.0.10 alias
|
||||
|
||||
You should then use 10.0.0.10 as the host in your database connection string. Also remember to include the IP address in the :code:`listen_address` within postgresql.conf. For instance:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
listen_addresses = 'localhost,10.0.0.10'
|
||||
|
||||
You might also need to add a new IPv4 local connection within pg_hba.conf. For instance:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
host all all 10.0.0.10/32 trust
|
||||
|
||||
The docker command will then look like this:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Run the server
|
||||
docker run --rm -p 3000:3000 \
|
||||
-e PGRST_DB_URI="postgres://app_user:password@10.0.0.10/postgres" \
|
||||
postgrest/postgrest
|
||||
|
||||
.. _pg-in-docker:
|
||||
|
||||
Containerized PostgREST *and* db with docker-compose
|
||||
----------------------------------------------------
|
||||
|
||||
To avoid having to install the database at all, you can run both it and the server in containers and link them together with docker-compose. Use this configuration:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# docker-compose.yml
|
||||
|
||||
version: '3'
|
||||
services:
|
||||
server:
|
||||
image: postgrest/postgrest
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
PGRST_DB_URI: postgres://app_user:password@db:5432/app_db
|
||||
PGRST_OPENAPI_SERVER_PROXY_URI: http://127.0.0.1:3000
|
||||
depends_on:
|
||||
- db
|
||||
db:
|
||||
image: postgres
|
||||
ports:
|
||||
- "5432:5432"
|
||||
environment:
|
||||
POSTGRES_DB: app_db
|
||||
POSTGRES_USER: app_user
|
||||
POSTGRES_PASSWORD: password
|
||||
# Uncomment this if you want to persist the data.
|
||||
# volumes:
|
||||
# - "./pgdata:/var/lib/postgresql/data"
|
||||
|
||||
Go into the directory where you saved this file and run :code:`docker-compose up`. You will see the logs of both the database and PostgREST, and be able to access the latter on port 3000.
|
||||
|
||||
If you want to have a visual overview of your API in your browser you can add swagger-ui to your :code:`docker-compose.yml`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
swagger:
|
||||
image: swaggerapi/swagger-ui
|
||||
ports:
|
||||
- "8080:8080"
|
||||
expose:
|
||||
- "8080"
|
||||
environment:
|
||||
API_URL: http://localhost:3000/
|
||||
|
||||
With this you can see the swagger-ui in your browser on port 8080.
|
||||
|
||||
.. _build_source:
|
||||
|
||||
Building from Source
|
||||
====================
|
||||
|
||||
When a pre-built binary does not exist for your system you can build the project from source.
|
||||
|
||||
.. note::
|
||||
|
||||
We discourage building and using PostgREST on **Alpine Linux** because of a reported GHC memory leak on that platform.
|
||||
|
||||
You can build PostgREST from source with `Stack <https://github.com/commercialhaskell/stack>`_. It will install any necessary Haskell dependencies on your system.
|
||||
|
||||
* `Install Stack <https://docs.haskellstack.org/en/stable/README/#how-to-install-stack>`_ for your platform
|
||||
* Install Library Dependencies
|
||||
|
||||
===================== =======================================
|
||||
Operating System Dependencies
|
||||
===================== =======================================
|
||||
Ubuntu/Debian libpq-dev, libgmp-dev, zlib1g-dev
|
||||
CentOS/Fedora/Red Hat postgresql-devel, zlib-devel, gmp-devel
|
||||
BSD postgresql12-client
|
||||
OS X libpq, gmp
|
||||
===================== =======================================
|
||||
|
||||
* Build and install binary
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/PostgREST/postgrest.git
|
||||
cd postgrest
|
||||
|
||||
# adjust local-bin-path to taste
|
||||
stack build --install-ghc --copy-bins --local-bin-path /usr/local/bin
|
||||
|
||||
.. note::
|
||||
|
||||
- If building fails and your system has less than 1GB of memory, try adding a swap file.
|
||||
- `--install-ghc` flag is only needed for the first build and can be omitted in the subsequent builds.
|
||||
|
||||
* Check that the server is installed: :code:`postgrest --help`.
|
||||
|
||||
.. _deploy_heroku:
|
||||
|
||||
Deploying to Heroku
|
||||
===================
|
||||
|
||||
1. Log into Heroku using the `Heroku CLI <https://devcenter.heroku.com/articles/heroku-cli>`_:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# If you have multiple Heroku accounts, use flag '--interactive' to switch between them
|
||||
heroku login --interactive
|
||||
|
||||
|
||||
2. Create a new Heroku app using the PostgREST buildpack:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir ${YOUR_APP_NAME}
|
||||
cd ${YOUR_APP_NAME}
|
||||
git init .
|
||||
|
||||
heroku apps:create ${YOUR_APP_NAME} --buildpack https://github.com/PostgREST/postgrest-heroku.git
|
||||
heroku git:remote -a ${YOUR_APP_NAME}
|
||||
|
||||
3. Create a new Heroku PostgreSQL add-on attached to the app and keep notes of the assigned add-on name (e.g. :code:`postgresql-curly-58902`) referred later as ${HEROKU_PG_DB_NAME}
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
heroku addons:create heroku-postgresql:standard-0 -a ${YOUR_APP_NAME}
|
||||
# wait until the add-on is available
|
||||
heroku pg:wait -a ${YOUR_APP_NAME}
|
||||
|
||||
4. Create the necessary user roles according to the
|
||||
`PostgREST documentation <https://postgrest.org/en/stable/auth.html>`_:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
heroku pg:credentials:create --name api_user -a ${YOUR_APP_NAME}
|
||||
# use the following command to ensure the new credential state is active before attaching it
|
||||
heroku pg:credentials -a ${YOUR_APP_NAME}
|
||||
|
||||
heroku addons:attach ${HEROKU_PG_DB_NAME} --credential api_user -a ${YOUR_APP_NAME}
|
||||
|
||||
5. Connect to the PostgreSQL database and create some sample data:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
heroku psql -a ${YOUR_APP_NAME}
|
||||
|
||||
.. code-block:: postgres
|
||||
|
||||
# from the psql command prompt execute the following commands:
|
||||
create schema api;
|
||||
|
||||
create table api.todos (
|
||||
id serial primary key,
|
||||
done boolean not null default false,
|
||||
task text not null,
|
||||
due timestamptz
|
||||
);
|
||||
|
||||
insert into api.todos (task) values
|
||||
('finish tutorial 0'), ('pat self on back');
|
||||
|
||||
grant usage on schema api to api_user;
|
||||
grant select on api.todos to api_user;
|
||||
|
||||
6. Create the :code:`Procfile`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
web: PGRST_SERVER_HOST=0.0.0.0 PGRST_SERVER_PORT=${PORT} PGRST_DB_URI=${PGRST_DB_URI:-${DATABASE_URL}} ./postgrest-${POSTGREST_VER}
|
||||
..
|
||||
|
||||
Set the following environment variables on Heroku:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
heroku config:set POSTGREST_VER=10.0.0
|
||||
heroku config:set PGRST_DB_SCHEMA=api
|
||||
heroku config:set PGRST_DB_ANON_ROLE=api_user
|
||||
..
|
||||
|
||||
PGRST_DB_URI can be set if an external database is used or if it's different from the default Heroku DATABASE_URL. This latter is used if nothing is provided.
|
||||
POSTGREST_VER is mandatory to select and build the required PostgREST release.
|
||||
|
||||
See https://postgrest.org/en/stable/configuration.html#environment-variables for the full list of environment variables.
|
||||
|
||||
7. Build and deploy your app:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git add Procfile
|
||||
git commit -m "PostgREST on Heroku"
|
||||
git push heroku master
|
||||
..
|
||||
|
||||
Your Heroku app should be live at :code:`${YOUR_APP_NAME}.herokuapp.com`
|
||||
|
||||
8. Test your app
|
||||
|
||||
From a terminal display the application logs:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
heroku logs -t
|
||||
..
|
||||
|
||||
From a different terminal retrieve with curl the records previously created:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl https://${YOUR_APP_NAME}.herokuapp.com/todos
|
||||
..
|
||||
|
||||
and test that any attempt to modify the table via a read-only user is not allowed:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl https://${YOUR_APP_NAME}.herokuapp.com/todos -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"task": "do bad thing"}'
|
||||
Reference in New Issue
Block a user