The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs - filter out read-only settings for config (#78970)
Jeff Bruemmeredae5380bb1a
diff --git a/src/metabase/cmd/config_file_gen.clj b/src/metabase/cmd/config_file_gen.cljindex 29a67fa18b9..306c3abd90e 100644--- a/src/metabase/cmd/config_file_gen.clj+++ b/src/metabase/cmd/config_file_gen.clj@@ -18,12 +18,20 @@[settings](reduce (fn [settings k] (assoc settings k nil)) settings settings-to-reset))+(defn config-file-settings+ "Filters settings down to those that are valid in a config file template. We include deprecated+ settings in the env var docs, but we exclude them from the config file template. We likewise+ exclude read-only (`:setter :none`) settings: the config file sets settings via the same path as+ the Admin settings, so it can never set them."+ [settings]+ (->> settings+ dox/remove-env-vars-we-should-not-document+ (filter dox/settable-in-config-file?)))+(defn settings- "Gets valid config settings. We include deprecated settings in the env var docs,- but we exclude them from the config file template."+ "Gets valid config settings."[]- (->> (dox/get-settings)- dox/remove-env-vars-we-should-not-document))+ (config-file-settings (dox/get-settings)))(defn get-name-and-default"Get a setting's name and its default."diff --git a/src/metabase/cmd/env_var_dox.clj b/src/metabase/cmd/env_var_dox.cljindex 08da4e9c270..fcdedbbea71 100644--- a/src/metabase/cmd/env_var_dox.clj+++ b/src/metabase/cmd/env_var_dox.clj@@ -123,11 +123,25 @@(when (string? d)d)))+(defn settable-in-config-file?+ "Can this setting be set via the `settings:` section of a configuration file?+ Settings with `:setter` `:none` are read-only: the config file calls the same `setting/set!` path as+ the Admin settings, so it will always reject them."+ [env-var]+ (not= :none (:setter env-var)))+(defn- format-config-name- "Formats the configuration file name for an environment variable."+ "Formats the configuration file name for an environment variable, or notes that the setting is+ read-only and can only be set with an environment variable."[env-var]- (if (= (:visibility env-var) :internal)+ (cond+ (not (settable-in-config-file? env-var))+ "Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file.md)."++ (= (:visibility env-var) :internal)""++ :else(str "[Configuration file name](./config-file.md): `" (:munged-name env-var) "`")))(defn- list-item@@ -175,7 +189,7 @@(contains? env-vars-not-to-mess-with (format-prefix env-var))))(defn- setter-none?- "Used to remove settings that lack a setter (`:setter :none`).+ "Used to remove undocumented settings that lack a setter (`:setter :none`).For example, settings that are derived from other settings."[env-var];; If the `defsetting` has a `:doc` key with a string, we should document it.diff --git a/test/metabase/cmd/config_file_gen_test.clj b/test/metabase/cmd/config_file_gen_test.cljindex 1fbbafdc4db..4190af50e0f 100644--- a/test/metabase/cmd/config_file_gen_test.clj+++ b/test/metabase/cmd/config_file_gen_test.clj@@ -1,7 +1,7 @@(ns metabase.cmd.config-file-gen-test(:require[clojure.test :refer :all]- [metabase.cmd.config-file-gen :refer [create-settings-map]]))+ [metabase.cmd.config-file-gen :refer [config-file-settings create-settings-map]]))(def example-settings '({:database-local :never,:cache? true,@@ -85,6 +85,33 @@:munged-name "deprecated-setting",:visibility :public}))+(def ^:private read-only-setting+ "A read-only (`:setter :none`) setting that also carries a `:doc` string, like+ `ai-usage-max-retention-days`. It can be read from an environment variable, so it belongs in the+ env var docs, but a config file can never set it."+ {:database-local :never,+ :cache? true,+ :user-local :never,+ :init nil,+ :default nil,+ :name :ai-usage-max-retention-days,+ :export? true,+ :type :integer,+ :enabled? nil,+ :encryption :no,+ :deprecated nil,+ :audit :never,+ :sensitive? false,+ :tag java.lang.Long,+ :on-change nil,+ :setter :none,+ :doc+ "Sets the maximum number of days Metabase preserves rows for the following application database tables:\n\n- `ai_usage_log`",+ :feature nil,+ :namespace 'metabase.metabot.settings,+ :munged-name "ai-usage-max-retention-days",+ :visibility :admin})+(def settings-map{:admin-email nil:aggregated-query-row-limit nil@@ -95,3 +122,15 @@(let [settings (create-settings-map example-settings)](is (= settings-mapsettings)))))++(deftest config-file-settings-excludes-read-only-settings-test+ (testing "Read-only settings are excluded from the config file template, even when they have a `:doc`"+ (let [names (->> (conj (vec example-settings) read-only-setting)+ config-file-settings+ (map :munged-name)+ set)]+ (is (not (contains? names "ai-usage-max-retention-days"))+ "a `:setter :none` setting must never be offered as a config file setting")+ (testing "and settable settings are still included"+ (is (contains? names "admin-email"))+ (is (contains? names "aggregated-query-row-limit"))))))diff --git a/test/metabase/cmd/env_var_dox_test.clj b/test/metabase/cmd/env_var_dox_test.cljindex b976914f0cf..c67a0adbd4c 100644--- a/test/metabase/cmd/env_var_dox_test.clj+++ b/test/metabase/cmd/env_var_dox_test.clj@@ -75,6 +75,35 @@(testing "returns nil when doc key is missing"(is (nil? (#'sut/format-doc {}))))))+(deftest ^:parallel settable-in-config-file?-test+ (testing "Read-only settings can't be set in a config file"+ (is (false? (sut/settable-in-config-file? {:setter :none}))))+ (testing "Settings with a setter can"+ (is (true? (sut/settable-in-config-file? {:setter (fn [_])})))+ (is (true? (sut/settable-in-config-file? {})))))++(def ^:private env-var-only-note+ "Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file.md).")++(deftest ^:parallel format-config-name-test+ (testing "Read-only settings are flagged as environment-variable-only, whatever their visibility"+ (is (= env-var-only-note+ (#'sut/format-config-name {:munged-name "show-google-sheets-integration"+ :setter :none+ :visibility :public})))+ (testing "including internal ones, which otherwise get no line at all"+ (is (= env-var-only-note+ (#'sut/format-config-name {:munged-name "audit-max-retention-days"+ :setter :none+ :visibility :internal})))))+ (testing "Internal settings with a setter get no config file line"+ (is (= "" (#'sut/format-config-name {:munged-name "internal-setting"+ :visibility :internal}))))+ (testing "Settable, non-internal settings get their config file name"+ (is (= "[Configuration file name](./config-file.md): `admin-email`"+ (#'sut/format-config-name {:munged-name "admin-email"+ :visibility :authenticated})))))+(deftest ^:parallel format-env-var-entry-with-false-doc-test(testing "format-env-var-entry doesn't crash when env-var has :doc false"(let [env-var-with-false-doc {:name :test-setting