add: config db-timezone-enabled for optional querying of timezones

To avoid repeated querying of `pg_timezone_names` every time schema
cache is reset, `Prefer: timezone` can be disabled by setting
`db-timezone-enabled = false`.

Signed-off-by: Taimoor Zaeem <taimoorzaeem@gmail.com>

CHANGELOG.md

@@ -14,6 +14,7 @@ All notable changes to this project will be documented in this file. From versio
   + Removed unnecessary double count when building the `Content-Range`.
 - Add config `client-error-verbosity` to customize error verbosity by @taimoorzaeem in #4088, #3980, #3824
 - Add `Vary` header to responses by @develop7 in #4609
+- Add config `db-timezone-enabled` for optional querying of timezones by @taimoorzaeem in #4751
 
 ### Changed
 

docs/references/api/preferences.rst

@@ -117,6 +117,10 @@ However, with ``handling=strict``, an invalid time zone preference will throw an
 
   HTTP/1.1 400 Bad Request
 
+.. note::
+
+  This feature requires querying `pg_timezone_names <https://www.postgresql.org/docs/current/view-pg-timezone-names.html>`_ during :ref:`schema_cache` load. If this is not desired, you can disable the feature with :ref:`db-timezone-enabled`.
+
 .. _prefer_return:
 
 Return Representation

docs/references/configuration.rst

@@ -540,6 +540,21 @@ db-schemas
 
   The list of database schemas to expose to clients. See :ref:`schemas`.
 
+.. _db-timezone-enabled:
+
+db-timezone-enabled
+-------------------
+
+  =============== =================================
+  **Type**        Boolean
+  **Default**     True
+  **Reloadable**  Y
+  **Environment** PGRST_DB_TIMEZONE_ENABLED
+  **In-Database** pgrst.db_timezone_enabled
+  =============== =================================
+
+  Enables the use of :ref:`prefer_timezone` preference header. Disabled when set to ``false``.
+
 .. _db-tx-end:
 
 db-tx-end

src/PostgREST/Config.hs

@@ -94,6 +94,7 @@ data AppConfig = AppConfig
   , configDbSchemas                :: NonEmpty Text
   , configDbConfig                 :: Bool
   , configDbPreConfig              :: Maybe QualifiedIdentifier
+  , configDbTimezoneEnabled        :: Bool
   , configDbTxAllowOverride        :: Bool
   , configDbTxRollbackAll          :: Bool
   , configDbUri                    :: Text
@@ -181,6 +182,7 @@ toText conf =
       ,("db-schemas",                q . T.intercalate "," . toList . configDbSchemas)
       ,("db-config",                     T.toLower . show . configDbConfig)
       ,("db-pre-config",             q . maybe mempty dumpQi . configDbPreConfig)
+      ,("db-timezone-enabled",           T.toLower . show . configDbTimezoneEnabled)
       ,("db-tx-end",                 q . showTxEnd)
       ,("db-uri",                    q . configDbUri)
       ,("jwt-aud",                   q . fromMaybe mempty . configJwtAudience)
@@ -290,6 +292,7 @@ parser optPath env dbSettings roleSettings roleIsolationLvl =
     <*> parseDbSchemas "db-schemas" "db-schema"
     <*> (fromMaybe True <$> optBool "db-config")
     <*> (fmap toQi <$> optString "db-pre-config")
+    <*> (fromMaybe True <$> optBool "db-timezone-enabled")
     <*> parseTxEnd "db-tx-end" snd
     <*> parseTxEnd "db-tx-end" fst
     <*> (fromMaybe "postgresql://" <$> optString "db-uri")
@@ -715,6 +718,9 @@ exampleConfigFile = S.unlines
   , "## The name of which database schema to expose to REST clients"
   , "db-schemas = \"public\""
   , ""
+  , "## Enable quering pg_timezone_names from db"
+  , "# db-timezone-enabled = true"
+  , ""
   , "## How to terminate database transactions"
   , "## Possible values are:"
   , "## commit (default)"

src/PostgREST/Config/Database.hs

@@ -56,6 +56,7 @@ dbSettingsNames =
   ,"db_prepared_statements"
   ,"db_root_spec"
   ,"db_schemas"
+  ,"db_timezone_enabled"
   ,"db_tx_end"
   ,"db_hoisted_tx_settings"
   ,"jwt_aud"

src/PostgREST/SchemaCache.hs

@@ -159,7 +159,9 @@ querySchemaCache conf@AppConfig{..} = do
   cRels   <- SQL.statement mempty $ allComputedRels prepared
   reps    <- SQL.statement conf $ dataRepresentations prepared
   mHdlers <- SQL.statement conf $ mediaHandlers prepared
-  tzones  <- SQL.statement mempty $ timezones prepared
+  tzones  <- if configDbTimezoneEnabled
+    then SQL.statement mempty $ timezones prepared
+    else pure S.empty
   _       <-
     let sleepCall = SQL.Statement "select pg_sleep($1 / 1000.0)" (param HE.int4) HD.noResult prepared in
     for_ configInternalSCQuerySleep (`SQL.statement` sleepCall) -- only used for testing
@@ -1109,7 +1111,13 @@ decodeMediaHandlers =
 timezones :: Bool -> SQL.Statement () TimezoneNames
 timezones = SQL.Statement sql HE.noParams decodeTimezones
   where
-    sql = "SELECT name FROM pg_timezone_names"
+    sql = encodeUtf8 $ unlines
+      -- This CTE wrapper is only added for clarifying the query under pg_stat_statements
+      ["WITH pgrst_timezones AS ("
+      , "  SELECT name FROM pg_timezone_names"
+      , ")"
+      , "SELECT * FROM pgrst_timezones"
+      ]
     decodeTimezones :: HD.Result TimezoneNames
     decodeTimezones = S.fromList <$> HD.rowList (column HD.text)
 

test/io/configs/expected/aliases.config

@@ -18,6 +18,7 @@ db-root-spec = "open_alias"
 db-schemas = "provided_through_alias"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/boolean-numeric.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/boolean-string.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/defaults.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = false
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/jspath-str-op-dump1.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/jspath-str-op-dump2.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/jspath-str-op-dump3.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/jspath-str-op-dump4.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/jspath-str-op-dump5.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/no-defaults-with-db-other-authenticator.config

@@ -18,6 +18,7 @@ db-root-spec = "other_root"
 db-schemas = "test,other_tenant1,other_tenant2"
 db-config = true
 db-pre-config = "postgrest.other_preconf"
+db-timezone-enabled = false
 db-tx-end = "rollback-allow-override"
 db-uri = "postgresql://"
 jwt-aud = "https://otherexample.org"

test/io/configs/expected/no-defaults-with-db.config

@@ -18,6 +18,7 @@ db-root-spec = "root"
 db-schemas = "test,tenant1,tenant2"
 db-config = true
 db-pre-config = "postgrest.preconf"
+db-timezone-enabled = false
 db-tx-end = "commit-allow-override"
 db-uri = "postgresql://"
 jwt-aud = "https://example.org"

test/io/configs/expected/no-defaults.config

@@ -18,6 +18,7 @@ db-root-spec = "openapi_v3"
 db-schemas = "multi,tenant,setup"
 db-config = false
 db-pre-config = "postgrest.pre_config"
+db-timezone-enabled = false
 db-tx-end = "rollback-allow-override"
 db-uri = "tmp_db"
 jwt-aud = "https://postgrest.org"

test/io/configs/expected/types.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/expected/utf-8.config

@@ -18,6 +18,7 @@ db-root-spec = ""
 db-schemas = "public"
 db-config = true
 db-pre-config = ""
+db-timezone-enabled = true
 db-tx-end = "commit"
 db-uri = "postgresql://"
 jwt-aud = ""

test/io/configs/no-defaults-env.yaml

@@ -20,6 +20,7 @@ PGRST_DB_ROOT_SPEC: openapi_v3
 PGRST_DB_SCHEMAS: multi,   tenant,setup
 PGRST_DB_CONFIG: false
 PGRST_DB_PRE_CONFIG: "postgrest.pre_config"
+PGRST_DB_TIMEZONE_ENABLED: false
 PGRST_DB_TX_END: rollback-allow-override
 PGRST_DB_URI: tmp_db
 PGRST_DB_USE_LEGACY_GUCS: false

test/io/configs/no-defaults.config

@@ -18,6 +18,7 @@ db-root-spec = "openapi_v3"
 db-schemas = "multi,   tenant,setup"
 db-config = false
 db-pre-config = "postgrest.pre_config"
+db-timezone-enabled = false
 db-tx-end = "rollback-allow-override"
 db-uri = "tmp_db"
 jwt-aud = "https://postgrest.org"

test/io/fixtures/db_config.sql

@@ -13,6 +13,7 @@ ALTER ROLE db_config_authenticator SET pgrst.db_pre_request = 'test.custom_heade
 ALTER ROLE db_config_authenticator SET pgrst.db_prepared_statements = 'false';
 ALTER ROLE db_config_authenticator SET pgrst.db_root_spec = 'root';
 ALTER ROLE db_config_authenticator SET pgrst.db_schemas = 'test, tenant1, tenant2';
+ALTER ROLE db_config_authenticator SET pgrst.db_timezone_enabled = 'false';
 ALTER ROLE db_config_authenticator SET pgrst.db_tx_end = 'commit-allow-override';
 ALTER ROLE db_config_authenticator SET pgrst.jwt_aud = 'https://example.org';
 ALTER ROLE db_config_authenticator SET pgrst.jwt_cache_max_entries = '86400';
@@ -67,6 +68,7 @@ ALTER ROLE other_authenticator SET pgrst.db_pre_request = 'test.other_custom_hea
 ALTER ROLE other_authenticator SET pgrst.db_prepared_statements = 'false';
 ALTER ROLE other_authenticator SET pgrst.db_root_spec = 'other_root';
 ALTER ROLE other_authenticator SET pgrst.db_schemas = 'test, other_tenant1, other_tenant2';
+ALTER ROLE other_authenticator SET pgrst.db_timezone_enabled = 'false';
 ALTER ROLE other_authenticator SET pgrst.jwt_aud = 'https://otherexample.org';
 ALTER ROLE other_authenticator SET pgrst.jwt_secret = 'ODERREALLYREALLYREALLYREALLYVERYSAFE';
 ALTER ROLE other_authenticator SET pgrst.jwt_secret_is_base64 = 'false';

test/observability/ObsHelper.hs

@@ -91,6 +91,7 @@ baseCfg = let secret = encodeUtf8 "reallyreallyreallyreallyverysafe" in
   , configDbSchemas                 = fromList ["test"]
   , configDbConfig                  = False
   , configDbPreConfig               = Nothing
+  , configDbTimezoneEnabled         = True
   , configDbUri                     = "postgresql://"
   , configFilePath                  = Nothing
   , configJWKS                      = rightToMaybe $ parseSecret secret

test/spec/Feature/Query/Preferences/TimezoneSpec.hs

@@ -10,9 +10,9 @@ import Test.Hspec.Wai.JSON
 import Protolude  hiding (get)
 import SpecHelper
 
-spec :: SpecWith ((), Application)
-spec =
-  describe "test Prefer: timezone" $ do
+enabledSpec :: SpecWith ((), Application)
+enabledSpec =
+  describe "test Prefer: timezone with db-timezone-enabled is true" $ do
     context "test Prefer: timezone=America/Los_Angeles" $ do
       it "should change timezone with handling=strict" $
         request methodGet "/timestamps"
@@ -60,3 +60,34 @@ spec =
           { matchStatus = 200
           , matchHeaders = [matchContentTypeJson
                            , "Preference-Applied" <:> "handling=lenient"]}
+
+
+disabledSpec :: SpecWith ((), Application)
+disabledSpec =
+  describe "test Prefer: timezone with db-timezone-enabled is false" $ do
+    context "test Prefer: timezone=America/Los_Angeles when timezone is disabled" $ do
+      it "should throw error with handling=strict" $
+        request methodGet "/timestamps"
+          [("Prefer", "handling=strict, timezone=America/Los_Angeles")]
+          ""
+          `shouldRespondWith`
+          [json|{"code":"PGRST122","details":"Invalid preferences: timezone=America/Los_Angeles","hint":null,"message":"Invalid preferences given with handling=strict"}|]
+          { matchStatus = 400 }
+
+      it "should return with default timezone without handling or with handling=lenient" $ do
+        request methodGet "/timestamps"
+          [("Prefer", "timezone=America/Los_Angeles")]
+          ""
+          `shouldRespondWith`
+          [json|[{"t":"2023-10-18T12:37:59.611+00:00"}, {"t":"2023-10-18T14:37:59.611+00:00"}, {"t":"2023-10-18T16:37:59.611+00:00"}]|]
+          { matchStatus = 200
+          , matchHeaders = [matchContentTypeJson]}
+
+        request methodGet "/timestamps"
+          [("Prefer", "handling=lenient, timezone=America/Los_Angeles")]
+          ""
+          `shouldRespondWith`
+          [json|[{"t":"2023-10-18T12:37:59.611+00:00"}, {"t":"2023-10-18T14:37:59.611+00:00"}, {"t":"2023-10-18T16:37:59.611+00:00"}]|]
+          { matchStatus = 200
+          , matchHeaders = [matchContentTypeJson
+                           , "Preference-Applied" <:> "handling=lenient"]}

test/spec/Main.hs

@@ -128,6 +128,7 @@ main = do
       unicodeApp           = appDbs testUnicodeCfg
       multipleSchemaApp    = appDbs testMultipleSchemaCfg
       ignorePrivOpenApi    = appDbs testIgnorePrivOpenApiCfg
+      timezoneDisabled     = appDbs testCfgTimezoneDisabled
 
 
   let analyze :: IO ()
@@ -157,7 +158,6 @@ main = do
         , ("Feature.Query.PlanSpec.disabledSpec"         , Feature.Query.PlanSpec.disabledSpec)
         , ("Feature.Query.Preferences.HandlingSpec"      , Feature.Query.Preferences.HandlingSpec.spec)
         , ("Feature.Query.Preferences.MaxAffectedSpec"   , Feature.Query.Preferences.MaxAffectedSpec.spec)
-        , ("Feature.Query.Preferences.TimezoneSpec"      , Feature.Query.Preferences.TimezoneSpec.spec)
         , ("Feature.Query.QuerySpec"                     , Feature.Query.QuerySpec.spec)
         , ("Feature.Query.RawOutputTypesSpec"            , Feature.Query.RawOutputTypesSpec.spec)
         , ("Feature.Query.RelatedQueriesSpec"            , Feature.Query.RelatedQueriesSpec.spec)
@@ -257,6 +257,15 @@ main = do
     parallel $ before withApp $
       describe "Feature.Query.AggregateFunctionsDisallowedSpec." Feature.Query.AggregateFunctionsSpec.disallowed
 
+    -- this test runs with db-timezone-enabled = true
+    parallel $ before withApp $
+      describe "Feature.Query.Preferences.TimezoneSpec.enabledSpec" Feature.Query.Preferences.TimezoneSpec.enabledSpec
+
+    -- this test runs with db-timezone-enabled = false
+    parallel $ before timezoneDisabled $
+      describe "Feature.Query.Preferences.TimezoneSpec.disabledSpec" Feature.Query.Preferences.TimezoneSpec.disabledSpec
+
+
     -- Note: the rollback tests can not run in parallel, because they test persistance and
     -- this results in race conditions
 

test/spec/SpecHelper.hs

@@ -132,6 +132,7 @@ baseCfg = let secret = encodeUtf8 "reallyreallyreallyreallyverysafe" in
   , configDbSchemas                 = fromList ["test"]
   , configDbConfig                  = False
   , configDbPreConfig               = Nothing
+  , configDbTimezoneEnabled         = True
   , configDbUri                     = "postgresql://"
   , configFilePath                  = Nothing
   , configJWKS                      = rightToMaybe $ parseSecret secret
@@ -254,6 +255,9 @@ testCfgServerTiming = baseCfg { configDbPlanEnabled = True }
 testCfgAggregatesEnabled :: AppConfig
 testCfgAggregatesEnabled = baseCfg { configDbAggregates = True }
 
+testCfgTimezoneDisabled :: AppConfig
+testCfgTimezoneDisabled = baseCfg { configDbTimezoneEnabled = False }
+
 analyzeTable :: Text -> IO ()
 analyzeTable tableName =
   void $ readProcess "psql" ["-U", "postgres", "--set", "ON_ERROR_STOP=1", "-a", "-c", toS $ "ANALYZE test.\"" <> tableName <> "\""] []