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
DB form test connection (#83100)
Nick Fitzpatrick1b136fafbea2
diff --git a/e2e/test/scenarios/admin/databases.cy.spec.js b/e2e/test/scenarios/admin/databases.cy.spec.jsindex 4a2a4680506..222874c12a2 100644--- a/e2e/test/scenarios/admin/databases.cy.spec.js+++ b/e2e/test/scenarios/admin/databases.cy.spec.js@@ -88,9 +88,8 @@ describe("admin > database > add", () => {cy.intercept("GET", "/api/database/:id").as("getDatabase");cy.visit("/admin/databases/create");- // should display a setup help card- // eslint-disable-next-line metabase/no-unscoped-text-selectors -- deprecated usage- cy.findByText("Need help connecting?");+ // should display a setup help link+ cy.findByRole("link", { name: "Need help connecting?" }).should("be.exist");cy.findByLabelText("Database type").click();});diff --git a/frontend/src/metabase-types/api/database.ts b/frontend/src/metabase-types/api/database.tsindex 1a87f2d973a..a3bd8ddef1f 100644--- a/frontend/src/metabase-types/api/database.ts+++ b/frontend/src/metabase-types/api/database.ts@@ -240,6 +240,21 @@ export interface UpdateDatabaseRequest {settings?: DatabaseSettings | null;}+export interface ValidateDatabaseRequest {+ details: {+ engine: string;+ details: Record<string, unknown>;+ /** Validate against an existing database, resolving details it left redacted */+ id?: DatabaseId;+ };+}++export type ValidateDatabaseResponse = {+ valid: boolean;+ message?: string;+ errors?: Record<string, string>;+};+export type DatabaseEditErrorType = {data: {message: string;diff --git a/frontend/src/metabase/api/database.ts b/frontend/src/metabase/api/database.tsindex c091ab18dd4..99e34cb0c31 100644--- a/frontend/src/metabase/api/database.ts+++ b/frontend/src/metabase/api/database.ts@@ -22,6 +22,8 @@ import type {SchemaName,Table,UpdateDatabaseRequest,+ ValidateDatabaseRequest,+ ValidateDatabaseResponse,} from "metabase-types/api";import { Api } from "./api";@@ -170,6 +172,16 @@ export const databaseApi = Api.injectEndpoints({}),providesTags: [listTag("field")],}),+ validateDatabase: builder.mutation<+ ValidateDatabaseResponse,+ ValidateDatabaseRequest+ >({+ query: (body) => ({+ method: "POST",+ url: "/api/database/validate",+ body,+ }),+ }),createDatabase: builder.mutation<Database, CreateDatabaseRequest>({query: (body) => ({method: "POST",@@ -319,6 +331,7 @@ export const {useLazyListDatabaseSchemaTablesQuery,useListVirtualDatabaseTablesQuery,useListDatabaseIdFieldsQuery,+ useValidateDatabaseMutation,useCreateDatabaseMutation,useUpdateDatabaseMutation,useDeleteDatabaseMutation,diff --git a/frontend/src/metabase/databases/components/DatabaseForm/DatabaseFormFooter.tsx b/frontend/src/metabase/databases/components/DatabaseForm/DatabaseFormFooter.tsxindex b12befa42ea..7a14916474f 100644--- a/frontend/src/metabase/databases/components/DatabaseForm/DatabaseFormFooter.tsx+++ b/frontend/src/metabase/databases/components/DatabaseForm/DatabaseFormFooter.tsx@@ -10,11 +10,12 @@ import type {} from "metabase/databases/types";import { FormSubmitButton } from "metabase/forms/components/FormSubmitButton";import { useSetting } from "metabase/settings";-import { Button, Flex, Text } from "metabase/ui";+import { ActionIcon, Button, Flex, Icon, Text, Tooltip } from "metabase/ui";import type { DatabaseData } from "metabase-types/api";import { DatabaseFormError } from "../DatabaseFormError";+import { DatabaseTestConnectionButton } from "./DatabaseTestConnectionButton";import { useHasConnectionError, useIsFormDirty } from "./utils";interface DatabaseFormFooterProps {@@ -34,6 +35,7 @@ export const DatabaseFormFooter = ({}: DatabaseFormFooterProps) => {const { values } = useFormikContext<DatabaseData>();const isNew = values.id == null;+ const isFullPage = location === "full-page";const hasConnectionError = useHasConnectionError();const isDirty = useIsFormDirty();@@ -44,25 +46,25 @@ export const DatabaseFormFooter = ({if (isAdvanced) {return (- <FormFooter- data-testid="form-footer"- px={location === "full-page" ? undefined : "xxl"}- >+ <FormFooter data-testid="form-footer" px={isFullPage ? undefined : "xxl"}><Flex justify="space-between" align="center" w="100%">- {isNew ? (- <ExternalLink- key="link"- href={docsUrl}- style={{ fontWeight: 500, fontSize: ".875rem" }}- >- {t`Need help connecting?`}- </ExternalLink>- ) : (- <div />- )}+ <Flex gap="sm" align="center">+ <DatabaseTestConnectionButton />+ {isNew && (+ <Tooltip label={t`Need help connecting?`}>+ <ActionIcon+ component={ExternalLink}+ href={docsUrl}+ aria-label={t`Need help connecting?`}+ >+ <Icon name="question" />+ </ActionIcon>+ </Tooltip>+ )}+ </Flex><Flex gap="sm">- <Button onClick={onCancel}>{t`Cancel`}</Button>+ {!isFullPage && <Button onClick={onCancel}>{t`Cancel`}</Button>}<FormSubmitButtondisabled={!isDirty}label={isNew ? t`Save` : t`Save changes`}diff --git a/frontend/src/metabase/databases/components/DatabaseForm/DatabaseTestConnectionButton.tsx b/frontend/src/metabase/databases/components/DatabaseForm/DatabaseTestConnectionButton.tsxnew file mode 100644index 00000000000..bf6790f1cc6--- /dev/null+++ b/frontend/src/metabase/databases/components/DatabaseForm/DatabaseTestConnectionButton.tsx@@ -0,0 +1,146 @@+import { type FormikErrors, useFormikContext } from "formik";+import { useState } from "react";+import { match } from "ts-pattern";+import { t } from "ttag";++import { useValidateDatabaseMutation } from "metabase/api";+import { getErrorMessage } from "metabase/api/utils";+import { useDebouncedValue } from "metabase/common/hooks/use-debounced-value";+import { useSetting } from "metabase/settings";+import { Button, Icon, Tooltip } from "metabase/ui";+import type { DatabaseData } from "metabase-types/api";++import { getSubmitValues } from "../../utils/schema";++import { getEngine } from "./utils";++const LOADING_INDICATOR_DELAY_MS = 300;++const isLoadingStarting = (_lastValue: boolean, newValue: boolean) => newValue;++type TestResult =+ | { status: "success"; valuesAtTest: DatabaseData }+ | { status: "error"; valuesAtTest: DatabaseData; message: string };++/** Formik types this as a string, but per-field errors arrive as an object keyed by field name */+const getDetailErrorPaths = (details: unknown): string[] => {+ if (typeof details === "object" && details !== null) {+ return Object.keys(details).map((name) => `details.${name}`);+ }++ return details ? ["details"] : [];+};++const getConnectionErrorPaths = ({+ engine,+ details,+}: FormikErrors<DatabaseData>) => [+ ...(engine ? ["engine"] : []),+ ...getDetailErrorPaths(details),+];++const TestResultIcon = ({ result }: { result: TestResult }) =>+ match(result)+ .with({ status: "success" }, () => (+ <Icon+ name="check_filled"+ c="feedback-positive"+ aria-label={t`Connection successful`}+ />+ ))+ .with({ status: "error" }, ({ message }) => (+ <Tooltip label={message} multiline maw="20rem">+ <Icon+ name="warning_round_filled"+ c="feedback-negative"+ aria-label={t`Connection failed`}+ />+ </Tooltip>+ ))+ .exhaustive();++export const DatabaseTestConnectionButton = () => {+ const { values, validateForm, setFieldError, setFieldTouched } =+ useFormikContext<DatabaseData>();+ const engines = useSetting("engines");+ const [validateDatabase, { isLoading }] = useValidateDatabaseMutation();+ const showLoading = useDebouncedValue(+ isLoading,+ LOADING_INDICATOR_DELAY_MS,+ isLoadingStarting,+ );+ const [lastResult, setLastResult] = useState<TestResult | null>(null);++ // Formik replaces `values` on every edit, so a new reference means the result is stale+ const result = lastResult?.valuesAtTest === values ? lastResult : null;++ const handleTestConnection = async () => {+ // the button stays clickable until the delayed loader appears+ if (isLoading) {+ return;+ }++ const invalidPaths = getConnectionErrorPaths(await validateForm());++ if (invalidPaths.length > 0) {+ invalidPaths.forEach((path) => setFieldTouched(path, true, false));+ return;+ }++ const engineKey = values.engine;+ if (engineKey == null) {+ return;+ }++ const submitValues = getSubmitValues(+ getEngine(engines, engineKey),+ values,+ true,+ );++ try {+ const response = await validateDatabase({+ details: {+ engine: engineKey,+ details: submitValues.details ?? {},+ // lets the backend resolve details we sent back redacted+ ...(values.id != null && { id: values.id }),+ },+ }).unwrap();++ if (response.valid) {+ setLastResult({ status: "success", valuesAtTest: values });+ return;+ }++ Object.entries(response.errors ?? {}).forEach(([name, message]) => {+ setFieldTouched(`details.${name}`, true, false);+ setFieldError(`details.${name}`, message);+ });++ setLastResult({+ status: "error",+ valuesAtTest: values,+ message: response.message ?? t`Couldn't connect to the database`,+ });+ } catch (error) {+ setLastResult({+ status: "error",+ valuesAtTest: values,+ message: getErrorMessage(error, t`Couldn't connect to the database`),+ });+ }+ };++ return (+ <Button+ data-testid="database-test-connection-button"+ disabled={values.engine == null}+ loading={showLoading}+ rightSection={result && <TestResultIcon result={result} />}+ onClick={handleTestConnection}+ >+ {t`Test connection`}+ </Button>+ );+};diff --git a/frontend/src/metabase/databases/components/DatabaseForm/tests/common.unit.spec.tsx b/frontend/src/metabase/databases/components/DatabaseForm/tests/common.unit.spec.tsxindex 16c3f36ad5b..f531e0eada5 100644--- a/frontend/src/metabase/databases/components/DatabaseForm/tests/common.unit.spec.tsx+++ b/frontend/src/metabase/databases/components/DatabaseForm/tests/common.unit.spec.tsx@@ -48,6 +48,18 @@ describe("DatabaseForm", () => {).toBeInTheDocument();});+ it("should show the cancel button when rendered in a modal", () => {+ setup({ location: "admin" });+ expect(screen.getByRole("button", { name: "Cancel" })).toBeInTheDocument();+ });++ it("should not show the cancel button when rendered as a full page", () => {+ setup({ location: "full-page" });+ expect(+ screen.queryByRole("button", { name: "Cancel" }),+ ).not.toBeInTheDocument();+ });+it("should not render hidden fields", async () => {setup();await userEvent.click(screen.getByText("Show advanced options"));diff --git a/frontend/src/metabase/databases/components/DatabaseForm/tests/setup.tsx b/frontend/src/metabase/databases/components/DatabaseForm/tests/setup.tsxindex 3ed0ec3dc57..39a4c8b0565 100644--- a/frontend/src/metabase/databases/components/DatabaseForm/tests/setup.tsx+++ b/frontend/src/metabase/databases/components/DatabaseForm/tests/setup.tsx@@ -2,6 +2,7 @@ import { setupEnterpriseOnlyPlugin } from "__support__/enterprise";import { mockSettings } from "__support__/settings";import { createMockState } from "__support__/state";import { renderWithProviders } from "__support__/ui";+import type { FormLocation } from "metabase/databases/types";import type {DatabaseData,Engine,@@ -103,6 +104,7 @@ export interface SetupOpts {engines?: Record<string, Engine>;initialValues?: Partial<DatabaseData> & { engine?: EngineKey };isAdvanced?: boolean;+ location?: FormLocation;}export const setup = ({@@ -111,6 +113,7 @@ export const setup = ({engines = TEST_ENGINES,initialValues = {},isAdvanced = true,+ location = "admin",}: SetupOpts = {}) => {const state = createMockState({settings: mockSettings({ ...settings, engines }),@@ -132,7 +135,7 @@ export const setup = ({}}config={{ isAdvanced }}onSubmit={onSubmit}- location="admin"+ location={location}/>,{storeInitialState: state,diff --git a/frontend/src/metabase/databases/components/DatabaseForm/tests/test-connection.unit.spec.tsx b/frontend/src/metabase/databases/components/DatabaseForm/tests/test-connection.unit.spec.tsxnew file mode 100644index 00000000000..c701e2740d7--- /dev/null+++ b/frontend/src/metabase/databases/components/DatabaseForm/tests/test-connection.unit.spec.tsx@@ -0,0 +1,153 @@+import userEvent from "@testing-library/user-event";+import fetchMock from "fetch-mock";++import { findRequests } from "__support__/server-mocks";+import { screen, waitFor } from "__support__/ui";+import type { ValidateDatabaseResponse } from "metabase-types/api";++import { type SetupOpts, setup } from "./setup";++/** `dbname` and `user` are the required fields of the postgres test config */+const VALID_DETAILS = { dbname: "birds", user: "admin", password: "hunter2" };++const POSTGRES_VALUES: SetupOpts["initialValues"] = {+ engine: "postgres",+ name: "My database",+ details: VALID_DETAILS,+};++const setupTestConnection = ({+ validateResponse = { valid: true },+ validateDelayMs = 0,+ ...opts+}: SetupOpts & {+ validateResponse?:+ | ValidateDatabaseResponse+ | { status: number; body: { message: string } };+ validateDelayMs?: number;+} = {}) => {+ fetchMock.post("path:/api/database/validate", validateResponse, {+ delay: validateDelayMs,+ });+ return setup(opts);+};++const getTestConnectionButton = () =>+ screen.getByRole("button", { name: /Test connection/i });++const clickTestConnection = async () => {+ await userEvent.click(getTestConnectionButton());+};++const findValidateRequests = async () => {+ const requests = await findRequests("POST");+ return requests.filter((request) =>+ request.url.includes("/api/database/validate"),+ );+};++describe("DatabaseForm > test connection", () => {+ it("should not test the connection when a required connection field is missing", async () => {+ setupTestConnection({+ initialValues: { engine: "postgres", name: "My database" },+ });++ await clickTestConnection();++ expect(await screen.findAllByText("required")).not.toHaveLength(0);+ expect(await findValidateRequests()).toHaveLength(0);+ });++ it.each([+ { name: "omit the id for a new database", id: undefined },+ { name: "send the id for an existing database", id: 42 },+ ])("should $name", async ({ id }) => {+ setupTestConnection({ initialValues: { ...POSTGRES_VALUES, id } });++ await clickTestConnection();++ await waitFor(async () => {+ expect(await findValidateRequests()).toHaveLength(1);+ });+ const [request] = await findValidateRequests();+ expect(request.body.details).toMatchObject({+ engine: "postgres",+ details: VALID_DETAILS,+ });+ expect(request.body.details.id).toBe(id);+ });++ it("should show the result until the form is edited, including while re-testing", async () => {+ setupTestConnection({+ initialValues: POSTGRES_VALUES,+ validateDelayMs: 200,+ });++ await clickTestConnection();+ expect(+ await screen.findByLabelText("Connection successful"),+ ).toBeInTheDocument();++ await clickTestConnection();+ expect(screen.getByLabelText("Connection successful")).toBeInTheDocument();+ await waitFor(async () => {+ expect(await findValidateRequests()).toHaveLength(2);+ });+ expect(screen.getByLabelText("Connection successful")).toBeInTheDocument();++ await userEvent.type(screen.getByLabelText("Host"), "x");+ expect(+ screen.queryByLabelText("Connection successful"),+ ).not.toBeInTheDocument();+ });++ it.each([+ {+ name: "an invalid connection",+ validateResponse: { valid: false, message: "Password is incorrect" },+ message: "Password is incorrect",+ },+ {+ name: "a failed request",+ validateResponse: { status: 500, body: { message: "Server exploded" } },+ message: "Server exploded",+ },+ ])(+ "should show the error in the failure icon's tooltip for $name",+ async ({ validateResponse, message }) => {+ setupTestConnection({ initialValues: POSTGRES_VALUES, validateResponse });++ await clickTestConnection();+ expect(+ await screen.findByLabelText("Connection failed"),+ ).toBeInTheDocument();++ await userEvent.hover(getTestConnectionButton());+ expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();++ await userEvent.hover(screen.getByLabelText("Connection failed"));+ expect(await screen.findByRole("tooltip")).toHaveTextContent(message);+ },+ );++ it("should delay the loader and ignore clicks while a test is running", async () => {+ setupTestConnection({+ initialValues: POSTGRES_VALUES,+ validateDelayMs: 800,+ });++ await clickTestConnection();+ expect(getTestConnectionButton()).not.toHaveAttribute("data-loading");++ await clickTestConnection();+ await waitFor(() =>+ expect(getTestConnectionButton()).toHaveAttribute("data-loading", "true"),+ );++ expect(+ await screen.findByLabelText("Connection successful"),+ ).toBeInTheDocument();+ expect(getTestConnectionButton()).not.toHaveAttribute("data-loading");+ expect(await findValidateRequests()).toHaveLength(1);+ });+});diff --git a/src/metabase/warehouses_rest/api.clj b/src/metabase/warehouses_rest/api.cljindex 81af409c91f..50496a3611b 100644--- a/src/metabase/warehouses_rest/api.clj+++ b/src/metabase/warehouses_rest/api.clj@@ -824,21 +824,72 @@{:status 400:body (dissoc details-or-error :valid)}))))+(defn- upsert-sensitive-fields+ "Replace any sensitive values the client left redacted with the original values.+ `details-key` is the key in the database map to use (e.g., :details or :write_data_details).+ When `engine-changed?` is truthy, the existing details belong to a different driver, so they are not merged into the+ new details (#77480)."+ ([database new-details]+ (upsert-sensitive-fields database new-details :details false))+ ([database new-details details-key]+ (upsert-sensitive-fields database new-details details-key false))+ ([database new-details details-key engine-changed?]+ (when new-details+ (let [existing-details (get database details-key)+ details (reduce+ (fn [details k]+ (if (= secret/protected-password (get details k))+ (m/update-existing details k (constantly (get-in database [details-key k])))+ details))+ new-details+ (database/sensitive-fields-for-db database))]+ (if engine-changed?+ details+ (merge existing-details details))))))++(defn- redact-sensitive-details+ "Redact `database`'s sensitive values in `details` so secrets resolved server-side are never echoed back."+ [database details]+ (reduce (fn [details k]+ (m/update-existing details k (fn [v] (when v secret/protected-password))))+ details+ (database/sensitive-fields-for-db database)))++(defn- test-existing-database-details+ "Like [[warehouses/test-connection-details]], but for `details` that are an edit of the existing `database`."+ [database engine details]+ (let [engine-changed? (not= (keyword engine) (:engine database))+ details (upsert-sensitive-fields database details :details engine-changed?)]+ ;; testing an existing Database's own engine is fine; we only want to prevent creating new H2/SQLite Databases+ (binding [driver.settings/*allow-testing-h2-connections* (or (not engine-changed?)+ driver.settings/*allow-testing-h2-connections*)+ driver.settings/*allow-testing-sqlite-connections* (or (not engine-changed?)+ driver.settings/*allow-testing-sqlite-connections*)]+ (redact-sensitive-details database (warehouses/test-connection-details engine details)))))+;; TODO (Cam 2025-11-25) please add a response schema to this API endpoint, it makes it easier for our customers to;; use our API + we will need it when we make auto-TypeScript-signature generation happen;;#_{:clj-kondo/ignore [:metabase/validate-defendpoint-has-response-schema]}(api.macros/defendpoint :post "/validate"- "Validate that we can connect to a database given a set of details."+ "Validate that we can connect to a database given a set of details.++ Pass the `id` of an existing Database to test edited details against it: sensitive values the client left redacted+ are resolved from the stored Database, and its own engine may be tested even when creating new Databases of that+ engine is disallowed.";; TODO - why do we pass the DB in under the key `details`?[_route-params_query-params- {{:keys [engine details]} :details} :- [:map {:closed true}- [:details [:map {:closed true}- [:engine DBEngineString]- [:details ms/DatabaseDetails]]]]]+ {{:keys [engine details id]} :details} :- [:map {:closed true}+ [:details [:map {:closed true}+ [:engine DBEngineString]+ [:details ms/DatabaseDetails]+ [:id {:optional true} [:maybe ms/PositiveInt]]]]]](api/check-superuser)- (let [details-or-error (warehouses/test-connection-details engine details)]+ (let [database (when id (api/write-check (warehouses-rest.db/database id)))+ details-or-error (if database+ (test-existing-database-details database engine details)+ (warehouses/test-connection-details engine details))];; details that come back without a `:valid` key at all are... valid!(update details-or-error :valid (comp not false?))))@@ -860,29 +911,6 @@;;; --------------------------------------------- PUT /api/database/:id -----------------------------------------------(defn- upsert-sensitive-fields- "Replace any sensitive values not overridden in the PUT with the original values.- `details-key` is the key in the database map to use (e.g., :details or :write_data_details).- When `engine-changed?` is truthy, the existing details belong to a different driver, so they are not merged into the- new details (#77480)."- ([database new-details]- (upsert-sensitive-fields database new-details :details false))- ([database new-details details-key]- (upsert-sensitive-fields database new-details details-key false))- ([database new-details details-key engine-changed?]- (when new-details- (let [existing-details (get database details-key)- details (reduce- (fn [details k]- (if (= secret/protected-password (get details k))- (m/update-existing details k (constantly (get-in database [details-key k])))- details))- new-details- (database/sensitive-fields-for-db database))]- (if engine-changed?- details- (merge existing-details details))))))-(def ^:private connection-marker-key->details-column{:write-data-connection "write_data_details"})diff --git a/test/metabase/warehouses_rest/api_test.clj b/test/metabase/warehouses_rest/api_test.cljindex e6c3e1ca093..2fa4a1f057b 100644--- a/test/metabase/warehouses_rest/api_test.clj+++ b/test/metabase/warehouses_rest/api_test.clj@@ -2109,6 +2109,41 @@:valid false}(api-validate-database! {:details {:engine :h2, :details {:db "ABC"}}})))))))+(def ^:private redacted-secret-db-details+ {:host "db.example.com", :port 5432, :dbname "x", :user "u", :password "hunter2"})++(deftest validate-database-resolves-redacted-secrets-test+ (testing "POST /api/database/validate"+ (testing "with an `id`, sensitive values the client left redacted come from the stored Database"+ (mt/with-temp [:model/Database db {:engine :postgres, :details redacted-secret-db-details}]+ (let [tested-details (atom nil)]+ (mt/with-dynamic-fn-redefs [warehouses.util/test-database-connection (fn [_engine details & _]+ (reset! tested-details details)+ nil)]+ (api-validate-database! {:details {:engine :postgres+ :id (u/the-id db)+ :details (assoc redacted-secret-db-details+ :host "new.example.com"+ :password secret/protected-password)}})+ (testing "the stored password reaches the driver, not the placeholder"+ (is (= "hunter2" (:password @tested-details))))+ (testing "the edited host is still the one tested"+ (is (= "new.example.com" (:host @tested-details))))))))))++(deftest validate-database-does-not-echo-secrets-test+ (testing "POST /api/database/validate"+ (testing "secrets resolved from the stored Database are not echoed back to the client"+ (mt/with-temp [:model/Database db {:engine :postgres, :details redacted-secret-db-details}]+ (mt/with-dynamic-fn-redefs [warehouses.util/test-database-connection (constantly nil)]+ (let [response (api-validate-database! {:details {:engine :postgres+ :id (u/the-id db)+ :details (assoc redacted-secret-db-details+ :password secret/protected-password)}})]+ (is (true? (:valid response)))+ (is (= secret/protected-password (:password response)))+ (testing "no value anywhere in the response is the real secret"+ (is (not-any? (partial = "hunter2") (vals response))))))))))+(deftest validate-database-test-2(testing "POST /api/database/validate"(let [call-count (atom 0)