Skip to content

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

Add version field support to data_app.yaml (#82557)

Timofey Kachaloveb845c2ea695
diff --git a/e2e/embedding-sdk-host-apps/vite-6-data-app-host-app/data_app.yaml b/e2e/embedding-sdk-host-apps/vite-6-data-app-host-app/data_app.yaml
index eba5e5b3e2a..112f1b2c983 100644
--- a/e2e/embedding-sdk-host-apps/vite-6-data-app-host-app/data_app.yaml
+++ b/e2e/embedding-sdk-host-apps/vite-6-data-app-host-app/data_app.yaml
@@ -1,4 +1,5 @@
name: Vite 6 Data App
+version: 1
path: ./dist/index.js
allowed_hosts:
- https://allowed.data-app.test
diff --git a/e2e/support/assets/data-apps/custom-error-component/data_app.yaml b/e2e/support/assets/data-apps/custom-error-component/data_app.yaml
index 040a3afbd80..1a604fccf95 100644
--- a/e2e/support/assets/data-apps/custom-error-component/data_app.yaml
+++ b/e2e/support/assets/data-apps/custom-error-component/data_app.yaml
@@ -1,2 +1,3 @@
name: Custom Error Component
+version: 1
path: ./dist/index.js
diff --git a/e2e/support/assets/data-apps/isolation/data_app.yaml b/e2e/support/assets/data-apps/isolation/data_app.yaml
index ae8da92b536..96961791805 100644
--- a/e2e/support/assets/data-apps/isolation/data_app.yaml
+++ b/e2e/support/assets/data-apps/isolation/data_app.yaml
@@ -1,2 +1,3 @@
name: Isolation
+version: 1
path: ./dist/index.js
diff --git a/e2e/support/assets/data-apps/kitchen-sink/data_app.yaml b/e2e/support/assets/data-apps/kitchen-sink/data_app.yaml
index 64aebc33050..13a6b1d1769 100644
--- a/e2e/support/assets/data-apps/kitchen-sink/data_app.yaml
+++ b/e2e/support/assets/data-apps/kitchen-sink/data_app.yaml
@@ -1,2 +1,3 @@
name: Kitchen Sink
+version: 1
path: ./dist/index.js
diff --git a/e2e/support/assets/data-apps/synced-actions-app/data_app.yaml b/e2e/support/assets/data-apps/synced-actions-app/data_app.yaml
index 86b0733c401..c0811b7f749 100644
--- a/e2e/support/assets/data-apps/synced-actions-app/data_app.yaml
+++ b/e2e/support/assets/data-apps/synced-actions-app/data_app.yaml
@@ -1,2 +1,3 @@
name: Synced Actions App
+version: 1
path: ./dist/index.js
diff --git a/e2e/support/assets/data-apps/synced-app/data_app.yaml b/e2e/support/assets/data-apps/synced-app/data_app.yaml
index 2d367561d2d..3ff729ed314 100644
--- a/e2e/support/assets/data-apps/synced-app/data_app.yaml
+++ b/e2e/support/assets/data-apps/synced-app/data_app.yaml
@@ -1,2 +1,3 @@
name: Synced App
+version: 1
path: ./dist/index.js
diff --git a/e2e/support/assets/example_synced_data_apps/data_apps/broken-bundle/data_app.yaml b/e2e/support/assets/example_synced_data_apps/data_apps/broken-bundle/data_app.yaml
index 400b85650c3..d95ac47d8d7 100644
--- a/e2e/support/assets/example_synced_data_apps/data_apps/broken-bundle/data_app.yaml
+++ b/e2e/support/assets/example_synced_data_apps/data_apps/broken-bundle/data_app.yaml
@@ -1,3 +1,4 @@
name: Broken Bundle
+version: 1
# Points at a file that isn't in the repo — a valid config, an un-loadable app.
path: ./missing.js
diff --git a/e2e/support/assets/example_synced_data_apps/data_apps/good/data_app.yaml b/e2e/support/assets/example_synced_data_apps/data_apps/good/data_app.yaml
index 820f73d5fb5..8d241b3ad25 100644
--- a/e2e/support/assets/example_synced_data_apps/data_apps/good/data_app.yaml
+++ b/e2e/support/assets/example_synced_data_apps/data_apps/good/data_app.yaml
@@ -1,3 +1,4 @@
name: Good App
description: A well-formed app that syncs cleanly
+version: 1
path: ./index.js
diff --git a/e2e/support/helpers/e2e-data-app-helpers.ts b/e2e/support/helpers/e2e-data-app-helpers.ts
index a4df9666b46..1be88140d29 100644
--- a/e2e/support/helpers/e2e-data-app-helpers.ts
+++ b/e2e/support/helpers/e2e-data-app-helpers.ts
@@ -24,10 +24,13 @@ export const fakeDataApp = (overrides: Partial<DataApp> = {}): DataApp => ({
name: DATA_APP_NAME,
display_name: DATA_APP_DISPLAY_NAME,
description: null,
+ version: 1,
+ outdated: false,
bundle_path: `data_apps/${DATA_APP_NAME}/dist/index.js`,
enabled: true,
resource_collection_id: null,
permission_group_id: null,
+ table_ids: [],
allowed_hosts: [],
bundle_hash: "e2e-bundle-hash",
last_synced_sha: "e2e0000",
diff --git a/e2e/test/scenarios/data-apps/admin.cy.spec.ts b/e2e/test/scenarios/data-apps/admin.cy.spec.ts
index 625f35c5447..8bf5f99c8c4 100644
--- a/e2e/test/scenarios/data-apps/admin.cy.spec.ts
+++ b/e2e/test/scenarios/data-apps/admin.cy.spec.ts
@@ -2,6 +2,7 @@ import {
DATA_APP_DISPLAY_NAME as APP_DISPLAY_NAME,
DATA_APP_NAME as APP_NAME,
} from "e2e/support/helpers";
+import type { DataApp } from "metabase-types/api";
import { DATA_APP_TEST_ENV as TEST_ENV } from "./helpers";
@@ -96,6 +97,69 @@ describe("scenarios > data apps > admin management", () => {
.findByText(/AI-generated React apps/)
.should("not.exist");
});
+
+ describe("outdated apps", () => {
+ // Only a bump of the supported version makes a real app outdated, so the flag
+ // the API computes is patched onto a real app's responses instead.
+ const OUTDATED_APP = "orders-app";
+
+ function markAppOutdated() {
+ cy.request<DataApp>("POST", `/api/apps/${OUTDATED_APP}/draft`)
+ .its("body.display_name")
+ .as("outdatedAppName");
+
+ cy.intercept("GET", "/api/apps", (req) => {
+ req.continue((res) => {
+ res.body = res.body.map((app: DataApp) =>
+ app.name === OUTDATED_APP
+ ? { ...app, version: 1, outdated: true }
+ : app,
+ );
+ });
+ });
+ cy.intercept(
+ { method: "GET", pathname: `/api/apps/${OUTDATED_APP}` },
+ (req) => {
+ req.continue((res) => {
+ res.body = { ...res.body, version: 1, outdated: true };
+ });
+ },
+ );
+ }
+
+ it("badges an outdated app, refuses to open it, and still lets an admin manage its users", () => {
+ markAppOutdated();
+
+ cy.visit("/admin/settings/apps");
+
+ cy.get<string>("@outdatedAppName").then((displayName) => {
+ cy.findByTestId(`data-app-list-item-${OUTDATED_APP}`)
+ .scrollIntoView()
+ .within(() => {
+ cy.findByText("Outdated").should("be.visible");
+ cy.findByText(displayName).should("be.visible");
+ cy.findByRole("link", { name: displayName }).should("not.exist");
+ cy.findByRole("button", {
+ name: `Actions for ${displayName}`,
+ }).click();
+ });
+ });
+
+ H.popover().findByText("Manage user access").click();
+
+ cy.location("pathname").should(
+ "eq",
+ `/admin/settings/apps/${OUTDATED_APP}/users`,
+ );
+ H.main()
+ .findByRole("heading", { name: "Manage access to this app" })
+ .should("be.visible");
+
+ H.openDataApp(OUTDATED_APP);
+ H.main().findByText("This data app is outdated").should("be.visible");
+ cy.get("iframe").should("not.exist");
+ });
+ });
});
// TODO(v65): data apps launch in v65 — replace the "no token" suite below with
diff --git a/e2e/test/scenarios/data-apps/viewing.cy.spec.ts b/e2e/test/scenarios/data-apps/viewing.cy.spec.ts
index 236ea1dd4d1..84a9a6589c0 100644
--- a/e2e/test/scenarios/data-apps/viewing.cy.spec.ts
+++ b/e2e/test/scenarios/data-apps/viewing.cy.spec.ts
@@ -192,6 +192,36 @@ describe("scenarios > data apps > viewing & routing", () => {
});
});
+ describe("outdated apps", () => {
+ it("tells a non-admin why an outdated app won't open", () => {
+ H.mockDataApp(APP_NAME, { displayName: APP_DISPLAY_NAME });
+
+ // The metadata endpoint refuses an outdated app to non-admins with this
+ // exact shape (see `check-not-outdated` in data_apps/api.clj).
+ cy.intercept(
+ { method: "GET", pathname: `/api/apps/${APP_NAME}` },
+ {
+ statusCode: 409,
+ body: {
+ "error-code": "data-app-outdated",
+ message: "This app was built for version 1 of data apps.",
+ },
+ },
+ );
+
+ cy.signInAsNormalUser();
+ H.openDataApp(APP_NAME);
+
+ H.main().within(() => {
+ cy.findByText("This data app is outdated").should("be.visible");
+ cy.findByText("This app was built for version 1 of data apps.").should(
+ "be.visible",
+ );
+ });
+ cy.get("iframe").should("not.exist");
+ });
+ });
+
describe("host error / not-ready screens", () => {
it("shows a themed host error screen when the bundle throws while rendering", () => {
H.mockDataApp(APP_NAME, {
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/README.md b/enterprise/backend/src/metabase_enterprise/data_apps/README.md
index 85f7afa99e9..00a8f97f5bd 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/README.md
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/README.md
@@ -22,8 +22,11 @@ data_apps/
```
`data_app.yaml` declares the display name and the bundle path relative to the app's own directory,
-plus two optional fields: a one-line `description` shown beside the name in the admin UI, and the
-origins the sandboxed bundle may `fetch`/XHR. See `config.clj` for the format and its validation.
+plus three optional fields: a one-line `description` shown beside the name in the admin UI, the
+`version` of the data app contract the app was built for (1 when absent; an app below the version
+this Metabase serves is outdated — badged for admins, hidden from everyone else, and a 409 to open),
+and the origins the sandboxed bundle may `fetch`/XHR. See `config.clj` for the format and its
+validation.
**The directory name is the slug.** Nothing in the config declares it. This is what makes slug
collisions structurally impossible — a repo can't hold two `data_apps/sales` directories, and
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/api.clj b/enterprise/backend/src/metabase_enterprise/data_apps/api.clj
index d4afbb31541..dcf79e47ac2 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/api.clj
@@ -88,6 +88,8 @@
[:name ms/NonBlankString]
[:display_name ms/NonBlankString]
[:description [:maybe :string]]
+ [:version ms/PositiveInt]
+ [:outdated :boolean]
[:bundle_path ms/NonBlankString]
[:enabled :boolean]
[:allowed_hosts [:sequential :string]]
@@ -208,10 +210,11 @@
;;; ------------------------------------------------ Apps ------------------------------------------------
(defn- data-app-response
- "Return full data-app metadata to superusers and only navigational fields to other users."
+ "Return full data-app metadata, with whether the app is outdated, to superusers and only
+ navigational fields to other users."
[app]
(if api/*is-superuser?*
- app
+ (assoc app :outdated (data-app.config/outdated? app))
(select-keys app [:name :display_name])))
(defn- data-app-list-response
@@ -235,12 +238,28 @@
{:status-code 409})))
app)
+(defn- check-not-outdated
+ "Refuse an app built for an older contract than this Metabase serves with a 409 carrying
+ `:error-code \"data-app-outdated\"`, so the client can show what to do. Applied where the
+ contract is served: the bundle for everyone, and the metadata for non-superusers, who have no
+ other use for it. Superusers still read it, to badge the app and manage its users."
+ [app]
+ (when (data-app.config/outdated? app)
+ (throw (ex-info (tru (str "This app was built for version {0} of data apps. Migrate it to the current "
+ "version, then rebuild and sync it again.")
+ (:version app))
+ {:status-code 409, :error-code "data-app-outdated"})))
+ app)
+
(api.macros/defendpoint :get "/" :- [:sequential [:or DataAppResponse PublicDataAppResponse]]
"List the data apps provided by the connected repository. Pass `available=true`
- to return only enabled apps without sync errors."
+ to return only enabled apps without sync errors. An outdated app is never
+ available, and otherwise listed only to superusers, who see it badged."
[_route-params
{:keys [available]} :- [:map {:closed true} [:available {:optional true} [:maybe :boolean]]]]
(let [apps (->> (data-apps.db/non-blob-data-apps available)
+ (remove #(and (or available (not api/*is-superuser?*))
+ (data-app.config/outdated? %)))
(mapv api/read-check))
warning-group-ids (when api/*is-superuser?*
(data-app.user-access/groups-with-permission-warnings apps))]
@@ -257,7 +276,7 @@
(api/check-superuser)
(let [app (api/check-404 (data-apps.db/non-blob-data-app-by-slug slug))]
(data-apps.db/update-data-app! (:id app) {:enabled enabled})
- (data-apps.db/non-blob-data-app (:id app))))
+ (data-app-response (data-apps.db/non-blob-data-app (:id app)))))
(api.macros/defendpoint :delete ["/:slug" :slug slug-regex] :- :nil
"Remove a single data app (its row and cached bundle). Intended for clearing out
@@ -284,7 +303,7 @@
(data-apps.db/existing-table-ids table-ids))
(tru "One or more tables do not exist."))
(data-apps.db/update-data-app! (:id app) {:table_ids table-ids})
- (data-apps.db/non-blob-data-app (:id app))))
+ (data-app-response (data-apps.db/non-blob-data-app (:id app)))))
(api.macros/defendpoint :post ["/:slug/user-permission-warnings" :slug slug-regex]
:- [:sequential PermissionWarning]
@@ -383,12 +402,13 @@
(api/check-400 (data-app.config/valid-slug? slug)
"Data app draft slugs must use lowercase letters, numbers, and dashes.")
(data-app.sync/ensure-draft! slug)
- (data-apps.db/non-blob-data-app-by-slug slug))
+ (data-app-response (data-apps.db/non-blob-data-app-by-slug slug)))
(api.macros/defendpoint :get ["/:slug" :slug slug-regex] :- [:or DataAppResponse PublicDataAppResponse]
"Fetch metadata for a single enabled data app by its slug."
[{:keys [slug]} :- [:map {:closed true} [:slug ms/NonBlankString]]]
- (data-app-response (read-check-data-app (data-apps.db/enabled-non-blob-data-app-by-slug slug))))
+ (let [app (read-check-data-app (data-apps.db/enabled-non-blob-data-app-by-slug slug))]
+ (data-app-response (cond-> app (not api/*is-superuser?*) check-not-outdated))))
(api.macros/defendpoint :get ["/:slug/bundle" :slug slug-regex] :- :any
"Serve the cached JS bundle for a single enabled data app by slug. Honors
@@ -400,7 +420,7 @@
respond
raise]
(try
- (let [row (read-check-data-app (data-apps.db/enabled-non-blob-data-app-by-slug slug))
+ (let [row (check-not-outdated (read-check-data-app (data-apps.db/enabled-non-blob-data-app-by-slug slug)))
hash (:bundle_hash row)
etag (some->> hash (format "\"%s\""))]
(cond
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/config.clj b/enterprise/backend/src/metabase_enterprise/data_apps/config.clj
index 73962b03351..b549647f49b 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/config.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/config.clj
@@ -4,6 +4,7 @@
name: Sales dashboard # display name
description: Pipeline … # optional — one line on what the app does
+ version: 1 # optional — data app contract version, 1 when absent
path: dist/index.js # bundle path, relative to this app's directory
allowed_hosts: # optional — origins the sandboxed bundle may fetch/XHR
- https://api.example.com
@@ -27,6 +28,38 @@
"Directory at the repo root that holds one subdirectory per data app."
"data_apps")
+(def supported-app-version
+ "The data app contract version this Metabase serves. Bumped only on a breaking
+ change to the contract, so an app declaring a lower `version` is outdated: it is
+ listed only to admins, badged, and never opened."
+ 1)
+
+(def ^:private initial-app-version
+ "The `version` of an app whose manifest declares none: every such app predates the
+ field, so this stays 1 while [[supported-app-version]] moves on."
+ 1)
+
+(defn outdated?
+ "Whether `app` was built for a contract version older than [[supported-app-version]]."
+ [{:keys [version]}]
+ (< version supported-app-version))
+
+(defn- parse-version
+ "Validate the optional `version`: a positive whole number, [[initial-app-version]]
+ when absent. Throws a 400 for anything else rather than coercing it, since a
+ string or a decimal here is a typo, not a version."
+ [raw ^String dir]
+ (cond
+ (nil? raw)
+ initial-app-version
+
+ (and (integer? raw) (pos? raw))
+ (long raw)
+
+ :else
+ (throw (ex-info (tru "{0}/{1}: \"version\" must be a positive whole number, such as 1." dir config-file-name)
+ {:status-code 400}))))
+
(def ^:private slug-pattern
"Lowercase letters/numbers separated by single dashes. An app *directory* must
match this: the name is used verbatim as the slug, never normalized. Folding
@@ -141,10 +174,12 @@
(defn parse-app-config
"Parse the bytes of one `data_app.yaml` from the app directory `dir` (e.g.
`data_apps/sales`) into `{:slug ..., :display_name ..., :description ...,
- :path ..., :allowed_hosts [...]}`. The slug is the directory's name; `path` is
- relative to the directory; `:description` is an optional one-liner (nil when
- absent or blank, capped at [[max-description-chars]]); `:allowed_hosts` is a
- (possibly empty) vector of origins the sandboxed bundle may reach. Throws an
+ :version ..., :path ..., :allowed_hosts [...]}`. The slug is the directory's
+ name; `path` is relative to the directory; `:description` is an optional
+ one-liner (nil when absent or blank, capped at [[max-description-chars]]);
+ `:version` is the contract version the app was built for (1 when absent);
+ `:allowed_hosts` is a (possibly empty) vector of origins the sandboxed bundle
+ may reach. Throws an
`ex-info` with `:status-code` 400 on malformed or incomplete content — including
a directory whose name isn't a usable slug, since that app has no URL to be served at."
[^bytes bytes ^String dir]
@@ -152,6 +187,7 @@
slug (dir-slug dir)
name (some-> (:name parsed) str str/trim not-empty)
description (parse-description (:description parsed) dir)
+ version (parse-version (:version parsed) dir)
path (some-> (:path parsed) normalize-path not-empty)
allowed-hosts (parse-allowed-hosts parsed dir)]
(when-not (re-matches slug-pattern slug)
@@ -169,4 +205,9 @@
(when (path-traversal? path)
(throw (ex-info (tru "{0}/{1}: \"path\" must not contain \"..\"." dir config-file-name)
{:status-code 400})))
- {:slug slug, :display_name name, :description description, :path path, :allowed_hosts allowed-hosts}))
+ {:slug slug
+ :display_name name
+ :description description
+ :version version
+ :path path
+ :allowed_hosts allowed-hosts}))
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/db.clj b/enterprise/backend/src/metabase_enterprise/data_apps/db.clj
index 522c39d8e9c..21dfb1feaf3 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/db.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/db.clj
@@ -11,7 +11,7 @@
(def ^:private non-blob-columns
"Columns to select for normal data-app metadata reads, excluding the raw bundle blob."
- [:model/DataApp :id :name :display_name :description :bundle_path :enabled :allowed_hosts
+ [:model/DataApp :id :name :display_name :description :version :bundle_path :enabled :allowed_hosts
:resource_collection_id :permission_group_id :table_ids :draft
:bundle_hash :last_synced_sha :last_synced_at :sync_error
:created_at :updated_at])
@@ -48,7 +48,8 @@
(mu/defn data-apps-sync-info
"The sync-relevant columns of every DataApp."
[]
- (t2/select [:model/DataApp :name :display_name :description :allowed_hosts :bundle_path :bundle_hash :sync_error]))
+ (t2/select [:model/DataApp :name :display_name :description :version :allowed_hosts :bundle_path
+ :bundle_hash :sync_error]))
(defn table-database-id
"The database ID for the Table with `table-id`, or nil."
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/schema.clj b/enterprise/backend/src/metabase_enterprise/data_apps/schema.clj
index eb3f107f2b6..bd27ba3c16a 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/schema.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/schema.clj
@@ -27,6 +27,7 @@
[:created_at {:optional true} [:maybe ms/TemporalInstant]]
[:updated_at {:optional true} [:maybe ms/TemporalInstant]]
[:description {:optional true} [:maybe :string]]
+ [:version {:optional true} ms/PositiveInt]
[:resource_collection_id {:optional true} [:maybe ms/PositiveInt]]
[:permission_group_id {:optional true} [:maybe ms/PositiveInt]]
[:table_ids {:optional true} [:maybe [:sequential ms/PositiveInt]]]
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/sync.clj b/enterprise/backend/src/metabase_enterprise/data_apps/sync.clj
index 3cb027029d1..f984fcf01d1 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/sync.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/sync.clj
@@ -82,7 +82,7 @@
returns file text or nil), iterate the folders under `data_apps/` and return one
entry per folder that is an app — it holds a `data_app.yaml`; a folder without
one is skipped. Each entry is a parsed app `{:slug :display_name :description
- :bundle :allowed_hosts}` (with `:bundle` the repo-root relative bundle path) or
+ :version :bundle :allowed_hosts}` (with `:bundle` the repo-root relative bundle path) or
`{:config-error <message>}`. Parse/read failures are isolated per app so one bad
config can't abort the sync.
@@ -99,11 +99,12 @@
:when (some #{config-path} (list-dir dir))]
(try
(if-let [content (read-file config-path)]
- (let [{:keys [slug display_name description path allowed_hosts]}
+ (let [{:keys [slug display_name description version path allowed_hosts]}
(data-app.config/parse-app-config (->bytes content) dir)]
{:slug slug
:display_name display_name
:description description
+ :version version
:bundle (str dir "/" path)
:allowed_hosts allowed_hosts})
{:slug (data-app.config/dir-slug dir), :config-error (tru "Could not read {0}." config-path)})
@@ -120,16 +121,19 @@
(data-apps.db/update-data-app-by-slug! slug row)
(data-apps.db/insert-data-app! (assoc row :name slug))))
+(def ^:private synced-metadata-keys
+ "The manifest-derived columns a sync stores whether or not the bundle loaded."
+ [:display_name :description :version :allowed_hosts :bundle_path])
+
(defn- app-metadata-changed?
"Whether the metadata a sync stores whether or not the bundle loaded differs from
the `existing` row. The failure path stores exactly these, so it asks this
directly; the success path adds the bundle to the question."
- [existing {:keys [display_name description bundle_path allowed_hosts]}]
- (or (not= (:display_name existing) display_name)
- (not= (:description existing) description)
- (not= (:bundle_path existing) bundle_path)
- (not= (vec (or (:allowed_hosts existing) []))
- (vec (or allowed_hosts [])))))
+ [existing fields]
+ (let [normalize (fn [row]
+ (-> (select-keys row synced-metadata-keys)
+ (update :allowed_hosts #(vec (or % [])))))]
+ (not= (normalize existing) (normalize fields))))
(defn- app-content-changed?
"Whether the just-synced content differs from the `existing` row (nil = a new
@@ -156,9 +160,10 @@
(defn- prepare-app
"Read one app's bundle before taking the permissions lock.
A bundle failure preserves the cached bundle and prepares metadata with `sync_error` instead."
- [existing {:keys [slug display_name description bundle sha read-file allowed_hosts]}]
+ [existing {:keys [slug display_name description version bundle sha read-file allowed_hosts]}]
(let [metadata {:display_name display_name
:description description
+ :version version
:allowed_hosts allowed_hosts
:bundle_path bundle}]
(try
@@ -190,7 +195,7 @@
(if existing
(mark-config-error! existing slug message)
(when fields
- (upsert-by-name! slug (assoc (select-keys fields [:display_name :description :allowed_hosts :bundle_path])
+ (upsert-by-name! slug (assoc (select-keys fields synced-metadata-keys)
:sync_error message))
true)))
(catch Throwable e
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/api_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/api_test.clj
index d58b2c0bdd3..6f8761b2a83 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/api_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/api_test.clj
@@ -2,6 +2,7 @@
(:require
[clojure.string :as str]
[clojure.test :refer :all]
+ [metabase-enterprise.data-apps.config :as data-app.config]
[metabase-enterprise.data-apps.query-definition :as query-definition]
[metabase-enterprise.data-apps.resources :as data-app.resources]
[metabase-enterprise.data-apps.sync :as data-app.sync]
@@ -726,6 +727,50 @@
(is (=? [{:name "ready" :display_name "Ready"}]
(mt/user-http-request :rasta :get 200 "apps?available=true"))))))
+(deftest outdated-apps-are-hidden-from-users-and-badged-for-admins-test
+ (mt/test-helpers-set-global-values!
+ (mt/with-premium-features #{:data-apps-preview}
+ (mt/with-model-cleanup [:model/DataApp :model/Collection :model/PermissionsGroup]
+ (t2/insert! :model/DataApp :name "old" :display_name "Old" :bundle_path "data_apps/old/index.js"
+ :bundle (.getBytes "BUNDLE" "UTF-8") :bundle_hash "abc123" :version 1)
+ (t2/insert! :model/DataApp :name "current" :display_name "Current" :bundle_path "data_apps/current/index.js"
+ :bundle (.getBytes "BUNDLE" "UTF-8") :bundle_hash "def456" :version 2)
+ (doseq [slug ["old" "current"]
+ :let [{:keys [permission_group_id]}
+ (data-app.resources/ensure-resources! (t2/select-one :model/DataApp :name slug))]]
+ (perms/add-user-to-group! (mt/user->id :rasta) permission_group_id))
+ (with-redefs [data-app.config/supported-app-version 2]
+ (testing "a regular user is never told about the outdated app in a list"
+ (doseq [url ["apps" "apps?available=true"]]
+ (is (= [{:name "current" :display_name "Current"}]
+ (mt/user-http-request :rasta :get 200 url)))))
+ (testing "for a regular user, opening an outdated app is a 409 that says what to do"
+ (doseq [url ["apps/old" "apps/old/bundle"]]
+ (is (=? {:error-code "data-app-outdated"
+ :message #"This app was built for version 1 of data apps.*"}
+ (mt/user-http-request :rasta :get 409 url)))))
+ (testing "the current app still opens"
+ (is (= {:name "current" :display_name "Current"}
+ (mt/user-http-request :rasta :get 200 "apps/current")))
+ (is (str/includes?
+ (str (mt/user-real-request :crowberto :get 200 "apps/current/bundle"))
+ "BUNDLE")))
+ (testing "an admin sees the outdated app flagged, and can still read it to manage its users"
+ (is (=? [{:name "current" :version 2 :outdated false}
+ {:name "old" :version 1 :outdated true}]
+ (mt/user-http-request :crowberto :get 200 "apps")))
+ (is (=? [{:name "current"}]
+ (mt/user-http-request :crowberto :get 200 "apps?available=true"))
+ "but the navbar's available list leaves it out for admins too")
+ (is (=? {:name "old" :version 1 :outdated true :permission_group_id pos-int?}
+ (mt/user-http-request :crowberto :get 200 "apps/old"))))
+ (testing "nobody gets an outdated bundle"
+ (is (=? {:error-code "data-app-outdated"}
+ (mt/user-http-request :crowberto :get 409 "apps/old/bundle"))))
+ (testing "a management response carries the flag too"
+ (is (=? {:name "old" :outdated true}
+ (mt/user-http-request :crowberto :put 200 "apps/old" {:enabled false})))))))))
+
(deftest bundle-includes-allowed-hosts-header-test
(mt/with-premium-features #{:data-apps-preview}
(mt/with-model-cleanup [:model/DataApp :model/Collection :model/PermissionsGroup]
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
index c71e8aaf21d..b8e0b19b817 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
@@ -15,10 +15,33 @@
([s dir] (data-app.config/parse-app-config (->bytes s) dir)))
(deftest parse-valid-config-test
- (is (= {:slug "sales" :display_name "Sales dashboard" :description nil :path "dist/index.js" :allowed_hosts []}
+ (is (= {:slug "sales" :display_name "Sales dashboard" :description nil :version 1
+ :path "dist/index.js" :allowed_hosts []}
(parse "name: Sales dashboard
path: ./dist/index.js"))))
+(deftest parse-version-test
+ (testing "absent means 1: every app predates the field"
+ (is (= 1 (:version (parse "name: X\npath: dist/index.js")))))
+ (testing "a whole number is carried through"
+ (is (= 3 (:version (parse "name: X\nversion: 3\npath: dist/index.js")))))
+ (testing "anything but a positive whole number is rejected, not coerced or compared as-is"
+ (doseq [bad ["0" "-1" "1.5" "'1'" "one" "[1]" "1.0.0"]]
+ (is (thrown-with-msg? clojure.lang.ExceptionInfo #"version.*positive whole number"
+ (parse (str "name: X\nversion: " bad "\npath: dist/index.js")))
+ (str "should reject: " (pr-str bad))))))
+
+(deftest template-manifest-declares-the-supported-version-test
+ (testing "the scaffolding template stamps the version this Metabase serves, so a new app is never born outdated"
+ (is (= data-app.config/supported-app-version
+ (:version (parse (slurp "skills/metabase-data-app-setup/template/data_app.yaml")))))))
+
+(deftest outdated-test
+ (testing "an app below the supported version is outdated; one at it is not"
+ (with-redefs [data-app.config/supported-app-version 2]
+ (is (data-app.config/outdated? {:version 1}))
+ (is (not (data-app.config/outdated? {:version 2}))))))
+
(deftest parse-description-test
(testing "an optional one-liner is trimmed and carried through"
(is (= "Pipeline health by region"
@@ -82,7 +105,7 @@ path: ./dist/index.js"))))
(deftest unknown-fields-are-ignored-test
(testing "unknown keys don't fail the parse — including a stray `slug`, which the directory name overrides"
- (is (= {:slug "sales" :display_name "X" :description nil :path "dist/index.js" :allowed_hosts []}
+ (is (= {:slug "sales" :display_name "X" :description nil :version 1 :path "dist/index.js" :allowed_hosts []}
(parse "name: X\nslug: elsewhere\nfuture_option: 1\npath: dist/index.js")))))
(deftest parse-errors-test
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/sync_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/sync_test.clj
index ec069f66de4..abc222093f0 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/sync_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/sync_test.clj
@@ -27,10 +27,11 @@
(defn- app-files
"The repo files for one app in `data_apps/<dir>`. `dir` is the app's slug — the
config declares no slug, it is the directory's name."
- [dir {:keys [name path bundle description]}]
+ [dir {:keys [name path bundle description version]}]
{(format "data_apps/%s/data_app.yaml" dir)
(str (format "name: %s\npath: %s\n" name path)
- (when description (format "description: %s\n" description)))
+ (when description (format "description: %s\n" description))
+ (when version (format "version: %s\n" version)))
(format "data_apps/%s/%s" dir path) bundle})
(deftest sync-from-snapshot-is-gated-by-the-data-apps-feature-test
@@ -44,7 +45,7 @@
(is (not (t2/exists? :model/DataApp :name "a"))
"materializes no data app")))
(mt/with-premium-features #{:data-apps-preview}
- (mt/with-model-cleanup [:model/DataApp]
+ (mt/with-model-cleanup [:model/DataApp :model/Collection :model/PermissionsGroup]
(is (=? {:synced 1 :changed 1}
(data-app.sync/sync-from-snapshot! (snapshot files)))
"with the feature it materializes the app as usual")
@@ -153,6 +154,27 @@
(is (=? {:changed 1} (sync-app)))
(is (nil? (t2/select-one-fn :description :model/DataApp :name "a")))))))
+(deftest version-is-optional-and-tracked-like-other-metadata-test
+ (mt/with-model-cleanup [:model/DataApp :model/Collection :model/PermissionsGroup]
+ (let [sync-app (fn [& {:as app}]
+ (data-app.sync/import-from-snapshot!
+ (snapshot (app-files "a" (merge {:name "A" :path "index.js" :bundle "V1"} app)))))]
+ (testing "an app that declares no version syncs as version 1"
+ (sync-app)
+ (is (= 1 (t2/select-one-fn :version :model/DataApp :name "a"))))
+ (testing "declaring one counts as a change and is materialized"
+ (is (=? {:changed 1} (sync-app :version 2)))
+ (is (= 2 (t2/select-one-fn :version :model/DataApp :name "a"))))
+ (testing "re-syncing the same version is not a change"
+ (is (=? {:changed 0} (sync-app :version 2))))
+ (testing "dropping it from the config falls back to version 1"
+ (is (=? {:changed 1} (sync-app)))
+ (is (= 1 (t2/select-one-fn :version :model/DataApp :name "a"))))
+ (testing "an invalid version is a config error that keeps the app's last good state"
+ (is (re-find #"\"version\" must be a positive whole number"
+ (first (:config-errors (sync-app :version "1.0.0")))))
+ (is (= 1 (t2/select-one-fn :version :model/DataApp :name "a")))))))
+
(deftest metadata-edits-count-while-an-app-keeps-failing-test
(testing "an app whose bundle is missing still stores metadata edits, so they count as changes"
(mt/with-model-cleanup [:model/DataApp :model/Collection :model/PermissionsGroup]
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/ManageDataAppsPage.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/ManageDataAppsPage.unit.spec.tsx
index 8498bab5023..1d5b4cf9411 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/ManageDataAppsPage.unit.spec.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/ManageDataAppsPage.unit.spec.tsx
@@ -108,6 +108,21 @@ describe("ManageDataAppsPage", () => {
expect(screen.getByText("Disabled")).toBeInTheDocument();
});
+ it("shows an outdated app as plain text with an Outdated badge", async () => {
+ setup({
+ apps: [
+ createMockDataApp({ name: "sales", version: 1, outdated: true }),
+ ],
+ });
+
+ expect(await screen.findByText("Sales")).toBeInTheDocument();
+ expect(
+ screen.queryByRole("link", { name: "Sales" }),
+ ).not.toBeInTheDocument();
+ expect(screen.getByText("Outdated")).toBeInTheDocument();
+ expect(screen.queryByText("Disabled")).not.toBeInTheDocument();
+ });
+
it("gives every app its own actions menu", async () => {
setup({
apps: [
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppStatusBadge/DataAppStatusBadge.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppStatusBadge/DataAppStatusBadge.tsx
index cc002b6d9a6..fdb89591966 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppStatusBadge/DataAppStatusBadge.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppStatusBadge/DataAppStatusBadge.tsx
@@ -1,26 +1,40 @@
import { t } from "ttag";
-import { Badge } from "metabase/ui";
+import { Badge, Tooltip } from "metabase/ui";
import type { DataApp } from "metabase-types/api";
+import { getOutdatedDataAppMessage } from "../../../constants";
+
type Props = {
app: DataApp;
};
-export const DataAppStatusBadge = ({ app }: Props) => {
- if (app.enabled) {
- return null;
- }
+export const DataAppStatusBadge = ({ app }: Props) => (
+ <>
+ {app.outdated && (
+ <Tooltip label={getOutdatedDataAppMessage(app.version)}>
+ <Badge
+ size="md"
+ c="text-primary"
+ bg="background_surface-warning-strong"
+ bdrs="xs"
+ tt="none"
+ >
+ {t`Outdated`}
+ </Badge>
+ </Tooltip>
+ )}
- return (
- <Badge
- size="md"
- c="text-secondary"
- bg="background-secondary"
- bdrs="xs"
- tt="none"
- >
- {t`Disabled`}
- </Badge>
- );
-};
+ {!app.enabled && (
+ <Badge
+ size="md"
+ c="text-secondary"
+ bg="background-secondary"
+ bdrs="xs"
+ tt="none"
+ >
+ {t`Disabled`}
+ </Badge>
+ )}
+ </>
+);
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.tsx
index 8ce0b60e289..ce5ed024514 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.tsx
@@ -48,7 +48,7 @@ const SyncStatus = ({ app }: Props) => {
};
export const DataAppSummary = ({ app }: Props) => {
- const isOpenable = app.enabled && !app.sync_error;
+ const isOpenable = app.enabled && !app.sync_error && !app.outdated;
return (
<Group align="center" flex="1" wrap="nowrap" miw={0}>
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.unit.spec.tsx
index b353859abcc..3b502fd17da 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.unit.spec.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSummary/DataAppSummary.unit.spec.tsx
@@ -48,6 +48,23 @@ describe("DataAppSummary", () => {
).not.toBeInTheDocument();
});
+ it("renders an outdated app's name as plain text (it refuses to open)", () => {
+ renderWithProviders(
+ <DataAppSummary
+ app={createMockDataApp({
+ display_name: "Sales",
+ enabled: true,
+ outdated: true,
+ })}
+ />,
+ );
+
+ expect(screen.getByText("Sales")).toBeInTheDocument();
+ expect(
+ screen.queryByRole("link", { name: "Sales" }),
+ ).not.toBeInTheDocument();
+ });
+
describe("description", () => {
it("renders the description when the app declares one", () => {
renderWithProviders(
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/components/DataAppView/DataAppView.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/components/DataAppView/DataAppView.tsx
index 9f9d34fc8cf..722fdd6e610 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/components/DataAppView/DataAppView.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/components/DataAppView/DataAppView.tsx
@@ -1,5 +1,14 @@
import cx from "classnames";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+ type ComponentProps,
+ type ReactNode,
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+} from "react";
+import { P, isMatching } from "ts-pattern";
import { t } from "ttag";
import { EmptyState } from "metabase/common/components/EmptyState";
@@ -15,8 +24,10 @@ import { useGetDataAppQuery } from "metabase-enterprise/api";
import {
DATA_APP_ERROR_MESSAGE_TYPE,
DATA_APP_LOAD_TIMEOUT_MS,
+ DATA_APP_OUTDATED_ERROR_CODE,
DATA_APP_READY_MESSAGE_TYPE,
type DataAppBundleErrorMessage,
+ getOutdatedDataAppMessage,
} from "../../constants";
import { attachIframeUrlMirror } from "../../lib/attach-iframe-url-mirror";
import { deriveIframeSrc } from "../../lib/derive-iframe-src";
@@ -25,6 +36,21 @@ import { isDataAppMessage } from "../../lib/is-data-app-message";
import S from "./DataAppView.module.css";
+const OUTDATED_ERROR_PATTERN = {
+ status: 409,
+ data: { "error-code": DATA_APP_OUTDATED_ERROR_CODE, message: P.string },
+};
+
+const CenteredEmptyState = ({
+ children,
+ ...props
+}: ComponentProps<typeof EmptyState> & { children?: ReactNode }) => (
+ <Flex direction="column" w="100%" h="100%" justify="center" align="center">
+ <EmptyState {...props} />
+ {children}
+ </Flex>
+);
+
/**
* /apps/:name(/*) — renders the requested data-app inside an isolated
* iframe, mirroring the iframe's internal route into the parent's URL.
@@ -228,39 +254,33 @@ export function DataAppView() {
);
}
+ if (isMatching(OUTDATED_ERROR_PATTERN, metaError)) {
+ return (
+ <CenteredEmptyState
+ title={t`This data app is outdated`}
+ message={metaError.data.message}
+ illustrationElement={<Icon name="warning" size={64} />}
+ />
+ );
+ }
+
if (status === 409) {
return (
- <Flex
- direction="column"
- w="100%"
- h="100%"
- justify="center"
- align="center"
- >
- <EmptyState
- title={t`This data app isn’t published yet`}
- message={t`An administrator needs to publish this data app before it can be opened.`}
- illustrationElement={<Icon name="hourglass" size={64} />}
- />
- </Flex>
+ <CenteredEmptyState
+ title={t`This data app isn’t published yet`}
+ message={t`An administrator needs to publish this data app before it can be opened.`}
+ illustrationElement={<Icon name="hourglass" size={64} />}
+ />
);
}
if (status === 403) {
return (
- <Flex
- direction="column"
- w="100%"
- h="100%"
- justify="center"
- align="center"
- >
- <EmptyState
- title={t`You don’t have access to this data app`}
- message={t`Ask an administrator for access to this data app.`}
- illustrationElement={<Icon name="key" size={64} />}
- />
- </Flex>
+ <CenteredEmptyState
+ title={t`You don’t have access to this data app`}
+ message={t`Ask an administrator for access to this data app.`}
+ illustrationElement={<Icon name="key" size={64} />}
+ />
);
}
@@ -273,6 +293,17 @@ export function DataAppView() {
);
}
+ // An admin still gets the metadata, to manage the app; nobody gets its bundle.
+ if (meta.outdated) {
+ return (
+ <CenteredEmptyState
+ title={t`This data app is outdated`}
+ message={getOutdatedDataAppMessage(meta.version)}
+ illustrationElement={<Icon name="warning" size={64} />}
+ />
+ );
+ }
+
if (bundleError) {
if (bundleError.notReady) {
return (
@@ -284,35 +315,27 @@ export function DataAppView() {
}
return (
- <Flex
- direction="column"
- w="100%"
- h="100%"
- justify="center"
- align="center"
+ <CenteredEmptyState
+ title={t`This data app couldn’t be loaded`}
+ message={
+ bundleError.message ||
+ t`Something went wrong while loading this app. Try refreshing the page.`
+ }
+ illustrationElement={
+ <div
+ className={cx(
+ QueryBuilderS.QueryErrorImage,
+ QueryBuilderS.QueryErrorImageServerError,
+ )}
+ />
+ }
>
- <EmptyState
- title={t`This data app couldn’t be loaded`}
- message={
- bundleError.message ||
- t`Something went wrong while loading this app. Try refreshing the page.`
- }
- illustrationElement={
- <div
- className={cx(
- QueryBuilderS.QueryErrorImage,
- QueryBuilderS.QueryErrorImageServerError,
- )}
- />
- }
- />
-
<ErrorDetails
className={CS.pt2}
errorBoxClassName={S.stackTrace}
details={bundleError.stack}
/>
- </Flex>
+ </CenteredEmptyState>
);
}
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/components/DataAppView/DataAppView.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/components/DataAppView/DataAppView.unit.spec.tsx
index c5a01f0bf43..9c76d481953 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/components/DataAppView/DataAppView.unit.spec.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/components/DataAppView/DataAppView.unit.spec.tsx
@@ -104,6 +104,35 @@ describe("DataAppView", () => {
).toBeInTheDocument();
});
+ it("shows the API's outdated message when the app 409s with the outdated error code", () => {
+ setup({
+ error: {
+ status: 409,
+ data: {
+ "error-code": "data-app-outdated",
+ message: "This app was built for version 1 of data apps.",
+ },
+ },
+ });
+
+ expect(screen.getByText("This data app is outdated")).toBeInTheDocument();
+ expect(
+ screen.getByText("This app was built for version 1 of data apps."),
+ ).toBeInTheDocument();
+ });
+
+ it("shows the outdated screen to an admin, who still receives the app's metadata", () => {
+ setup({ data: createMockDataApp({ version: 1, outdated: true }) });
+
+ expect(screen.getByText("This data app is outdated")).toBeInTheDocument();
+ expect(
+ screen.getByText(
+ "This app was built for version 1 of data apps. Migrate it to the current version, then rebuild and sync it again.",
+ ),
+ ).toBeInTheDocument();
+ expect(screen.queryByTitle("Sales")).not.toBeInTheDocument();
+ });
+
it("renders the app inside an iframe once metadata resolves", () => {
setup({ data: createMockDataApp({ display_name: "Sales" }) });
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/constants.ts b/enterprise/frontend/src/metabase-enterprise/data_apps/constants.ts
index c9cd7f495b4..dcdfee671f2 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/constants.ts
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/constants.ts
@@ -1,3 +1,5 @@
+import { t } from "ttag";
+
export const DATA_APP_ERROR_MESSAGE_TYPE = "metabase.data-app.error" as const;
export type DataAppBundleErrorMessage = {
@@ -18,3 +20,9 @@ export const DATA_APP_READY_MESSAGE_TYPE = "metabase.data-app.ready" as const;
* spinner that would otherwise never resolve.
*/
export const DATA_APP_LOAD_TIMEOUT_MS = 20_000;
+
+/** `error-code` of the 409 the API returns for an app built for an older data app version. */
+export const DATA_APP_OUTDATED_ERROR_CODE = "data-app-outdated";
+
+export const getOutdatedDataAppMessage = (version: number) =>
+ t`This app was built for version ${version} of data apps. Migrate it to the current version, then rebuild and sync it again.`;
diff --git a/frontend/src/metabase-types/api/data-app.ts b/frontend/src/metabase-types/api/data-app.ts
index 1d146d23d28..899524da0ef 100644
--- a/frontend/src/metabase-types/api/data-app.ts
+++ b/frontend/src/metabase-types/api/data-app.ts
@@ -13,6 +13,13 @@ export interface DataApp {
display_name: string;
/** Optional one-line summary of what the app does. */
description: string | null;
+ /** Data app contract version the app was built for; 1 when the manifest declares none. */
+ version: number;
+ /**
+ * Whether `version` is older than the one this Metabase serves. Admin-only:
+ * regular users never receive an outdated app.
+ */
+ outdated: boolean;
/** Path within the repo to the built bundle. */
bundle_path: string;
/** Admin toggle. When false the app is not served. */
diff --git a/frontend/src/metabase-types/api/mocks/data-app.ts b/frontend/src/metabase-types/api/mocks/data-app.ts
index 8df4cbb0858..e19d7a03e20 100644
--- a/frontend/src/metabase-types/api/mocks/data-app.ts
+++ b/frontend/src/metabase-types/api/mocks/data-app.ts
@@ -5,6 +5,8 @@ export const createMockDataApp = (opts?: Partial<DataApp>): DataApp => ({
name: "sales",
display_name: "Sales",
description: null,
+ version: 1,
+ outdated: false,
bundle_path: "data_apps/sales/dist/index.js",
enabled: true,
resource_collection_id: 1,
diff --git a/resources/migrations/065/20260915_data_app_version.yaml b/resources/migrations/065/20260915_data_app_version.yaml
new file mode 100644
index 00000000000..e1f686d8fb1
--- /dev/null
+++ b/resources/migrations/065/20260915_data_app_version.yaml
@@ -0,0 +1,26 @@
+## Record the data app contract version each app was built for.
+##
+## Authored as `version:` in the app's `data_app.yaml`. An app that declares none
+## is a version 1 app, so the column defaults to 1 and is never NULL. Metabase
+## compares it against the version it serves and treats a lower one as outdated.
+
+databaseChangeLog:
+ - changeSet:
+ id: v65.2026-09-15T00:00:00
+ author: timofei
+ comment: Add version column to data_app
+ changes:
+ - addColumn:
+ tableName: data_app
+ columns:
+ - column:
+ name: version
+ type: integer
+ defaultValueNumeric: 1
+ remarks: Data app contract version from the manifest. 1 when the app declares none.
+ constraints:
+ nullable: false
+ rollback:
+ - dropColumn:
+ tableName: data_app
+ columnName: version
diff --git a/skills/metabase-data-app-setup/SKILL.md b/skills/metabase-data-app-setup/SKILL.md
index 00d79d02831..1603ec2c781 100644
--- a/skills/metabase-data-app-setup/SKILL.md
+++ b/skills/metabase-data-app-setup/SKILL.md
@@ -134,6 +134,7 @@ Once the template is in `<repo>/data_apps/<slug>/` (run everything below from th
```yaml
name: Sales App # display name shown in the admin UI
description: Pipeline health and quota attainment by region # optional — see below
+ version: 1 # data app contract version — leave as-is (see below)
path: ./dist/index.js # bundle path, relative to this app's directory — leave as-is unless you change the build output
# allowed_hosts: # optional — external origins the app may fetch/XHR (see below)
# - https://api.example.com
@@ -150,6 +151,15 @@ Once the template is in `<repo>/data_apps/<slug>/` (run everything below from th
Replace the template's placeholder with a real sentence about *this* app, or
delete the line entirely if it adds nothing beyond the name.
+ **`version`** — the data app contract version this app's code targets, a
+ whole number. The template ships the version this skill targets; do not
+ change it by hand. Metabase bumps the version it serves only on a breaking
+ change to the contract. An app on an older version is marked *Outdated* in
+ the admin list, hidden from every other user, and refuses to open until it
+ is migrated to the current contract, its `version` raised to match, rebuilt,
+ and synced. Migrating an app from one version to the next is a separate,
+ instructed procedure; never do it ad hoc.
+
**`allowed_hosts`** — only needed if the app calls an **external** API directly
with `fetch`/`XHR`. The sandbox blocks all network egress by default; listing an
origin here (exact or a `*.` subdomain wildcard) opens it in both `npm run dev`
diff --git a/skills/metabase-data-app-setup/template/README.md b/skills/metabase-data-app-setup/template/README.md
index b06357b3241..7a0befc9af2 100644
--- a/skills/metabase-data-app-setup/template/README.md
+++ b/skills/metabase-data-app-setup/template/README.md
@@ -38,18 +38,18 @@ import (manual "Pull changes", auto-import, or startup).
```
.
-├── data_app.yaml ← manifest: name, bundle path, allowed_hosts
-├── package.json ← @metabase/embedding-sdk-react + react/react-dom + Vite toolchain
-├── vite.config.ts ← one-liner: `export default dataAppConfig()`
+├── data_app.yaml - manifest: version, name, bundle path, allowed_hosts
+├── package.json - @metabase/embedding-sdk-react + react/react-dom + Vite toolchain
+├── vite.config.ts - one-liner: `export default dataAppConfig()`
├── tsconfig.json
├── queries/ ← every query, as `defineQuery(...)` exports (see its README)
│ └── README.md
├── actions/ ← every action, as `defineAction(...)` exports (see its README)
│ └── README.md
├── src/
-│ ├── index.tsx ← entry — default-exports a factory returning { component, providerProps }
-│ ├── App.tsx ← edit this; pure content, no <MetabaseProvider> wrap
-│ └── theme.ts ← the SDK theme, passed via providerProps
+│ ├── index.tsx - entry — default-exports a factory returning { component, providerProps }
+│ ├── App.tsx - edit this; pure content, no <MetabaseProvider> wrap
+│ └── theme.ts - the SDK theme, passed via providerProps
├── .env.local.example
└── .gitignore
```
diff --git a/skills/metabase-data-app-setup/template/data_app.yaml b/skills/metabase-data-app-setup/template/data_app.yaml
index cef4d227c62..43fb1b9b106 100644
--- a/skills/metabase-data-app-setup/template/data_app.yaml
+++ b/skills/metabase-data-app-setup/template/data_app.yaml
@@ -1,3 +1,5 @@
+version: 1
+
name: Data App Template
description: A summary of what this app does