Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

GHY-3687 Handle is_sample database (#74839)

Eric Normandf6bf515793db
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index a23c5895221..a145b2beddc 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -2698,6 +2698,7 @@
lib
permissions
premium-features
+ sample-data
settings
setup
sync
@@ -3524,6 +3525,7 @@
permissions
premium-features
query-processor
+ sample-data
server
settings
sql-tools
diff --git a/enterprise/backend/src/metabase_enterprise/advanced_config/file/databases.clj b/enterprise/backend/src/metabase_enterprise/advanced_config/file/databases.clj
index e32df469c9a..e1960ec0560 100644
--- a/enterprise/backend/src/metabase_enterprise/advanced_config/file/databases.clj
+++ b/enterprise/backend/src/metabase_enterprise/advanced_config/file/databases.clj
@@ -6,6 +6,7 @@
[metabase-enterprise.advanced-config.file.interface :as advanced-config.file.i]
[metabase-enterprise.advanced-config.settings :as advanced-config.settings]
[metabase.driver.util :as driver.u]
+ [metabase.sample-data.core :as sample-data]
[metabase.util :as u]
[metabase.util.log :as log]
[metabase.util.quick-task :as quick-task]
@@ -23,6 +24,9 @@
(s/def :metabase-enterprise.advanced-config.file.databases.config-file-spec/is_stub
boolean?)
+(s/def :metabase-enterprise.advanced-config.file.databases.config-file-spec/is_sample
+ boolean?)
+
(defn- valid-regex-patterns? [patterns]
(every? (fn [pattern]
(try
@@ -49,7 +53,8 @@
:metabase-enterprise.advanced-config.file.databases.config-file-spec/name
:metabase-enterprise.advanced-config.file.databases.config-file-spec/details]
:opt-un [:metabase-enterprise.advanced-config.file.databases.config-file-spec/settings
- :metabase-enterprise.advanced-config.file.databases.config-file-spec/is_stub]))
+ :metabase-enterprise.advanced-config.file.databases.config-file-spec/is_stub
+ :metabase-enterprise.advanced-config.file.databases.config-file-spec/is_sample]))
(defmethod advanced-config.file.i/section-spec :databases
[_section]
@@ -66,9 +71,31 @@
[database]
(dissoc database :uploads_enabled :uploads_schema_name :uploads_table_prefix))
+(defn- init-sample-database!
+ "Handle an `:is_sample true` config entry. Validates that the entry refers to
+ the canonical Sample Database (name + engine), then recreates it from the
+ bundled fixture if one is not already present. The entry's `:details` are
+ ignored — the sample DB always uses its bundled H2 file."
+ [database]
+ (when (or (not= (:name database) sample-data/sample-database-name)
+ (not= (:engine database) "h2"))
+ (throw (ex-info (format "Invalid is_sample entry: name must be %s and engine must be \"h2\"; got name %s, engine %s"
+ (pr-str sample-data/sample-database-name)
+ (pr-str (:name database))
+ (pr-str (:engine database)))
+ {:status-code 400
+ :name (:name database)
+ :engine (:engine database)})))
+ (if (t2/exists? :model/Database :is_sample true)
+ (log/info "Sample Database already present; ignoring is_sample config entry")
+ (do
+ (log/info (u/format-color :green "Recreating Sample Database from is_sample config entry"))
+ (sample-data/extract-and-sync-sample-database!))))
+
(defn- init-from-config-file!
[database]
- (if (contains? database :delete)
+ (cond
+ (contains? database :delete)
;; Databases can be managed as a service by us. When the service is canceled, we need to delete any information
;; Metabase has about them, including any stored credentials. This is a config file flag instead of a CLI command,
;; so we can ensure the database stays deleted even after restoring backups.
@@ -80,6 +107,11 @@
(when-let [existing-database-id (t2/select-one-pk :model/Database :engine (:engine database), :name (:name database))]
(log/info (u/format-color :blue "Deleting Database %s %s" (:engine database) (pr-str (:name database))))
(t2/delete! :model/Database existing-database-id)))
+
+ (:is_sample database)
+ (init-sample-database! database)
+
+ :else
(do
;; assert that we are able to connect to this Database. Otherwise, throw an Exception.
;; Stubs are placeholders with no usable details, so we skip the connection test.
diff --git a/enterprise/backend/src/metabase_enterprise/workspaces/config.clj b/enterprise/backend/src/metabase_enterprise/workspaces/config.clj
index 326a51c60cc..e8546556839 100644
--- a/enterprise/backend/src/metabase_enterprise/workspaces/config.clj
+++ b/enterprise/backend/src/metabase_enterprise/workspaces/config.clj
@@ -6,6 +6,7 @@
[metabase-enterprise.workspaces.models.workspace-database]
[metabase.driver :as driver]
[metabase.driver.util :as driver.u]
+ [metabase.sample-data.core :as sample-data]
[metabase.util.yaml :as yaml]
[toucan2.core :as t2]))
@@ -87,8 +88,8 @@
(defn- stub-databases
"Databases that exist in the instance but are not provisioned for this workspace.
- Excludes the sample DB (handled by GHY-3687), the audit DB, and routing-target
- databases (destinations with `:router_database_id` set)."
+ Excludes the sample DB (emitted separately by `sample-database-entries`), the
+ audit DB, and routing-target databases (destinations with `:router_database_id` set)."
[workspace-db-ids]
(t2/select :model/Database
{:where [:and
@@ -99,6 +100,17 @@
[:not-in :id workspace-db-ids]
true)]}))
+(defn- sample-database-entries
+ "If the instance has a Sample Database, emit a single placeholder entry the
+ import side will use to recreate it. Always uses the canonical name/engine —
+ the entry is a directive (\"there should be a sample DB here\"), not a snapshot."
+ []
+ (when (t2/exists? :model/Database :is_sample true)
+ [{:name sample-data/sample-database-name
+ :engine "h2"
+ :details {}
+ :is_sample true}]))
+
(defn build-workspace-config
"Return a downloadable config.yml-shaped map for `workspace-id`:
@@ -131,9 +143,12 @@
:let [db (get dbs-by-id (:database_id wsd))]]
[wsd db])
ws-entries (mapv (fn [[wsd db]] (database-entry wsd db)) pairs)
- stub-entries (mapv stub-database-entry (stub-databases workspace-db-ids))]
+ stub-entries (mapv stub-database-entry (stub-databases workspace-db-ids))
+ sample-entries (sample-database-entries)]
{:version 1
- :config {:databases (into ws-entries stub-entries)
+ :config {:databases (-> ws-entries
+ (into stub-entries)
+ (into sample-entries))
:workspace {:name (:name ws)
:databases (into {} (map (fn [[wsd db]] (workspace-database-entry wsd db))) pairs)}}}))))
diff --git a/enterprise/backend/test/metabase_enterprise/advanced_config/file/databases_test.clj b/enterprise/backend/test/metabase_enterprise/advanced_config/file/databases_test.clj
index 2ada1403858..01fb1020f6e 100644
--- a/enterprise/backend/test/metabase_enterprise/advanced_config/file/databases_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/advanced_config/file/databases_test.clj
@@ -5,6 +5,7 @@
[metabase-enterprise.advanced-config.file.databases :as advanced-config.file.databases]
[metabase.app-db.core :as mdb]
[metabase.driver.settings :as driver.settings]
+ [metabase.sample-data.core :as sample-data]
[metabase.sync.sync-metadata :as sync-metadata]
[metabase.test :as mt]
[metabase.util :as u]
@@ -119,6 +120,80 @@
(testing "existing :is_stub flag is preserved (still false)"
(is (false? (:is_stub reloaded)))))))))
+(deftest init-from-config-file-sample-recreates-missing-test
+ (testing "An is_sample entry triggers recreation of the Sample Database when one is not present."
+ (let [delete-existing! (fn []
+ (when-let [ids (seq (t2/select-pks-vec :model/Database :is_sample true))]
+ (t2/delete! :model/Database :id [:in ids])))
+ extract-calls (atom 0)]
+ (delete-existing!)
+ (try
+ (with-redefs [sample-data/extract-and-sync-sample-database!
+ (fn []
+ (swap! extract-calls inc)
+ ;; simulate extract by inserting a sample row
+ (t2/insert! :model/Database
+ {:name "Sample Database" :engine :h2 :details {} :is_sample true}))]
+ (is (= :ok
+ (advanced-config.file/initialize!
+ {:version 1
+ :config {:databases [{:name "Sample Database"
+ :engine "h2"
+ :details {}
+ :is_sample true}]}})))
+ (testing "extract-and-sync-sample-database! is invoked exactly once"
+ (is (= 1 @extract-calls)))
+ (testing "a sample DB row now exists"
+ (is (t2/exists? :model/Database :is_sample true))))
+ (finally
+ (delete-existing!))))))
+
+(deftest init-from-config-file-sample-noop-when-present-test
+ (testing "An is_sample entry is a no-op when the Sample Database already exists."
+ (let [extract-calls (atom 0)]
+ (mt/with-temp [:model/Database _existing {:name "Sample Database"
+ :engine :h2
+ :details {:db "preexisting"}
+ :is_sample true}]
+ (with-redefs [sample-data/extract-and-sync-sample-database!
+ (fn [] (swap! extract-calls inc))]
+ (is (= :ok
+ (advanced-config.file/initialize!
+ {:version 1
+ :config {:databases [{:name "Sample Database"
+ :engine "h2"
+ :details {}
+ :is_sample true}]}})))
+ (testing "extract-and-sync-sample-database! is NOT invoked"
+ (is (zero? @extract-calls)))
+ (testing "existing sample row is untouched"
+ (is (= {:db "preexisting"}
+ (:details (t2/select-one :model/Database :is_sample true))))))))))
+
+(deftest init-from-config-file-sample-rejects-wrong-name-test
+ (testing "An is_sample entry with a name other than the canonical Sample Database name is rejected."
+ (is (thrown-with-msg?
+ ExceptionInfo
+ #"(?i)sample database"
+ (advanced-config.file/initialize!
+ {:version 1
+ :config {:databases [{:name "ABC"
+ :engine "h2"
+ :details {}
+ :is_sample true}]}})))))
+
+(deftest init-from-config-file-sample-rejects-wrong-engine-test
+ (testing "An is_sample entry with an engine other than h2 is rejected."
+ (is (thrown-with-msg?
+ ExceptionInfo
+ #"(?i)sample database"
+ (advanced-config.file/initialize!
+ {:version 1
+ :config {:databases [{:name "Sample Database"
+ :engine "postgres"
+ :details {}
+ :is_sample true}]}})))))
+
(deftest sync-test
(testing "`init-from-config-file!` returns syncs database in a separate thread by default"
;; unset setting to test default behavior
diff --git a/enterprise/backend/test/metabase_enterprise/workspaces/config_test.clj b/enterprise/backend/test/metabase_enterprise/workspaces/config_test.clj
index f160b07c65c..a676133c245 100644
--- a/enterprise/backend/test/metabase_enterprise/workspaces/config_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/workspaces/config_test.clj
@@ -31,7 +31,7 @@
(is (= 1 (:version cfg)))
(is (= #{:databases :workspace} (set (keys (:config cfg))))))
(testing "databases entry"
- (let [own-dbs (remove :is_stub (-> cfg :config :databases))
+ (let [own-dbs (remove (some-fn :is_stub :is_sample) (-> cfg :config :databases))
db (first own-dbs)]
(is (= 1 (count own-dbs)))
(is (= "Analytics Data Warehouse" (:name db)))
@@ -142,8 +142,8 @@
(let [cfg (config/build-workspace-config ws-id)]
(is (= 1 (:version cfg)))
(is (= "Empty" (-> cfg :config :workspace :name)))
- (is (empty? (remove :is_stub (-> cfg :config :databases)))
- "no non-stub databases since the workspace has none of its own")
+ (is (empty? (remove (some-fn :is_stub :is_sample) (-> cfg :config :databases)))
+ "no non-stub, non-sample databases since the workspace has none of its own")
(is (= {} (-> cfg :config :workspace :databases)))))))
(deftest build-workspace-config-injects-stubs-for-non-workspace-dbs-test
@@ -190,3 +190,27 @@
(testing "A missing workspace returns nil"
(mt/with-model-cleanup [:model/Workspace]
(is (nil? (config/build-workspace-config Integer/MAX_VALUE))))))
+
+(deftest build-workspace-config-emits-sample-database-test
+ (testing "When a Sample Database exists in the instance, /config emits an entry with
+ standardized name/engine, empty :details, and :is_sample true. The entry is
+ distinct from stub entries and does not depend on the sample DB's actual
+ stored name/engine."
+ (mt/with-temp [:model/Database _sample {:name "Some Renamed Sample"
+ :engine :h2
+ :details {:db "real-sample-details"}
+ :is_sample true}
+ :model/Workspace {ws-id :id} {:name "sample-emit-ws"
+ :creator_id (mt/user->id :crowberto)}]
+ (let [cfg-dbs (-> (config/build-workspace-config ws-id) :config :databases)
+ samples (filter :is_sample cfg-dbs)]
+ (testing "exactly one sample entry is emitted"
+ (is (= 1 (count samples))))
+ (testing "sample entry uses standardized name/engine with empty :details"
+ (is (= {:name "Sample Database"
+ :engine "h2"
+ :details {}
+ :is_sample true}
+ (first samples))))
+ (testing "sample entry is NOT also marked as a stub"
+ (is (not (:is_stub (first samples)))))))))
diff --git a/mage/src/mage/modules.clj b/mage/src/mage/modules.clj
index bed99f1bfb8..4eb0033c361 100644
--- a/mage/src/mage/modules.clj
+++ b/mage/src/mage/modules.clj
@@ -132,6 +132,7 @@
pulse
remote-sync
request
+ sample-data
search
secrets
server
diff --git a/src/metabase/sample_data/core.clj b/src/metabase/sample_data/core.clj
index f98aeb1b0ad..aeab6970ce9 100644
--- a/src/metabase/sample_data/core.clj
+++ b/src/metabase/sample_data/core.clj
@@ -8,4 +8,5 @@
(p/import-vars
[metabase.sample-data.impl
extract-and-sync-sample-database!
+ sample-database-name
update-sample-database-if-needed!])
diff --git a/src/metabase/sample_data/impl.clj b/src/metabase/sample_data/impl.clj
index 587117bb1b9..779d5451937 100644
--- a/src/metabase/sample_data/impl.clj
+++ b/src/metabase/sample_data/impl.clj
@@ -15,7 +15,11 @@
(set! *warn-on-reflection* true)
-(def ^:private ^String sample-database-name "Sample Database")
+(def ^String sample-database-name
+ "Canonical name of the bundled Sample Database. Shared with consumers that need to
+ identify or validate the sample DB (e.g. workspace-manager config import)."
+ "Sample Database")
+
(def ^:private ^String sample-database-filename "sample-database.db.mv.db")
(defn- sample-db-dir-from-env