Skip to content

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

[Admin settings] Show help documentation to connect DB in a side panel (#63420)

Andersonae422678b26c
diff --git a/e2e/test/scenarios/admin/databases.cy.spec.js b/e2e/test/scenarios/admin/databases.cy.spec.js
index 3c1e50c64da..f5a2f5a0e44 100644
--- a/e2e/test/scenarios/admin/databases.cy.spec.js
+++ b/e2e/test/scenarios/admin/databases.cy.spec.js
@@ -422,6 +422,71 @@ describe("admin > database > add", () => {
});
});
+describe("database page > side panel", () => {
+ beforeEach(() => {
+ H.restore();
+ cy.signInAsAdmin();
+ H.activateToken("pro-self-hosted");
+ cy.visit("/admin/databases/create");
+ });
+
+ it("should show side panel with help content when 'Help is here' is clicked", () => {
+ cy.findByRole("button", { name: /Help is here/ }).click();
+ cy.findByTestId("database-help-side-panel").within(() => {
+ cy.findByText("Add PostgreSQL").should("be.visible");
+ cy.findByRole("link", { name: /Read the full docs/ }).should(
+ "be.visible",
+ );
+ cy.findByRole("link", { name: /Talk to an expert/ }).should("be.visible");
+ cy.findByRole("button", { name: /Invite a teammate to help you/ }).should(
+ "be.visible",
+ );
+ });
+ });
+
+ it("should update the side panel content when the engine is changed", () => {
+ const enginesMap = [
+ { name: "Amazon Athena", file: "athena" },
+ { name: "BigQuery", file: "bigquery" },
+ { name: "Amazon Redshift", file: "redshift" },
+ { name: "ClickHouse", file: "clickhouse" },
+ { name: "Databricks", file: "databricks" },
+ { name: "Druid", file: "druid" },
+ { name: "MongoDB", file: "mongo" },
+ { name: "MySQL", file: "mysql" },
+ { name: "PostgreSQL", file: "postgresql" },
+ { name: "Presto", file: "presto" },
+ { name: "SQL Server", file: "sql-server" },
+ { name: "Snowflake", file: "snowflake" },
+ { name: "Spark SQL", file: "sparksql" },
+ { name: "Starburst (Trino)", file: "starburst" },
+ ];
+
+ for (const engineSpec of enginesMap) {
+ cy.findByTestId("database-form").within(() => {
+ cy.findByLabelText("Database type").click();
+ });
+ H.popover().contains(engineSpec.name).click();
+ cy.findByRole("button", { name: /Help is here/ }).click();
+ cy.findByTestId("database-help-side-panel").within(() => {
+ cy.findByText("Add " + engineSpec.name).should("be.visible");
+ cy.findByRole("link", { name: /Read the full docs/ })
+ .should("have.attr", "href")
+ .and("contain", engineSpec.file);
+
+ // Check we don't have an error when loading the doc contents
+ cy.findByRole("alert").should("not.exist");
+ cy.contains("Failed to load detailed documentation").should(
+ "not.exist",
+ );
+ });
+
+ cy.findByRole("button", { name: /Close panel/ }).click();
+ cy.findByTestId("database-help-side-panel").should("not.exist");
+ }
+ });
+});
+
describe("scenarios > admin > databases > exceptions", () => {
beforeEach(() => {
H.restore();
diff --git a/frontend/src/metabase-types/analytics/event.ts b/frontend/src/metabase-types/analytics/event.ts
index a8c74c9ae34..99f1a5504c1 100644
--- a/frontend/src/metabase-types/analytics/event.ts
+++ b/frontend/src/metabase-types/analytics/event.ts
@@ -337,6 +337,11 @@ export type DocumentPrintEvent = ValidateEvent<{
target_id: number | null;
}>;
+export type DatabaseHelpClickedEvent = ValidateEvent<{
+ event: "database_help_clicked";
+ triggered_from: "admin" | "setup";
+}>;
+
export type EmbedWizardEvent =
| EmbedWizardExperienceSelectedEvent
| EmbedWizardResourceSelectedEvent
@@ -392,4 +397,5 @@ export type SimpleEvent =
| DocumentCreatedEvent
| DocumentReplaceCardEvent
| DocumentUpdatedEvent
- | DocumentPrintEvent;
+ | DocumentPrintEvent
+ | DatabaseHelpClickedEvent;
diff --git a/frontend/src/metabase-types/api/settings.ts b/frontend/src/metabase-types/api/settings.ts
index 43137ec3c91..da4f75b911a 100644
--- a/frontend/src/metabase-types/api/settings.ts
+++ b/frontend/src/metabase-types/api/settings.ts
@@ -38,6 +38,7 @@ export const engineKeys = [
"databricks",
"druid-jdbc",
"druid",
+ "mongo",
"mysql",
"oracle",
"postgres",
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseEditConnectionForm.tsx b/frontend/src/metabase/admin/databases/components/DatabaseEditConnectionForm.tsx
index 21cf0cdb56d..48d25547271 100644
--- a/frontend/src/metabase/admin/databases/components/DatabaseEditConnectionForm.tsx
+++ b/frontend/src/metabase/admin/databases/components/DatabaseEditConnectionForm.tsx
@@ -40,6 +40,7 @@ export const DatabaseEditConnectionForm = withRouter(
handleSaveDb,
onSubmitted,
onCancel,
+ onEngineChange,
route,
location,
config,
@@ -52,6 +53,7 @@ export const DatabaseEditConnectionForm = withRouter(
handleSaveDb?: (database: DatabaseData) => Promise<{ id: DatabaseId }>;
onSubmitted: (savedDB: { id: DatabaseId }) => void;
onCancel: () => void;
+ onEngineChange?: (engineKey: string | undefined) => void;
route: Route;
location: LocationDescriptorObject;
autofocusFieldName?: string;
@@ -98,6 +100,7 @@ export const DatabaseEditConnectionForm = withRouter(
onSubmit={handleSubmit}
setIsDirty={setIsDirty}
location={formLocation}
+ onEngineChange={onEngineChange}
/>
) : (
<Text my="md">{t`This database is managed by Metabase Cloud and cannot be modified.`}</Text>
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/DatabaseHelpSidePanel.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/DatabaseHelpSidePanel.tsx
new file mode 100644
index 00000000000..25423fcc411
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/DatabaseHelpSidePanel.tsx
@@ -0,0 +1,120 @@
+import { useDisclosure } from "@mantine/hooks";
+import { Link } from "react-router";
+import { c, t } from "ttag";
+
+import { NewUserModal } from "metabase/admin/people/containers/NewUserModal";
+import { useDocsUrl, useSetting } from "metabase/common/hooks";
+import { getHelpUrl } from "metabase/common/utils/help-url";
+import CS from "metabase/css/core/index.css";
+import { getEngines } from "metabase/databases/selectors";
+import { useSelector } from "metabase/lib/redux";
+import { getIsPaidPlan } from "metabase/selectors/settings";
+import { getUserIsAdmin } from "metabase/selectors/user";
+import {
+ ActionIcon,
+ Box,
+ Button,
+ Divider,
+ Flex,
+ Icon,
+ ScrollArea,
+ Title,
+} from "metabase/ui";
+import type { EngineKey } from "metabase-types/api";
+
+import {
+ ENGINE_DOC_MAP,
+ EmbeddedEngineDocContent,
+} from "./EmbeddedEngineDocContent";
+
+interface Props {
+ engineKey: EngineKey;
+ onClose: VoidFunction;
+}
+
+export const DatabaseHelpSidePanel = ({ engineKey, onClose }: Props) => {
+ const engines = useSelector(getEngines);
+ const { url: fullDocsUrl, showMetabaseLinks } = useDocsUrl(
+ `databases/connections/${ENGINE_DOC_MAP[engineKey]}`,
+ );
+ const [showUserModal, { toggle: toggleUserModal }] = useDisclosure(false);
+ const isPaidPlan = useSelector(getIsPaidPlan);
+ const version = useSetting("version");
+ const talkToExpertUrl = getHelpUrl(isPaidPlan, version.tag);
+ const isAdmin = useSelector(getUserIsAdmin);
+
+ if (!engines[engineKey]) {
+ return null;
+ }
+
+ const driverName = engines[engineKey]?.["driver-name"];
+
+ return (
+ <ScrollArea
+ component="aside"
+ data-testid="database-help-side-panel"
+ display="flex"
+ flex={{ sm: "1 0 20rem", md: "1 0 26.5rem", base: "1 0 100%" }}
+ h="100%"
+ >
+ <Box p="xl" w="100%">
+ <Flex align="baseline" justify="space-between" mb="md">
+ <Title order={2} size="h4">
+ {c("{0} is the database engine name").t`Add ${driverName}`}
+ </Title>
+ <ActionIcon aria-label={t`Close panel`} onClick={onClose}>
+ <Icon name="close" />
+ </ActionIcon>
+ </Flex>
+ {showMetabaseLinks && (
+ <>
+ <Button
+ className={CS.link}
+ component={Link}
+ leftSection={<Icon name="reference" />}
+ p={0}
+ target="_blank"
+ to={fullDocsUrl}
+ variant="subtle"
+ >
+ {t`Read the full docs`}
+ </Button>
+ <Divider variant="dashed" />
+ </>
+ )}
+ {isAdmin && (
+ <>
+ <Button
+ className={CS.link}
+ leftSection={<Icon name="mail" />}
+ onClick={toggleUserModal}
+ p={0}
+ variant="subtle"
+ >
+ {t`Invite a teammate to help you`}
+ </Button>
+ <Divider variant="dashed" />
+ </>
+ )}
+ {showMetabaseLinks && isPaidPlan && (
+ <>
+ <Button
+ className={CS.link}
+ component={Link}
+ leftSection={<Icon name="person" />}
+ p={0}
+ target="_blank"
+ to={talkToExpertUrl}
+ variant="subtle"
+ >
+ {t`Talk to an expert`}
+ </Button>
+ <Divider variant="dashed" />
+ </>
+ )}
+ <EmbeddedEngineDocContent engineKey={engineKey} />
+ </Box>
+ {showUserModal && <NewUserModal onClose={toggleUserModal} />}
+ </ScrollArea>
+ );
+};
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/DatabaseHelpSidePanel.unit.spec.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/DatabaseHelpSidePanel.unit.spec.tsx
new file mode 100644
index 00000000000..ff79cf91aae
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/DatabaseHelpSidePanel.unit.spec.tsx
@@ -0,0 +1,147 @@
+import { act } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import fetchMock from "fetch-mock";
+import { Route } from "react-router";
+
+import { setupEnterprisePlugins } from "__support__/enterprise";
+import { mockSettings } from "__support__/settings";
+import { renderWithProviders, screen, within } from "__support__/ui";
+import type { EngineKey } from "metabase-types/api";
+import {
+ createMockEngines,
+ createMockGroup,
+ createMockTokenFeatures,
+ createMockTokenStatus,
+ createMockUser,
+} from "metabase-types/api/mocks";
+import { createMockState } from "metabase-types/store/mocks";
+
+import { DatabaseHelpSidePanel } from "./DatabaseHelpSidePanel";
+
+jest.mock(
+ "docs/databases/connections/postgresql.md",
+ () => "Postgres MD Content",
+);
+
+interface SetupOptions {
+ onClose?: VoidFunction;
+ engineKey?: EngineKey;
+ paidPlan?: boolean;
+ showMetabaseLinks?: boolean;
+ isAdmin?: boolean;
+}
+
+const setup = (opts: SetupOptions) => {
+ const {
+ onClose = jest.fn(),
+ engineKey = "postgres",
+ paidPlan = true,
+ showMetabaseLinks = true,
+ isAdmin = true,
+ } = opts;
+ const storeInitialState = createMockState({
+ currentUser: createMockUser({ is_superuser: isAdmin }),
+ settings: mockSettings({
+ "show-metabase-links": showMetabaseLinks,
+ "token-status": paidPlan
+ ? createMockTokenStatus({
+ valid: true,
+ })
+ : undefined,
+ "token-features": createMockTokenFeatures({ whitelabel: true }),
+ "is-hosted?": true,
+ engines: createMockEngines(),
+ }),
+ });
+ setupEnterprisePlugins();
+
+ renderWithProviders(
+ <Route
+ component={() => (
+ <DatabaseHelpSidePanel engineKey={engineKey} onClose={onClose} />
+ )}
+ path="/"
+ />,
+ {
+ withRouter: true,
+ storeInitialState,
+ },
+ );
+};
+
+describe("DatabaseHelpSidePanel", () => {
+ it("should render help links and the engine md content", async () => {
+ await act(async () => {
+ setup({});
+ });
+ expect(
+ screen.getByRole("link", { name: /Read the full docs/ }),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole("button", { name: /Invite a teammate to help you/ }),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole("link", { name: /Talk to an expert/ }),
+ ).toBeInTheDocument();
+ expect(await screen.findByText(/Postgres MD Content/)).toBeInTheDocument();
+ });
+
+ it("should not render invite user button if not an admin", async () => {
+ await act(async () => {
+ setup({ isAdmin: false });
+ });
+
+ expect(
+ screen.queryByRole("button", { name: /Invite a teammate to help you/ }),
+ ).not.toBeInTheDocument();
+ });
+
+ it("should not render links if showMetabaseLinks is false", async () => {
+ await act(async () => {
+ setup({ showMetabaseLinks: false });
+ });
+
+ expect(
+ screen.queryByRole("link", { name: /Read the full docs/ }),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByRole("link", { name: /Talk to an expert/ }),
+ ).not.toBeInTheDocument();
+ });
+
+ it("should not render 'Talk to an expert' link if not in a paid plan", async () => {
+ await act(async () => {
+ setup({ paidPlan: false });
+ });
+
+ expect(
+ screen.queryByRole("link", { name: /Talk to an expert/ }),
+ ).not.toBeInTheDocument();
+ });
+
+ it("should call onClose prop when close button is clicked", async () => {
+ const onClose = jest.fn();
+ await act(async () => {
+ setup({ onClose });
+ });
+
+ expect(onClose).not.toHaveBeenCalled();
+ await userEvent.click(screen.getByRole("img", { name: "close icon" }));
+ expect(onClose).toHaveBeenCalledTimes(1);
+ });
+
+ it("should render 'new user' modal when 'Invite a teammate...' button is clicked", async () => {
+ fetchMock.get("path:/api/permissions/group", [createMockGroup()]);
+ await act(async () => {
+ setup({ isAdmin: true });
+ });
+ await userEvent.click(
+ screen.getByRole("button", { name: /Invite a teammate to help you/ }),
+ );
+ const dialog = screen.getByRole("dialog");
+ expect(dialog).toBeInTheDocument();
+ expect(
+ within(dialog).getByRole("heading", { name: /Create user/ }),
+ ).toBeInTheDocument();
+ });
+});
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.module.css b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.module.css
new file mode 100644
index 00000000000..682a95bf04f
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.module.css
@@ -0,0 +1,42 @@
+.markdown {
+ line-height: 1.5;
+ margin-top: var(--mantine-spacing-md);
+
+ ul {
+ list-style: disc;
+ margin-bottom: 1.25rem;
+ padding-left: 1.25rem;
+ }
+
+ h2,
+ h3,
+ h4 {
+ margin: 0.5rem 0;
+ display: inline-block;
+ }
+
+ h2 {
+ font-size: var(--mantine-h4-font-size);
+ }
+
+ h3,
+ h4 {
+ font-size: var(--mantine-h5-font-size);
+ }
+
+ pre {
+ background-color: var(--mb-color-background-light);
+ padding: 8px 10px;
+ }
+
+ code {
+ text-wrap: auto;
+ }
+
+ blockquote {
+ background-color: var(--mb-color-bg-medium);
+ border-radius: 0.25rem;
+ margin: 0.25rem 0 1.25rem;
+ padding: 1rem 1.5rem;
+ }
+}
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.tsx
new file mode 100644
index 00000000000..6990a5c0799
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.tsx
@@ -0,0 +1,62 @@
+import { useRef } from "react";
+import { useMount } from "react-use";
+
+import Markdown from "metabase/common/components/Markdown";
+import { Alert, Box, Loader, Text } from "metabase/ui";
+import type { EngineKey } from "metabase-types/api";
+
+import S from "./EmbeddedEngineDocContent.module.css";
+import { MarkdownLink } from "./MarkdownLink";
+import { hideUnnecessaryElements } from "./markdown-utils";
+import { useEngineDocMarkdownContent } from "./useEngineDocMarkdownContent";
+
+interface Props {
+ engineKey: EngineKey;
+}
+
+const markdownComponentsOverride = {
+ a: MarkdownLink,
+};
+
+export const EmbeddedEngineDocContent = ({ engineKey }: Props) => {
+ const { markdownContent, isLoading, loadingError } =
+ useEngineDocMarkdownContent(engineKey);
+ const markdownRef = useRef<HTMLDivElement>(null);
+
+ useMount(() => {
+ if (!markdownRef.current) {
+ return;
+ }
+
+ const observer = new MutationObserver(() => {
+ // Using observer to ensure hideUnnecessaryElements is called after the markdown is rendered
+ hideUnnecessaryElements(markdownRef.current);
+ });
+
+ observer.observe(markdownRef.current, { childList: true, subtree: true });
+
+ return () => {
+ observer.disconnect();
+ };
+ });
+
+ return (
+ <Box ref={markdownRef} w="100%">
+ {loadingError && (
+ <Alert color="bg-dark" variant="outline" mt="xl">
+ <Text>{loadingError}</Text>
+ </Alert>
+ )}
+ {isLoading ? (
+ <Loader mx="auto" mt="xl" display="block" data-testid="loader" />
+ ) : (
+ <Markdown
+ className={S.markdown}
+ components={markdownComponentsOverride}
+ >
+ {markdownContent || ""}
+ </Markdown>
+ )}
+ </Box>
+ );
+};
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.unit.spec.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.unit.spec.tsx
new file mode 100644
index 00000000000..6027abb8fa8
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/EmbeddedEngineDocContent.unit.spec.tsx
@@ -0,0 +1,43 @@
+import { waitFor } from "@testing-library/react";
+
+import { render, screen } from "__support__/ui";
+
+import { EmbeddedEngineDocContent } from "./EmbeddedEngineDocContent";
+
+jest.mock(
+ "docs/databases/connections/postgresql.md",
+ () => "Postgres Markdown content",
+);
+jest.mock("docs/databases/connections/athena.md", () => {
+ throw new Error("Failed to import file");
+});
+
+describe("EmbeddedEngineDocContent", () => {
+ it("renders markdown content", async () => {
+ render(<EmbeddedEngineDocContent engineKey="postgres" />);
+ expect(
+ await screen.findByText("Postgres Markdown content"),
+ ).toBeInTheDocument();
+ });
+
+ it("renders a loading state", async () => {
+ render(<EmbeddedEngineDocContent engineKey="postgres" />);
+
+ expect(screen.getByTestId("loader")).toBeInTheDocument();
+ await waitFor(() => {
+ expect(screen.queryByTestId("loader")).not.toBeInTheDocument();
+ });
+ });
+
+ it("renders an alert with error message when markdown fails to load", async () => {
+ const errorEngineKey = "athena"; // Loading this engine throws an error
+ jest.spyOn(console, "error").mockImplementationOnce(() => {});
+ render(<EmbeddedEngineDocContent engineKey={errorEngineKey} />);
+
+ expect(await screen.findByRole("alert")).toBeInTheDocument();
+ expect(
+ screen.getByText("Failed to load detailed documentation"),
+ ).toBeInTheDocument();
+ expect(console.error).toHaveBeenCalled();
+ });
+});
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/MarkdownLink.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/MarkdownLink.tsx
new file mode 100644
index 00000000000..00f0bf15f27
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/MarkdownLink.tsx
@@ -0,0 +1,27 @@
+import type { ComponentProps } from "react";
+import { Link } from "react-router";
+
+import CS from "metabase/css/core/index.css";
+import { useSelector } from "metabase/lib/redux";
+import { getDocsUrl } from "metabase/selectors/settings";
+import type { State } from "metabase-types/store";
+
+export const MarkdownLink = ({ href, children }: ComponentProps<"a">) => {
+ const parsedUrl = useSelector((state) => getParsedMDLinkUrl(state, href));
+
+ return (
+ <Link to={parsedUrl} className={CS.link} target="_blank">
+ {children}
+ </Link>
+ );
+};
+
+const getParsedMDLinkUrl = (state: State, href?: string) => {
+ if (href?.includes(".md") && !href?.startsWith("http")) {
+ const relativeDocPath = href.replace(".md", "");
+ const finalPath = `databases/connections/${relativeDocPath}`;
+ return getDocsUrl(state, { page: finalPath });
+ }
+
+ return href || "";
+};
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/MarkdownLink.unit.spec.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/MarkdownLink.unit.spec.tsx
new file mode 100644
index 00000000000..886829012f6
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/MarkdownLink.unit.spec.tsx
@@ -0,0 +1,57 @@
+import type { ReactNode } from "react";
+import { Route } from "react-router";
+
+import { renderWithProviders, screen } from "__support__/ui";
+import { createMockVersion } from "metabase-types/api/mocks";
+import {
+ createMockSettingsState,
+ createMockState,
+} from "metabase-types/store/mocks";
+
+import { MarkdownLink } from "./MarkdownLink";
+
+interface SetupProps {
+ href: string;
+ children: ReactNode;
+}
+
+const setup = ({ href, children }: SetupProps) => {
+ const storeInitialState = createMockState({
+ settings: createMockSettingsState({
+ "show-metabase-links": true,
+ version: createMockVersion({ tag: "v0.1" }),
+ }),
+ });
+ return renderWithProviders(
+ <Route
+ component={() => <MarkdownLink href={href}>{children}</MarkdownLink>}
+ path="/"
+ />,
+ {
+ initialRoute: "/",
+ withRouter: true,
+ storeInitialState,
+ },
+ );
+};
+
+describe("MarkdownLink", () => {
+ it("should render a link", () => {
+ setup({ href: "https://metabase.com", children: "Metabase Link" });
+ expect(
+ screen.getByRole("link", { name: "Metabase Link" }),
+ ).toBeInTheDocument();
+ expect(screen.getByRole("link", { name: "Metabase Link" })).toHaveAttribute(
+ "href",
+ "https://metabase.com",
+ );
+ });
+
+ it("should transform relative .md file links into external doc links", () => {
+ setup({ href: "../../another-file.md", children: "Metabase Link" });
+ expect(screen.getByRole("link", { name: "Metabase Link" })).toHaveAttribute(
+ "href",
+ "https://www.metabase.com/docs/v0.1/databases/connections/../../another-file.html",
+ );
+ });
+});
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/constants.ts b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/constants.ts
new file mode 100644
index 00000000000..a5392f3d879
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/constants.ts
@@ -0,0 +1,25 @@
+import type { EngineKey } from "metabase-types/api";
+
+/**
+ * Maps engine key to the markdown file in docs/databases/connections/
+ */
+export const ENGINE_DOC_MAP: Partial<Record<EngineKey, string>> = {
+ athena: "athena",
+ "bigquery-cloud-sdk": "bigquery",
+ clickhouse: "clickhouse",
+ databricks: "databricks",
+ "druid-jdbc": "druid",
+ druid: "druid",
+ mongo: "mongodb",
+ mysql: "mysql",
+ oracle: "oracle",
+ postgres: "postgresql",
+ "presto-jdbc": "presto",
+ redshift: "redshift",
+ snowflake: "snowflake",
+ sparksql: "sparksql",
+ sqlite: "sqlite",
+ sqlserver: "sql-server",
+ starburst: "starburst",
+ vertica: "vertica",
+};
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/index.ts b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/index.ts
new file mode 100644
index 00000000000..b7e956828ab
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/index.ts
@@ -0,0 +1,2 @@
+export { EmbeddedEngineDocContent } from "./EmbeddedEngineDocContent";
+export { ENGINE_DOC_MAP } from "./constants";
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/markdown-utils.ts b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/markdown-utils.ts
new file mode 100644
index 00000000000..6ca7b18da2d
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/markdown-utils.ts
@@ -0,0 +1,50 @@
+/**
+ * Hides elements rendered from the markdown doc that we don't want to show in the side panel.
+ * These include h1 and other introductory elements, as well as jekyll template includes.
+ */
+export const hideUnnecessaryElements = (element: HTMLElement | null) => {
+ if (!element) {
+ return;
+ }
+
+ hideIntroductoryElements(element);
+ hideJekyllTemplateIncludes(element);
+};
+
+const hideJekyllTemplateIncludes = (element: HTMLElement) => {
+ // Hide elements matching template includes (we can't parse them from the app)
+ element.querySelectorAll("p").forEach((element) => {
+ // Check if the element's text content contains "{%" and it has no child elements
+ if (element.textContent?.includes("{%") && element.children.length === 0) {
+ (element as HTMLElement).style.display = "none";
+ }
+ });
+};
+
+const hideIntroductoryElements = (element: HTMLElement) => {
+ // Hide initial elements, like title and heading (they are redundant in this context)
+ const h1Element = element.querySelector("h1");
+
+ if (h1Element) {
+ h1Element.style.display = "none";
+
+ // Hide everything before the h1
+ let prevSibling = h1Element.previousElementSibling as HTMLElement;
+
+ while (prevSibling) {
+ prevSibling.style.display = "none";
+ prevSibling = prevSibling.previousElementSibling as HTMLElement;
+ }
+
+ // Hide blockquote and p elements after the h1 (and before the next heading)
+ let nextSibling = h1Element.nextElementSibling as HTMLElement;
+
+ while (
+ nextSibling?.tagName === "BLOCKQUOTE" ||
+ nextSibling?.tagName === "P"
+ ) {
+ nextSibling.style.display = "none";
+ nextSibling = nextSibling.nextElementSibling as HTMLElement;
+ }
+ }
+};
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/markdown-utils.unit.spec.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/markdown-utils.unit.spec.tsx
new file mode 100644
index 00000000000..d89a47b188a
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/markdown-utils.unit.spec.tsx
@@ -0,0 +1,41 @@
+import { render, screen } from "__support__/ui";
+import Markdown from "metabase/common/components/Markdown";
+
+import { hideUnnecessaryElements } from "./markdown-utils";
+
+describe("EmbeddedEngineDocContent/utils", () => {
+ describe("hideUnnecessaryElements", () => {
+ it("should hide h1 and elements immediately below it", () => {
+ const testMDContent =
+ "# This is an H1 element \n\n" +
+ "This is some text after the H1 element \n\n" +
+ "> This is a blockquote after the H1 element\n\n" +
+ "## This is an H2 element\n\n" +
+ "This is some text after the H2 element\n\n" +
+ "{% This is a template include %}\n\n" +
+ "This is some text after the template include";
+
+ const { container } = render(
+ <Markdown data-testid="markdown">{testMDContent}</Markdown>,
+ );
+ hideUnnecessaryElements(container);
+ expect(screen.getByText(/This is an H1 element/)).not.toBeVisible();
+ expect(
+ screen.getByText(/This is some text after the H1 element/),
+ ).not.toBeVisible();
+ expect(
+ screen.getByText(/This is a blockquote after the H1 element/),
+ ).not.toBeVisible();
+ expect(screen.getByText(/This is a template include/)).not.toBeVisible();
+
+ // Other elements should be visible
+ expect(screen.getByText(/This is an H2 element/)).toBeVisible();
+ expect(
+ screen.getByText(/This is some text after the H2 element/),
+ ).toBeVisible();
+ expect(
+ screen.getByText(/This is some text after the template include/),
+ ).toBeVisible();
+ });
+ });
+});
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/useEngineDocMarkdownContent.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/useEngineDocMarkdownContent.tsx
new file mode 100644
index 00000000000..c40fce9cd60
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/useEngineDocMarkdownContent.tsx
@@ -0,0 +1,44 @@
+import { useEffect, useState } from "react";
+import { t } from "ttag";
+
+import type { EngineKey } from "metabase-types/api";
+
+import { ENGINE_DOC_MAP } from "./constants";
+
+export const useEngineDocMarkdownContent = (engineKey: EngineKey) => {
+ const [markdownContent, setMarkdownContent] = useState<string>();
+ const [loadingError, setLoadingError] = useState<string>();
+ const [isLoading, setIsLoading] = useState<boolean>(false);
+
+ useEffect(() => {
+ const docFileName = ENGINE_DOC_MAP[engineKey];
+
+ if (!docFileName) {
+ setMarkdownContent(undefined);
+ setLoadingError(t`Failed to load detailed documentation`);
+ return;
+ }
+
+ setIsLoading(true);
+ setLoadingError(undefined);
+
+ import(`docs/databases/connections/${docFileName}.md`)
+ .then((result: { default: string }) => {
+ setMarkdownContent(result.default);
+ })
+ .catch((err) => {
+ setMarkdownContent(undefined);
+ setLoadingError(t`Failed to load detailed documentation`);
+ console.error(
+ "Failed to load documentation for engine:",
+ engineKey,
+ err,
+ );
+ })
+ .finally(() => {
+ setIsLoading(false);
+ });
+ }, [engineKey]);
+
+ return { markdownContent, loadingError, isLoading };
+};
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/useEngineDocMarkdownContent.unit.spec.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/useEngineDocMarkdownContent.unit.spec.tsx
new file mode 100644
index 00000000000..e830334b358
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/EmbeddedEngineDocContent/useEngineDocMarkdownContent.unit.spec.tsx
@@ -0,0 +1,88 @@
+import { renderHook, waitFor } from "@testing-library/react";
+
+import type { EngineKey } from "metabase-types/api";
+
+import { useEngineDocMarkdownContent } from "./useEngineDocMarkdownContent";
+
+jest.mock("docs/databases/connections/postgresql.md", () => "# Postgres doc");
+jest.mock("docs/databases/connections/athena.md", () => {
+ throw new Error("Failed to import file");
+});
+
+describe("useEngineDocMarkdownContent", () => {
+ beforeEach(() => {
+ jest.spyOn(console, "error").mockImplementation(() => {});
+ });
+
+ describe("when markdown content loads successfully", () => {
+ it("should return the markdownContent", async () => {
+ const { result } = renderHook(() =>
+ useEngineDocMarkdownContent("postgres"),
+ );
+ await waitFor(() => {
+ expect(result.current.markdownContent).toBeDefined();
+ });
+
+ expect(result.current.markdownContent).toContain("# Postgres doc");
+ expect(result.current.loadingError).toBeUndefined();
+ });
+
+ it("should handle loading state", async () => {
+ const { result } = renderHook(() =>
+ useEngineDocMarkdownContent("postgres"),
+ );
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => {
+ expect(result.current.markdownContent).toBeDefined();
+ });
+ expect(result.current.isLoading).toBe(false);
+ });
+ });
+
+ describe("when markdown content fails to load", () => {
+ it("should set loadingError and return undefined markdownContent", async () => {
+ const { result } = renderHook(() =>
+ useEngineDocMarkdownContent("invalid-engine" as EngineKey),
+ );
+ await waitFor(() => {
+ expect(result.current.loadingError).toBe(
+ "Failed to load detailed documentation",
+ );
+ });
+
+ expect(result.current.markdownContent).toBeUndefined();
+ });
+
+ it("calls console.error when engine key is valid but import fails", async () => {
+ const consoleErrorMock = jest.spyOn(console, "error");
+ const { result } = renderHook(() =>
+ useEngineDocMarkdownContent("athena"),
+ );
+ await waitFor(() => {
+ expect(result.current.loadingError).toBe(
+ "Failed to load detailed documentation",
+ );
+ });
+
+ expect(consoleErrorMock).toHaveBeenCalledWith(
+ "Failed to load documentation for engine:",
+ "athena",
+ expect.any(Error),
+ );
+ expect(result.current.markdownContent).toBeUndefined();
+ });
+
+ it("should handle loading state", async () => {
+ const { result } = renderHook(() =>
+ useEngineDocMarkdownContent("athena" as EngineKey),
+ );
+ expect(result.current.isLoading).toBe(true);
+ await waitFor(() => {
+ expect(result.current.loadingError).toBe(
+ "Failed to load detailed documentation",
+ );
+ });
+ expect(result.current.isLoading).toBe(false);
+ });
+ });
+});
diff --git a/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/index.tsx b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/index.tsx
new file mode 100644
index 00000000000..67bc1713e2d
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/components/DatabaseHelpSidePanel/index.tsx
@@ -0,0 +1,2 @@
+export { DatabaseHelpSidePanel } from "./DatabaseHelpSidePanel";
+export { ENGINE_DOC_MAP } from "./EmbeddedEngineDocContent";
diff --git a/frontend/src/metabase/admin/databases/containers/DatabasePage.tsx b/frontend/src/metabase/admin/databases/containers/DatabasePage.tsx
index 226d024f544..9b3db1c6396 100644
--- a/frontend/src/metabase/admin/databases/containers/DatabasePage.tsx
+++ b/frontend/src/metabase/admin/databases/containers/DatabasePage.tsx
@@ -1,45 +1,128 @@
+import { useDisclosure } from "@mantine/hooks";
+import { useEffect, useState } from "react";
import type { Route } from "react-router";
+import { t } from "ttag";
-import { Box, Title } from "metabase/ui";
+import { getEngines } from "metabase/databases/selectors";
+import { useSelector } from "metabase/lib/redux";
+import {
+ Box,
+ Button,
+ Divider,
+ Flex,
+ Icon,
+ ScrollArea,
+ Text,
+ Title,
+} from "metabase/ui";
+import type { EngineKey } from "metabase-types/api";
import { DatabaseEditConnectionForm } from "../components/DatabaseEditConnectionForm";
+import {
+ DatabaseHelpSidePanel,
+ ENGINE_DOC_MAP,
+} from "../components/DatabaseHelpSidePanel";
import { useDatabaseConnection } from "../hooks/use-database-connection";
+import { trackHelpButtonClick } from "./analytics";
+
interface DatabasePageProps {
params: { databaseId: string };
route: Route;
}
export function DatabasePage({ params, route }: DatabasePageProps) {
+ const engines = useSelector(getEngines);
const { database, databaseReq, handleCancel, handleOnSubmit, title, config } =
- useDatabaseConnection({ databaseId: params.databaseId });
+ useDatabaseConnection({ databaseId: params.databaseId, engines });
+ const [showSidePanel, { open: openSidePanel, close: closeSidePanel }] =
+ useDisclosure(false);
+ const [selectedEngineKey, setSelectedEngineKey] = useState<EngineKey>(
+ database?.engine as EngineKey,
+ );
+ const helpContentsExist =
+ !!selectedEngineKey && !!ENGINE_DOC_MAP[selectedEngineKey];
+
+ const onEngineChange = (engineKey?: string) => {
+ setSelectedEngineKey(engineKey as EngineKey);
+ };
+
+ useEffect(() => {
+ if (!helpContentsExist) {
+ closeSidePanel();
+ }
+ }, [closeSidePanel, helpContentsExist]);
+
+ const onHelpButtonClick = () => {
+ if (!showSidePanel) {
+ openSidePanel();
+ trackHelpButtonClick();
+ }
+ };
return (
- <Box
- w="100%"
- maw={{
- base: `calc(28.5rem + 2rem)`,
- md: `calc(28.5rem + 4rem)`,
- }}
- mx="auto"
- p={{
- base: `md`,
- md: `xl`,
- }}
- >
- <Title order={1} mb="lg">
- {title}
- </Title>
- <DatabaseEditConnectionForm
- database={database}
- isAttachedDWH={database?.is_attached_dwh ?? false}
- initializeError={databaseReq.error}
- onSubmitted={handleOnSubmit}
- route={route}
- onCancel={handleCancel}
- config={config}
- formLocation="full-page"
- />
- </Box>
+ <Flex direction="row" h="100%">
+ <Box h="100%" w="100%" component={ScrollArea}>
+ <Box
+ w="100%"
+ maw={{
+ base: `calc(28.5rem + 2rem)`,
+ md: `calc(28.5rem + 4rem)`,
+ }}
+ mx="auto"
+ p={{
+ base: `md`,
+ md: `xl`,
+ }}
+ >
+ <Flex
+ mb="lg"
+ align="center"
+ justify="space-between"
+ wrap="wrap"
+ columnGap="lg"
+ >
+ <Title order={1} fz="h2">
+ {title}
+ </Title>
+ {helpContentsExist && (
+ <Text>
+ {t`Need a hand?`}{" "}
+ <Button
+ h="auto"
+ onClick={onHelpButtonClick}
+ p={0}
+ style={{ verticalAlign: "baseline" }}
+ variant="subtle"
+ >
+ {t`Help is here`}
+ <Icon name="chevronright" size={12} ml="xs" />
+ </Button>
+ </Text>
+ )}
+ </Flex>
+ <DatabaseEditConnectionForm
+ database={database}
+ isAttachedDWH={database?.is_attached_dwh ?? false}
+ initializeError={databaseReq.error}
+ onSubmitted={handleOnSubmit}
+ route={route}
+ onCancel={handleCancel}
+ config={config}
+ formLocation="full-page"
+ onEngineChange={onEngineChange}
+ />
+ </Box>
+ </Box>
+ {showSidePanel && (
+ <>
+ <Divider orientation="vertical" h="100%" />
+ <DatabaseHelpSidePanel
+ engineKey={selectedEngineKey}
+ onClose={closeSidePanel}
+ />
+ </>
+ )}
+ </Flex>
);
}
diff --git a/frontend/src/metabase/admin/databases/containers/DatabasePage.unit.spec.tsx b/frontend/src/metabase/admin/databases/containers/DatabasePage.unit.spec.tsx
new file mode 100644
index 00000000000..5e3e6e50180
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/containers/DatabasePage.unit.spec.tsx
@@ -0,0 +1,49 @@
+import { waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Route } from "react-router";
+
+import { mockSettings } from "__support__/settings";
+import { renderWithProviders, screen } from "__support__/ui";
+import { createMockEngines } from "metabase-types/api/mocks";
+import { createMockState } from "metabase-types/store/mocks";
+
+import { DatabasePage } from "./DatabasePage";
+
+jest.mock(
+ "docs/databases/connections/postgresql.md",
+ () => "Postgres MD Content",
+);
+
+const setup = () => {
+ renderWithProviders(<Route path="/" component={DatabasePage} />, {
+ withRouter: true,
+ storeInitialState: createMockState({
+ settings: mockSettings({
+ engines: createMockEngines(),
+ }),
+ }),
+ });
+};
+
+describe("DatabasePage", () => {
+ describe("Help button", () => {
+ it("should render the 'Help is here' button", () => {
+ setup();
+ expect(
+ screen.getByRole("button", { name: /Help is here/ }),
+ ).toBeInTheDocument();
+ });
+
+ it("should show the side panel when 'Help is here' button is clicked", async () => {
+ setup();
+ await userEvent.click(
+ screen.getByRole("button", { name: /Help is here/ }),
+ );
+ await waitFor(() => {
+ expect(
+ screen.getByTestId("database-help-side-panel"),
+ ).toBeInTheDocument();
+ });
+ });
+ });
+});
diff --git a/frontend/src/metabase/admin/databases/containers/analytics.ts b/frontend/src/metabase/admin/databases/containers/analytics.ts
new file mode 100644
index 00000000000..71e64a80cae
--- /dev/null
+++ b/frontend/src/metabase/admin/databases/containers/analytics.ts
@@ -0,0 +1,8 @@
+import { trackSimpleEvent } from "metabase/lib/analytics";
+
+export const trackHelpButtonClick = () => {
+ trackSimpleEvent({
+ event: "database_help_clicked",
+ triggered_from: "admin",
+ });
+};
diff --git a/frontend/src/metabase/admin/databases/hooks/use-database-connection.ts b/frontend/src/metabase/admin/databases/hooks/use-database-connection.ts
index 5c9b5d42ad2..a581cfde364 100644
--- a/frontend/src/metabase/admin/databases/hooks/use-database-connection.ts
+++ b/frontend/src/metabase/admin/databases/hooks/use-database-connection.ts
@@ -2,20 +2,24 @@ import { push } from "react-router-redux";
import { t } from "ttag";
import { skipToken, useGetDatabaseQuery } from "metabase/api";
+import { getDefaultEngineKey } from "metabase/databases/utils/engine";
import { useDispatch } from "metabase/lib/redux";
import { PLUGIN_DB_ROUTING } from "metabase/plugins";
-import type { DatabaseId } from "metabase-types/api";
+import type { DatabaseId, Engine, EngineKey } from "metabase-types/api";
interface UseDatabaseConnectionProps {
databaseId?: string;
+ engines?: Record<EngineKey, Engine>;
}
export const useDatabaseConnection = ({
databaseId,
+ engines,
}: UseDatabaseConnectionProps) => {
const dispatch = useDispatch();
const queryParams = new URLSearchParams(location.search);
- const preselectedEngine = queryParams.get("engine") ?? undefined;
+ const preselectedEngine =
+ queryParams.get("engine") ?? getDefaultEngineKey(engines || {});
const addingNewDatabase = databaseId === undefined;
const databaseReq = useGetDatabaseQuery(
diff --git a/frontend/src/metabase/common/utils/help-url.ts b/frontend/src/metabase/common/utils/help-url.ts
new file mode 100644
index 00000000000..52935f43309
--- /dev/null
+++ b/frontend/src/metabase/common/utils/help-url.ts
@@ -0,0 +1,15 @@
+export const getHelpUrl = (
+ premium: boolean,
+ versionTag: string = "latest",
+ diag?: string,
+) => {
+ let helpUrl = premium
+ ? `https://www.metabase.com/help-premium?utm_source=in-product&utm_medium=menu&utm_campaign=help&instance_version=${versionTag}`
+ : `https://www.metabase.com/help?utm_source=in-product&utm_medium=menu&utm_campaign=help&instance_version=${versionTag}`;
+
+ if (diag) {
+ helpUrl += `&diag=${diag}`;
+ }
+
+ return helpUrl;
+};
diff --git a/frontend/src/metabase/databases/components/DatabaseConnectionUri/engines-config.ts b/frontend/src/metabase/databases/components/DatabaseConnectionUri/engines-config.ts
index 060649eb1ac..14902913d1c 100644
--- a/frontend/src/metabase/databases/components/DatabaseConnectionUri/engines-config.ts
+++ b/frontend/src/metabase/databases/components/DatabaseConnectionUri/engines-config.ts
@@ -1,6 +1,6 @@
import type { EngineKey } from "metabase-types/api/settings";
-type Placeholder = string;
+type Placeholder = string | undefined;
export const enginesConfig: Record<EngineKey, Placeholder> = {
athena: "jdbc:athena://WorkGroup=primary;Region=us-east-1;",
@@ -13,6 +13,7 @@ export const enginesConfig: Record<EngineKey, Placeholder> = {
"jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/;transparent_reconnection=true",
databricks:
"jdbc:databricks://127.0.0.1:8123;httpPath=/sql/1.0/endpoints/abc;OAuthSecret=1234567890;OAuth2ClientId=xyz",
+ mongo: undefined,
mysql: "jdbc:mysql://user:pass@host:3306/dbname?ssl=true",
oracle:
"jdbc:oracle:thin:@mydbhost:1521/mydbservice?ssl_server_cert_dn=ServerDN",
diff --git a/frontend/src/metabase/databases/components/DatabaseConnectionUri/parse-connection-regex.ts b/frontend/src/metabase/databases/components/DatabaseConnectionUri/parse-connection-regex.ts
index 1f7abf6063f..6c576bc4833 100644
--- a/frontend/src/metabase/databases/components/DatabaseConnectionUri/parse-connection-regex.ts
+++ b/frontend/src/metabase/databases/components/DatabaseConnectionUri/parse-connection-regex.ts
@@ -30,7 +30,10 @@ const druidRegex = new RegExp(
"i",
);
-const connectionStringRegexes: Record<EngineKey, RegExp | RegExp[]> = {
+const connectionStringRegexes: Record<
+ EngineKey,
+ RegExp | RegExp[] | undefined
+> = {
athena: new RegExp(
"^" +
jdbcPrefix +
@@ -83,6 +86,7 @@ const connectionStringRegexes: Record<EngineKey, RegExp | RegExp[]> = {
),
druid: druidRegex,
"druid-jdbc": druidRegex,
+ mongo: undefined,
mysql: new RegExp(
"^" +
jdbcPrefix +
diff --git a/frontend/src/metabase/home/components/Onboarding/tests/premium.unit.spec.tsx b/frontend/src/metabase/home/components/Onboarding/tests/premium.unit.spec.tsx
index 6c391ea1275..e494a957297 100644
--- a/frontend/src/metabase/home/components/Onboarding/tests/premium.unit.spec.tsx
+++ b/frontend/src/metabase/home/components/Onboarding/tests/premium.unit.spec.tsx
@@ -87,7 +87,7 @@ describe("Onboarding (EE with token)", () => {
expect(helpSection).toBeInTheDocument();
expect(within(helpSection).getByRole("link")).toHaveAttribute(
"href",
- "https://www.metabase.com/help-premium?utm_source=in-product&utm_medium=menu&utm_campaign=help&instance_version=v1&diag=null",
+ "https://www.metabase.com/help-premium?utm_source=in-product&utm_medium=menu&utm_campaign=help&instance_version=v1",
);
expect(
within(helpSection).getByRole("button", { name: "Get Help" }),
diff --git a/frontend/src/metabase/nav/components/ProfileLink/useHelpLink.ts b/frontend/src/metabase/nav/components/ProfileLink/useHelpLink.ts
index 37de9d77987..d3dc9c397a3 100644
--- a/frontend/src/metabase/nav/components/ProfileLink/useHelpLink.ts
+++ b/frontend/src/metabase/nav/components/ProfileLink/useHelpLink.ts
@@ -1,6 +1,7 @@
import { useEffect, useState } from "react";
import { useSetting } from "metabase/common/hooks";
+import { getHelpUrl } from "metabase/common/utils/help-url";
import { useSelector } from "metabase/lib/redux";
import { getIsPaidPlan } from "metabase/selectors/settings";
import { UtilApi } from "metabase/services";
@@ -14,13 +15,13 @@ export const useHelpLink = (): { visible: boolean; href: string } => {
);
const [bugReportDetails, setBugReportDetails] = useState(null);
const user = useSelector(getUser);
- const isAdmin = user?.is_superuser;
+ const isAdmin = !!user?.is_superuser;
const isPaidPlan = useSelector(getIsPaidPlan);
const version = useSetting("version");
- const compactBugReportDetailsForUrl = encodeURIComponent(
- JSON.stringify(bugReportDetails),
- );
+ const compactBugReportDetailsForUrl = bugReportDetails
+ ? encodeURIComponent(JSON.stringify(bugReportDetails))
+ : undefined;
useEffect(() => {
if (isAdmin && isPaidPlan) {
@@ -29,12 +30,15 @@ export const useHelpLink = (): { visible: boolean; href: string } => {
}, [isAdmin, isPaidPlan]);
const visible = helpLinkSetting !== "hidden";
+ const showPremiumHelp = isAdmin && isPaidPlan;
const href =
helpLinkSetting === "custom"
? helpLinkCustomDestinationSetting
- : isAdmin && isPaidPlan
- ? `https://www.metabase.com/help-premium?utm_source=in-product&utm_medium=menu&utm_campaign=help&instance_version=${version.tag}&diag=${compactBugReportDetailsForUrl}`
- : `https://www.metabase.com/help?utm_source=in-product&utm_medium=menu&utm_campaign=help&instance_version=${version.tag}`;
+ : getHelpUrl(
+ showPremiumHelp,
+ version.tag,
+ showPremiumHelp ? compactBugReportDetailsForUrl : undefined,
+ );
return { visible, href };
};
diff --git a/frontend/src/metabase/nav/components/ProfileLink/useHelpLink.unit.spec.ts b/frontend/src/metabase/nav/components/ProfileLink/useHelpLink.unit.spec.ts
new file mode 100644
index 00000000000..0da894ccb21
--- /dev/null
+++ b/frontend/src/metabase/nav/components/ProfileLink/useHelpLink.unit.spec.ts
@@ -0,0 +1,83 @@
+import fetchMock from "fetch-mock";
+
+import { mockSettings } from "__support__/settings";
+import { renderHookWithProviders, waitFor } from "__support__/ui";
+import type { HelpLinkSetting } from "metabase-types/api";
+import {
+ createMockTokenStatus,
+ createMockUser,
+ createMockVersion,
+} from "metabase-types/api/mocks";
+import { createMockState } from "metabase-types/store/mocks";
+
+import { useHelpLink } from "./useHelpLink";
+
+interface SetupOptions {
+ customLinkDestination?: string;
+ helpLinkSetting?: HelpLinkSetting;
+ isAdmin?: boolean;
+ isPaidPlan?: boolean;
+}
+
+const setup = (opts?: SetupOptions) => {
+ const { isPaidPlan, customLinkDestination, helpLinkSetting, isAdmin } =
+ opts || {};
+ const storeInitialState = createMockState({
+ currentUser: createMockUser({ is_superuser: !!isAdmin }),
+ settings: mockSettings({
+ "token-status": isPaidPlan
+ ? createMockTokenStatus({ valid: true })
+ : undefined,
+ version: createMockVersion({ tag: "0.2" }),
+ "help-link-custom-destination": customLinkDestination || undefined,
+ "help-link": helpLinkSetting,
+ }),
+ });
+ return renderHookWithProviders(() => useHelpLink(), {
+ storeInitialState,
+ });
+};
+
+const defaultHelpLink =
+ "https://www.metabase.com/help?utm_source=in-product&utm_medium=menu&utm_campaign=help&instance_version=0.2";
+const premiumHelpLink =
+ "https://www.metabase.com/help-premium?utm_source=in-product&utm_medium=menu&utm_campaign=help&instance_version=0.2";
+
+describe("useHelpLink", () => {
+ beforeEach(() => {
+ fetchMock.get("path:/api/bug-reporting/details", "");
+ });
+
+ describe("metabase help link", () => {
+ it.each`
+ isAdmin | isPaidPlan | expectedLink
+ ${true} | ${true} | ${premiumHelpLink}
+ ${true} | ${false} | ${defaultHelpLink}
+ ${false} | ${true} | ${defaultHelpLink}
+ ${false} | ${false} | ${defaultHelpLink}
+ `(
+ "should return correct link when isAdmin=$isAdmin and isPaidPlan=$isPaidPlan",
+ async ({ isAdmin, isPaidPlan, expectedLink }) => {
+ const { result } = setup({ isAdmin, isPaidPlan });
+ await waitFor(() => {
+ expect(result.current?.href).toBe(expectedLink);
+ });
+ expect(result.current?.visible).toBe(true);
+ },
+ );
+ });
+
+ it("should return visible=false when helpLinkSetting is 'hidden'", () => {
+ const { result } = setup({ helpLinkSetting: "hidden" });
+ expect(result.current.visible).toBe(false);
+ });
+
+ it("should return a custom link when the setting is custom", () => {
+ const { result } = setup({
+ customLinkDestination: "https://custom-destination.com/help",
+ helpLinkSetting: "custom",
+ });
+ expect(result.current.href).toBe("https://custom-destination.com/help");
+ expect(result.current.visible).toBe(true);
+ });
+});
diff --git a/frontend/src/types/markdown.d.ts b/frontend/src/types/markdown.d.ts
new file mode 100644
index 00000000000..f8c8012b38a
--- /dev/null
+++ b/frontend/src/types/markdown.d.ts
@@ -0,0 +1,5 @@
+declare module "*.md" {
+ const content: string;
+ // eslint-disable-next-line import/no-default-export
+ export default content;
+}
diff --git a/jest.config.js b/jest.config.js
index 26f9215aab8..8f593fb3c08 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -62,6 +62,7 @@ const baseConfig = {
* As we use SDK components in new iframe embedding, we need to import them here.
**/
"sdk-specific-imports": "<rootDir>/frontend/src/metabase/lib/noop.js",
+ "docs/(.*)$": "<rootDir>/docs/$1",
},
transformIgnorePatterns: [
`<rootDir>/node_modules/(?!(${esmPackages.join("|")})/)`,
diff --git a/rspack.main.config.js b/rspack.main.config.js
index ef993fe7a29..ba1d8b17a1f 100644
--- a/rspack.main.config.js
+++ b/rspack.main.config.js
@@ -22,6 +22,7 @@ const {
const ASSETS_PATH = __dirname + "/resources/frontend_client/app/assets";
const FONTS_PATH = __dirname + "/resources/frontend_client/app/fonts";
+const DOCS_PATH = __dirname + "/docs";
const FRONTEND_BUILD_CONFIGS_PATH = __dirname + "/frontend/build";
const SRC_PATH = __dirname + "/frontend/src/metabase";
const LIB_SRC_PATH = __dirname + "/frontend/src/metabase-lib";
@@ -177,6 +178,10 @@ const config = {
enforce: "pre",
use: ["source-map-loader"],
},
+ {
+ test: /\.md/,
+ type: "asset/source",
+ },
{
test: /\.svg/,
type: "asset/source",
@@ -212,6 +217,7 @@ const config = {
"build-configs": FRONTEND_BUILD_CONFIGS_PATH,
assets: ASSETS_PATH,
fonts: FONTS_PATH,
+ docs: DOCS_PATH,
metabase: SRC_PATH,
"metabase-lib": LIB_SRC_PATH,
"metabase-enterprise": ENTERPRISE_SRC_PATH,
diff --git a/tsconfig.json b/tsconfig.json
index 80b7252e4de..624a5985110 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -12,7 +12,8 @@
"./enterprise/frontend/test/*"
],
"build-configs/*": ["./frontend/build/*"],
- "cljs/*": ["./target/cljs_dev/*"]
+ "cljs/*": ["./target/cljs_dev/*"],
+ "docs/*": ["./docs/*"]
},
"plugins": [
{