From bc3d735bf3be806b433eee1fcd70d38146caf710 Mon Sep 17 00:00:00 2001
From: Auke Booij <auke@hasura.io>
Date: Tue, 30 Jun 2020 10:39:25 +0200
Subject: [PATCH] server/docs: add instructions to fix loss of float precision
 in PostgreSQL <= 11 (#5187)

This adds a server flag, --pg-connection-options, that can be used to set a PostgreSQL connection parameter, extra_float_digits, that needs to be used to avoid loss of data on older versions of PostgreSQL, which have odd default behavior when returning float values. (fixes #5092)
---
 CHANGELOG.md                                  |  2 ++
 .../manual/api-reference/postgresql-types.rst |  9 ++++++--
 .../graphql-engine-flags/reference.rst        | 21 ++++++++++++++-----
 server/src-lib/Hasura/Server/Init.hs          | 10 ++++++++-
 4 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 042c557d30c..91b933b9509 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,7 @@
 
 (Add entries here in the order of: server, console, cli, docs, others)
 
+- server: add `--pg-connection-options` command-line flag for passing parameters to PostgreSQL (close #5092) (#5187)
 - server: improve memory usage of idle websockets connections (#5190)
 - server: few relay fixes (fix #5020, #5037, #5046) (#5013)
 - server: raise error on startup when `--unauthorized-role` is ignored (#4736)
@@ -40,6 +41,7 @@
 - console: allow configuring session_argument for custom functions (close #4499) (#4922)
 - console: fix listen update column config selection for event trigger (close #5042) (#5043)
 - cli: add new flags up-sql and down-sql to generate sql based migrations from the CLI (#5026)
+- docs: add instructions on fixing loss of data when using floats (close #5092)
 - docs: add page on setting up v2 migrations (close #4746) (#4898)
 
 ## `v1.3.0-beta.1`
diff --git a/docs/graphql/manual/api-reference/postgresql-types.rst b/docs/graphql/manual/api-reference/postgresql-types.rst
index ecc33853e5a..08bb45cefb0 100644
--- a/docs/graphql/manual/api-reference/postgresql-types.rst
+++ b/docs/graphql/manual/api-reference/postgresql-types.rst
@@ -53,6 +53,13 @@ E.g.
      }
    ]
 
+.. note::
+
+   To avoid loss of data when retrieving IEEE 754 style data from the database,
+   please refer to the :ref:`server_flag_reference` for instructions on setting
+   the ``extra_float_digits`` parameter, which has a bad default value in
+   PostgreSQL 11 and older.
+
 .. _Numeric:
 
 Numeric
@@ -327,5 +334,3 @@ E.g. For macaddr type
 .. Note::
 
    You can learn more about PostgreSQL data types `here <https://www.postgresql.org/docs/current/static/datatype.html>`__.
-
-
diff --git a/docs/graphql/manual/deployment/graphql-engine-flags/reference.rst b/docs/graphql/manual/deployment/graphql-engine-flags/reference.rst
index ee159a79e82..e803dcc52b9 100644
--- a/docs/graphql/manual/deployment/graphql-engine-flags/reference.rst
+++ b/docs/graphql/manual/deployment/graphql-engine-flags/reference.rst
@@ -46,12 +46,23 @@ Or you can specify the following options *(only via flags)*:
 
 .. code-block:: none
 
-      --host               Postgres server host
-  -p, --port               Postgres server port
-  -u, --user               Database user name
-  -p, --password           Password of the user
-  -d, --dbname             Database name to connect to
+      --host                      Postgres server host
+  -p, --port                      Postgres server port
+  -u, --user                      Database user name
+  -p, --password                  Password of the user
+  -d, --dbname                    Database name to connect to
+  -o, --pg-connection-options     PostgreSQL connection options
 
+.. note::
+
+   The default configuration of PostgreSQL 11 and older may result in loss of
+   precision when retrieving IEEE 754 style data, such as ``float4``, ``real``
+   or ``double precision`` values, from the database.  To avoid this, set the
+   ``extra_float_digits`` PostgreSQL connection parameter to 3.  This can be
+   done by passing ``'--pg-connection-options=-c extra_float_digits=3'`` to
+   ``graphql-engine``, or by passing this option as part of the database url:
+
+   ``postgres://admin:mypass@mydomain.com:5432/mydb?options=-c%20extra_float_digits%3D3``
 
 .. _command-flags:
 
diff --git a/server/src-lib/Hasura/Server/Init.hs b/server/src-lib/Hasura/Server/Init.hs
index 1540b51bd0e..274ee2317f3 100644
--- a/server/src-lib/Hasura/Server/Init.hs
+++ b/server/src-lib/Hasura/Server/Init.hs
@@ -492,7 +492,7 @@ adminInternalErrorsEnv =
 parseRawConnInfo :: Parser RawConnInfo
 parseRawConnInfo =
   RawConnInfo <$> host <*> port <*> user <*> password
-              <*> dbUrl <*> dbName <*> pure Nothing
+              <*> dbUrl <*> dbName <*> options
               <*> retries
   where
     host = optional $
@@ -532,6 +532,14 @@ parseRawConnInfo =
                   metavar "<DBNAME>" <>
                   help "Database name to connect to"
                 )
+
+    options = optional $
+      strOption ( long "pg-connection-options" <>
+                  short 'o' <>
+                  metavar "<DATABASE-OPTIONS>" <>
+                  help "PostgreSQL options"
+                )
+
     retries = optional $
       option auto ( long "retries" <>
                     metavar "NO OF RETRIES" <>