From 79620396edc776ed8ebf969ae05c5af9afb99277 Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Sun, 7 May 2023 13:03:58 -0300 Subject: [PATCH] remove manual inclusion of pages on index * drop unavailable doc pages from release notes * rename releases pages so they order in TOC --- docs/_static/css/custom.css | 20 +++ docs/{ => explanations}/admin.rst | 10 +- docs/{ => explanations}/db_authz.rst | 7 +- docs/{ => explanations}/install.rst | 4 +- docs/index.rst | 139 +++------------- docs/{ => references}/api.rst | 9 +- docs/{ => references}/auth.rst | 11 +- docs/{ => references}/configuration.rst | 8 +- docs/{ => references}/connection_pool.rst | 2 +- docs/{ => references}/errors.rst | 22 +-- docs/{ => references}/schema_cache.rst | 5 +- docs/{ => references}/transactions.rst | 33 ++-- docs/releases/{v9.0.0.rst => v09.0.0.rst} | 8 +- docs/releases/{v9.0.1.rst => v09.0.1.rst} | 4 +- docs/releases/v10.0.0.rst | 8 +- docs/releases/v10.2.0.rst | 4 +- docs/releases/v5.2.0.rst | 26 --- docs/releases/v6.0.2.rst | 79 --------- docs/releases/v7.0.0.rst | 106 ------------ docs/releases/v7.0.1.rst | 69 -------- docs/releases/v8.0.0.rst | 191 ---------------------- docs/tutorials/tut0.rst | 2 +- postgrest.dict | 1 + 23 files changed, 112 insertions(+), 656 deletions(-) rename docs/{ => explanations}/admin.rst (98%) rename docs/{ => explanations}/db_authz.rst (98%) rename docs/{ => explanations}/install.rst (99%) rename docs/{ => references}/api.rst (99%) rename docs/{ => references}/auth.rst (98%) rename docs/{ => references}/configuration.rst (99%) rename docs/{ => references}/connection_pool.rst (99%) rename docs/{ => references}/errors.rst (99%) rename docs/{ => references}/schema_cache.rst (99%) rename docs/{ => references}/transactions.rst (96%) rename docs/releases/{v9.0.0.rst => v09.0.0.rst} (96%) rename docs/releases/{v9.0.1.rst => v09.0.1.rst} (99%) delete mode 100644 docs/releases/v5.2.0.rst delete mode 100644 docs/releases/v6.0.2.rst delete mode 100644 docs/releases/v7.0.0.rst delete mode 100644 docs/releases/v7.0.1.rst delete mode 100644 docs/releases/v8.0.0.rst diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index fc7f2edb6..7000d0fce 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -65,3 +65,23 @@ div.line-block { .wy-table-responsive { overflow: visible !important; } + +#tutorials span.caption-text { + display: none; +} + +#references span.caption-text { + display: none; +} + +#explanations span.caption-text { + display: none; +} + +#how-tos span.caption-text { + display: none; +} + +#ecosystem span.caption-text { + display: none; +} diff --git a/docs/admin.rst b/docs/explanations/admin.rst similarity index 98% rename from docs/admin.rst rename to docs/explanations/admin.rst index ecd7972d1..1315ae14a 100644 --- a/docs/admin.rst +++ b/docs/explanations/admin.rst @@ -1,5 +1,8 @@ .. _admin: +Admin +##### + Hardening PostgREST =================== @@ -140,11 +143,6 @@ 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. -Errors ------- - -See the :doc:`Errors ` reference page for detailed information on the errors that PostgREST returns. - .. _pgrst_logging: Logging @@ -248,7 +246,7 @@ To do this, set the configuration variable :ref:`admin-server-port` to the port 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 :doc:`Schema Cache `. A request will return ``200 OK`` if it is ready or ``503`` if not. +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``: diff --git a/docs/db_authz.rst b/docs/explanations/db_authz.rst similarity index 98% rename from docs/db_authz.rst rename to docs/explanations/db_authz.rst index 6e3748aad..eb6b3041b 100644 --- a/docs/db_authz.rst +++ b/docs/explanations/db_authz.rst @@ -1,6 +1,7 @@ -.. raw:: html +.. _db_authz: -

Database Authorization

+Database Authorization +###################### Database authorization is the process of granting and verifying database access permissions. PostgreSQL manages permissions using the concept of roles. @@ -101,7 +102,7 @@ A PostgREST instance exposes all the tables, views, and stored procedures of the 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 +.. image:: ../_static/db.png You must explicitly allow roles to access the exposed schemas: diff --git a/docs/install.rst b/docs/explanations/install.rst similarity index 99% rename from docs/install.rst rename to docs/explanations/install.rst index 508f830b0..8d3a6455a 100644 --- a/docs/install.rst +++ b/docs/explanations/install.rst @@ -1,7 +1,7 @@ .. _install: Installation -============ +############ The release page has `pre-compiled binaries for Mac OS X, Windows, Linux and FreeBSD `_ . The Linux binary is a static executable that can be run on any Linux distribution. @@ -95,7 +95,7 @@ For a complete reference of the configuration file, see :ref:`configuration`. 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 + .. image:: ../_static/win-err-dialog.png It usually lives in :code:`C:\Program Files\PostgreSQL\\bin`. See this `article `_ about how to modify the system path. diff --git a/docs/index.rst b/docs/index.rst index 24ff6547b..e0931674c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -95,18 +95,10 @@ The project has a friendly and growing community. Join our `chat room - v10.0.0 - v9.0.1 - v9.0.0 - releases/v8.0.0 - releases/v7.0.1 - releases/v7.0.0 - releases/v6.0.2 - releases/v5.2.0 + releases/* Tutorials --------- @@ -116,14 +108,11 @@ Are you new to PostgREST? This is the place to start! .. toctree:: :glob: :caption: Tutorials - :hidden: + :maxdepth: 1 tutorials/* -- :doc:`tutorials/tut0` -- :doc:`tutorials/tut1` - -Also have a look at :doc:`Installation ` and :ref:`community_tutorials`. +Also have a look at :ref:`install` and :ref:`community_tutorials`. References ---------- @@ -131,54 +120,12 @@ References Technical references for PostgREST's functionality. .. toctree:: - :caption: Authentication - :hidden: + :glob: + :caption: References + :name: references + :maxdepth: 1 - auth.rst - -.. toctree:: - :caption: API - :hidden: - - api.rst - -.. toctree:: - :caption: Transactions - :hidden: - - transactions.rst - -.. toctree:: - :caption: Connection Pool - :hidden: - - connection_pool.rst - -.. toctree:: - :caption: Configuration - :hidden: - - configuration.rst - -.. toctree:: - :caption: Schema Cache - :hidden: - - schema_cache.rst - -.. toctree:: - :caption: Errors - :hidden: - - errors.rst - -- :doc:`Authentication ` -- :doc:`API ` -- :doc:`Transactions ` -- :doc:`Connection pool ` -- :doc:`configuration` -- :doc:`Schema Cache ` -- :doc:`Errors ` + references/* Explanations ------------ @@ -186,50 +133,25 @@ Explanations Key concepts in PostgREST. .. toctree:: - :caption: Database Authorization - :hidden: + :glob: + :caption: Explanations + :name: explanations + :maxdepth: 1 - db_authz.rst + explanations/* -.. toctree:: - :caption: Administration - :hidden: - - admin.rst - -.. toctree:: - :caption: Installation - :hidden: - - install.rst - -- :doc:`Database Authorization ` -- :doc:`Administration ` -- :doc:`Installation ` - -.. _how_tos: - -How-to guides -------------- +How-tos +------- Recipes that'll help you address specific use-cases. .. toctree:: :glob: :caption: How-to guides - :hidden: + :name: how-tos + :maxdepth: 1 - how-tos/sql-user-management - how-tos/working-with-postgresql-data-types - how-tos/sql-user-management-using-postgres-users-and-passwords - how-tos/providing-images-for-img - how-tos/create-soap-endpoint - -- :doc:`how-tos/sql-user-management` -- :doc:`how-tos/working-with-postgresql-data-types` -- :doc:`how-tos/sql-user-management-using-postgres-users-and-passwords` -- :doc:`how-tos/providing-images-for-img` -- :doc:`how-tos/create-soap-endpoint` + how-tos/* Ecosystem --------- @@ -238,28 +160,11 @@ PostgREST has a growing ecosystem of examples, libraries, and experiments. Here .. toctree:: :caption: Ecosystem - :hidden: + :name: ecosystem + :maxdepth: 1 ecosystem.rst -* :ref:`external_jwt` -* :ref:`community_tutorials` -* :ref:`templates` -* :ref:`eco_example_apps` -* :ref:`devops` -* :ref:`eco_external_notification` -* :ref:`eco_extensions` -* :ref:`clientside_libraries` - - -Release Notes -------------- - -Changes among versions. - -- :doc:`releases/v9.0.0` -- :doc:`releases/v8.0.0` - In Production ------------- diff --git a/docs/api.rst b/docs/references/api.rst similarity index 99% rename from docs/api.rst rename to docs/references/api.rst index e2b163ecc..0dd517fc2 100644 --- a/docs/api.rst +++ b/docs/references/api.rst @@ -1,3 +1,8 @@ +.. _api: + +API +### + .. role:: sql(code) :language: sql @@ -873,7 +878,7 @@ In addition to providing RESTful routes for each table and view, PostgREST allow API call. This reduces the need for multiple API requests. The server uses **foreign keys** to determine which tables and views can be returned together. For example, consider a database of films and their awards: -.. image:: _static/film.png +.. image:: ../_static/film.png .. important:: @@ -1552,7 +1557,7 @@ Target Disambiguation For example, suppose you have the following ``orders`` and ``addresses`` tables: -.. image:: _static/orders.png +.. image:: ../_static/orders.png And you try to embed ``orders`` with ``addresses`` (this is the **target**): diff --git a/docs/auth.rst b/docs/references/auth.rst similarity index 98% rename from docs/auth.rst rename to docs/references/auth.rst index 31eb5e31e..2501c3536 100644 --- a/docs/auth.rst +++ b/docs/references/auth.rst @@ -1,8 +1,7 @@ -.. raw:: html +Authentication +============== -

Authentication

- -PostgREST is designed to keep the database at the center of API security. All :doc:`authorization happens in the database ` . It is PostgREST's job to **authenticate** requests -- i.e. verify that a client is who they say they are -- and then let the database **authorize** client actions. +PostgREST is designed to keep the database at the center of API security. All :ref:`authorization happens in the database ` . It is PostgREST's job to **authenticate** requests -- i.e. verify that a client is who they say they are -- and then let the database **authorize** client actions. .. _roles: @@ -11,7 +10,7 @@ Overview of role system There are three types of roles used by PostgREST, the **authenticator**, **anonymous** and **user** roles. The database administrator creates these roles and configures PostgREST to use them. -.. image:: _static/security-roles.png +.. image:: ../_static/security-roles.png The authenticator role is used for connecting to the database and should be configured to have very limited access. It is a chameleon whose job is to "become" other users to service authenticated HTTP requests. @@ -32,7 +31,7 @@ User Impersonation The picture below shows how the server handles authentication. If auth succeeds, it switches into the user role specified by the request, otherwise it switches into the anonymous role (if it's set in :ref:`db-anon-role`). -.. image:: _static/security-anon-choice.png +.. image:: ../_static/security-anon-choice.png This role switching mechanism is called **user impersonation**. In PostgreSQL it's done with the ``SET ROLE`` statement. diff --git a/docs/configuration.rst b/docs/references/configuration.rst similarity index 99% rename from docs/configuration.rst rename to docs/references/configuration.rst index 25d8e9282..d27eb0bcb 100644 --- a/docs/configuration.rst +++ b/docs/references/configuration.rst @@ -1,7 +1,7 @@ .. _configuration: Configuration -============= +############# Without configuration, PostgREST won't be able to serve requests. At the minimum it needs either :ref:`a role to serve anonymous requests with ` - or :ref:`a secret to use for JWT authentication `. Config parameters can be provided via :ref:`file_config`, via :ref:`env_variables_config` or through :ref:`in_db_config`. @@ -16,7 +16,7 @@ Config parameters are read in the following order: .. _file_config: Config File ------------ +=========== PostgREST can read a config file. There is no predefined location for this file, you must specify the file path as the one and only argument to the server: @@ -55,14 +55,14 @@ You can run ``postgrest --example`` to display all possible configuration parame .. _env_variables_config: Environment Variables ---------------------- +===================== You can also set these :ref:`configuration parameters ` using environment variables. They are capitalized, have a ``PGRST_`` prefix, and use underscores. For example: ``PGRST_DB_URI`` corresponds to ``db-uri`` and ``PGRST_APP_SETTINGS_*`` to ``app.settings.*``. .. _in_db_config: In-Database Configuration -------------------------- +========================= By adding settings to the **authenticator** role (see :ref:`roles`), you can make the database the single source of truth for PostgREST's configuration. This is enabled by :ref:`db-config`. diff --git a/docs/connection_pool.rst b/docs/references/connection_pool.rst similarity index 99% rename from docs/connection_pool.rst rename to docs/references/connection_pool.rst index 9bb38c3c6..c7f6d7ed0 100644 --- a/docs/connection_pool.rst +++ b/docs/references/connection_pool.rst @@ -1,5 +1,5 @@ Connection Pool ---------------- +=============== Every request to an :doc:`API resource ` borrows a connection from the connection pool to start a :doc:`transaction `. diff --git a/docs/errors.rst b/docs/references/errors.rst similarity index 99% rename from docs/errors.rst rename to docs/references/errors.rst index 74c4a3f84..e481a70fd 100644 --- a/docs/errors.rst +++ b/docs/references/errors.rst @@ -1,12 +1,12 @@ .. _error_source: -Error Format -============ +Errors +###### PostgREST error messages follow the PostgreSQL error structure. It includes ``MESSAGE``, ``DETAIL``, ``HINT``, ``ERRCODE`` and will add an HTTP status code to the response. Errors from PostgreSQL ----------------------- +====================== PostgREST will forward errors coming from PostgreSQL. For instance, when querying a nonexistent table: @@ -31,7 +31,7 @@ PostgREST will forward errors coming from PostgreSQL. For instance, when queryin .. _status_codes: HTTP Status Codes -================= +----------------- PostgREST translates `PostgreSQL error codes `_ into HTTP status as follows: @@ -97,7 +97,7 @@ PostgREST translates `PostgreSQL error codes `: @@ -123,7 +123,7 @@ Errors that come from PostgREST itself maintain the same structure. But differ i .. _pgrst_errors: PostgREST Error Codes -===================== +--------------------- PostgREST error codes have the form ``PGRSTgxx`` @@ -134,7 +134,7 @@ PostgREST error codes have the form ``PGRSTgxx`` .. _pgrst0**: Group 0 - Connection --------------------- +~~~~~~~~~~~~~~~~~~~~ Related to the connection with the database. @@ -161,7 +161,7 @@ Related to the connection with the database. .. _pgrst1**: Group 1 - Api Request ---------------------- +~~~~~~~~~~~~~~~~~~~~~ Related to the HTTP request elements. @@ -252,7 +252,7 @@ Related to the HTTP request elements. .. _pgrst2**: Group 2 - Schema Cache ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ Related to a :ref:`stale schema cache `. Most of the time, these errors are solved by :ref:`reloading the schema cache `. @@ -285,7 +285,7 @@ Related to a :ref:`stale schema cache `. Most of the time, these e .. _pgrst3**: Group 3 - JWT -------------- +~~~~~~~~~~~~~ Related to the authentication process using JWT. You can follow the :ref:`tut1` for an example on how to implement authentication and the :doc:`Authentication page ` for more information on this process. @@ -310,7 +310,7 @@ Related to the authentication process using JWT. You can follow the :ref:`tut1` .. _pgrst_X**: Group X - Internal ------------------- +~~~~~~~~~~~~~~~~~~ Internal errors. If you encounter any of these, you may have stumbled on a PostgREST bug, please `open an issue `_ and we'll be glad to fix it. diff --git a/docs/schema_cache.rst b/docs/references/schema_cache.rst similarity index 99% rename from docs/schema_cache.rst rename to docs/references/schema_cache.rst index cfd9f0bb2..44d9fd2d2 100644 --- a/docs/schema_cache.rst +++ b/docs/references/schema_cache.rst @@ -1,8 +1,7 @@ .. _schema_cache: -.. raw:: html - -

Schema Cache

+Schema Cache +============ Some PostgREST features need metadata from the database schema. Getting this metadata requires expensive queries. To avoid repeating this work, PostgREST uses a schema cache. diff --git a/docs/transactions.rst b/docs/references/transactions.rst similarity index 96% rename from docs/transactions.rst rename to docs/references/transactions.rst index 7a73131c0..565a2e6d0 100644 --- a/docs/transactions.rst +++ b/docs/references/transactions.rst @@ -1,6 +1,5 @@ -.. raw:: html - -

Transactions

+Transactions +============ After :ref:`user_impersonation`, every request to an :doc:`API resource ` runs inside a transaction. The sequence of the transaction is as follows: @@ -14,7 +13,7 @@ After :ref:`user_impersonation`, every request to an :doc:`API resource ` r .. _access_mode: Access Mode -=========== +----------- The access mode on :ref:`tables_views` is determined by the HTTP method. @@ -59,14 +58,14 @@ Modifying the database inside READ ONLY transactions is not possible. PostgREST The :ref:`options_requests` method doesn't start a transaction, so it's not relevant here. Isolation Level -=============== +--------------- Every transaction uses the PostgreSQL default isolation level: READ COMMITTED. .. _tx_settings: Transaction-Scoped Settings -=========================== +--------------------------- PostgREST uses settings tied to the transaction lifetime. These can be used to get data about the HTTP request. Or to modify the HTTP response. @@ -87,7 +86,7 @@ And you can set them with ``set_config`` set_config('response.', 'value1' ,true); Request Role and Search Path ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Because of :ref:`user_impersonation`, PostgREST sets the standard ``role``. You can get this in different ways: @@ -105,7 +104,7 @@ Additionally it also sets the ``search_path`` based on :ref:`db-schemas` and :re .. _guc_req_headers_cookies_claims: Request Headers, Cookies and JWT claims ---------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PostgREST stores the headers, cookies and headers as JSON. To get them: @@ -130,7 +129,7 @@ PostgREST stores the headers, cookies and headers as JSON. To get them: .. _guc_req_path_method: Request Path and Method ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ The path and method are stored as ``text``. @@ -143,7 +142,7 @@ The path and method are stored as ``text``. .. _guc_resp_hdrs: Response Headers ----------------- +~~~~~~~~~~~~~~~~ You can set ``response.headers`` to add headers to the HTTP response. For instance, this statement would add caching headers to the response: @@ -169,7 +168,7 @@ Notice that the ``response.headers`` should be set to an *array* of single-key o .. _guc_resp_status: Response Status Code --------------------- +~~~~~~~~~~~~~~~~~~~~ You can set the ``response.status`` to override the default status code PostgREST provides. For instance, the following function would replace the default ``200`` status code. @@ -207,24 +206,24 @@ If the status code is standard, PostgREST will complete the status message(**I'm .. _main_query: Main query -========== +---------- The main query is produced by requesting the :doc:`API resources `. Transaction End -=============== +--------------- If the transaction doesn't fail, it will always end in a COMMIT. Unless :ref:`db-tx-end` is configured to ROLLBACK in any case or conditionally with ``Prefer: tx=rollback``. This can be used for testing purposes. Aborting transactions -===================== +--------------------- Any database failure(like a failed constraint) will result in a rollback of the transaction. You can also do a RAISE inside a function to cause a rollback. .. _raise_error: Raise errors with HTTP Status Codes ------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can return non-200 HTTP status codes by raising SQL exceptions. For instance, here's a saucy function that always responds with an error: @@ -279,7 +278,7 @@ Returns: .. _pre-request: Pre-Request -=========== +----------- The pre-request is a function that can run after the :ref:`tx_settings` are set and before the :ref:`main_query`. It's enabled with :ref:`db-pre-request`. @@ -288,7 +287,7 @@ This provides an opportunity to modify settings or raise an exception to prevent .. _pre_req_headers: Setting headers via pre-request -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As an example, let's add some cache headers for all requests that come from an Internet Explorer(6 or 7) browser. diff --git a/docs/releases/v9.0.0.rst b/docs/releases/v09.0.0.rst similarity index 96% rename from docs/releases/v9.0.0.rst rename to docs/releases/v09.0.0.rst index 5963e8237..5827f542a 100644 --- a/docs/releases/v9.0.0.rst +++ b/docs/releases/v09.0.0.rst @@ -1,6 +1,6 @@ -PostgREST 9.0.0 -=============== +9.0.0 +===== This major version is released with PostgreSQL 14 compatibility and is accompanied with new features and bug fixes. You can look at the detailed changelog and download the pre-compiled binaries on the `GitHub release page `_. @@ -50,7 +50,7 @@ Error messages Documentation improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Added ``curl`` snippets to the :doc:`API <../api>` page. +* Added ``curl`` snippets to the :ref:`api` page. * Added the :ref:`automatic_recovery` section. @@ -74,7 +74,7 @@ Breaking changes * Dropped support for PostgreSQL 9.5 as it already reached its end-of-life according to `PostgreSQL versioning policy `_. -* Partitions of a `partitioned table `_ are no longer included in the :doc:`../schema_cache`. This is so errors are not generated when doing resource embedding on partitioned tables. +* Partitions of a `partitioned table `_ are no longer included in the :ref:`schema_cache`. This is so errors are not generated when doing resource embedding on partitioned tables. * Dropped support for doing :ref:`hint_disamb` using dots instead of exclamation marks, e.g. doing ``select=*,projects.client_id(*)`` instead of ``select=*,projects!client_id(*)``). Using dots was undocumented and deprecated back in `v6.0.2 `_. diff --git a/docs/releases/v9.0.1.rst b/docs/releases/v09.0.1.rst similarity index 99% rename from docs/releases/v9.0.1.rst rename to docs/releases/v09.0.1.rst index dfbaa5735..bac8795b1 100644 --- a/docs/releases/v9.0.1.rst +++ b/docs/releases/v09.0.1.rst @@ -1,6 +1,6 @@ -PostgREST 9.0.1 -=============== +9.0.1 +===== This version includes important fixes for production environments and other miscellaneous fixes. You can download the pre-compiled binaries on the `GitHub release page `_. diff --git a/docs/releases/v10.0.0.rst b/docs/releases/v10.0.0.rst index 9177fcfbc..e703324a4 100644 --- a/docs/releases/v10.0.0.rst +++ b/docs/releases/v10.0.0.rst @@ -1,6 +1,6 @@ -PostgREST 10.0.0 -================ +10.0.0 +====== Features -------- @@ -73,9 +73,9 @@ Documentation improvements * Added the :ref:`file_descriptors` subsection. -* Added a reference page for :doc:`Error documentation `. +* Added a reference page for :ref:`error_source`. -* Moved the :ref:`error_source` and the :ref:`status_codes` sections to the :doc:`errors reference page `. +* Moved the :ref:`error_source` and the :ref:`status_codes` sections to the :ref:`errors reference page `. * Moved the *Casting type to custom JSON* how-to to the :ref:`casting_range_to_json` subsection. diff --git a/docs/releases/v10.2.0.rst b/docs/releases/v10.2.0.rst index ff7dc61ea..96121b410 100644 --- a/docs/releases/v10.2.0.rst +++ b/docs/releases/v10.2.0.rst @@ -1,6 +1,6 @@ -PostgREST 10.2.0 -================ +10.2.0 +====== This minor version adds bug fixes and some features that provide stability to v10.0.0. These release notes include the changes added in versions `10.1.0 `_, `10.1.1 `_ and `10.1.2 `_. You can look at the detailed changelog and download the pre-compiled binaries on the `GitHub release page `_. diff --git a/docs/releases/v5.2.0.rst b/docs/releases/v5.2.0.rst deleted file mode 100644 index d32044526..000000000 --- a/docs/releases/v5.2.0.rst +++ /dev/null @@ -1,26 +0,0 @@ -v5.2.0 -====== - -* Explicit qualification introduced in ``v5.0`` is no longer necessary, this section will not be included from this version onwards. A :ref:`db-extra-search-path` configuration parameter was introduced to avoid the need to explictly qualify database objects. If you install PostgreSQL extensions on the ``public`` schema, they'll work normally from now on. - -* Now you can filter :ref:`tabs-cols-w-spaces`. - -* Included the ability to quote columns that have :ref:`reserved-chars`. - -* Thanks to `Zhou Feng `_, now is possible to reference an external file in :ref:`db-uri`. - -* Thanks to `Russell Davies `_, Json Web Key Sets are now accepted by :ref:`jwt-secret`. - -Thanks ------- - -This release was made possible thanks to: - -* `Daniel Babiak `_ -* `Michel Pelletier `_ -* Tsingson Qin -* Jay Hannah -* Victor Adossi -* Petr Beles - -If you like to join them please consider `supporting PostgREST development `_. diff --git a/docs/releases/v6.0.2.rst b/docs/releases/v6.0.2.rst deleted file mode 100644 index 47f870e44..000000000 --- a/docs/releases/v6.0.2.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. |br| raw:: html - -
- -v6.0.2 -====== - -Full changelog is available at `PostgREST releases page `_. - -Added ------ - -* Ignoring payload keys for insert/update can be now done with the ``?columns`` query parameter. See :ref:`specify_columns`. - |br| -- `@steve-chavez `_ - -* `websearch_to_tsquery `_ can now be used - through the ``wfts`` operator. See :ref:`fts`. - |br| -- `@herulume `_ - -* Resource Embedding on materialized views is now possible. See :ref:`embedding_views`. - |br| -- `@vitorbaptista `_ - -* Bulk calling an RPC is now allowed. See :ref:`bulk_call`. - |br| -- `@steve-chavez `_ - -* It's now possible to request a ``text/plain`` output. See :ref:`scalar_return_formats`. - |br| -- `@steve-chavez `_ - -* Config option for specifying PostgREST database pool timeout ``db-pool-timeout``. - |br| -- `@Qu4tro `_ - -* Config option for binding the PostgREST web server to an unix socket. See :ref:`server-unix-socket`. - |br| -- `@Dansvidania `_ - -* Config option for extending the supported media types. See :ref:`raw-media-types`. - |br| -- `@Dansvidania `_ - -* We now offer an statically linked binary for Linux. Look for **postgrest--linux-x64-static.tar.xz** on the - `releases page `_. - |br| -- `@clojurians-org `_ - -* A :ref:`how_tos` section was added to the documentation. - -Changed -------- - -* ``SIGHUP`` support was removed. You should use ``SIGUSR1`` instead. See :ref:`schema_reloading`. - -* server-host default of ``127.0.0.1`` was changed to ``!4``. See :ref:`server-host`. - -Thanks ------- - -This release is sponsored by: - -.. image:: ../_static/cybertec.png - :target: https://www.cybertec-postgresql.com/en/ - :width: 13em - -.. image:: ../_static/2ndquadrant.png - :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo - :width: 13em - -.. image:: ../_static/retool.png - :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest - :width: 13em - -* `Daniel Babiak `_ -* Evans Fernandes -* Tsingson Qin -* Michel Pelletier -* Jay Hannah -* Robert Stolarz -* Kofi Gumbs -* Nicholas DiBiase -* Christopher Reid -* Nathan Bouscal - -If you like to join them please consider `supporting PostgREST development `_. diff --git a/docs/releases/v7.0.0.rst b/docs/releases/v7.0.0.rst deleted file mode 100644 index 67357c9b2..000000000 --- a/docs/releases/v7.0.0.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. |br| raw:: html - -
- -v7.0.0 -====== - -You can download this release at the `PostgREST v7.0.0 release page `_. - -Added ------ - -* Support for :ref:`Switching to a schema ` defined in :ref:`db-schemas`. - |br| -- `@steve-chavez `_, `@mahmoudkassem `_ - -* Support for :ref:`planned_count` and :ref:`estimated_count`. - |br| -- `@steve-chavez `_, `@LorenzHenk `_ - -* Support for the :ref:`on_conflict ` query parameter to UPSERT based on a unique constraint. - |br| -- `@ykst `_ - -* Support for :ref:`Resource Embedding Disambiguation `. - |br| -- `@steve-chavez `_ - -* Support for user defined socket permission via :ref:`server-unix-socket-mode` config option - |br| -- `@Dansvidania `_ - -* HTTP logic improvements -- `@steve-chavez `_ - - + Support for HTTP HEAD requests. - + GUCs for :ref:`guc_req_path_method`. - + Support for :ref:`pre_req_headers`. - + Allow overriding provided headers(Content-Type, Location, etc) by :ref:`guc_resp_hdrs` - + Access to the ``Authorization`` header value through ``request.header.authorization`` - -* Documentation improvements - - + Explanation for :doc:`Schema Structure <../db_authz>`. - + Reference for :ref:`s_proc_embed`. - + Reference for :ref:`mutation_embed`. - + Reference for filters on :ref:`json_columns`. - + How-to for :ref:`providing_img`. - + Added :ref:`community_tutorials` section. - -Fixed ------ - -* Allow embedding a view when its source table foreign key is UNIQUE - |br| -- `@bwbroersma `_ - -* ``Accept: application/vnd.pgrst.object+json`` behavior is now enforced for POST/PATCH/DELETE regardless of ``Prefer: return=minimal`` - |br| -- `@dwagin `_ - -* Fix self join resource embedding on PATCH - |br| -- `@herulume `_, `@steve-chavez `_ - -* Allow PATCH/DELETE without ``Prefer: return=minimal`` on tables with no SELECT privileges - |br| -- `@steve-chavez `_ - -* Fix many to many resource embedding for RPC/PATCH - |br| -- `@steve-chavez `_ - -Changed -------- - -* :ref:`bulk_call` should now be done by specifying a ``Prefer: params=multiple-objects`` header. This fixes a performance regression when calling stored procedures. - -* Resource Embedding now outputs an error when multiple relationships between two tables are found, see :ref:`embed_disamb`. - -* ``server-proxy-uri`` config option has been renamed to :ref:`openapi-server-proxy-uri`. - -* Default Unix Socket file mode from 755 to 660 - -Thanks ------- - -This release was made possible thanks to: - -.. image:: ../_static/cybertec.png - :target: https://www.cybertec-postgresql.com/en/ - :width: 13em - -.. image:: ../_static/2ndquadrant.png - :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo - :width: 13em - -.. image:: ../_static/retool.png - :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest - :width: 13em - -* `Daniel Babiak `_ -* Evans Fernandes -* Jan Sommer -* Tsingson Qin -* Michel Pelletier -* Jay Hannah -* Robert Stolarz -* Kofi Gumbs -* Nicholas DiBiase -* Christopher Reid -* Nathan Bouscal -* Daniel Rafaj -* David Fenko - - -If you like to join them please consider `supporting PostgREST development `_. diff --git a/docs/releases/v7.0.1.rst b/docs/releases/v7.0.1.rst deleted file mode 100644 index 541c46245..000000000 --- a/docs/releases/v7.0.1.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. |br| raw:: html - -
- -v7.0.1 -====== - -You can see the full changelog at `PostgREST v7.0.1 release page `_. - -Fixed ------ - -* Fix overloaded computed columns on RPC - |br| -- `@wolfgangwalther `_ - -* Fix POST, PATCH, DELETE with ``?select=`` and ``Prefer: return=minimal`` and PATCH with empty body - |br| -- `@wolfgangwalther `_ - -* Fix missing ``openapi-server-proxy-uri`` config option - |br| -- `@steve-chavez `_ - -* Fix ``Content-Profile`` not working for POST RPC - |br| -- `@steve-chavez `_ - -* Fix PUT restriction for including all columns in payload - |br| -- `@steve-chavez `_ - -* Documentation improvements - - + Added package managers to :ref:`install`. - -Changed -------- - -* From this version onwards, the release page will include a single Linux static executable that can be run on any Linux distribution. - -Thanks ------- - -This release was made possible thanks to: - -.. image:: ../_static/cybertec.png - :target: https://www.cybertec-postgresql.com/en/ - :width: 13em - -.. image:: ../_static/2ndquadrant.png - :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo - :width: 13em - -.. image:: ../_static/retool.png - :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest - :width: 13em - -* `Daniel Babiak `_ -* Evans Fernandes -* Jan Sommer -* Tsingson Qin -* Michel Pelletier -* Jay Hannah -* Robert Stolarz -* Kofi Gumbs -* Nicholas DiBiase -* Christopher Reid -* Nathan Bouscal -* Daniel Rafaj -* David Fenko - - -If you'd like to join them, consider `supporting PostgREST development `_. diff --git a/docs/releases/v8.0.0.rst b/docs/releases/v8.0.0.rst deleted file mode 100644 index 69fb70bd2..000000000 --- a/docs/releases/v8.0.0.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. |br| raw:: html - -
- -v8.0.0 -====== - -You can download this release at the `PostgREST v8.0.0 release page `_. - -Added ------ - -* Allow HTTP status override through the :ref:`response.status ` GUC. - |br| -- `@steve-chavez `_ - -* Allow :ref:`s_procs_variadic`. - |br| -- `@wolfgangwalther `_ - -* Allow :ref:`embedding_view_chains` recursively to any depth. - |br| -- `@wolfgangwalther `_ - -* No downtime when reloading the schema cache. See :ref:`schema_reloading`. - |br| -- `@steve-chavez `_ - -* Allow schema cache reloading using PostgreSQL :ref:`NOTIFY ` command. This enables :ref:`auto_schema_reloading`. - |br| -- `@steve-chavez `_ - -* Allow sending the header ``Prefer: headers-only`` to get a response with a ``Location`` header. See :ref:`insert`. - |br| -- `@laurenceisla `_ - -* Allow :ref:`external_connection_poolers` such as PgBouncer in transaction pooling mode. - |br| -- `@laurenceisla `_ - -* Allow :ref:`config_reloading` by sending a SIGUSR2 signal. - |br| -- `@steve-chavez `_ - -* Allow ``Bearer`` with and without capitalization as authentication schema. See :ref:`client_auth`. - |br| -- `@wolfgangwalther `_ - -* :ref:`in_db_config` that can be :ref:`reloaded with NOTIFY `. - |br| -- `@steve-chavez `_ - -* Allow OPTIONS to generate HTTP methods based on views triggers. See :ref:`OPTIONS requests `. - |br| -- `@laurenceisla `_ - -* Show timestamps for server diagnostic information. See :ref:`pgrst_logging`. - |br| -- `@steve-chavez `_ - -* Config options for showing a full OpenAPI output regardless of the JWT role privileges and for disabling it altogether. See :ref:`openapi-mode`. - |br| -- `@steve-chavez `_ - -* Config option for logging level. See :ref:`log-level`. - |br| -- `@steve-chavez `_ - -* Config option for enabling or disabling prepared statements. See :ref:`db-prepared-statements`. - |br| -- `@steve-chavez `_ - -* Config option for specifying how to terminate the transactions (allowing rollbacks, useful for testing). See :ref:`db-tx-end`. - |br| -- `@wolfgangwalther `_ - -* Documentation improvements - - + Added the :doc:`../schema_cache` page. - + Moved the :ref:`schema_reloading` reference from :doc:`../admin` to :doc:`../schema_cache` - -Changed -------- - -* Docker images are now optimized to be built from the scratch image. This reduces the compressed image size from over 30 MB to about 4 MB. - For more details, see `Docker image built with Nix `_. - |br| -- `@monacoremo `_ - -* The Docker image no longer has an internal ``/etc/postgrest.conf`` file, you must use :ref:`env_variables_config` to configure it. - |br| -- `@wolfgangwalther `_ - -* The ``pg_listen`` `utility `_ is no longer needed to automatically reload the schema cache - and it's replaced entirely by database notifications. See :ref:`auto_schema_reloading`. - |br| -- `@steve-chavez `_ - -* POST requests for insertions no longer include a ``Location`` header in the response by default and behave the same way as having a - ``Prefer: return=minimal`` header in the request. This prevents permissions errors when having a write-only table. See :ref:`insert`. - |br| -- `@laurenceisla `_ - -* Modified the default logging level from ``info`` to ``error``. See :ref:`log-level`. - |br| -- `@steve-chavez `_ - -* Changed the error message for a not found RPC on a stale schema (see :ref:`stale_schema`) and for the unsupported case of - overloaded functions with the same argument names but different types. - |br| -- `@laurenceisla `_ - -* Changed the error message for the no relationship found error. See :ref:`stale_schema`. - |br| -- `@laurenceisla `_ - -Fixed ------ - -* Fix showing UNKNOWN on ``postgrest --help`` invocation. - |br| -- `@monacoremo `_ - -* Removed single column restriction to allow composite foreign keys in join tables. - |br| -- `@goteguru `_ - -* Fix expired JWTs starting an empty transaction on the db. - |br| -- `@steve-chavez `_ - -* Fix location header for POST request with ``select=`` without PK. - |br| -- `@wolfgangwalther `_ - -* Fix error messages on connection failure for localized PostgreSQL on Windows. - |br| -- `@wolfgangwalther `_ - -* Fix ``application/octet-stream`` appending ``charset=utf-8``. - |br| -- `@steve-chavez `_ - -* Fix overloading of functions with unnamed arguments. - |br| -- `@wolfgangwalther `_ - -* Return ``405 Method not Allowed`` for GET of volatile RPC instead of 500. - |br| -- `@wolfgangwalther `_ - -* Fix RPC return type handling and embedding for domains with composite base type. - |br| -- `@wolfgangwalther `_ - -* Fix embedding through views that have COALESCE with subselect. - |br| -- `@wolfgangwalther `_ - -* Fix parsing of boolean config values for Docker environment variables, now it accepts double quoted truth values ``("true", "false")`` and numbers ``("1", "0")``. - |br| -- `@wolfgangwalther `_ - -* Fix using ``app.settings.xxx`` config options in Docker, now they can be used as ``PGRST_APP_SETTINGS_xxx``. - |br| -- `@wolfgangwalther `_ - -* Fix panic when attempting to run with unix socket on non-unix host and properly close unix domain socket on exit. - |br| -- `@monacoremo `_ - -* Disregard internal junction (in non-exposed schema) when embedding. - |br| -- `@steve-chavez `_ - -* Fix requests for overloaded functions from HTML forms to no longer hang. - |br| -- `@laurenceisla `_ - -Thanks ------- - -Big thanks from the `PostgREST team `_ to our sponsors! - -.. container:: image-container - - .. image:: ../_static/cybertec-new.png - :target: https://www.cybertec-postgresql.com/en/?utm_source=postgrest.org&utm_medium=referral&utm_campaign=postgrest - :width: 13em - - .. image:: ../_static/2ndquadrant.png - :target: https://www.2ndquadrant.com/en/?utm_campaign=External%20Websites&utm_source=PostgREST&utm_medium=Logo - :width: 13em - - .. image:: ../_static/retool.png - :target: https://retool.com/?utm_source=sponsor&utm_campaign=postgrest - :width: 13em - - .. image:: ../_static/gnuhost.png - :target: https://gnuhost.eu/?utm_source=sponsor&utm_campaign=postgrest - :width: 13em - - .. image:: ../_static/supabase.png - :target: https://supabase.com/?utm_source=postgrest%20backers&utm_medium=open%20source%20partner&utm_campaign=postgrest%20backers%20github&utm_term=homepage - :width: 13em - - .. image:: ../_static/oblivious.jpg - :target: https://oblivious.ai/?utm_source=sponsor&utm_campaign=postgrest - :width: 13em - -* Evans Fernandes -* Jan Sommer -* `Franz Gusenbauer `_ -* `Daniel Babiak `_ -* Tsingson Qin -* Michel Pelletier -* Jay Hannah -* Robert Stolarz -* Nicholas DiBiase -* Christopher Reid -* Nathan Bouscal -* Daniel Rafaj -* David Fenko -* Remo Rechkemmer -* Severin Ibarluzea -* Tom Saleeba -* Pawel Tyll - -If you like to join them please consider `supporting PostgREST development `_. diff --git a/docs/tutorials/tut0.rst b/docs/tutorials/tut0.rst index 7b2ce647c..2d86c871f 100644 --- a/docs/tutorials/tut0.rst +++ b/docs/tutorials/tut0.rst @@ -165,7 +165,7 @@ PostgREST can use a configuration file to tell it how to connect to the database db-schemas = "api" db-anon-role = "web_anon" -The configuration file has other :doc:`options <../configuration>`, but this is all we need. +The configuration file has other :ref:`options `, but this is all we need. If you are not using Docker, make sure that your port number is correct and replace `postgres` with the name of the database where you added the todos table. Now run the server: diff --git a/postgrest.dict b/postgrest.dict index d99c43b30..7fed84b22 100644 --- a/postgrest.dict +++ b/postgrest.dict @@ -179,6 +179,7 @@ Tcl tmuxp todo todos +tos Tsingson tsquery tx