graphql-engine/docs/graphql/core/api-reference/pgdump.rst
Rikin Kachhia 8246bcc9d3 docs: misc fixes
- add config api to default enabled api list
- add source key to pg_dump api ref
- add websocket-compression option to config ref
- add websocket-timeout option to config ref
- document using negative integers to decrement
- update one-to-one nested insert caveat

https://github.com/hasura/graphql-engine-mono/pull/2146

GitOrigin-RevId: d76bcdc136b2a25b9f2589155142f3272aa69c7b
2021-08-24 12:08:36 +00:00

107 lines
2.9 KiB
ReStructuredText

.. meta::
:description: Hasura PG dump API reference
:keywords: hasura, docs, PG dump API, API reference
.. _pg_dump_api_reference:
PG Dump API Reference
=====================
.. contents:: Table of contents
:backlinks: none
:depth: 1
:local:
Introduction
------------
The PG Dump API is an admin-only endpoint that can be used to execute ``pg_dump`` on the
Postgres instance that Hasura is configured with.
The primary motive of this API is to provide convenience methods to initialise migrations from an
existing Hasura instance. But the functionality can be later expanded to do other things
such as taking a data dump etc.
Endpoint
--------
All requests are ``POST`` requests to the ``/v1alpha1/pg_dump`` endpoint.
API Spec
--------
Request
^^^^^^^
.. code-block:: http
POST /v1alpha1/pg_dump HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin
{
"opts": ["-O", "-x", "--schema-only", "--schema", "public"],
"clean_output": true,
"source": "<database-source-name>"
}
- ``opts``: Arguments to be passed to the ``pg_dump`` tool. Represented as array
of strings. The underlying command that is executed is:
.. code-block:: bash
pg_dump $DATABASE_URL $OPTS -f $FILENAME
- ``clean_output``: When this optional argument is set to ``true``, the output SQL from
the command is cleaned to remove the following:
- SQL front matter, like SET statements.
- ``CREATE SCHEMA public``.
- ``COMMENT ON SCHEMA public is 'standard public schema'``;
- Comments (``--``) and empty newlines.
- Postgres triggers created by Hasura for event triggers.
- ``source``: the name of the connected database on which to run ``pg_dump`` on. If skipped,
it is set to ``default``
Sample response
^^^^^^^^^^^^^^^
.. code-block:: http
HTTP/1.1 200 OK
Content-Type: application/sql
SET check_function_bodies = false;
CREATE TABLE public.author (
id integer NOT NULL,
name text NOT NULL
);
CREATE SEQUENCE public.author_id_seq
AS integer
START WITH 1
INCREMENT BY 1
NO MINVALUE
NO MAXVALUE
CACHE 1;
ALTER SEQUENCE public.author_id_seq OWNED BY public.author.id;
ALTER TABLE ONLY public.author ALTER COLUMN id SET DEFAULT nextval('public.author_id_seq'::regclass);
Disabling PG Dump API
---------------------
Since this API can be used to dump all the Postgres data and schema, it can be
disabled, especially in production deployments.
The ``enabled-apis`` flag or the ``HASURA_GRAPHQL_ENABLED_APIS`` env var can be used to
enable/disable this API. By default, The PG DumpAPI is enabled. To disable it, you need to explicitly
state that this API is not enabled. i.e. remove it from the list of enabled APIs.
.. code-block:: bash
# enable only graphql & metadata apis, disable pgdump
--enabled-apis="graphql,metadata"
HASURA_GRAPHQL_ENABLED_APIS="graphql,metadata"
See :ref:`server_flag_reference` for info on setting the above flag/env var.