Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

feat: new guide (#20943)

ecmadaob7fdc58211b2
diff --git a/frontend/src/app/layouts/BodyLayout.tsx b/frontend/src/app/layouts/BodyLayout.tsx
index f6a86cca57..7f0a641c94 100644
--- a/frontend/src/app/layouts/BodyLayout.tsx
+++ b/frontend/src/app/layouts/BodyLayout.tsx
@@ -12,6 +12,8 @@ import { DashboardSidebar } from "@/components/DashboardSidebar";
import { ProjectSidebar } from "@/components/ProjectSidebar";
import { Quickstart } from "@/components/Quickstart";
import { RoutePermissionGuardShell } from "@/components/RoutePermissionGuardShell";
+import { WorkspaceSetupGuide } from "@/components/WorkspaceSetupGuide";
+import { useAppStore } from "@/stores/app";
// Ported from `src/layouts/BodyLayout.vue`. Mounts the workspace
// `DashboardBodyShell` (header + sidebar slot + body slot) and portals the
@@ -36,6 +38,7 @@ export function BodyLayout() {
// Workspace "My Issues" is a standalone full-width page: header (with logo)
// but no sidebar, mirroring the Vue IssuesRouteShell (variant="issues").
const isMyIssues = currentRouteName === WORKSPACE_ROUTE_MY_ISSUES;
+ const isSaaSMode = useAppStore((s) => s.isSaaSMode());
// Project-scoped routes (`workspace.project.*`) get the project sidebar; the
// bare projects list (`workspace.project`) keeps the workspace sidebar.
const isProjectRoute = Boolean(
@@ -116,7 +119,10 @@ export function BodyLayout() {
: null}
{targets.quickstart
- ? createPortal(<Quickstart />, targets.quickstart)
+ ? createPortal(
+ isSaaSMode ? <WorkspaceSetupGuide /> : <Quickstart />,
+ targets.quickstart
+ )
: null}
</>
);
diff --git a/frontend/src/components/WorkspaceSetupGuide.test.tsx b/frontend/src/components/WorkspaceSetupGuide.test.tsx
new file mode 100644
index 0000000000..b01a141af3
--- /dev/null
+++ b/frontend/src/components/WorkspaceSetupGuide.test.tsx
@@ -0,0 +1,1084 @@
+import type { ReactElement, ReactNode } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mocks = vi.hoisted(() => ({
+ isSaaSMode: vi.fn(() => true),
+ projectsByName: {} as Record<string, unknown>,
+ instancesByName: {} as Record<string, unknown>,
+ databasesByName: {} as Record<string, unknown>,
+ fetchProjectList: vi.fn(async () => ({
+ projects: [] as unknown[],
+ nextPageToken: "",
+ })),
+ fetchInstanceList: vi.fn(async () => ({
+ instances: [] as unknown[],
+ nextPageToken: "",
+ })),
+ fetchDatabases: vi.fn(async (_?: { parent?: string }) => ({
+ databases: [] as unknown[],
+ nextPageToken: "",
+ })),
+ introState: {} as Record<string, boolean>,
+ getIntroStateByKey: vi.fn((_key: string) => false),
+ saveIntroStateByKey: vi.fn(
+ (_: { key: string; newState: boolean }) => undefined
+ ),
+ introStateVersion: 0,
+ searchQueryHistories: vi.fn(async () => ({
+ queryHistories: [] as unknown[],
+ nextPageToken: "",
+ })),
+ workspacePolicy: {
+ bindings: [{ role: "roles/workspaceAdmin", members: ["[email protected]"] }],
+ },
+ hasWorkspacePermissionV2: vi.fn(() => true),
+ preCreateIssue: vi.fn(),
+ currentRoute: { name: "workspace.home" } as { name?: string },
+ routerPush: vi.fn(),
+ defaultProjectName: "projects/default",
+}));
+
+const dismissedIntroStateKey = "workspace-setup-guide.dismissed";
+
+vi.mock("react-i18next", () => ({
+ initReactI18next: { type: "3rdParty", init: () => {} },
+ useTranslation: () => ({
+ t: (key: string) => key,
+ }),
+}));
+
+vi.mock("@/components/RouterLink", () => ({
+ RouterLink: ({
+ children,
+ to,
+ ...props
+ }: {
+ children: ReactNode;
+ to: {
+ name?: string;
+ params?: Record<string, string>;
+ query?: Record<string, string>;
+ hash?: string;
+ };
+ }) => (
+ <a
+ data-route-name={to.name}
+ data-route-params={JSON.stringify(to.params ?? {})}
+ data-query={to.query?.intro}
+ data-query-project={to.query?.project}
+ data-hash={to.hash}
+ {...props}
+ >
+ {children}
+ </a>
+ ),
+}));
+
+vi.mock("@/app/router", () => ({
+ router: {
+ push: mocks.routerPush,
+ },
+ useCurrentRoute: () => mocks.currentRoute,
+}));
+
+vi.mock("@/stores/app", () => {
+ const getState = () => ({
+ isSaaSMode: mocks.isSaaSMode,
+ projectsByName: mocks.projectsByName,
+ instancesByName: mocks.instancesByName,
+ databasesByName: mocks.databasesByName,
+ currentUserName: "users/[email protected]",
+ currentUser: {
+ name: "users/[email protected]",
+ email: "[email protected]",
+ workspace: "workspaces/default",
+ },
+ workspace: { name: "workspaces/default" },
+ workspacePolicy: mocks.workspacePolicy,
+ serverInfo: { defaultProject: mocks.defaultProjectName },
+ introStateVersion: mocks.introStateVersion,
+ getIntroStateByKey: mocks.getIntroStateByKey,
+ });
+ const useAppStore = (selector?: (s: ReturnType<typeof getState>) => unknown) =>
+ selector ? selector(getState()) : getState();
+ useAppStore.getState = () => ({
+ ...getState(),
+ fetchProjectList: mocks.fetchProjectList,
+ fetchInstanceList: mocks.fetchInstanceList,
+ fetchDatabases: mocks.fetchDatabases,
+ saveIntroStateByKey: mocks.saveIntroStateByKey,
+ });
+ return { useAppStore };
+});
+
+vi.mock("@/api", () => ({
+ sqlServiceClientConnect: {
+ searchQueryHistories: mocks.searchQueryHistories,
+ },
+}));
+
+vi.mock("@/utils", () => ({
+ extractDatabaseResourceName: (name: string) => {
+ const match = name.match(/^instances\/([^/]+)\/databases\/([^/]+)$/);
+ return {
+ instanceName: match?.[1] ?? "",
+ databaseName: match?.[2] ?? "",
+ };
+ },
+ extractInstanceResourceName: (name: string) =>
+ name.replace(/^instances\//, ""),
+ extractProjectResourceName: (name: string) =>
+ name.replace(/^projects\//, ""),
+ hasWorkspacePermissionV2: mocks.hasWorkspacePermissionV2,
+}));
+
+vi.mock("@/lib/plan/issue", () => ({
+ preCreateIssue: mocks.preCreateIssue,
+}));
+
+import { WorkspaceSetupGuide } from "./WorkspaceSetupGuide";
+
+let container: HTMLDivElement;
+let root: ReturnType<typeof createRoot>;
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.introState = {};
+ mocks.introStateVersion = 0;
+ mocks.getIntroStateByKey.mockImplementation(
+ (key: string) => mocks.introState[key] ?? false
+ );
+ mocks.saveIntroStateByKey.mockImplementation(({ key, newState }) => {
+ mocks.introState[key] = newState;
+ mocks.introStateVersion += 1;
+ });
+ mocks.isSaaSMode.mockReturnValue(true);
+ mocks.projectsByName = {};
+ mocks.instancesByName = {};
+ mocks.databasesByName = {};
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [],
+ nextPageToken: "",
+ });
+ mocks.searchQueryHistories.mockResolvedValue({
+ queryHistories: [],
+ nextPageToken: "",
+ });
+ mocks.workspacePolicy = {
+ bindings: [{ role: "roles/workspaceAdmin", members: ["[email protected]"] }],
+ };
+ mocks.hasWorkspacePermissionV2.mockReturnValue(true);
+ mocks.currentRoute = { name: "workspace.home" };
+ mocks.defaultProjectName = "projects/default";
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+ act(() => {
+ root.unmount();
+ });
+ document.body.removeChild(container);
+});
+
+const render = async (element: ReactElement) => {
+ await act(async () => {
+ root.render(element);
+ await Promise.resolve();
+ await Promise.resolve();
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+};
+
+describe("WorkspaceSetupGuide", () => {
+ it("renders outside SaaS mode", async () => {
+ mocks.isSaaSMode.mockReturnValue(false);
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.self"
+ );
+ expect(mocks.fetchProjectList).toHaveBeenCalled();
+ });
+
+ it("shows the first incomplete setup action for SaaS workspaces", async () => {
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.self"
+ );
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.project"
+ );
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.instance"
+ );
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.database"
+ );
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.query"
+ );
+ expect(
+ container.querySelector("[data-testid='setup-step-hasInstance']")?.tagName
+ ).toBe("BUTTON");
+ expect(
+ container.querySelector("[data-testid='setup-step-hasProjectDatabase']")
+ ?.tagName
+ ).toBe("BUTTON");
+ expect(
+ container.querySelector("[data-testid='setup-step-hasFirstQuery']")
+ ?.tagName
+ ).toBe("BUTTON");
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ expect(
+ container.textContent?.match(/workspace-setup-guide\.steps\.query/g)
+ ?.length
+ ).toBe(1);
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.project›workspace-setup-guide.steps.instance"
+ );
+ expect(container.textContent).not.toContain(
+ "workspace-setup-guide.steps.project/workspace-setup-guide.steps.instance"
+ );
+
+ await act(async () => {
+ (
+ container.querySelector(
+ "[data-testid='setup-step-hasInstance']"
+ ) as HTMLButtonElement | null
+ )?.click();
+ await Promise.resolve();
+ });
+
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.instance",
+ query: { intro: "create-instance" },
+ });
+ });
+
+ it("hides when the workspace has more than one member", async () => {
+ mocks.workspacePolicy = {
+ bindings: [
+ {
+ role: "roles/workspaceAdmin",
+ },
+ ],
+ };
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toBe("");
+ expect(mocks.fetchProjectList).not.toHaveBeenCalled();
+ });
+
+ it("shows setup step descriptions in tooltips", async () => {
+ vi.useFakeTimers();
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).not.toContain(
+ "workspace-setup-guide.descriptions.project"
+ );
+
+ const projectStep = container.querySelector(
+ "[data-testid='setup-step-hasProject']"
+ );
+
+ await act(async () => {
+ projectStep?.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+ vi.advanceTimersByTime(100);
+ await Promise.resolve();
+ });
+
+ expect(
+ document.getElementById("bb-react-layer-overlay")?.textContent
+ ).toContain("workspace-setup-guide.descriptions.project");
+ expect(container.textContent).not.toContain(
+ "workspace-setup-guide.descriptions.project"
+ );
+ });
+
+ it("shows previous-step guidance in tooltips for disabled setup steps", async () => {
+ vi.useFakeTimers();
+ await render(<WorkspaceSetupGuide />);
+
+ const prepareDatabaseStep = container.querySelector(
+ "[data-testid='setup-step-hasProjectDatabase']"
+ ) as HTMLButtonElement | null;
+
+ expect(prepareDatabaseStep).toBeDisabled();
+
+ await act(async () => {
+ prepareDatabaseStep?.parentElement?.dispatchEvent(
+ new FocusEvent("focusin", { bubbles: true })
+ );
+ vi.advanceTimersByTime(100);
+ await Promise.resolve();
+ });
+
+ expect(
+ document.getElementById("bb-react-layer-overlay")?.textContent
+ ).toContain("workspace-setup-guide.previous-step-required");
+ });
+
+ it("can be dismissed for the current workspace and user", async () => {
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.self"
+ );
+
+ const dismissButton = container.querySelector(
+ "[data-testid='dismiss-guide']"
+ ) as HTMLButtonElement | null;
+
+ await act(async () => {
+ dismissButton?.click();
+ await Promise.resolve();
+ });
+
+ expect(mocks.saveIntroStateByKey).toHaveBeenCalledWith({
+ key: dismissedIntroStateKey,
+ newState: true,
+ });
+ expect(mocks.introState[dismissedIntroStateKey]).toBe(true);
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toBe("");
+ });
+
+ it("stays hidden after it is dismissed", async () => {
+ mocks.introState[dismissedIntroStateKey] = true;
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toBe("");
+ expect(mocks.fetchProjectList).not.toHaveBeenCalled();
+ });
+
+ it("advances to the instance step after a project exists", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ const instanceStep = container.querySelector(
+ "[data-testid='setup-step-hasInstance']"
+ );
+ expect(instanceStep?.tagName).toBe("BUTTON");
+ await act(async () => {
+ (instanceStep as HTMLButtonElement | null)?.click();
+ await Promise.resolve();
+ });
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.instance",
+ query: { intro: "create-instance" },
+ });
+ expect(
+ container.querySelector("[data-testid='setup-step-hasFirstQuery']")
+ ?.tagName
+ ).toBe("BUTTON");
+ });
+
+ it("disables the prepare database step until a project and instance exist", async () => {
+ await render(<WorkspaceSetupGuide />);
+
+ expect(
+ container.querySelector(
+ "[data-testid='setup-step-hasProjectDatabase']"
+ )
+ ).toBeDisabled();
+
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(
+ container.querySelector(
+ "[data-testid='setup-step-hasProjectDatabase']"
+ )
+ ).toBeDisabled();
+ });
+
+ it("routes prepare database with transfer context for the database page to resolve after loading", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ const prepareStep = container.querySelector(
+ "[data-testid='setup-step-hasProjectDatabase']"
+ ) as HTMLButtonElement | null;
+
+ expect(prepareStep).not.toBeDisabled();
+
+ await act(async () => {
+ prepareStep?.click();
+ await Promise.resolve();
+ });
+
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.database",
+ query: {
+ intro: "prepare-database",
+ tip: "transfer-databases-to-project",
+ },
+ });
+ });
+
+ it("routes prepare database with a transfer tip when workspace databases exist outside the project", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockImplementation(async ({ parent } = {}) => ({
+ databases:
+ parent === "-"
+ ? [{ name: "instances/instance-a/databases/db-a" }]
+ : [],
+ nextPageToken: "",
+ }));
+
+ await render(<WorkspaceSetupGuide />);
+
+ const prepareStep = container.querySelector(
+ "[data-testid='setup-step-hasProjectDatabase']"
+ ) as HTMLButtonElement | null;
+
+ expect(prepareStep).not.toBeDisabled();
+
+ await act(async () => {
+ prepareStep?.click();
+ await Promise.resolve();
+ });
+
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.database",
+ query: {
+ intro: "prepare-database",
+ tip: "transfer-databases-to-project",
+ },
+ });
+ });
+
+ it("highlights the setup step matching the current route", async () => {
+ mocks.currentRoute = { name: "workspace.instance" };
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasInstance']")
+ ?.getAttribute("class")
+ ).toContain("bg-accent/10");
+
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("stays visible and asks for a project when an instance exists first", async () => {
+ mocks.currentRoute = { name: "workspace.instance.detail" };
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/default" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [{ name: "instances/instance-a/databases/db-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.self"
+ );
+
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("does not use the default project as the setup project", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [
+ { name: "projects/default" },
+ { name: "projects/project-a" },
+ ],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockImplementation(async ({ parent } = {}) => ({
+ databases:
+ parent === "projects/project-a"
+ ? [{ name: "instances/instance-a/databases/db-a" }]
+ : [],
+ nextPageToken: "",
+ }));
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(mocks.fetchDatabases).toHaveBeenCalledWith({
+ parent: "projects/project-a",
+ pageSize: 1,
+ silent: true,
+ });
+
+ const actionButton = container.querySelector(
+ "[data-testid='secondary-action']"
+ ) as HTMLButtonElement | null;
+
+ await act(async () => {
+ actionButton?.click();
+ await Promise.resolve();
+ });
+
+ expect(mocks.preCreateIssue).toHaveBeenCalledWith("projects/project-a", [
+ "instances/instance-a/databases/db-a",
+ ]);
+ });
+
+ it("does not show the active guide action when already on its route", async () => {
+ mocks.currentRoute = { name: "workspace.instance.create" };
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.instance"
+ );
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ expect(container.querySelector("[data-testid='dismiss-guide']")).not.toBeNull();
+ });
+
+ it("highlights the setup step matching the current route", async () => {
+ mocks.currentRoute = { name: "workspace.project" };
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasProject']")
+ ?.getAttribute("class")
+ ).toContain("bg-accent/10");
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasProjectDatabase']")
+ ?.getAttribute("class")
+ ).not.toContain("bg-accent/10");
+
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("does not highlight the create project step on project database pages", async () => {
+ mocks.currentRoute = { name: "workspace.project.database" };
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasProject']")
+ ?.getAttribute("class")
+ ).not.toContain("bg-accent/10");
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasInstance']")
+ ?.getAttribute("class")
+ ).not.toContain("bg-accent/10");
+
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("does not highlight the next setup step on unrelated pages", async () => {
+ mocks.currentRoute = { name: "workspace.home" };
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ for (const key of [
+ "hasProject",
+ "hasInstance",
+ "hasProjectDatabase",
+ "hasFirstQuery",
+ ]) {
+ expect(
+ container
+ .querySelector(`[data-testid='setup-step-${key}']`)
+ ?.getAttribute("class")
+ ).not.toContain("bg-accent/10");
+ }
+
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("asks users to create a database when the connected instance has no databases", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockImplementation(async ({ parent } = {}) => ({
+ databases: parent === "projects/project-a" ? [] : [],
+ nextPageToken: "",
+ }));
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.database"
+ );
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("asks users to transfer a database when the connected instance has no project database", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockImplementation(async ({ parent } = {}) => ({
+ databases:
+ parent === "instances/instance-a"
+ ? [{ name: "instances/instance-a/databases/db-a" }]
+ : [],
+ nextPageToken: "",
+ }));
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.database"
+ );
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("opens SQL Editor as the primary action after a database is connected", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [{ name: "instances/instance-a/databases/db-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.query"
+ );
+ expect(mocks.searchQueryHistories).toHaveBeenCalledWith(
+ expect.objectContaining({
+ pageSize: 1,
+ filter: 'type == "QUERY"',
+ })
+ );
+
+ const actionLink = container.querySelector(
+ "[data-testid='active-action']"
+ );
+ expect(actionLink?.getAttribute("data-route-name")).toBe(
+ "sql-editor.database"
+ );
+ expect(actionLink?.getAttribute("data-route-params")).toBe(
+ JSON.stringify({
+ project: "project-a",
+ instance: "instance-a",
+ database: "db-a",
+ })
+ );
+ expect(actionLink?.textContent).toContain(
+ "workspace-setup-guide.actions.query"
+ );
+
+ const secondaryAction = container.querySelector(
+ "[data-testid='secondary-action']"
+ );
+ expect(secondaryAction).not.toBeNull();
+ expect(
+ secondaryAction!.compareDocumentPosition(actionLink as Node) &
+ Node.DOCUMENT_POSITION_FOLLOWING
+ ).toBe(Node.DOCUMENT_POSITION_FOLLOWING);
+ });
+
+ it("activates the query step when users click it after visiting another step", async () => {
+ mocks.currentRoute = { name: "workspace.database" };
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [{ name: "instances/instance-a/databases/db-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasProjectDatabase']")
+ ?.getAttribute("class")
+ ).toContain("bg-accent/10");
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasFirstQuery']")
+ ?.getAttribute("class")
+ ).not.toContain("bg-accent/10");
+
+ const queryStep = container.querySelector(
+ "[data-testid='setup-step-hasFirstQuery']"
+ );
+
+ expect(queryStep?.tagName).toBe("BUTTON");
+ expect(queryStep?.getAttribute("class")).not.toContain("bg-accent/10");
+
+ await act(async () => {
+ (queryStep as HTMLButtonElement | null)?.click();
+ await Promise.resolve();
+ });
+
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasFirstQuery']")
+ ?.getAttribute("class")
+ ).toContain("bg-accent/10");
+ expect(
+ container.querySelector("[data-testid='active-action']")?.textContent
+ ).toContain("workspace-setup-guide.actions.query");
+ });
+
+ it("opens the first database change flow as a secondary action", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [{ name: "instances/instance-a/databases/db-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ const changeButton = container.querySelector(
+ "[data-testid='secondary-action']"
+ ) as HTMLButtonElement | null;
+ expect(changeButton?.tagName).toBe("BUTTON");
+ expect(changeButton?.textContent).toContain(
+ "workspace-setup-guide.actions.change"
+ );
+
+ await act(async () => {
+ changeButton?.click();
+ await Promise.resolve();
+ });
+
+ expect(mocks.preCreateIssue).toHaveBeenCalledWith("projects/project-a", [
+ "instances/instance-a/databases/db-a",
+ ]);
+ });
+
+ it("stays visible after the first query exists", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [{ name: "instances/instance-a/databases/db-a" }],
+ nextPageToken: "",
+ });
+ mocks.searchQueryHistories.mockResolvedValue({
+ queryHistories: [{ name: "projects/project-a/queryHistories/1" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.self"
+ );
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.query"
+ );
+ expect(
+ container.querySelector("[data-testid='active-action']")?.textContent
+ ).toContain("workspace-setup-guide.actions.query");
+ });
+
+ it("checks first query before a project database exists", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [],
+ nextPageToken: "",
+ });
+ await render(<WorkspaceSetupGuide />);
+
+ expect(mocks.searchQueryHistories).toHaveBeenCalledWith(
+ expect.objectContaining({
+ pageSize: 1,
+ filter: 'type == "QUERY"',
+ })
+ );
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("keeps the query step disabled before a project database exists", async () => {
+ mocks.currentRoute = { name: "workspace.database" };
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ const queryStep = container.querySelector(
+ "[data-testid='setup-step-hasFirstQuery']"
+ );
+
+ expect(queryStep?.tagName).toBe("BUTTON");
+ expect(queryStep).toBeDisabled();
+ expect(queryStep?.getAttribute("class")).not.toContain("bg-accent/10");
+
+ await act(async () => {
+ (queryStep as HTMLButtonElement | null)?.click();
+ await Promise.resolve();
+ });
+
+ expect(
+ container
+ .querySelector("[data-testid='setup-step-hasFirstQuery']")
+ ?.getAttribute("class")
+ ).not.toContain("bg-accent/10");
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+ });
+
+ it("refreshes when a new instance is added to the app store", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.instance"
+ );
+
+ mocks.instancesByName = { "instances/instance-a": {} };
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.database"
+ );
+ });
+
+ it("keeps the guide visible while progress is refreshing", async () => {
+ let resolveProjectList:
+ | ((value: { projects: unknown[]; nextPageToken: string }) => void)
+ | undefined;
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.self"
+ );
+
+ mocks.currentRoute = { name: "workspace.instance.detail" };
+ mocks.instancesByName = { "instances/instance-a": {} };
+ mocks.fetchProjectList.mockReturnValue(
+ new Promise((resolve) => {
+ resolveProjectList = resolve;
+ })
+ );
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.self"
+ );
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.steps.project"
+ );
+
+ await act(async () => {
+ resolveProjectList?.({ projects: [], nextPageToken: "" });
+ await Promise.resolve();
+ });
+ });
+
+ it("refreshes when a database is added to the app store", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+
+ mocks.databasesByName = {
+ "instances/instance-a/databases/db-a": {},
+ };
+ mocks.fetchDatabases.mockImplementation(async ({ parent } = {}) => ({
+ databases:
+ parent === "projects/project-a"
+ ? [{ name: "instances/instance-a/databases/db-a" }]
+ : [],
+ nextPageToken: "",
+ }));
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.actions.change"
+ );
+ });
+
+ it("refreshes when the route changes after setup progress changes elsewhere", async () => {
+ mocks.fetchProjectList.mockResolvedValue({
+ projects: [{ name: "projects/project-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/instance-a" }],
+ nextPageToken: "",
+ });
+ mocks.fetchDatabases.mockResolvedValue({
+ databases: [],
+ nextPageToken: "",
+ });
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.querySelector("[data-testid='active-action']")).toBeNull();
+
+ mocks.currentRoute = { name: "workspace.member" };
+ mocks.fetchDatabases.mockImplementation(async ({ parent } = {}) => ({
+ databases:
+ parent === "projects/project-a"
+ ? [{ name: "instances/instance-a/databases/db-a" }]
+ : [],
+ nextPageToken: "",
+ }));
+
+ await render(<WorkspaceSetupGuide />);
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.actions.change"
+ );
+ });
+});
diff --git a/frontend/src/components/WorkspaceSetupGuide.tsx b/frontend/src/components/WorkspaceSetupGuide.tsx
new file mode 100644
index 0000000000..7f05b837c0
--- /dev/null
+++ b/frontend/src/components/WorkspaceSetupGuide.tsx
@@ -0,0 +1,407 @@
+import { create } from "@bufbuild/protobuf";
+import { CheckCircle, Circle, X } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { sqlServiceClientConnect } from "@/api";
+import { type RouteTarget, router, useCurrentRoute } from "@/app/router";
+import {
+ DATABASE_ROUTE_DASHBOARD,
+ INSTANCE_ROUTE_DASHBOARD,
+ PROJECT_V1_ROUTE_DASHBOARD,
+ SQL_EDITOR_DATABASE_MODULE,
+} from "@/app/router/handles";
+import { RouterLink } from "@/components/RouterLink";
+import { Button, buttonVariants } from "@/components/ui/button";
+import { Tooltip } from "@/components/ui/tooltip";
+import { useIntroStateByKey } from "@/hooks/useAppState";
+import { preCreateIssue } from "@/lib/plan/issue";
+import {
+ CREATE_INSTANCE_PRODUCT_INTRO,
+ CREATE_PROJECT_PRODUCT_INTRO,
+ PREPARE_DATABASE_PRODUCT_INTRO,
+ PREPARE_DATABASE_TRANSFER_TIP,
+ PRODUCT_INTRO_QUERY_KEY,
+ PRODUCT_INTRO_TIP_QUERY_KEY,
+} from "@/lib/productIntro";
+import { cn } from "@/lib/utils";
+import { useAppStore } from "@/stores/app";
+import { SearchQueryHistoriesRequestSchema } from "@/types/proto-es/v1/sql_service_pb";
+import {
+ extractDatabaseResourceName,
+ extractProjectResourceName,
+ hasWorkspacePermissionV2,
+} from "@/utils";
+
+type SetupKeys = {
+ hasProject: boolean;
+ hasInstance: boolean;
+ hasProjectDatabase: boolean;
+ hasFirstQuery: boolean;
+};
+
+type SetupState = SetupKeys & {
+ hasWorkspaceDatabase: boolean;
+ projectName: string;
+ databaseName: string;
+};
+
+type SetupStep = {
+ key: keyof SetupKeys;
+ label: string;
+ description: string;
+ link?: RouteTarget;
+ done: boolean;
+ disabled?: boolean;
+ matchesRoute?: (routeName: string | undefined) => boolean;
+};
+
+const initialSetupState: SetupState = {
+ hasProject: false,
+ hasInstance: false,
+ hasWorkspaceDatabase: false,
+ hasProjectDatabase: false,
+ hasFirstQuery: false,
+ projectName: "",
+ databaseName: "",
+};
+
+const WORKSPACE_SETUP_GUIDE_DISMISSED_KEY = "workspace-setup-guide.dismissed";
+
+const isRouteInside = (routeName: string | undefined, parentName: string) =>
+ routeName === parentName || !!routeName?.startsWith(`${parentName}.`);
+
+export function WorkspaceSetupGuide() {
+ const { t } = useTranslation();
+ const currentRoute = useCurrentRoute();
+ const dismissed = useIntroStateByKey(WORKSPACE_SETUP_GUIDE_DISMISSED_KEY);
+ const defaultProject = useAppStore((s) => s.serverInfo?.defaultProject ?? "");
+ const projectCacheSize = useAppStore(
+ (s) => Object.keys(s.projectsByName).length
+ );
+ const instanceCacheSize = useAppStore(
+ (s) => Object.keys(s.instancesByName).length
+ );
+ const databaseCacheSize = useAppStore(
+ (s) => Object.keys(s.databasesByName).length
+ );
+ const workspaceMemberCount = useAppStore((s) =>
+ (s.workspacePolicy?.bindings ?? []).reduce(
+ (count, binding) => count + binding.members.length,
+ 0
+ )
+ );
+ const hasSingleWorkspaceMember = workspaceMemberCount === 1;
+ const [loading, setLoading] = useState(true);
+ const [selectedStepKey, setSelectedStepKey] = useState<keyof SetupKeys>();
+ const [setupState, setSetupState] = useState<SetupState>(initialSetupState);
+
+ useEffect(() => {
+ setSelectedStepKey(undefined);
+ }, [currentRoute.name]);
+
+ const onSelectStep = (step: SetupStep) => {
+ setSelectedStepKey(step.key);
+ if (step.link) {
+ void router.push(step.link);
+ }
+ };
+
+ useEffect(() => {
+ if (dismissed || !hasSingleWorkspaceMember) {
+ setSetupState(initialSetupState);
+ setLoading(false);
+ return;
+ }
+
+ void (async () => {
+ const store = useAppStore.getState();
+ const [projectResult, instanceResult] = await Promise.allSettled([
+ useAppStore.getState().fetchProjectList({
+ pageSize: 1,
+ silent: true,
+ filter: {
+ excludeDefault: true,
+ },
+ }),
+ hasWorkspacePermissionV2("bb.instances.list")
+ ? useAppStore.getState().fetchInstanceList({
+ pageSize: 1,
+ silent: true,
+ })
+ : Promise.resolve({ instances: [] }),
+ ]);
+
+ const projectName =
+ projectResult.status === "fulfilled"
+ ? (projectResult.value.projects.find(
+ (project) => project.name !== defaultProject
+ )?.name ?? "")
+ : "";
+ const hasProject = !!projectName;
+ const hasInstance =
+ instanceCacheSize > 0 ||
+ (instanceResult.status === "fulfilled" &&
+ instanceResult.value.instances.length > 0);
+ let databaseName = "";
+ let hasWorkspaceDatabase = databaseCacheSize > 0;
+ let hasFirstQuery = false;
+
+ if (projectName || hasInstance) {
+ const [projectDatabaseResult, workspaceDatabaseResult] =
+ await Promise.allSettled([
+ projectName
+ ? store.fetchDatabases({
+ parent: projectName,
+ pageSize: 1,
+ silent: true,
+ })
+ : Promise.resolve({ databases: [] }),
+ hasInstance
+ ? store.fetchDatabases({
+ parent: "-",
+ pageSize: 1,
+ silent: true,
+ })
+ : Promise.resolve({ databases: [] }),
+ ]);
+ if (projectDatabaseResult.status === "fulfilled") {
+ databaseName = projectDatabaseResult.value.databases[0]?.name ?? "";
+ }
+ if (workspaceDatabaseResult.status === "fulfilled") {
+ hasWorkspaceDatabase =
+ hasWorkspaceDatabase ||
+ workspaceDatabaseResult.value.databases.length > 0;
+ }
+ }
+
+ try {
+ const queryHistoryResult =
+ await sqlServiceClientConnect.searchQueryHistories(
+ create(SearchQueryHistoriesRequestSchema, {
+ pageSize: 1,
+ filter: 'type == "QUERY"',
+ })
+ );
+ hasFirstQuery = queryHistoryResult.queryHistories.length > 0;
+ } catch {
+ hasFirstQuery = false;
+ }
+
+ setSetupState({
+ hasProject,
+ hasInstance,
+ hasWorkspaceDatabase,
+ hasProjectDatabase: !!databaseName,
+ hasFirstQuery,
+ projectName,
+ databaseName,
+ });
+ setLoading(false);
+ })();
+ }, [
+ databaseCacheSize,
+ defaultProject,
+ dismissed,
+ hasSingleWorkspaceMember,
+ instanceCacheSize,
+ projectCacheSize,
+ currentRoute.name,
+ ]);
+
+ const projectId = setupState.projectName
+ ? extractProjectResourceName(setupState.projectName)
+ : "";
+ const databaseRouteParams = useMemo(() => {
+ if (!setupState.databaseName || !projectId) {
+ return undefined;
+ }
+ const { instanceName, databaseName } = extractDatabaseResourceName(
+ setupState.databaseName
+ );
+ if (!instanceName || !databaseName) {
+ return undefined;
+ }
+ return {
+ project: projectId,
+ instance: instanceName,
+ database: databaseName,
+ };
+ }, [projectId, setupState.databaseName]);
+
+ const steps = useMemo<SetupStep[]>(
+ () => [
+ {
+ key: "hasProject",
+ label: t("workspace-setup-guide.steps.project"),
+ description: t("workspace-setup-guide.descriptions.project"),
+ link: {
+ name: PROJECT_V1_ROUTE_DASHBOARD,
+ query: { [PRODUCT_INTRO_QUERY_KEY]: CREATE_PROJECT_PRODUCT_INTRO },
+ },
+ done: setupState.hasProject,
+ matchesRoute: (routeName) => routeName === PROJECT_V1_ROUTE_DASHBOARD,
+ },
+ {
+ key: "hasInstance",
+ label: t("workspace-setup-guide.steps.instance"),
+ description: t("workspace-setup-guide.descriptions.instance"),
+ link: {
+ name: INSTANCE_ROUTE_DASHBOARD,
+ query: { [PRODUCT_INTRO_QUERY_KEY]: CREATE_INSTANCE_PRODUCT_INTRO },
+ },
+ done: setupState.hasInstance,
+ matchesRoute: (routeName) =>
+ isRouteInside(routeName, INSTANCE_ROUTE_DASHBOARD),
+ },
+ {
+ key: "hasProjectDatabase",
+ label: t("workspace-setup-guide.steps.database"),
+ description: t("workspace-setup-guide.descriptions.database"),
+ link: {
+ name: DATABASE_ROUTE_DASHBOARD,
+ query: !setupState.hasProjectDatabase
+ ? {
+ [PRODUCT_INTRO_QUERY_KEY]: PREPARE_DATABASE_PRODUCT_INTRO,
+ [PRODUCT_INTRO_TIP_QUERY_KEY]: PREPARE_DATABASE_TRANSFER_TIP,
+ }
+ : {
+ [PRODUCT_INTRO_QUERY_KEY]: PREPARE_DATABASE_PRODUCT_INTRO,
+ },
+ },
+ done: setupState.hasProjectDatabase,
+ disabled: !setupState.hasProject || !setupState.hasInstance,
+ matchesRoute: (routeName) =>
+ isRouteInside(routeName, DATABASE_ROUTE_DASHBOARD),
+ },
+ {
+ key: "hasFirstQuery",
+ label: t("workspace-setup-guide.steps.query"),
+ description: t("workspace-setup-guide.descriptions.sql-editor"),
+ done: setupState.hasFirstQuery,
+ disabled: !setupState.hasProjectDatabase,
+ matchesRoute: (routeName) =>
+ isRouteInside(routeName, SQL_EDITOR_DATABASE_MODULE),
+ },
+ ],
+ [setupState, t]
+ );
+
+ const activeStep = steps.find((step) => !step.done) ?? steps.at(-1)!;
+ const selectedStep = steps.find((step) => step.key === selectedStepKey);
+ const routeMatchedStep = steps.find(
+ (step) => step.matchesRoute?.(currentRoute.name) ?? false
+ );
+ const highlightedStep = selectedStep ?? routeMatchedStep;
+ const actionStep =
+ highlightedStep && !highlightedStep.done ? highlightedStep : activeStep;
+
+ const handleCreateFirstChange = () => {
+ void preCreateIssue(setupState.projectName, [setupState.databaseName]);
+ };
+
+ const handleDismiss = () => {
+ useAppStore.getState().saveIntroStateByKey({
+ key: WORKSPACE_SETUP_GUIDE_DISMISSED_KEY,
+ newState: true,
+ });
+ };
+
+ if (dismissed || !hasSingleWorkspaceMember || loading) {
+ return null;
+ }
+
+ return (
+ <div className="flex w-full shrink-0 items-center gap-x-3 border-t border-block-border bg-white px-4 py-3 shadow-[0_-2px_10px_rgba(0,0,0,0.04)]">
+ <div className="flex min-w-0 flex-1 items-center gap-x-4 overflow-hidden">
+ <div className="flex shrink-0 items-baseline gap-x-2">
+ <div className="shrink-0 text-sm font-medium text-main">
+ {t("workspace-setup-guide.self")}
+ </div>
+ </div>
+ <div className="flex min-w-0 flex-1 items-center gap-x-2 overflow-x-auto pr-2">
+ {steps.map((step, index) => {
+ const isHighlighted = step.key === highlightedStep?.key;
+ const tooltipContent = step.disabled
+ ? t("workspace-setup-guide.previous-step-required")
+ : step.description;
+ const className = cn(
+ "inline-flex items-center gap-x-1.5 rounded-sm px-2 py-1 text-sm whitespace-nowrap",
+ isHighlighted
+ ? "bg-accent/10 text-accent"
+ : step.done
+ ? "text-control-light"
+ : "text-control"
+ );
+
+ return (
+ <div key={step.key} className="inline-flex items-center gap-x-2">
+ <Tooltip content={tooltipContent}>
+ <Button
+ type="button"
+ appearance="secondary"
+ data-testid={`setup-step-${step.key}`}
+ className={cn(
+ className,
+ "h-auto justify-start py-1 font-normal"
+ )}
+ disabled={step.disabled}
+ onClick={() => onSelectStep(step)}
+ >
+ {step.done ? (
+ <CheckCircle className="h-4 w-4 text-success" />
+ ) : (
+ <Circle className="h-4 w-4" />
+ )}
+ <span>{step.label}</span>
+ </Button>
+ </Tooltip>
+ {index < steps.length - 1 && (
+ <span className="text-control-light">›</span>
+ )}
+ </div>
+ );
+ })}
+ </div>
+ </div>
+ <div className="ml-auto flex shrink-0 items-center gap-x-2">
+ {actionStep.key === "hasFirstQuery" &&
+ setupState.projectName &&
+ setupState.databaseName && (
+ <Button
+ type="button"
+ data-testid="secondary-action"
+ appearance="secondary"
+ size="sm"
+ className="hidden xl:inline-flex"
+ onClick={handleCreateFirstChange}
+ >
+ {t("workspace-setup-guide.actions.change")}
+ </Button>
+ )}
+ {actionStep.key === "hasFirstQuery" && (
+ <RouterLink
+ data-testid="active-action"
+ to={{
+ name: SQL_EDITOR_DATABASE_MODULE,
+ params: databaseRouteParams,
+ }}
+ className={buttonVariants({ size: "sm" })}
+ >
+ {t("workspace-setup-guide.actions.query")}
+ </RouterLink>
+ )}
+ <Button
+ type="button"
+ data-testid="dismiss-guide"
+ aria-label={t("workspace-setup-guide.dismiss")}
+ appearance="secondary"
+ size="sm"
+ className="text-control-light hover:text-control"
+ onClick={handleDismiss}
+ >
+ <X className="h-4 w-4" />
+ </Button>
+ </div>
+ </div>
+ );
+}
diff --git a/frontend/src/components/database/CreateDatabaseSheet.test.tsx b/frontend/src/components/database/CreateDatabaseSheet.test.tsx
index 256fe55e99..50509e444a 100644
--- a/frontend/src/components/database/CreateDatabaseSheet.test.tsx
+++ b/frontend/src/components/database/CreateDatabaseSheet.test.tsx
@@ -15,11 +15,13 @@ import { Engine } from "@/types/proto-es/v1/common_pb";
vi.mock("@/components/InstanceSelect", () => ({
InstanceSelect: (props: {
onChange: (name: string, instance: unknown) => void;
+ disabled?: boolean;
portal?: boolean;
value: string;
}) =>
createElement("input", {
"data-testid": "instance-select",
+ disabled: props.disabled,
"data-portal": String(Boolean(props.portal)),
value: props.value,
onChange: (e: React.ChangeEvent<HTMLInputElement>) =>
@@ -166,6 +168,7 @@ const appStoreState = {
},
getProjectByName: (name: string) =>
appStoreState.projectsByName[name] ?? UNKNOWN_PROJECT,
+ instancesByName: {} as Record<string, unknown>,
projectsByName: {} as Record<
string,
{
@@ -248,6 +251,7 @@ beforeEach(() => {
document.body.appendChild(container);
root = createRoot(container);
appStoreState.environmentList = [];
+ appStoreState.instancesByName = {};
appStoreState.projectsByName = {};
mocks.instancesByName = {};
mocks.permissions = {};
@@ -276,6 +280,7 @@ function setupProjectMock(enforceIssueTitle: boolean) {
issueLabels: [],
forceIssueLabels: false,
}));
+ appStoreState.instancesByName[TEST_INSTANCE.name] = TEST_INSTANCE;
mocks.instancesByName[TEST_INSTANCE.name] = TEST_INSTANCE;
mocks.getOrFetchInstanceByName.mockResolvedValue(TEST_INSTANCE);
}
@@ -396,6 +401,29 @@ describe("CreateDatabaseSheet — enforceIssueTitle (BYT-9310)", () => {
expect(getCreateButton().disabled).toBe(false);
});
+ it("prefills and locks a fixed instance", async () => {
+ setupProjectMock(false);
+
+ await act(async () => {
+ root.render(
+ createElement(CreateDatabaseSheet, {
+ open: true,
+ onClose: () => {},
+ projectName: "projects/foo",
+ instanceName: TEST_INSTANCE.name,
+ })
+ );
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+
+ const instanceSelect = container.querySelector(
+ "[data-testid='instance-select']"
+ ) as HTMLInputElement;
+ expect(instanceSelect.value).toBe(TEST_INSTANCE.name);
+ expect(instanceSelect.disabled).toBe(true);
+ });
+
it("clears the inherited environment when switching to an instance without one", async () => {
setupProjectMock(false);
const emptyEnvironmentInstance = {
diff --git a/frontend/src/components/database/CreateDatabaseSheet.tsx b/frontend/src/components/database/CreateDatabaseSheet.tsx
index 975ea7c176..cc0c6f8915 100644
--- a/frontend/src/components/database/CreateDatabaseSheet.tsx
+++ b/frontend/src/components/database/CreateDatabaseSheet.tsx
@@ -69,26 +69,40 @@ export interface CreateDatabaseSheetProps {
onClose: () => void;
// If provided, lock project selection to this project
projectName?: string;
+ // If provided, lock instance selection to this instance
+ instanceName?: string;
}
interface CreateDatabaseSession {
id: number;
open: boolean;
fixedProjectName?: string;
+ fixedInstanceName?: string;
}
export function CreateDatabaseSheet(props: CreateDatabaseSheetProps) {
- const { open, onClose, projectName: fixedProjectName } = props;
+ const {
+ open,
+ onClose,
+ projectName: fixedProjectName,
+ instanceName: fixedInstanceName,
+ } = props;
const sessionRef = useRef<CreateDatabaseSession>({
id: 0,
open: false,
fixedProjectName,
+ fixedInstanceName,
});
const session = sessionRef.current;
if (open) {
- if (!session.open || session.fixedProjectName !== fixedProjectName) {
+ if (
+ !session.open ||
+ session.fixedProjectName !== fixedProjectName ||
+ session.fixedInstanceName !== fixedInstanceName
+ ) {
session.id += 1;
session.fixedProjectName = fixedProjectName;
+ session.fixedInstanceName = fixedInstanceName;
}
session.open = true;
} else {
@@ -103,10 +117,11 @@ export function CreateDatabaseSheet(props: CreateDatabaseSheetProps) {
<Sheet open={open} onOpenChange={(next) => !next && onClose()}>
<SheetContent width="standard">
<CreateDatabaseForm
- key={`${session.id}:${session.fixedProjectName ?? ""}`}
+ key={`${session.id}:${session.fixedProjectName ?? ""}:${session.fixedInstanceName ?? ""}`}
open={open}
onClose={onClose}
fixedProjectName={session.fixedProjectName}
+ fixedInstanceName={session.fixedInstanceName}
sessionId={session.id}
isSessionActive={isSessionActive}
/>
@@ -119,12 +134,14 @@ function CreateDatabaseForm({
open,
onClose,
fixedProjectName,
+ fixedInstanceName,
sessionId,
isSessionActive,
}: {
open: boolean;
onClose: () => void;
fixedProjectName?: string;
+ fixedInstanceName?: string;
sessionId: number;
isSessionActive: (id: number) => boolean;
}) {
@@ -318,6 +335,25 @@ function CreateDatabaseForm({
}
};
+ useEffect(() => {
+ if (!open || !fixedInstanceName) {
+ return;
+ }
+ const inst = useAppStore.getState().instancesByName[fixedInstanceName];
+ if (inst) {
+ void handleInstanceChange(fixedInstanceName, inst);
+ return;
+ }
+ setInstanceName(fixedInstanceName);
+ void useAppStore
+ .getState()
+ .getOrFetchInstanceByName(fixedInstanceName)
+ .then((fetched) => handleInstanceChange(fixedInstanceName, fetched))
+ .catch(() => {});
+ // Fixed-instance initialization follows the sheet session. Manual instance
+ // changes still go through InstanceSelect.onChange.
+ }, [fixedInstanceName, open, sessionId]);
+
const handleCreate = async () => {
if (!allowCreate || creating) return;
setCreating(true);
@@ -455,6 +491,7 @@ function CreateDatabaseForm({
value={instanceName}
onChange={handleInstanceChange}
engines={enginesSupportCreateDatabase()}
+ disabled={!!fixedInstanceName}
portal
/>
</FormField>
diff --git a/frontend/src/components/database/DatabaseTable.test.tsx b/frontend/src/components/database/DatabaseTable.test.tsx
index e770e35aeb..9185460dfc 100644
--- a/frontend/src/components/database/DatabaseTable.test.tsx
+++ b/frontend/src/components/database/DatabaseTable.test.tsx
@@ -62,16 +62,19 @@ vi.mock("./DatabaseTableView", () => ({
emptyPlaceholder,
onRowClick,
selectOnRowClick,
+ selectionColumnIntroTarget,
}: {
databases: Database[];
emptyPlaceholder?: React.ReactNode;
onRowClick?: (database: Database, event: React.MouseEvent) => void;
selectOnRowClick?: boolean;
+ selectionColumnIntroTarget?: string;
}) => (
<div
data-testid="database-names"
data-has-row-click={Boolean(onRowClick)}
data-select-on-row-click={Boolean(selectOnRowClick)}
+ data-selection-column-intro-target={selectionColumnIntroTarget ?? ""}
>
{databases.map((database) => database.name).join(",")}
{emptyPlaceholder && (
@@ -240,4 +243,33 @@ describe("DatabaseTable", () => {
expect(view?.getAttribute("data-has-row-click")).toBe("false");
expect(view?.getAttribute("data-select-on-row-click")).toBe("true");
});
+
+ test("forwards selection column intro target to the table view", async () => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+
+ mocks.fetchDatabases.mockResolvedValueOnce({
+ databases: [db1],
+ nextPageToken: "",
+ });
+
+ await act(async () => {
+ root!.render(
+ <DatabaseTable
+ filter={{}}
+ parent="instances/i"
+ selectedNames={new Set()}
+ onSelectedNamesChange={vi.fn()}
+ selectionColumnIntroTarget="prepare-database"
+ />
+ );
+ await Promise.resolve();
+ });
+
+ const view = container.querySelector("[data-testid='database-names']");
+ expect(view?.getAttribute("data-selection-column-intro-target")).toBe(
+ "prepare-database"
+ );
+ });
});
diff --git a/frontend/src/components/database/DatabaseTable.tsx b/frontend/src/components/database/DatabaseTable.tsx
index 623e36b5be..6282abc061 100644
--- a/frontend/src/components/database/DatabaseTable.tsx
+++ b/frontend/src/components/database/DatabaseTable.tsx
@@ -36,8 +36,10 @@ export interface DatabaseTableProps {
* it every render and re-fires the effect on every parent re-render.
*/
onDatabasesChange?: (databases: Database[]) => void;
+ onLoadingChange?: (loading: boolean) => void;
refreshToken?: number;
emptyPlaceholder?: React.ReactNode;
+ selectionColumnIntroTarget?: string;
}
function databaseFilterKey(filter: DatabaseFilter | string | undefined) {
@@ -72,8 +74,10 @@ export function DatabaseTable({
selectedNames,
onSelectedNamesChange,
onDatabasesChange,
+ onLoadingChange,
refreshToken,
emptyPlaceholder,
+ selectionColumnIntroTarget,
}: DatabaseTableProps) {
const [databases, setDatabases] = useState<Database[]>([]);
const [loading, setLoading] = useState(true);
@@ -174,6 +178,9 @@ export function DatabaseTable({
useEffect(() => {
onDatabasesChange?.(databases);
}, [databases, onDatabasesChange]);
+ useEffect(() => {
+ onLoadingChange?.(loading);
+ }, [loading, onLoadingChange]);
const handleRowClick = useCallback((db: Database, e: React.MouseEvent) => {
const url = router.resolve(autoDatabaseRoute(db)).fullPath;
@@ -203,6 +210,7 @@ export function DatabaseTable({
onSortChange={setSort}
onRowClick={selectOnRowClick ? undefined : handleRowClick}
selectOnRowClick={selectOnRowClick}
+ selectionColumnIntroTarget={selectionColumnIntroTarget}
/>
<div className="mt-4 mx-2">
<PagedTableFooter
diff --git a/frontend/src/components/database/DatabaseTableView.test.tsx b/frontend/src/components/database/DatabaseTableView.test.tsx
index 40b2f7d56e..39ead7ab5f 100644
--- a/frontend/src/components/database/DatabaseTableView.test.tsx
+++ b/frontend/src/components/database/DatabaseTableView.test.tsx
@@ -133,4 +133,36 @@ describe("DatabaseTableView", () => {
databases.map((database) => database.name)
);
});
+
+ test("can expose the selection column as a product intro target", async () => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+
+ await act(async () => {
+ root!.render(
+ <DatabaseTableView
+ databases={[makeDatabase("instances/i/databases/db1")]}
+ mode="PROJECT"
+ selectedNames={new Set()}
+ onSelectedNamesChange={vi.fn()}
+ selectionColumnIntroTarget="prepare-database"
+ />
+ );
+ await Promise.resolve();
+ });
+
+ const target = container.querySelector(
+ "[data-product-intro-target='prepare-database']"
+ );
+
+ expect(target).toBeTruthy();
+ expect(target?.getAttribute("data-product-intro-preserve-position")).toBe(
+ "true"
+ );
+ expect(target?.className).toContain("w-12");
+ expect(target?.className).toContain("bottom-0");
+ expect(target?.className).toContain("pointer-events-none");
+ expect(target?.className).not.toContain("h-full");
+ });
});
diff --git a/frontend/src/components/database/DatabaseTableView.tsx b/frontend/src/components/database/DatabaseTableView.tsx
index a239ae2b31..41cc89a49a 100644
--- a/frontend/src/components/database/DatabaseTableView.tsx
+++ b/frontend/src/components/database/DatabaseTableView.tsx
@@ -64,6 +64,7 @@ interface DatabaseTableViewProps {
onRowClick?: (db: Database, e: React.MouseEvent) => void;
/** Select the row when it is clicked and no explicit row handler is set. */
selectOnRowClick?: boolean;
+ selectionColumnIntroTarget?: string;
}
const isAllSelected = (databases: Database[], selected?: Set<string>) =>
@@ -110,6 +111,7 @@ export function DatabaseTableView({
onSortChange,
onRowClick,
selectOnRowClick = false,
+ selectionColumnIntroTarget,
}: DatabaseTableViewProps) {
const { t } = useTranslation();
const scrollContainerRef = useRef<HTMLDivElement>(null);
@@ -352,8 +354,15 @@ export function DatabaseTableView({
<div
ref={scrollContainerRef}
data-testid="database-table-scroll-container"
- className="overflow-x-auto border rounded-sm"
+ className="relative overflow-x-auto border rounded-sm"
>
+ {showSelection && selectionColumnIntroTarget && (
+ <div
+ data-product-intro-target={selectionColumnIntroTarget}
+ data-product-intro-preserve-position="true"
+ className="pointer-events-none absolute bottom-0 left-0 top-0 z-10 w-12"
+ />
+ )}
<Table className="table-fixed" style={{ minWidth: `${totalWidth}px` }}>
<colgroup>
{showSelection && <col style={{ width: "48px" }} />}
diff --git a/frontend/src/components/header/ProjectCreateDialog.tsx b/frontend/src/components/header/ProjectCreateDialog.tsx
index 0c38580671..03c87888f9 100644
--- a/frontend/src/components/header/ProjectCreateDialog.tsx
+++ b/frontend/src/components/header/ProjectCreateDialog.tsx
@@ -24,7 +24,10 @@ import {
useNotify,
useWorkspacePermission,
} from "@/hooks/useAppState";
-import { CONNECT_DATABASE_PRODUCT_INTRO } from "@/lib/productIntro";
+import {
+ CONNECT_DATABASE_PRODUCT_INTRO,
+ PRODUCT_INTRO_QUERY_KEY,
+} from "@/lib/productIntro";
import { projectNamePrefix } from "@/lib/resourceName";
import { useAppStore } from "@/stores/app";
import type { Project } from "@/types/proto-es/v1/project_service_pb";
@@ -116,7 +119,7 @@ export function ProjectCreateDialog({
params: {
projectId: extractProjectResourceName(createdProject.name),
},
- query: { intro: CONNECT_DATABASE_PRODUCT_INTRO },
+ query: { [PRODUCT_INTRO_QUERY_KEY]: CONNECT_DATABASE_PRODUCT_INTRO },
});
}
diff --git a/frontend/src/components/header/ProjectCreateDialogLayout.test.ts b/frontend/src/components/header/ProjectCreateDialogLayout.test.ts
index f2891a1a71..4f9e3bbb85 100644
--- a/frontend/src/components/header/ProjectCreateDialogLayout.test.ts
+++ b/frontend/src/components/header/ProjectCreateDialogLayout.test.ts
@@ -33,7 +33,7 @@ describe("ProjectCreateDialog layout", () => {
"projectId: extractProjectResourceName(createdProject.name)"
);
expect(source).toContain(
- "query: { intro: CONNECT_DATABASE_PRODUCT_INTRO }"
+ "query: { [PRODUCT_INTRO_QUERY_KEY]: CONNECT_DATABASE_PRODUCT_INTRO }"
);
expect(source).not.toContain("path: `/${createdProject.name}`");
});
diff --git a/frontend/src/components/instance/InstanceFormButtons.test.tsx b/frontend/src/components/instance/InstanceFormButtons.test.tsx
index c097604fa5..f3cb76b1fb 100644
--- a/frontend/src/components/instance/InstanceFormButtons.test.tsx
+++ b/frontend/src/components/instance/InstanceFormButtons.test.tsx
@@ -261,8 +261,8 @@ describe("InstanceFormButtons", () => {
name: "workspace.project.database",
params: { projectId: "demo" },
query: {
+ intro: "project-instance-synced",
syncingInstance: "prod",
- intro: "connect-database",
},
});
expect(mocks.context?.onDismiss).not.toHaveBeenCalled();
@@ -312,6 +312,35 @@ describe("InstanceFormButtons", () => {
});
});
+ test("redirects no-project instance creation to the instance databases tab", async () => {
+ mocks.routerCurrentQuery = {};
+ const container = document.createElement("div");
+ const root = createRoot(container);
+
+ await act(async () => {
+ root.render(<InstanceFormButtons />);
+ });
+
+ const createButton = Array.from(container.querySelectorAll("button")).find(
+ (button) => button.textContent?.includes("common.create")
+ ) as HTMLButtonElement;
+ await act(async () => {
+ createButton.click();
+ await flushPromises();
+ });
+
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.instance.detail",
+ params: { instanceId: "prod" },
+ query: { syncingInstance: "prod" },
+ hash: "databases",
+ });
+
+ await act(async () => {
+ root.unmount();
+ });
+ });
+
test("uses structured recovery category from connection test failures", async () => {
const context = mocks.context as {
emitShowConnectionOptions: ReturnType<typeof vi.fn>;
diff --git a/frontend/src/components/instance/InstanceFormButtons.tsx b/frontend/src/components/instance/InstanceFormButtons.tsx
index 28eba841ea..15612b2b3a 100644
--- a/frontend/src/components/instance/InstanceFormButtons.tsx
+++ b/frontend/src/components/instance/InstanceFormButtons.tsx
@@ -3,8 +3,14 @@ import { cloneDeep, isEqual } from "lodash-es";
import { useMemo, useState } from "react";
import { useTranslation } from "react-i18next";
import { router } from "@/app/router";
-import { PROJECT_V1_ROUTE_DATABASES } from "@/app/router/handles";
-import { CONNECT_DATABASE_PRODUCT_INTRO } from "@/lib/productIntro";
+import {
+ INSTANCE_ROUTE_DETAIL,
+ PROJECT_V1_ROUTE_DATABASES,
+} from "@/app/router/handles";
+import {
+ PRODUCT_INTRO_QUERY_KEY,
+ PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,
+} from "@/lib/productIntro";
import { cn } from "@/lib/utils";
import { pushNotification } from "@/stores";
import { useAppStore } from "@/stores/app";
@@ -264,12 +270,18 @@ export function InstanceFormButtons({
name: PROJECT_V1_ROUTE_DATABASES,
params: { projectId: projectContext.id },
query: {
+ [PRODUCT_INTRO_QUERY_KEY]: PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,
syncingInstance: extractInstanceResourceName(createdInstance.name),
- intro: CONNECT_DATABASE_PRODUCT_INTRO,
},
});
} else {
- router.push(`/${createdInstance.name}`);
+ const instanceId = extractInstanceResourceName(createdInstance.name);
+ router.push({
+ name: INSTANCE_ROUTE_DETAIL,
+ params: { instanceId },
+ query: { syncingInstance: instanceId },
+ hash: "databases",
+ });
}
pushNotification({
diff --git a/frontend/src/hooks/useAppState.ts b/frontend/src/hooks/useAppState.ts
index 1918bbb3bb..d48859f0d9 100644
--- a/frontend/src/hooks/useAppState.ts
+++ b/frontend/src/hooks/useAppState.ts
@@ -478,6 +478,16 @@ export function useQuickstartReset() {
return useAppStore((state) => state.resetQuickstartProgress);
}
+export function useIntroStateByKey(key: string) {
+ const introStateVersion = useAppStore((state) => state.introStateVersion);
+ const getIntroStateByKey = useAppStore((state) => state.getIntroStateByKey);
+
+ return useMemo(
+ () => getIntroStateByKey(key),
+ [getIntroStateByKey, introStateVersion, key]
+ );
+}
+
export function useCreateProject() {
const createProject = useAppStore((state) => state.createProject);
const setRecentProject = useAppStore((state) => state.setRecentProject);
diff --git a/frontend/src/lib/productIntro.css b/frontend/src/lib/productIntro.css
index 482c2631c4..3aeba0bedd 100644
--- a/frontend/src/lib/productIntro.css
+++ b/frontend/src/lib/productIntro.css
@@ -93,6 +93,9 @@
}
.bb-product-intro-active {
- position: relative;
z-index: 1000000001;
}
+
+.bb-product-intro-active:not([data-product-intro-preserve-position]) {
+ position: relative;
+}
diff --git a/frontend/src/lib/productIntro.ts b/frontend/src/lib/productIntro.ts
index 90ae10748f..5850d6c260 100644
--- a/frontend/src/lib/productIntro.ts
+++ b/frontend/src/lib/productIntro.ts
@@ -4,7 +4,13 @@ import { router, useCurrentRoute } from "@/app/router";
import "./productIntro.css";
export const PRODUCT_INTRO_QUERY_KEY = "intro";
+export const PRODUCT_INTRO_TIP_QUERY_KEY = "tip";
export const CONNECT_DATABASE_PRODUCT_INTRO = "connect-database";
+export const CREATE_PROJECT_PRODUCT_INTRO = "create-project";
+export const CREATE_INSTANCE_PRODUCT_INTRO = "create-instance";
+export const PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO = "project-instance-synced";
+export const PREPARE_DATABASE_PRODUCT_INTRO = "prepare-database";
+export const PREPARE_DATABASE_TRANSFER_TIP = "transfer-databases-to-project";
export const EXTERNAL_URL_PRODUCT_INTRO = "external-url";
export const AI_ASSISTANT_PRODUCT_INTRO = "ai-assistant";
export const DOMAIN_RESTRICTION_PRODUCT_INTRO = "domain-restriction";
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index cccd990f51..55f195a7c9 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -672,6 +672,7 @@
"column": "Column",
"columns": "Columns",
"comment": "Comment",
+ "create-database": "Create database",
"data-size": "Data size",
"edit-environment": "Edit Environment",
"edit-labels": "Edit Labels",
@@ -804,11 +805,17 @@
"failed-to-sync-schema": "Failed to sync schema",
"failed-to-sync-schema-for-database-database-value-name": "Failed to sync schema for database \"{{name}}\".",
"functions": "Functions",
+ "instance-databases-synced-action": "Transfer to project",
+ "instance-databases-synced-description": "Transfer databases to a project to start governed changes.",
+ "instance-databases-synced-title": "Transfer databases to a project",
+ "instance-no-databases-action": "Create database",
+ "instance-no-databases-description": "Create a database in this instance, then transfer it to a project to start governed changes.",
+ "instance-no-databases-title": "No databases found",
"n-databases-had-sync-errors": "{{0}} database(s) had sync errors",
"packages": "Packages",
"partitions": "Partitions",
"procedures": "Procedures",
- "project-instance-synced-action": "Create first change",
+ "project-instance-synced-action": "Create database change",
"project-instance-synced-description": "Your database is ready in this project. Start with a governed database change when you are ready.",
"project-instance-synced-sql-editor-action": "Open SQL Editor",
"project-instance-synced-title": "Database connected",
@@ -940,6 +947,7 @@
"public": "Public IP"
},
"connect-database-to-project": "Connect database to project",
+ "connect-instance": "Connect instance",
"connecting-database-to-project": "Connecting database...",
"connection-info": "Connection info",
"connection-options": "Connection Options",
@@ -1774,10 +1782,10 @@
"warning": "This action cannot be undone. All project data including issues, configurations, and history will be permanently removed."
}
},
- "connect-database": "Connect database",
- "connect-database-empty-placeholder": "Connect an instance to sync databases into this project",
- "connect-database-intro-description": "Connect a database so Bytebase can sync it into this project.",
- "connect-database-intro-title": "Connect your first database",
+ "connect-instance": "Connect instance",
+ "connect-instance-empty-placeholder": "Connect an instance to sync databases into this project",
+ "connect-instance-intro-description": "Connect an instance so Bytebase can sync databases into this project.",
+ "connect-instance-intro-title": "Connect the instance",
"create-modal": {
"project-name": "Project Name",
"success-prompt": "Successfully created project {{name}}."
@@ -3344,5 +3352,37 @@
},
"worksheet": {
"self": "Worksheet"
+ },
+ "workspace-setup-guide": {
+ "actions": {
+ "change": "Create database change",
+ "query": "Go to SQL Editor"
+ },
+ "descriptions": {
+ "database": "Create or transfer a database into a project before querying data.",
+ "instance": "Connect an instance so Bytebase can sync your databases.",
+ "project": "Create a project to organize databases and changes.",
+ "sql-editor": "Query data in SQL Editor, or create a governed database change."
+ },
+ "dismiss": "Dismiss guide",
+ "intro": {
+ "database-description": "Create a database in your connected instance.",
+ "database-title": "Create a database",
+ "instance-description": "Create an instance so Bytebase can connect to your database server.",
+ "instance-title": "Connect the instance",
+ "project-description": "Create a project first. Databases can be synced into it after the instance is connected.",
+ "project-title": "Create a project",
+ "transfer-description": "Select one or more databases, then transfer them to the project.",
+ "transfer-title": "Select databases"
+ },
+ "prepare-database-tip": "Select databases to transfer to the project.",
+ "previous-step-required": "You need to finish the previous step.",
+ "self": "Set up Bytebase",
+ "steps": {
+ "database": "Prepare database",
+ "instance": "Connect instance",
+ "project": "Create project",
+ "query": "Query data"
+ }
}
}
diff --git a/frontend/src/locales/es-ES.json b/frontend/src/locales/es-ES.json
index b01b767bf7..e95d25b1d3 100644
--- a/frontend/src/locales/es-ES.json
+++ b/frontend/src/locales/es-ES.json
@@ -672,6 +672,7 @@
"column": "Columna",
"columns": "Columnas",
"comment": "Comentario",
+ "create-database": "Crear base de datos",
"data-size": "Tamaño de datos",
"edit-environment": "Editar entorno",
"edit-labels": "Editar etiquetas",
@@ -804,11 +805,17 @@
"failed-to-sync-schema": "Error al sincronizar el esquema",
"failed-to-sync-schema-for-database-database-value-name": "Error al sincronizar el esquema para la base de datos \"{{name}}\".",
"functions": "Funciones",
+ "instance-databases-synced-action": "Transferir al proyecto",
+ "instance-databases-synced-description": "Transfiere las bases de datos a un proyecto para empezar cambios gobernados.",
+ "instance-databases-synced-title": "Transferir bases de datos a un proyecto",
+ "instance-no-databases-action": "Crear base de datos",
+ "instance-no-databases-description": "Crea una base de datos en esta instancia y luego transfiérela a un proyecto para empezar cambios gobernados.",
+ "instance-no-databases-title": "No se encontraron bases de datos",
"n-databases-had-sync-errors": "{{0}} base(s) de datos tuvieron errores de sincronización",
"packages": "Paquetes",
"partitions": "Particiones",
"procedures": "Procedimientos",
- "project-instance-synced-action": "Crear primer cambio",
+ "project-instance-synced-action": "Crear cambio de base de datos",
"project-instance-synced-description": "Tu base de datos está lista en este proyecto. Empieza con un cambio de base de datos gobernado cuando estés listo.",
"project-instance-synced-sql-editor-action": "Abrir SQL Editor",
"project-instance-synced-title": "Base de datos conectada",
@@ -940,6 +947,7 @@
"public": "IP pública"
},
"connect-database-to-project": "Conectar base de datos al proyecto",
+ "connect-instance": "Conectar instancia",
"connecting-database-to-project": "Conectando base de datos...",
"connection-info": "Información de conexión",
"connection-options": "Opciones de conexión",
@@ -1774,10 +1782,10 @@
"warning": "Esta acción no se puede deshacer. Todos los datos del proyecto, incluidos problemas, configuraciones e historial, se eliminarán permanentemente."
}
},
- "connect-database": "Conectar base de datos",
- "connect-database-empty-placeholder": "Conecta una instancia para sincronizar bases de datos en este proyecto",
- "connect-database-intro-description": "Conecta una base de datos para que Bytebase pueda sincronizarla en este proyecto.",
- "connect-database-intro-title": "Conecta tu primera base de datos",
+ "connect-instance": "Conectar instancia",
+ "connect-instance-empty-placeholder": "Conecta una instancia para sincronizar bases de datos en este proyecto",
+ "connect-instance-intro-description": "Conecta una instancia para que Bytebase sincronice bases de datos en este proyecto.",
+ "connect-instance-intro-title": "Conectar la instancia",
"create-modal": {
"project-name": "Proyecto Nombre",
"success-prompt": "Proyecto {{name}} creado exitosamente."
@@ -3344,5 +3352,37 @@
},
"worksheet": {
"self": "Hoja de trabajo"
+ },
+ "workspace-setup-guide": {
+ "actions": {
+ "change": "Crear cambio de base de datos",
+ "query": "Ir a SQL Editor"
+ },
+ "descriptions": {
+ "database": "Crea o transfiere una base de datos a un proyecto antes de consultar datos.",
+ "instance": "Conecta una instancia para que Bytebase pueda sincronizar tus bases de datos.",
+ "project": "Crea un proyecto para organizar bases de datos y cambios.",
+ "sql-editor": "Consulta datos en SQL Editor o crea un cambio de base de datos gobernado."
+ },
+ "dismiss": "Cerrar guía",
+ "intro": {
+ "database-description": "Crea una base de datos en tu instancia conectada.",
+ "database-title": "Crear base de datos",
+ "instance-description": "Crea una instancia para que Bytebase pueda conectarse a tu servidor de base de datos.",
+ "instance-title": "Conectar la instancia",
+ "project-description": "Crea primero un proyecto. Las bases de datos se pueden sincronizar en él después de conectar la instancia.",
+ "project-title": "Crear un proyecto",
+ "transfer-description": "Selecciona una o más bases de datos y transfiérelas al proyecto.",
+ "transfer-title": "Seleccionar bases de datos"
+ },
+ "prepare-database-tip": "Selecciona las bases de datos para transferirlas al proyecto.",
+ "previous-step-required": "Debes terminar el paso anterior.",
+ "self": "Configurar Bytebase",
+ "steps": {
+ "database": "Preparar base de datos",
+ "instance": "Conectar instancia",
+ "project": "Crear proyecto",
+ "query": "Consultar datos"
+ }
}
}
diff --git a/frontend/src/locales/ja-JP.json b/frontend/src/locales/ja-JP.json
index a2e1f8e56f..2ca0014802 100644
--- a/frontend/src/locales/ja-JP.json
+++ b/frontend/src/locales/ja-JP.json
@@ -672,6 +672,7 @@
"column": "列",
"columns": "カラム",
"comment": "コメント",
+ "create-database": "データベースを作成",
"data-size": "データサイズ",
"edit-environment": "環境の編集",
"edit-labels": "ラベルを編集",
@@ -804,11 +805,17 @@
"failed-to-sync-schema": "スキーマの同期に失敗しました",
"failed-to-sync-schema-for-database-database-value-name": "データベース \"{{name}}\" のスキーマの同期に失敗しました。",
"functions": "関数",
+ "instance-databases-synced-action": "プロジェクトへ転送",
+ "instance-databases-synced-description": "管理された変更を始めるには、データベースをプロジェクトへ転送してください。",
+ "instance-databases-synced-title": "データベースをプロジェクトへ転送",
+ "instance-no-databases-action": "データベースを作成",
+ "instance-no-databases-description": "このインスタンスにデータベースを作成し、プロジェクトへ転送して管理された変更を開始します。",
+ "instance-no-databases-title": "データベースが見つかりません",
"n-databases-had-sync-errors": "{{0}} 個のデータベースで同期エラーが発生しました",
"packages": "パッケージ",
"partitions": "パーティション",
"procedures": "ストアドプロシージャ",
- "project-instance-synced-action": "最初の変更を作成",
+ "project-instance-synced-action": "データベース変更を作成",
"project-instance-synced-description": "このプロジェクトでデータベースを利用できるようになりました。準備ができたら、管理されたデータベース変更から始めてください。",
"project-instance-synced-sql-editor-action": "SQL Editor を開く",
"project-instance-synced-title": "データベースが接続されました",
@@ -940,6 +947,7 @@
"public": "パブリック IP"
},
"connect-database-to-project": "データベースをプロジェクトに接続",
+ "connect-instance": "インスタンスを接続",
"connecting-database-to-project": "データベースを接続中...",
"connection-info": "接続情報",
"connection-options": "接続オプション",
@@ -1774,10 +1782,10 @@
"warning": "この操作は元に戻せません。イシュー、設定、履歴を含むすべてのプロジェクトデータが完全に削除されます。"
}
},
- "connect-database": "データベースに接続",
- "connect-database-empty-placeholder": "インスタンスを接続して、このプロジェクトにデータベースを同期します",
- "connect-database-intro-description": "データベースを接続すると、Bytebase がこのプロジェクトに同期します。",
- "connect-database-intro-title": "最初のデータベースを接続",
+ "connect-instance": "インスタンスを接続",
+ "connect-instance-empty-placeholder": "インスタンスを接続して、このプロジェクトにデータベースを同期します",
+ "connect-instance-intro-description": "インスタンスを接続すると、Bytebase がデータベースをこのプロジェクトに同期します。",
+ "connect-instance-intro-title": "インスタンスを接続",
"create-modal": {
"project-name": "プロジェクト名前",
"success-prompt": "{{name}} が正常に作成されました。"
@@ -3344,5 +3352,37 @@
},
"worksheet": {
"self": "ワークシート"
+ },
+ "workspace-setup-guide": {
+ "actions": {
+ "change": "データベース変更を作成",
+ "query": "SQL Editor に移動"
+ },
+ "descriptions": {
+ "database": "データをクエリする前に、データベースを作成するかプロジェクトに転送します。",
+ "instance": "インスタンスを接続して、Bytebase がデータベースを同期できるようにします。",
+ "project": "データベースと変更を整理するプロジェクトを作成します。",
+ "sql-editor": "SQL Editor でデータをクエリするか、ガバナンス付きデータベース変更を作成します。"
+ },
+ "dismiss": "ガイドを閉じる",
+ "intro": {
+ "database-description": "接続済みインスタンスにデータベースを作成します。",
+ "database-title": "データベースを作成",
+ "instance-description": "Bytebase がデータベースサーバーに接続できるようにインスタンスを作成します。",
+ "instance-title": "インスタンスを接続",
+ "project-description": "まずプロジェクトを作成します。インスタンス接続後、データベースをそのプロジェクトに同期できます。",
+ "project-title": "プロジェクトを作成",
+ "transfer-description": "1つ以上のデータベースを選択し、プロジェクトに転送します。",
+ "transfer-title": "データベースを選択"
+ },
+ "prepare-database-tip": "プロジェクトに転送するデータベースを選択します。",
+ "previous-step-required": "前のステップを先に完了する必要があります。",
+ "self": "Bytebase をセットアップ",
+ "steps": {
+ "database": "データベースを準備",
+ "instance": "インスタンスを接続",
+ "project": "プロジェクトを作成",
+ "query": "データをクエリ"
+ }
}
}
diff --git a/frontend/src/locales/vi-VN.json b/frontend/src/locales/vi-VN.json
index 93eb6e9f3e..7c30a1671d 100644
--- a/frontend/src/locales/vi-VN.json
+++ b/frontend/src/locales/vi-VN.json
@@ -672,6 +672,7 @@
"column": "Cột",
"columns": "Cột",
"comment": "Bình luận",
+ "create-database": "Tạo cơ sở dữ liệu",
"data-size": "Kích thước dữ liệu",
"edit-environment": "Chỉnh sửa Môi trường",
"edit-labels": "Chỉnh sửa nhãn",
@@ -804,11 +805,17 @@
"failed-to-sync-schema": "Đồng bộ hóa lược đồ thất bại",
"failed-to-sync-schema-for-database-database-value-name": "Đồng bộ schema thất bại cho cơ sở dữ liệu \"{{name}}\".",
"functions": "Hàm",
+ "instance-databases-synced-action": "Chuyển sang dự án",
+ "instance-databases-synced-description": "Chuyển cơ sở dữ liệu sang một dự án để bắt đầu thay đổi được quản trị.",
+ "instance-databases-synced-title": "Chuyển cơ sở dữ liệu sang dự án",
+ "instance-no-databases-action": "Tạo cơ sở dữ liệu",
+ "instance-no-databases-description": "Tạo cơ sở dữ liệu trong instance này, sau đó chuyển nó sang một dự án để bắt đầu thay đổi được quản trị.",
+ "instance-no-databases-title": "Không tìm thấy cơ sở dữ liệu",
"n-databases-had-sync-errors": "{{0}} cơ sở dữ liệu gặp lỗi đồng bộ",
"packages": "Gói",
"partitions": "Phân vùng",
"procedures": "Thủ tục",
- "project-instance-synced-action": "Tạo thay đổi đầu tiên",
+ "project-instance-synced-action": "Tạo thay đổi cơ sở dữ liệu",
"project-instance-synced-description": "Cơ sở dữ liệu của bạn đã sẵn sàng trong dự án này. Hãy bắt đầu bằng một thay đổi cơ sở dữ liệu được quản trị khi bạn sẵn sàng.",
"project-instance-synced-sql-editor-action": "Mở SQL Editor",
"project-instance-synced-title": "Đã kết nối cơ sở dữ liệu",
@@ -940,6 +947,7 @@
"public": "IP công khai"
},
"connect-database-to-project": "Kết nối cơ sở dữ liệu với dự án",
+ "connect-instance": "Kết nối instance",
"connecting-database-to-project": "Đang kết nối cơ sở dữ liệu...",
"connection-info": "Thông tin kết nối",
"connection-options": "Tùy chọn kết nối",
@@ -1774,10 +1782,10 @@
"warning": "Hành động này không thể hoàn tác. Tất cả dữ liệu dự án bao gồm vấn đề, cấu hình và lịch sử sẽ bị xóa vĩnh viễn."
}
},
- "connect-database": "Kết nối cơ sở dữ liệu",
- "connect-database-empty-placeholder": "Kết nối một phiên bản để đồng bộ cơ sở dữ liệu vào dự án này",
- "connect-database-intro-description": "Kết nối cơ sở dữ liệu để Bytebase đồng bộ vào dự án này.",
- "connect-database-intro-title": "Kết nối cơ sở dữ liệu đầu tiên",
+ "connect-instance": "Kết nối instance",
+ "connect-instance-empty-placeholder": "Kết nối instance để đồng bộ cơ sở dữ liệu vào dự án này",
+ "connect-instance-intro-description": "Kết nối instance để Bytebase đồng bộ cơ sở dữ liệu vào dự án này.",
+ "connect-instance-intro-title": "Kết nối instance",
"create-modal": {
"project-name": "Dự án Tên",
"success-prompt": "Đã tạo thành công dự án {{name}}."
@@ -3344,5 +3352,37 @@
},
"worksheet": {
"self": "Bảng tính"
+ },
+ "workspace-setup-guide": {
+ "actions": {
+ "change": "Tạo thay đổi cơ sở dữ liệu",
+ "query": "Đi tới SQL Editor"
+ },
+ "descriptions": {
+ "database": "Tạo hoặc chuyển cơ sở dữ liệu vào dự án trước khi truy vấn dữ liệu.",
+ "instance": "Kết nối instance để Bytebase có thể đồng bộ cơ sở dữ liệu của bạn.",
+ "project": "Tạo dự án để quản lý cơ sở dữ liệu và thay đổi.",
+ "sql-editor": "Truy vấn dữ liệu trong SQL Editor hoặc tạo thay đổi cơ sở dữ liệu được quản trị."
+ },
+ "dismiss": "Đóng hướng dẫn",
+ "intro": {
+ "database-description": "Tạo cơ sở dữ liệu trong instance đã kết nối.",
+ "database-title": "Tạo cơ sở dữ liệu",
+ "instance-description": "Tạo instance để Bytebase có thể kết nối tới máy chủ cơ sở dữ liệu của bạn.",
+ "instance-title": "Kết nối instance",
+ "project-description": "Tạo một dự án trước. Cơ sở dữ liệu có thể được đồng bộ vào dự án đó sau khi instance được kết nối.",
+ "project-title": "Tạo dự án",
+ "transfer-description": "Chọn một hoặc nhiều cơ sở dữ liệu, sau đó chuyển chúng vào dự án.",
+ "transfer-title": "Chọn cơ sở dữ liệu"
+ },
+ "prepare-database-tip": "Chọn cơ sở dữ liệu để chuyển vào dự án.",
+ "previous-step-required": "Bạn cần hoàn thành bước trước đó.",
+ "self": "Thiết lập Bytebase",
+ "steps": {
+ "database": "Chuẩn bị cơ sở dữ liệu",
+ "instance": "Kết nối instance",
+ "project": "Tạo dự án",
+ "query": "Truy vấn dữ liệu"
+ }
}
}
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 3d9cc1869b..63b15928a1 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -672,6 +672,7 @@
"column": "列",
"columns": "列",
"comment": "注释",
+ "create-database": "创建数据库",
"data-size": "数据大小",
"edit-environment": "编辑环境",
"edit-labels": "编辑标签",
@@ -804,11 +805,17 @@
"failed-to-sync-schema": "同步 schema 失败",
"failed-to-sync-schema-for-database-database-value-name": "同步数据库 \"{{name}}\" 的 schema 失败。",
"functions": "函数",
+ "instance-databases-synced-action": "转移到项目",
+ "instance-databases-synced-description": "将数据库转移到项目后,即可开始创建受管变更。",
+ "instance-databases-synced-title": "将数据库转移到项目",
+ "instance-no-databases-action": "创建数据库",
+ "instance-no-databases-description": "在该实例中创建数据库,然后将其转移到项目以开始受管变更。",
+ "instance-no-databases-title": "未找到数据库",
"n-databases-had-sync-errors": "{{0}} 个数据库同步出错",
"packages": "包",
"partitions": "分区",
"procedures": "存储过程",
- "project-instance-synced-action": "创建第一个变更",
+ "project-instance-synced-action": "创建数据库变更",
"project-instance-synced-description": "你的数据库已在此项目中就绪。准备好后,可以从受管数据库变更开始。",
"project-instance-synced-sql-editor-action": "打开 SQL Editor",
"project-instance-synced-title": "数据库已连接",
@@ -940,6 +947,7 @@
"public": "公共 IP"
},
"connect-database-to-project": "连接数据库到项目",
+ "connect-instance": "连接实例",
"connecting-database-to-project": "正在连接数据库...",
"connection-info": "连接信息",
"connection-options": "连接选项",
@@ -1774,10 +1782,10 @@
"warning": "此操作无法撤消。包括工单、配置和历史记录在内的所有项目数据将被永久删除。"
}
},
- "connect-database": "连接数据库",
- "connect-database-empty-placeholder": "连接实例,将数据库同步到此项目",
- "connect-database-intro-description": "连接数据库后,Bytebase 会将它同步到这个项目中。",
- "connect-database-intro-title": "连接第一个数据库",
+ "connect-instance": "连接实例",
+ "connect-instance-empty-placeholder": "连接实例,将数据库同步到此项目",
+ "connect-instance-intro-description": "连接实例后,Bytebase 会将数据库同步到这个项目中。",
+ "connect-instance-intro-title": "连接实例",
"create-modal": {
"project-name": "项目名称",
"success-prompt": "成功创建 {{name}}."
@@ -3344,5 +3352,37 @@
},
"worksheet": {
"self": "工作表"
+ },
+ "workspace-setup-guide": {
+ "actions": {
+ "change": "创建数据库变更",
+ "query": "前往 SQL Editor"
+ },
+ "descriptions": {
+ "database": "创建数据库或将数据库转移到项目中,然后查询数据。",
+ "instance": "连接实例,让 Bytebase 可以同步你的数据库。",
+ "project": "创建项目来管理数据库和变更。",
+ "sql-editor": "在 SQL Editor 中查询数据,或创建受管数据库变更。"
+ },
+ "dismiss": "关闭指南",
+ "intro": {
+ "database-description": "在已连接的实例中创建数据库。",
+ "database-title": "创建数据库",
+ "instance-description": "创建实例,让 Bytebase 可以连接到你的数据库服务器。",
+ "instance-title": "连接实例",
+ "project-description": "先创建一个项目。实例连接后,数据库可以同步到该项目中。",
+ "project-title": "创建项目",
+ "transfer-description": "选择一个或多个数据库,然后转移到项目。",
+ "transfer-title": "选择数据库"
+ },
+ "prepare-database-tip": "选择数据库并转移到项目。",
+ "previous-step-required": "你需要先完成上一步。",
+ "self": "设置 Bytebase",
+ "steps": {
+ "database": "准备数据库",
+ "instance": "连接实例",
+ "project": "创建项目",
+ "query": "查询数据"
+ }
}
}
diff --git a/frontend/src/routes/auth/ProfileSetupPage.test.tsx b/frontend/src/routes/auth/ProfileSetupPage.test.tsx
index 83b60d1edb..2ee7a4ae9d 100644
--- a/frontend/src/routes/auth/ProfileSetupPage.test.tsx
+++ b/frontend/src/routes/auth/ProfileSetupPage.test.tsx
@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
import { fireEvent } from "@testing-library/react";
import type { ReactElement } from "react";
import { act } from "react";
@@ -11,6 +14,8 @@ import type { Workspace } from "@/types/proto-es/v1/workspace_service_pb";
globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
).IS_REACT_ACT_ENVIRONMENT = true;
+const componentDir = dirname(fileURLToPath(import.meta.url));
+
const mocks = vi.hoisted(() => ({
canUpdateWorkspace: true,
currentUser: {
@@ -167,6 +172,19 @@ beforeEach(async () => {
});
describe("ProfileSetupPage", () => {
+ test("uses the shared product intro query key after creating a project", () => {
+ const source = readFileSync(join(componentDir, "ProfileSetupPage.tsx"), {
+ encoding: "utf8",
+ });
+
+ expect(source).toContain(
+ "query: { [PRODUCT_INTRO_QUERY_KEY]: CONNECT_DATABASE_PRODUCT_INTRO }"
+ );
+ expect(source).toContain(
+ "query: { [PRODUCT_INTRO_QUERY_KEY]: CREATE_PROJECT_PRODUCT_INTRO }"
+ );
+ });
+
test("shows workspace name when the sole member can update the workspace", () => {
const page = renderIntoContainer(<ProfileSetupPage />);
@@ -303,7 +321,32 @@ describe("ProfileSetupPage", () => {
expect(mocks.createProject).not.toHaveBeenCalled();
expect(mocks.setRecentProject).not.toHaveBeenCalled();
- expect(mocks.routerReplace).toHaveBeenCalledWith("/");
+ expect(mocks.routerReplace).toHaveBeenCalledWith({
+ name: "workspace.project",
+ query: { intro: "create-project" },
+ });
+
+ page.unmount();
+ });
+
+ test("skips profile setup to the projects page with create project highlighted", async () => {
+ const page = renderIntoContainer(<ProfileSetupPage />);
+
+ page.render();
+
+ const skip = Array.from(page.container.querySelectorAll("button")).find(
+ (button) => button.textContent?.includes("settings.profile.setup-skip")
+ ) as HTMLButtonElement;
+ await act(async () => {
+ skip.click();
+ await Promise.resolve();
+ });
+
+ expect(mocks.createProject).not.toHaveBeenCalled();
+ expect(mocks.routerReplace).toHaveBeenCalledWith({
+ name: "workspace.project",
+ query: { intro: "create-project" },
+ });
page.unmount();
});
diff --git a/frontend/src/routes/auth/ProfileSetupPage.tsx b/frontend/src/routes/auth/ProfileSetupPage.tsx
index c67a38e8b2..3fdf7c2737 100644
--- a/frontend/src/routes/auth/ProfileSetupPage.tsx
+++ b/frontend/src/routes/auth/ProfileSetupPage.tsx
@@ -3,7 +3,10 @@ import { FieldMaskSchema } from "@bufbuild/protobuf/wkt";
import { useCallback, useEffect, useRef, useState } from "react";
import { useTranslation } from "react-i18next";
import { router } from "@/app/router";
-import { PROJECT_V1_ROUTE_DATABASES } from "@/app/router/handles";
+import {
+ PROJECT_V1_ROUTE_DASHBOARD,
+ PROJECT_V1_ROUTE_DATABASES,
+} from "@/app/router/handles";
import { ResourceIdField } from "@/components/ResourceIdField";
import { UserAvatar } from "@/components/UserAvatar";
import { Button } from "@/components/ui/button";
@@ -15,7 +18,11 @@ import {
useWorkspace,
useWorkspacePermission,
} from "@/hooks/useAppState";
-import { CONNECT_DATABASE_PRODUCT_INTRO } from "@/lib/productIntro";
+import {
+ CONNECT_DATABASE_PRODUCT_INTRO,
+ CREATE_PROJECT_PRODUCT_INTRO,
+ PRODUCT_INTRO_QUERY_KEY,
+} from "@/lib/productIntro";
import { pushNotification } from "@/stores";
import { useAppStore } from "@/stores/app";
import { projectNamePrefix } from "@/stores/modules/v1/common";
@@ -69,11 +76,6 @@ export function ProfileSetupPage() {
const projectTitleTrimmed = projectTitle.trim();
const shouldCreateProject = canCreateProject && !!projectTitleTrimmed;
- const redirectUrl = () => {
- const q = new URLSearchParams(window.location.search);
- return q.get("redirect") || "/";
- };
-
const validateProjectResourceId = useCallback(
async (id: string): Promise<ValidatedMessage[]> => {
try {
@@ -140,10 +142,10 @@ export function ProfileSetupPage() {
params: {
projectId: extractProjectResourceName(createdProjectName),
},
- query: { intro: CONNECT_DATABASE_PRODUCT_INTRO },
+ query: { [PRODUCT_INTRO_QUERY_KEY]: CONNECT_DATABASE_PRODUCT_INTRO },
});
} else {
- router.replace(redirectUrl());
+ goToDashboard();
}
} catch {
pushNotification({
@@ -156,8 +158,11 @@ export function ProfileSetupPage() {
}
};
- const handleSkip = () => {
- router.replace(redirectUrl());
+ const goToDashboard = () => {
+ router.replace({
+ name: PROJECT_V1_ROUTE_DASHBOARD,
+ query: { [PRODUCT_INTRO_QUERY_KEY]: CREATE_PROJECT_PRODUCT_INTRO },
+ });
};
const displayName = name.trim() || currentUser?.email || "?";
@@ -237,7 +242,7 @@ export function ProfileSetupPage() {
</Button>
<Button
appearance="secondary"
- onClick={handleSkip}
+ onClick={goToDashboard}
className="w-full"
>
{t("settings.profile.setup-skip")}
diff --git a/frontend/src/routes/project/ProjectDatabasesPage.test.tsx b/frontend/src/routes/project/ProjectDatabasesPage.test.tsx
index 8c47929a7d..42c9c33b66 100644
--- a/frontend/src/routes/project/ProjectDatabasesPage.test.tsx
+++ b/frontend/src/routes/project/ProjectDatabasesPage.test.tsx
@@ -9,6 +9,7 @@ import { preCreateIssue } from "@/lib/plan/issue";
const mocks = vi.hoisted(() => ({
visibleDatabases: [] as { name: string }[],
+ databasesByName: {} as Record<string, { name: string }>,
routerCurrentQuery: {} as Record<string, unknown>,
routerPush: vi.fn(),
useProductIntro: vi.fn(),
@@ -62,17 +63,56 @@ vi.mock("@/components/database", async () => {
open
? React.createElement("div", { "data-testid": "create-database-sheet" })
: null,
- DatabaseBatchOperationsBar: () => null,
+ DatabaseBatchOperationsBar: ({
+ databases,
+ onTransferProject,
+ onToggleSelectAll,
+ }: {
+ databases: { name: string }[];
+ onTransferProject?: () => void;
+ onToggleSelectAll: () => void;
+ }) =>
+ React.createElement(
+ "div",
+ {
+ "data-testid": "batch-operations-bar",
+ "data-selected-count": String(databases.length),
+ "data-has-transfer": String(!!onTransferProject),
+ },
+ React.createElement(
+ "button",
+ {
+ "data-testid": "batch-select-all",
+ onClick: onToggleSelectAll,
+ },
+ "select all"
+ ),
+ databases.length > 0 && onTransferProject
+ ? React.createElement(
+ "button",
+ {
+ "data-testid": "batch-transfer-project",
+ onClick: onTransferProject,
+ },
+ "database.transfer-project"
+ )
+ : null
+ ),
DatabaseTable: ({
emptyPlaceholder,
+ onSelectedNamesChange,
onDatabasesChange,
}: {
emptyPlaceholder?: React.ReactNode;
+ onSelectedNamesChange: (selectedNames: Set<string>) => void;
onDatabasesChange: (databases: { name: string }[]) => void;
}) => {
React.useEffect(() => {
onDatabasesChange(mocks.visibleDatabases);
- }, [onDatabasesChange]);
+ onSelectedNamesChange(
+ new Set(mocks.visibleDatabases.map((d) => d.name))
+ );
+ }, [onDatabasesChange, onSelectedNamesChange]);
return React.createElement(
"div",
{ "data-testid": "database-table" },
@@ -80,6 +120,10 @@ vi.mock("@/components/database", async () => {
);
},
LabelEditorSheet: () => null,
+ TransferProjectSheet: ({ open }: { open: boolean }) =>
+ open
+ ? React.createElement("div", { "data-testid": "transfer-project-sheet" })
+ : null,
};
});
@@ -93,14 +137,25 @@ vi.mock("@/lib/plan/issue", () => ({
vi.mock("@/lib/productIntro", () => ({
CONNECT_DATABASE_PRODUCT_INTRO: "connect-database",
+ PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO: "project-instance-synced",
PRODUCT_INTRO_QUERY_KEY: "intro",
useProductIntro: mocks.useProductIntro,
}));
+vi.mock("@/types", async () => {
+ const actual = await vi.importActual<typeof import("@/types")>("@/types");
+ return {
+ ...actual,
+ isDefaultProject: (name: string) => name === "projects/default",
+ };
+});
+
vi.mock("@/stores/app", () => {
const appState = {
removeDatabaseMetadataCache: mocks.removeDatabaseMetadataCache,
- databasesByName: {},
+ get databasesByName() {
+ return mocks.databasesByName;
+ },
projectsByName: {},
environmentList: [],
};
@@ -138,6 +193,7 @@ vi.mock("@/utils", async () => {
beforeEach(async () => {
vi.clearAllMocks();
mocks.visibleDatabases = [];
+ mocks.databasesByName = {};
mocks.routerCurrentQuery = {};
mocks.workspacePermissions = new Set([
"bb.instances.create",
@@ -147,7 +203,7 @@ beforeEach(async () => {
});
describe("ProjectDatabasesPage", () => {
- test("shows a connect database action when the project has no databases", async () => {
+ test("shows a connect instance action when the project has no databases and no workspace instances", async () => {
const container = document.createElement("div");
const root = createRoot(container);
@@ -158,12 +214,12 @@ describe("ProjectDatabasesPage", () => {
const toolbarButton = container.querySelector(
'button[data-product-intro-target="connect-database"]'
);
- expect(toolbarButton?.textContent).toContain("project.connect-database");
+ expect(toolbarButton?.textContent).toContain("project.connect-instance");
expect(
container.querySelector("[data-testid='database-table'] button")
).toBe(null);
expect(container.textContent).toContain(
- "project.connect-database-empty-placeholder"
+ "project.connect-instance-empty-placeholder"
);
act(() => {
@@ -183,8 +239,8 @@ describe("ProjectDatabasesPage", () => {
expect(mocks.useProductIntro).toHaveBeenCalledWith({
id: "connect-database",
- title: "project.connect-database-intro-title",
- description: "project.connect-database-intro-description",
+ title: "project.connect-instance-intro-title",
+ description: "project.connect-instance-intro-description",
disabled: false,
});
@@ -265,7 +321,7 @@ describe("ProjectDatabasesPage", () => {
const button = container.querySelector(
'button[data-product-intro-target="connect-database"]'
) as HTMLButtonElement;
- expect(button.textContent?.trim()).toContain("project.connect-database");
+ expect(button.textContent?.trim()).toContain("project.connect-instance");
expect(button.disabled).toBe(true);
expect(
container.querySelector("[data-testid='database-table'] button")
@@ -314,6 +370,49 @@ describe("ProjectDatabasesPage", () => {
});
});
+ test("falls back to create database after redirected instance sync finds no databases", async () => {
+ vi.useFakeTimers();
+ mocks.routerCurrentQuery = { syncingInstance: "prod" };
+ mocks.fetchInstanceList.mockResolvedValue({
+ instances: [{ name: "instances/prod", title: "Prod" }],
+ });
+ const container = document.createElement("div");
+ const root = createRoot(container);
+
+ await act(async () => {
+ root.render(<ProjectDatabasesPage projectId="demo" />);
+ await Promise.resolve();
+ });
+
+ expect(container.textContent).toContain(
+ "db.project-instance-syncing-title"
+ );
+
+ await act(async () => {
+ vi.advanceTimersByTime(60000);
+ await Promise.resolve();
+ });
+
+ expect(container.textContent).not.toContain(
+ "db.project-instance-syncing-title"
+ );
+ const button = container.querySelector("button") as HTMLButtonElement;
+ expect(button.textContent?.trim()).toContain("project.add-database");
+
+ await act(async () => {
+ button.click();
+ });
+
+ expect(
+ container.querySelector("[data-testid='create-database-sheet']")
+ ).not.toBeNull();
+
+ act(() => {
+ root.unmount();
+ });
+ vi.useRealTimers();
+ });
+
test("shows next action after redirected instance databases finish syncing", async () => {
mocks.routerCurrentQuery = { syncingInstance: "prod" };
mocks.visibleDatabases = [{ name: "instances/prod/databases/app" }];
@@ -337,6 +436,17 @@ describe("ProjectDatabasesPage", () => {
expect(container.textContent).not.toContain(
"db.project-instance-syncing-title"
);
+ expect(
+ container
+ .querySelector("[role='alert']")
+ ?.getAttribute("data-product-intro-target")
+ ).toBe("project-instance-synced");
+ expect(mocks.useProductIntro).toHaveBeenCalledWith({
+ id: "project-instance-synced",
+ title: "db.project-instance-synced-title",
+ description: "db.project-instance-synced-description",
+ disabled: false,
+ });
const nextActionButton = Array.from(
container.querySelectorAll("button")
@@ -358,6 +468,8 @@ describe("ProjectDatabasesPage", () => {
"db.project-instance-synced-sql-editor-action"
)
) as HTMLButtonElement;
+ expect(sqlEditorButton.className).toContain("bg-accent");
+ expect(nextActionButton.className).toContain("border-control-border");
await act(async () => {
sqlEditorButton.click();
});
@@ -376,26 +488,51 @@ describe("ProjectDatabasesPage", () => {
});
});
- test("recognizes syncInstance query alias for manually opened URLs", async () => {
- mocks.routerCurrentQuery = {
- syncInstance: "prod",
- intro: "connect-database",
- };
+ test("shows transfer project batch action for the default project", async () => {
mocks.visibleDatabases = [{ name: "instances/prod/databases/app" }];
+ mocks.databasesByName = {
+ "instances/prod/databases/app": { name: "instances/prod/databases/app" },
+ };
const container = document.createElement("div");
const root = createRoot(container);
await act(async () => {
- root.render(<ProjectDatabasesPage projectId="demo" />);
+ root.render(<ProjectDatabasesPage projectId="default" />);
+ await Promise.resolve();
+ });
+ await act(async () => {
+ await Promise.resolve();
});
- expect(container.textContent).toContain("db.project-instance-synced-title");
- expect(container.textContent).toContain(
- "db.project-instance-synced-action"
- );
+ const selectAllButton = container.querySelector(
+ '[data-testid="batch-select-all"]'
+ ) as HTMLButtonElement;
+ await act(async () => {
+ selectAllButton.click();
+ });
+
+ const batchBar = container.querySelector(
+ '[data-testid="batch-operations-bar"]'
+ ) as HTMLElement;
+ expect(batchBar.dataset.hasTransfer).toBe("true");
+ expect(batchBar.dataset.selectedCount).toBe("1");
+
+ const transferButton = container.querySelector(
+ '[data-testid="batch-transfer-project"]'
+ ) as HTMLButtonElement;
+ expect(transferButton?.textContent).toContain("database.transfer-project");
+
+ await act(async () => {
+ transferButton.click();
+ });
+
+ expect(
+ container.querySelector('[data-testid="transfer-project-sheet"]')
+ ).not.toBeNull();
act(() => {
root.unmount();
});
});
+
});
diff --git a/frontend/src/routes/project/ProjectDatabasesPage.tsx b/frontend/src/routes/project/ProjectDatabasesPage.tsx
index 00ebd3965b..62233feae8 100644
--- a/frontend/src/routes/project/ProjectDatabasesPage.tsx
+++ b/frontend/src/routes/project/ProjectDatabasesPage.tsx
@@ -20,6 +20,7 @@ import {
DatabaseBatchOperationsBar,
DatabaseTable,
LabelEditorSheet,
+ TransferProjectSheet,
} from "@/components/database";
import { EditEnvironmentSheet } from "@/components/EditEnvironmentSheet";
import { PermissionGuard } from "@/components/PermissionGuard";
@@ -40,6 +41,7 @@ import type { DatabaseFilter } from "@/lib/databaseFilter";
import { preCreateIssue } from "@/lib/plan/issue";
import {
CONNECT_DATABASE_PRODUCT_INTRO,
+ PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,
useProductIntro,
} from "@/lib/productIntro";
import { pushNotification } from "@/stores";
@@ -99,11 +101,13 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
const [showCreateDrawer, setShowCreateDrawer] = useState(false);
const [showLabelEditor, setShowLabelEditor] = useState(false);
const [showEditEnvDrawer, setShowEditEnvDrawer] = useState(false);
+ const [showTransferDrawer, setShowTransferDrawer] = useState(false);
const [showUnassignConfirm, setShowUnassignConfirm] = useState(false);
const [refreshToken, setRefreshToken] = useState(0);
const [workspaceHasInstance, setWorkspaceHasInstance] = useState<
boolean | undefined
>(undefined);
+ const [syncingRefreshExhausted, setSyncingRefreshExhausted] = useState(false);
const autoRefreshCountRef = useRef(0);
const [searchParams, setSearchParams] = useState<SearchParams>({
@@ -231,9 +235,10 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
const [selectedNames, setSelectedNames] = useState<Set<string>>(new Set());
const [visibleDatabases, setVisibleDatabases] = useState<Database[]>([]);
const syncingInstanceId = useMemo(() => {
- const { syncingInstance, syncInstance } = router.currentRoute.value.query;
- const value = syncingInstance ?? syncInstance;
- return typeof value === "string" && value ? value : undefined;
+ const { syncingInstance } = router.currentRoute.value.query;
+ return typeof syncingInstance === "string" && syncingInstance
+ ? syncingInstance
+ : undefined;
}, []);
const selectedDatabases = useMemo(() => {
if (selectedNames.size === 0) return [];
@@ -262,12 +267,17 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
}, []);
useEffect(() => {
- if (!syncingInstanceId || visibleDatabases.length > 0) return;
+ if (!syncingInstanceId || visibleDatabases.length > 0) {
+ setSyncingRefreshExhausted(false);
+ return;
+ }
+ setSyncingRefreshExhausted(false);
autoRefreshCountRef.current = 0;
const timer = window.setInterval(() => {
autoRefreshCountRef.current += 1;
refresh();
if (autoRefreshCountRef.current >= 12) {
+ setSyncingRefreshExhausted(true);
window.clearInterval(timer);
}
}, 5000);
@@ -401,6 +411,40 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
[refresh, t]
);
+ const handleTransferProject = useCallback(
+ async (projectName: string) => {
+ try {
+ await useAppStore.getState().batchUpdateDatabases(
+ create(BatchUpdateDatabasesRequestSchema, {
+ parent: "-",
+ requests: selectedDatabasesRef.current.map((database) =>
+ create(UpdateDatabaseRequestSchema, {
+ database: create(DatabaseSchema$, {
+ name: database.name,
+ project: projectName,
+ }),
+ updateMask: create(FieldMaskSchema, { paths: ["project"] }),
+ })
+ ),
+ })
+ );
+ refresh();
+ pushNotification({
+ module: "bytebase",
+ style: "SUCCESS",
+ title: t("database.successfully-transferred-databases"),
+ });
+ } catch {
+ pushNotification({
+ module: "bytebase",
+ style: "CRITICAL",
+ title: t("common.failed"),
+ });
+ }
+ },
+ [refresh, t]
+ );
+
const handleUnassign = useCallback(async () => {
const defaultProject =
useAppStore.getState().serverInfo?.defaultProject ?? "";
@@ -439,19 +483,22 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
}, [projectName, selectedDatabaseNames]);
const hasVisibleDatabase = visibleDatabases.length > 0;
- const showSyncingInstanceHint = !!syncingInstanceId && !hasVisibleDatabase;
+ const showSyncingInstanceHint =
+ !!syncingInstanceId && !hasVisibleDatabase && !syncingRefreshExhausted;
const showPostSyncNextAction = !!syncingInstanceId && hasVisibleDatabase;
const checkingWorkspaceInstance =
!hasVisibleDatabase &&
!showSyncingInstanceHint &&
+ !syncingRefreshExhausted &&
workspaceHasInstance === undefined;
const emptyProjectHasInstance =
!hasVisibleDatabase &&
- workspaceHasInstance === true &&
+ (workspaceHasInstance === true || syncingRefreshExhausted) &&
!showSyncingInstanceHint;
const emptyProjectShouldConnectInstance =
!hasVisibleDatabase &&
workspaceHasInstance === false &&
+ !syncingRefreshExhausted &&
!showSyncingInstanceHint;
const handleCreateFirstChange = useCallback(() => {
@@ -478,14 +525,20 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
useProductIntro({
id: CONNECT_DATABASE_PRODUCT_INTRO,
- title: t("project.connect-database-intro-title"),
- description: t("project.connect-database-intro-description"),
+ title: t("project.connect-instance-intro-title"),
+ description: t("project.connect-instance-intro-description"),
disabled:
showSyncingInstanceHint ||
hasVisibleDatabase ||
workspaceHasInstance !== false ||
!canCreateInstance,
});
+ useProductIntro({
+ id: PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO,
+ title: t("db.project-instance-synced-title"),
+ description: t("db.project-instance-synced-description"),
+ disabled: !showPostSyncNextAction,
+ });
const handleCreateDatabaseAction = useCallback(() => {
if (checkingWorkspaceInstance) return;
@@ -545,7 +598,7 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
? t("common.create")
: emptyProjectHasInstance
? t("project.add-database")
- : t("project.connect-database")}
+ : t("project.connect-instance")}
</Button>
</PermissionGuard>
)}
@@ -571,30 +624,34 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
{showPostSyncNextAction && (
<Alert
variant="info"
+ data-product-intro-target={PROJECT_INSTANCE_SYNCED_PRODUCT_INTRO}
title={t("db.project-instance-synced-title")}
description={
- <div className="flex flex-col gap-y-3 sm:flex-row sm:items-center sm:justify-between sm:gap-x-4">
+ <div className="flex flex-col gap-y-3">
<span>{t("db.project-instance-synced-description")}</span>
- <div className="flex flex-wrap items-center gap-x-2 gap-y-2">
+ <div className="ml-auto flex flex-wrap items-center gap-x-2 gap-y-2">
<PermissionGuard
- permissions={["bb.sql.select"]}
+ permissions={PERMISSIONS_FOR_DATABASE_CREATE_ISSUE}
project={project}
>
<Button
size="sm"
appearance="outline"
- onClick={handleOpenFirstDatabaseInSQLEditor}
+ onClick={handleCreateFirstChange}
>
- <SquareTerminal className="size-4" />
- {t("db.project-instance-synced-sql-editor-action")}
+ {t("db.project-instance-synced-action")}
</Button>
</PermissionGuard>
<PermissionGuard
- permissions={PERMISSIONS_FOR_DATABASE_CREATE_ISSUE}
+ permissions={["bb.sql.select"]}
project={project}
>
- <Button size="sm" onClick={handleCreateFirstChange}>
- {t("db.project-instance-synced-action")}
+ <Button
+ size="sm"
+ onClick={handleOpenFirstDatabaseInSQLEditor}
+ >
+ <SquareTerminal className="size-4" />
+ {t("db.project-instance-synced-sql-editor-action")}
</Button>
</PermissionGuard>
</div>
@@ -625,7 +682,7 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
<span className="text-sm text-control-light">
{emptyProjectHasInstance
? t("project.add-database-empty-placeholder")
- : t("project.connect-database-empty-placeholder")}
+ : t("project.connect-instance-empty-placeholder")}
</span>
)
}
@@ -638,6 +695,9 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
onSyncSchema={handleSyncSchema}
onEditLabels={() => setShowLabelEditor(true)}
onEditEnvironment={() => setShowEditEnvDrawer(true)}
+ onTransferProject={
+ isDefault ? () => setShowTransferDrawer(true) : undefined
+ }
onUnassign={isDefault ? undefined : () => setShowUnassignConfirm(true)}
onChangeDatabase={isDefault ? undefined : handleChangeDatabase}
allSelected={
@@ -670,6 +730,12 @@ export function ProjectDatabasesPage({ projectId }: { projectId: string }) {
onClose={() => setShowLabelEditor(false)}
onApply={handleLabelsApply}
/>
+ <TransferProjectSheet
+ open={showTransferDrawer}
+ databases={selectedDatabases}
+ onClose={() => setShowTransferDrawer(false)}
+ onTransfer={handleTransferProject}
+ />
{/* Unassign confirmation dialog */}
{showUnassignConfirm && (
diff --git a/frontend/src/routes/workspace/CreateInstancePage.test.tsx b/frontend/src/routes/workspace/CreateInstancePage.test.tsx
index 0560a9cc11..123553c749 100644
--- a/frontend/src/routes/workspace/CreateInstancePage.test.tsx
+++ b/frontend/src/routes/workspace/CreateInstancePage.test.tsx
@@ -203,7 +203,7 @@ describe("CreateInstancePage", () => {
test("keeps syncing instance and intro context when dismissing to the project database page", () => {
mocks.routerCurrentQuery = {
project: "demo",
- syncInstance: "prod",
+ syncingInstance: "prod",
intro: "connect-database",
};
const container = document.createElement("div");
diff --git a/frontend/src/routes/workspace/CreateInstancePage.tsx b/frontend/src/routes/workspace/CreateInstancePage.tsx
index 8d66381421..bc2dc76479 100644
--- a/frontend/src/routes/workspace/CreateInstancePage.tsx
+++ b/frontend/src/routes/workspace/CreateInstancePage.tsx
@@ -47,14 +47,12 @@ export function CreateInstancePage() {
const {
project: projectId,
syncingInstance,
- syncInstance,
intro,
} = router.currentRoute.value.query;
if (typeof projectId === "string" && projectId) {
const query: Record<string, string> = {};
- const instanceId = syncingInstance ?? syncInstance;
- if (typeof instanceId === "string" && instanceId) {
- query.syncingInstance = instanceId;
+ if (typeof syncingInstance === "string" && syncingInstance) {
+ query.syncingInstance = syncingInstance;
}
if (typeof intro === "string" && intro) {
query.intro = intro;
diff --git a/frontend/src/routes/workspace/DatabasesPage.test.tsx b/frontend/src/routes/workspace/DatabasesPage.test.tsx
index 762fc2bdda..e17fe5f3a9 100644
--- a/frontend/src/routes/workspace/DatabasesPage.test.tsx
+++ b/frontend/src/routes/workspace/DatabasesPage.test.tsx
@@ -1,4 +1,4 @@
-import { act } from "react";
+import { act, useEffect } from "react";
import { createRoot } from "react-dom/client";
import { MemoryRouter } from "react-router";
import { beforeEach, describe, expect, test, vi } from "vitest";
@@ -10,10 +10,14 @@ import { beforeEach, describe, expect, test, vi } from "vitest";
const mocks = vi.hoisted(() => ({
routerPush: vi.fn(),
routerReplace: vi.fn(),
+ currentRoute: { query: {} as Record<string, string> },
batchSyncDatabases: vi.fn(),
batchUpdateDatabases: vi.fn(),
removeDatabaseMetadataCache: vi.fn(),
+ useProductIntro: vi.fn(),
hasWorkspacePermission: true,
+ databaseTableRows: [] as unknown[],
+ databaseTableLoading: false,
}));
let DatabasesPage: typeof import("./DatabasesPage").DatabasesPage;
@@ -26,11 +30,14 @@ vi.mock("react-i18next", () => ({
vi.mock("@/app/router", () => ({
router: {
currentRoute: {
- value: { query: {} },
+ get value() {
+ return mocks.currentRoute;
+ },
},
push: mocks.routerPush,
replace: mocks.routerReplace,
},
+ useCurrentRoute: () => mocks.currentRoute,
}));
vi.mock("@/components/AdvancedSearch", () => ({
@@ -65,6 +72,13 @@ vi.mock("@/components/WorkspacePageLayout", () => ({
),
}));
+vi.mock("@/lib/productIntro", () => ({
+ PREPARE_DATABASE_PRODUCT_INTRO: "prepare-database",
+ PREPARE_DATABASE_TRANSFER_TIP: "transfer-databases-to-project",
+ PRODUCT_INTRO_TIP_QUERY_KEY: "tip",
+ useProductIntro: mocks.useProductIntro,
+}));
+
vi.mock("@/components/database", () => ({
CreateDatabaseSheet: ({ open }: { open: boolean }) => (
<div data-testid="create-database-sheet" data-open={String(open)} />
@@ -72,19 +86,53 @@ vi.mock("@/components/database", () => ({
DatabaseBatchOperationsBar: () => null,
DatabaseTable: ({
emptyPlaceholder,
+ selectionColumnIntroTarget,
+ onDatabasesChange,
+ onLoadingChange,
}: {
emptyPlaceholder?: React.ReactNode;
+ selectionColumnIntroTarget?: string;
+ onDatabasesChange?: (databases: unknown[]) => void;
+ onLoadingChange?: (loading: boolean) => void;
}) => (
+ <DatabaseTableMock
+ emptyPlaceholder={emptyPlaceholder}
+ selectionColumnIntroTarget={selectionColumnIntroTarget}
+ onDatabasesChange={onDatabasesChange}
+ onLoadingChange={onLoadingChange}
+ />
+ ),
+ LabelEditorSheet: () => null,
+ TransferProjectSheet: () => null,
+}));
+
+const DatabaseTableMock = ({
+ emptyPlaceholder,
+ selectionColumnIntroTarget,
+ onDatabasesChange,
+ onLoadingChange,
+}: {
+ emptyPlaceholder?: React.ReactNode;
+ selectionColumnIntroTarget?: string;
+ onDatabasesChange?: (databases: unknown[]) => void;
+ onLoadingChange?: (loading: boolean) => void;
+}) => {
+ useEffect(() => {
+ onDatabasesChange?.(mocks.databaseTableRows);
+ }, [onDatabasesChange]);
+ useEffect(() => {
+ onLoadingChange?.(mocks.databaseTableLoading);
+ }, [onLoadingChange]);
+ return (
<div
data-testid="database-table"
data-has-empty-placeholder={String(!!emptyPlaceholder)}
+ data-selection-column-intro-target={selectionColumnIntroTarget ?? ""}
>
{emptyPlaceholder}
</div>
- ),
- LabelEditorSheet: () => null,
- TransferProjectSheet: () => null,
-}));
+ );
+};
vi.mock("@/stores/app", () => {
const appState = {
@@ -130,6 +178,9 @@ vi.mock("@/utils", async () => {
beforeEach(async () => {
vi.clearAllMocks();
mocks.hasWorkspacePermission = true;
+ mocks.currentRoute = { query: {} };
+ mocks.databaseTableRows = [];
+ mocks.databaseTableLoading = false;
({ DatabasesPage } = await import("./DatabasesPage"));
});
@@ -160,6 +211,11 @@ describe("DatabasesPage", () => {
.querySelector("[data-testid='create-database-sheet']")
?.getAttribute("data-open")
).toBe("false");
+ expect(mocks.useProductIntro).toHaveBeenCalledWith({
+ id: "prepare-database",
+ title: "workspace-setup-guide.intro.database-title",
+ description: "workspace-setup-guide.intro.database-description",
+ });
act(() => {
root.unmount();
@@ -180,9 +236,12 @@ describe("DatabasesPage", () => {
});
const createButton = Array.from(container.querySelectorAll("button")).find(
- (button) => button.textContent?.includes("common.create")
+ (button) => button.textContent?.includes("database.create-database")
) as HTMLButtonElement;
expect(createButton).toBeTruthy();
+ expect(createButton.getAttribute("data-product-intro-target")).toBe(
+ "prepare-database"
+ );
await act(async () => {
createButton.click();
@@ -200,4 +259,139 @@ describe("DatabasesPage", () => {
root.unmount();
});
});
+
+ test("shows a transfer tip from the prepare database query", async () => {
+ mocks.currentRoute = {
+ query: {
+ intro: "prepare-database",
+ tip: "transfer-databases-to-project",
+ },
+ };
+ mocks.databaseTableRows = [{ name: "instances/i/databases/db" }];
+ const container = document.createElement("div");
+ const root = createRoot(container);
+
+ await act(async () => {
+ root.render(
+ <MemoryRouter>
+ <DatabasesPage />
+ </MemoryRouter>
+ );
+ await Promise.resolve();
+ });
+
+ expect(container.textContent).toContain(
+ "workspace-setup-guide.prepare-database-tip"
+ );
+ const alert = container.querySelector("[role='alert']");
+ expect(alert?.className).toContain("w-auto");
+ expect(alert?.hasAttribute("data-product-intro-target")).toBe(false);
+ expect(
+ container
+ .querySelector("[data-testid='database-table']")
+ ?.getAttribute("data-selection-column-intro-target")
+ ).toBe("prepare-database");
+ expect(mocks.useProductIntro).toHaveBeenCalledWith({
+ id: "prepare-database",
+ title: "workspace-setup-guide.intro.transfer-title",
+ description: "workspace-setup-guide.intro.transfer-description",
+ });
+ expect(
+ Array.from(container.querySelectorAll("button"))
+ .find((button) =>
+ button.textContent?.includes("database.create-database")
+ )
+ ?.hasAttribute("data-product-intro-target")
+ ).toBe(false);
+
+ act(() => {
+ root.unmount();
+ });
+ });
+
+ test("waits for the table to load before highlighting the transfer selection column", async () => {
+ mocks.currentRoute = {
+ query: {
+ intro: "prepare-database",
+ tip: "transfer-databases-to-project",
+ },
+ };
+ mocks.databaseTableLoading = true;
+ mocks.databaseTableRows = [{ name: "instances/i/databases/db" }];
+ const container = document.createElement("div");
+ const root = createRoot(container);
+
+ await act(async () => {
+ root.render(
+ <MemoryRouter>
+ <DatabasesPage />
+ </MemoryRouter>
+ );
+ await Promise.resolve();
+ });
+
+ expect(mocks.useProductIntro).toHaveBeenCalledWith(
+ expect.objectContaining({
+ id: "prepare-database",
+ disabled: true,
+ })
+ );
+ expect(
+ container
+ .querySelector("[data-testid='database-table']")
+ ?.getAttribute("data-selection-column-intro-target")
+ ).toBe("");
+ expect(
+ Array.from(container.querySelectorAll("button"))
+ .find((button) =>
+ button.textContent?.includes("database.create-database")
+ )
+ ?.hasAttribute("data-product-intro-target")
+ ).toBe(false);
+
+ act(() => {
+ root.unmount();
+ });
+ });
+
+ test("falls back to highlighting create database after transfer context loads with no rows", async () => {
+ mocks.currentRoute = {
+ query: {
+ intro: "prepare-database",
+ tip: "transfer-databases-to-project",
+ },
+ };
+ mocks.databaseTableRows = [];
+ const container = document.createElement("div");
+ const root = createRoot(container);
+
+ await act(async () => {
+ root.render(
+ <MemoryRouter>
+ <DatabasesPage />
+ </MemoryRouter>
+ );
+ await Promise.resolve();
+ });
+
+ expect(container.textContent).not.toContain(
+ "workspace-setup-guide.prepare-database-tip"
+ );
+ expect(
+ container
+ .querySelector("[data-testid='database-table']")
+ ?.getAttribute("data-selection-column-intro-target")
+ ).toBe("");
+ expect(
+ Array.from(container.querySelectorAll("button"))
+ .find((button) =>
+ button.textContent?.includes("database.create-database")
+ )
+ ?.getAttribute("data-product-intro-target")
+ ).toBe("prepare-database");
+
+ act(() => {
+ root.unmount();
+ });
+ });
});
diff --git a/frontend/src/routes/workspace/DatabasesPage.tsx b/frontend/src/routes/workspace/DatabasesPage.tsx
index b5d6a31065..24259c0f3e 100644
--- a/frontend/src/routes/workspace/DatabasesPage.tsx
+++ b/frontend/src/routes/workspace/DatabasesPage.tsx
@@ -3,6 +3,7 @@ import { FieldMaskSchema } from "@bufbuild/protobuf/wkt";
import { Plus } from "lucide-react";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useTranslation } from "react-i18next";
+import { useCurrentRoute } from "@/app/router";
import {
AdvancedSearch,
getValueFromScopes,
@@ -21,6 +22,7 @@ import { EditEnvironmentSheet } from "@/components/EditEnvironmentSheet";
import { EngineIcon } from "@/components/EngineIcon";
import { EnvironmentLabel } from "@/components/EnvironmentLabel";
import { PermissionGuard } from "@/components/PermissionGuard";
+import { Alert } from "@/components/ui/alert";
import { Button } from "@/components/ui/button";
import {
WorkspacePageLayout,
@@ -32,6 +34,12 @@ import {
useURLSearchParam,
} from "@/hooks/useURLSearchParam";
import type { DatabaseFilter } from "@/lib/databaseFilter";
+import {
+ PREPARE_DATABASE_PRODUCT_INTRO,
+ PREPARE_DATABASE_TRANSFER_TIP,
+ PRODUCT_INTRO_TIP_QUERY_KEY,
+ useProductIntro,
+} from "@/lib/productIntro";
import { pushNotification } from "@/stores";
import { useAppStore } from "@/stores/app";
import {
@@ -70,6 +78,7 @@ const parseDatabaseSearch = createAdvancedSearchParser([
export function DatabasesPage() {
const { t } = useTranslation();
+ const currentRoute = useCurrentRoute();
const databasesByName = useAppStore((s) => s.databasesByName);
const getDatabaseByName = useAppStore((s) => s.getDatabaseByName);
const removeDatabaseMetadataCache = useAppStore(
@@ -289,9 +298,34 @@ export function DatabasesPage() {
}
}, []);
+ const showPrepareDatabaseTip =
+ currentRoute.query[PRODUCT_INTRO_TIP_QUERY_KEY] ===
+ PREPARE_DATABASE_TRANSFER_TIP;
+
// Selection state
const [selectedNames, setSelectedNames] = useState<Set<string>>(new Set());
const [visibleDatabases, setVisibleDatabases] = useState<Database[]>([]);
+ const [databaseTableLoading, setDatabaseTableLoading] = useState(true);
+
+ const shouldShowTransferIntro =
+ showPrepareDatabaseTip &&
+ !databaseTableLoading &&
+ visibleDatabases.length > 0;
+ const shouldShowCreateDatabaseIntro =
+ !showPrepareDatabaseTip ||
+ (!databaseTableLoading && visibleDatabases.length === 0);
+ useProductIntro({
+ id: PREPARE_DATABASE_PRODUCT_INTRO,
+ title: shouldShowTransferIntro
+ ? t("workspace-setup-guide.intro.transfer-title")
+ : t("workspace-setup-guide.intro.database-title"),
+ description: shouldShowTransferIntro
+ ? t("workspace-setup-guide.intro.transfer-description")
+ : t("workspace-setup-guide.intro.database-description"),
+ ...(showPrepareDatabaseTip && databaseTableLoading
+ ? { disabled: true }
+ : {}),
+ });
const selectedDatabases = useMemo(() => {
if (selectedNames.size === 0) return [];
@@ -461,6 +495,11 @@ export function DatabasesPage() {
permissions={["bb.instances.list", "bb.issues.create"]}
>
<Button
+ data-product-intro-target={
+ shouldShowCreateDatabaseIntro
+ ? PREPARE_DATABASE_PRODUCT_INTRO
+ : undefined
+ }
disabled={
!hasWorkspacePermissionV2("bb.instances.list") ||
!hasWorkspacePermissionV2("bb.issues.create")
@@ -468,18 +507,28 @@ export function DatabasesPage() {
onClick={() => setShowCreateDrawer(true)}
>
<Plus className="h-4 w-4 mr-1" />
- {t("common.create")}
+ {t("database.create-database")}
</Button>
</PermissionGuard>
</WorkspacePageToolbar>
+ {shouldShowTransferIntro && (
+ <Alert className="mx-4 w-auto" variant="info">
+ {t("workspace-setup-guide.prepare-database-tip")}
+ </Alert>
+ )}
+
<DatabaseTable
filter={filter}
mode="ALL"
selectedNames={selectedNames}
onSelectedNamesChange={setSelectedNames}
onDatabasesChange={setVisibleDatabases}
+ onLoadingChange={setDatabaseTableLoading}
refreshToken={refreshToken}
+ selectionColumnIntroTarget={
+ shouldShowTransferIntro ? PREPARE_DATABASE_PRODUCT_INTRO : undefined
+ }
/>
{/* Batch operations bar */}
diff --git a/frontend/src/routes/workspace/InstanceDetailPage.test.tsx b/frontend/src/routes/workspace/InstanceDetailPage.test.tsx
new file mode 100644
index 0000000000..350da2aed1
--- /dev/null
+++ b/frontend/src/routes/workspace/InstanceDetailPage.test.tsx
@@ -0,0 +1,220 @@
+import type { ReactElement, ReactNode } from "react";
+import { act, useEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Database } from "@/types/proto-es/v1/database_service_pb";
+import type { Instance } from "@/types/proto-es/v1/instance_service_pb";
+import type { Project } from "@/types/proto-es/v1/project_service_pb";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mocks = vi.hoisted(() => ({
+ location: {
+ pathname: "/instances/prod",
+ search: "?syncingInstance=prod",
+ hash: "#databases",
+ },
+ navigate: vi.fn(),
+ databases: [
+ {
+ name: "instances/prod/databases/app",
+ project: "projects/default",
+ },
+ ] as Database[],
+ projects: [{ name: "projects/default" }] as Project[],
+ instance: {
+ name: "instances/prod",
+ title: "Prod",
+ engine: 1,
+ state: 1,
+ environment: "environments/test",
+ roles: [],
+ } as unknown as Instance,
+ fetchProjectList: vi.fn(async () => ({
+ projects: [] as Project[],
+ nextPageToken: "",
+ })),
+ getOrFetchInstanceByName: vi.fn(),
+ removeDatabaseMetadataCache: vi.fn(),
+ removeCacheByInstance: vi.fn(),
+ syncInstance: vi.fn(),
+ batchSyncDatabases: vi.fn(),
+ batchUpdateDatabases: vi.fn(),
+ pushNotification: vi.fn(),
+}));
+
+vi.mock("react-router", () => ({
+ useLocation: () => mocks.location,
+ useNavigate: () => mocks.navigate,
+}));
+
+vi.mock("react-i18next", () => ({
+ initReactI18next: { type: "3rdParty", init: () => {} },
+ useTranslation: () => ({
+ t: (key: string) => key,
+ }),
+}));
+
+vi.mock("@/stores/app", () => {
+ const getState = () => ({
+ databasesByName: {},
+ projectsByName: {},
+ getDatabaseByName: (name: string) =>
+ mocks.databases.find((database) => database.name === name) ??
+ mocks.databases[0],
+ removeDatabaseMetadataCache: mocks.removeDatabaseMetadataCache,
+ instancesByName: { "instances/prod": mocks.instance },
+ environmentList: [],
+ serverInfo: { defaultProject: "projects/default" },
+ });
+ const useAppStore = (selector?: (s: ReturnType<typeof getState>) => unknown) =>
+ selector ? selector(getState()) : getState();
+ useAppStore.getState = () => ({
+ ...getState(),
+ getOrFetchInstanceByName: mocks.getOrFetchInstanceByName,
+ syncInstance: mocks.syncInstance,
+ removeCacheByInstance: mocks.removeCacheByInstance,
+ batchSyncDatabases: mocks.batchSyncDatabases,
+ batchUpdateDatabases: mocks.batchUpdateDatabases,
+ fetchProjectList: mocks.fetchProjectList,
+ });
+ return { useAppStore };
+});
+
+vi.mock("@/stores", () => ({
+ pushNotification: mocks.pushNotification,
+}));
+
+vi.mock("@/utils", () => ({
+ extractProjectResourceName: (name: string) => name.split("/").pop() ?? "",
+ getDefaultPagination: () => 10,
+ instanceV1Name: (instance: Instance) => instance.title,
+ isValidDatabaseName: (name: string) =>
+ /^instances\/[^/]+\/databases\/[^/]+$/.test(name),
+ setDocumentTitle: vi.fn(),
+}));
+
+vi.mock("@/components/AdvancedSearch", () => ({
+ AdvancedSearch: () => <div />,
+ getValueFromScopes: () => undefined,
+}));
+
+vi.mock("@/components/EngineIcon", () => ({
+ EngineIcon: () => <div />,
+}));
+
+vi.mock("@/components/EnvironmentLabel", () => ({
+ EnvironmentLabel: () => <div />,
+}));
+
+vi.mock("@/components/EditEnvironmentSheet", () => ({
+ EditEnvironmentSheet: () => null,
+}));
+
+vi.mock("@/components/ui/tabs", () => ({
+ Tabs: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+ TabsList: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+ TabsPanel: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+ TabsTrigger: ({ children }: { children: ReactNode }) => (
+ <button type="button">{children}</button>
+ ),
+}));
+
+vi.mock("@/components/instance", () => ({
+ InstanceActionDropdown: () => null,
+ InstanceFormBody: () => null,
+ InstanceFormButtons: () => null,
+ InstanceFormProvider: ({ children }: { children: ReactNode }) => (
+ <div>{children}</div>
+ ),
+ InstanceRoleTable: () => null,
+ InstanceSyncButton: () => null,
+ useInstanceFormContext: () => ({ isDirty: false }),
+}));
+
+vi.mock("@/components/database", () => ({
+ CreateDatabaseSheet: () => null,
+ DatabaseBatchOperationsBar: () => null,
+ DatabaseTable: ({
+ onDatabasesChange,
+ }: {
+ onDatabasesChange?: (databases: Database[]) => void;
+ }) => {
+ useEffect(() => {
+ onDatabasesChange?.(mocks.databases);
+ }, [onDatabasesChange]);
+ return <div />;
+ },
+ LabelEditorSheet: () => null,
+ TransferProjectSheet: () => null,
+}));
+
+import { InstanceDetailPage } from "./InstanceDetailPage";
+
+let container: HTMLDivElement;
+let root: ReturnType<typeof createRoot>;
+
+const render = async (element: ReactElement) => {
+ await act(async () => {
+ root.render(element);
+ await Promise.resolve();
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+};
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.location = {
+ pathname: "/instances/prod",
+ search: "?syncingInstance=prod",
+ hash: "#databases",
+ };
+ mocks.databases = [
+ {
+ name: "instances/prod/databases/app",
+ project: "projects/default",
+ },
+ ] as Database[];
+ mocks.projects = [{ name: "projects/default" }] as Project[];
+ mocks.fetchProjectList.mockImplementation(async () => ({
+ projects: mocks.projects,
+ nextPageToken: "",
+ }));
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+});
+
+afterEach(() => {
+ act(() => {
+ root.unmount();
+ });
+ document.body.removeChild(container);
+});
+
+describe("InstanceDetailPage", () => {
+ it("does not show the post-sync transfer action when there is no user project", async () => {
+ await render(<InstanceDetailPage instanceId="prod" />);
+
+ expect(container.textContent).not.toContain(
+ "db.instance-databases-synced-title"
+ );
+ expect(mocks.fetchProjectList).toHaveBeenCalled();
+ });
+
+ it("shows the post-sync transfer action when there is a user project", async () => {
+ mocks.projects = [
+ { name: "projects/default" },
+ { name: "projects/app" },
+ ] as Project[];
+
+ await render(<InstanceDetailPage instanceId="prod" />);
+
+ expect(container.textContent).toContain(
+ "db.instance-databases-synced-title"
+ );
+ });
+});
diff --git a/frontend/src/routes/workspace/InstanceDetailPage.tsx b/frontend/src/routes/workspace/InstanceDetailPage.tsx
index 938d722e7d..d859f062d0 100644
--- a/frontend/src/routes/workspace/InstanceDetailPage.tsx
+++ b/frontend/src/routes/workspace/InstanceDetailPage.tsx
@@ -11,6 +11,7 @@ import {
type ValueOption,
} from "@/components/AdvancedSearch";
import {
+ CreateDatabaseSheet,
DatabaseBatchOperationsBar,
DatabaseTable,
LabelEditorSheet,
@@ -29,6 +30,7 @@ import {
useInstanceFormContext,
} from "@/components/instance";
import { Alert } from "@/components/ui/alert";
+import { Button } from "@/components/ui/button";
import { Tabs, TabsList, TabsPanel, TabsTrigger } from "@/components/ui/tabs";
import { useUnsavedChangesGuard } from "@/hooks/useUnsavedChangesGuard";
import type { DatabaseFilter } from "@/lib/databaseFilter";
@@ -69,6 +71,7 @@ export function InstanceDetailPage({ instanceId }: { instanceId: string }) {
const location = useLocation();
const navigate = useNavigate();
const databasesByName = useAppStore((s) => s.databasesByName);
+ const projectsByName = useAppStore((s) => s.projectsByName);
const getDatabaseByName = useAppStore((s) => s.getDatabaseByName);
const removeDatabaseMetadataCache = useAppStore(
(s) => s.removeDatabaseMetadataCache
@@ -93,10 +96,14 @@ export function InstanceDetailPage({ instanceId }: { instanceId: string }) {
const [selectedNames, setSelectedNames] = useState<Set<string>>(new Set());
const [visibleDatabases, setVisibleDatabases] = useState<Database[]>([]);
const [refreshToken, setRefreshToken] = useState(0);
+ const autoRefreshCountRef = useRef(0);
const [syncing, setSyncing] = useState(false);
const [showLabelEditor, setShowLabelEditor] = useState(false);
const [showEditEnvDrawer, setShowEditEnvDrawer] = useState(false);
const [showTransferDrawer, setShowTransferDrawer] = useState(false);
+ const [showCreateDrawer, setShowCreateDrawer] = useState(false);
+ const [syncingRefreshExhausted, setSyncingRefreshExhausted] = useState(false);
+ const [hasUserProject, setHasUserProject] = useState(false);
const selectedDatabases = useMemo(() => {
if (selectedNames.size === 0) return [];
@@ -118,6 +125,29 @@ export function InstanceDetailPage({ instanceId }: { instanceId: string }) {
setSelectedNames(new Set());
}, []);
+ const syncingInstanceId = useMemo(() => {
+ const query = new URLSearchParams(location.search);
+ return query.get("syncingInstance") || undefined;
+ }, [location.search]);
+
+ useEffect(() => {
+ if (!syncingInstanceId || visibleDatabases.length > 0) {
+ setSyncingRefreshExhausted(false);
+ return;
+ }
+ setSyncingRefreshExhausted(false);
+ autoRefreshCountRef.current = 0;
+ const timer = window.setInterval(() => {
+ autoRefreshCountRef.current += 1;
+ refresh();
+ if (autoRefreshCountRef.current >= 12) {
+ setSyncingRefreshExhausted(true);
+ window.clearInterval(timer);
+ }
+ }, 5000);
+ return () => window.clearInterval(timer);
+ }, [syncingInstanceId, visibleDatabases.length, refresh]);
+
const handleSyncSchema = useCallback(async () => {
if (syncing) return;
setSyncing(true);
@@ -331,6 +361,9 @@ export function InstanceDetailPage({ instanceId }: { instanceId: string }) {
const defaultProjectId = useAppStore((s) =>
extractProjectResourceName(s.serverInfo?.defaultProject ?? "")
);
+ const defaultProjectName = useAppStore(
+ (s) => s.serverInfo?.defaultProject ?? ""
+ );
const unassignedProjectOption = useMemo<ValueOption>(
() => ({
value: defaultProjectId,
@@ -414,6 +447,71 @@ export function InstanceDetailPage({ instanceId }: { instanceId: string }) {
[location.pathname, location.search, navigate]
);
+ useEffect(() => {
+ if (!syncingInstanceId || visibleDatabases.length === 0) {
+ setHasUserProject(false);
+ return;
+ }
+
+ const isUserProject = (project?: { name?: string }) =>
+ !!defaultProjectName &&
+ !!project?.name &&
+ project.name !== defaultProjectName;
+
+ if (Object.values(projectsByName).some(isUserProject)) {
+ setHasUserProject(true);
+ return;
+ }
+
+ let cancelled = false;
+ void (async () => {
+ try {
+ const { projects } = await useAppStore.getState().fetchProjectList({
+ pageSize: getDefaultPagination(),
+ silent: true,
+ });
+ if (cancelled) {
+ return;
+ }
+ setHasUserProject(projects.some(isUserProject));
+ } catch {
+ if (!cancelled) {
+ setHasUserProject(false);
+ }
+ }
+ })();
+
+ return () => {
+ cancelled = true;
+ };
+ }, [
+ defaultProjectName,
+ projectsByName,
+ syncingInstanceId,
+ visibleDatabases.length,
+ ]);
+
+ const showSyncingInstanceHint =
+ !!syncingInstanceId &&
+ visibleDatabases.length === 0 &&
+ !syncingRefreshExhausted;
+ const showNoDatabasesAfterSync =
+ !!syncingInstanceId &&
+ visibleDatabases.length === 0 &&
+ syncingRefreshExhausted;
+ const showPostSyncTransferAction =
+ !!syncingInstanceId && visibleDatabases.length > 0 && hasUserProject;
+ const syncingInstanceTitle =
+ syncingInstanceId === instanceId
+ ? instanceV1Name(instance)
+ : syncingInstanceId;
+ const handleTransferSyncedDatabases = useCallback(() => {
+ setSelectedNames(
+ new Set(visibleDatabases.map((database) => database.name))
+ );
+ setShowTransferDrawer(true);
+ }, [visibleDatabases]);
+
return (
<div className="p-4 flex flex-col gap-y-2">
{/* Archive banner */}
@@ -470,6 +568,54 @@ export function InstanceDetailPage({ instanceId }: { instanceId: string }) {
<TabsPanel value="databases" keepMounted={false}>
<div className="flex flex-col gap-y-2">
+ {showSyncingInstanceHint && (
+ <Alert
+ variant="info"
+ title={t("db.project-instance-syncing-title", {
+ instance: syncingInstanceTitle,
+ })}
+ description={
+ <div className="flex flex-col gap-y-3 sm:flex-row sm:items-center sm:justify-between sm:gap-x-4">
+ <span>{t("db.project-instance-syncing-description")}</span>
+ <Button size="sm" appearance="outline" onClick={refresh}>
+ {t("common.refresh")}
+ </Button>
+ </div>
+ }
+ />
+ )}
+ {showPostSyncTransferAction && (
+ <Alert
+ variant="info"
+ title={t("db.instance-databases-synced-title")}
+ description={
+ <div className="flex flex-col gap-y-3 sm:flex-row sm:items-center sm:justify-between sm:gap-x-4">
+ <span>{t("db.instance-databases-synced-description")}</span>
+ <Button size="sm" onClick={handleTransferSyncedDatabases}>
+ {t("db.instance-databases-synced-action")}
+ </Button>
+ </div>
+ }
+ />
+ )}
+ {showNoDatabasesAfterSync && (
+ <Alert
+ variant="info"
+ title={t("db.instance-no-databases-title")}
+ description={
+ <div className="flex flex-col gap-y-3 sm:flex-row sm:items-center sm:justify-between sm:gap-x-4">
+ <span>{t("db.instance-no-databases-description")}</span>
+ <Button
+ size="sm"
+ appearance="outline"
+ onClick={() => setShowCreateDrawer(true)}
+ >
+ {t("db.instance-no-databases-action")}
+ </Button>
+ </div>
+ }
+ />
+ )}
<AdvancedSearch
params={searchParams}
onParamsChange={setSearchParams}
@@ -493,6 +639,11 @@ export function InstanceDetailPage({ instanceId }: { instanceId: string }) {
onClose={() => setShowTransferDrawer(false)}
onTransfer={handleTransferProject}
/>
+ <CreateDatabaseSheet
+ open={showCreateDrawer}
+ onClose={() => setShowCreateDrawer(false)}
+ instanceName={instanceName}
+ />
<DatabaseTable
filter={filter}
parent={instance.name}
diff --git a/frontend/src/routes/workspace/InstancesPage.tsx b/frontend/src/routes/workspace/InstancesPage.tsx
index d111492e65..cba008c3bb 100644
--- a/frontend/src/routes/workspace/InstancesPage.tsx
+++ b/frontend/src/routes/workspace/InstancesPage.tsx
@@ -80,6 +80,10 @@ import {
serializeAdvancedSearch,
useURLSearchParam,
} from "@/hooks/useURLSearchParam";
+import {
+ CREATE_INSTANCE_PRODUCT_INTRO,
+ useProductIntro,
+} from "@/lib/productIntro";
import { cn } from "@/lib/utils";
import { pushNotification } from "@/stores";
import { useAppStore } from "@/stores/app";
@@ -861,6 +865,12 @@ export function InstancesPage() {
);
const canCreate = hasWorkspacePermissionV2("bb.instances.create");
+ useProductIntro({
+ id: CREATE_INSTANCE_PRODUCT_INTRO,
+ title: t("workspace-setup-guide.intro.instance-title"),
+ description: t("workspace-setup-guide.intro.instance-description"),
+ disabled: !canCreate,
+ });
const allSelected =
instances.length > 0 && selectedNames.size === instances.length;
const someSelected =
@@ -1031,9 +1041,13 @@ export function InstancesPage() {
onParamsChange={setSearchParams}
/>
<PermissionGuard permissions={["bb.instances.create"]}>
- <Button disabled={!canCreate} onClick={navigateToCreate}>
+ <Button
+ data-product-intro-target={CREATE_INSTANCE_PRODUCT_INTRO}
+ disabled={!canCreate}
+ onClick={navigateToCreate}
+ >
<Plus className="h-4 w-4 mr-1" />
- {t("common.create")}
+ {t("instance.connect-instance")}
</Button>
</PermissionGuard>
</WorkspacePageToolbar>
diff --git a/frontend/src/routes/workspace/ProjectsPage.tsx b/frontend/src/routes/workspace/ProjectsPage.tsx
index dc8eaa586a..b23e4623ec 100644
--- a/frontend/src/routes/workspace/ProjectsPage.tsx
+++ b/frontend/src/routes/workspace/ProjectsPage.tsx
@@ -46,6 +46,10 @@ import {
serializeAdvancedSearch,
useURLSearchParam,
} from "@/hooks/useURLSearchParam";
+import {
+ CREATE_PROJECT_PRODUCT_INTRO,
+ useProductIntro,
+} from "@/lib/productIntro";
import { cn } from "@/lib/utils";
import { pushNotification } from "@/stores";
import { useAppStore } from "@/stores/app";
@@ -579,6 +583,13 @@ export function ProjectsPage() {
const canCreate = hasWorkspacePermissionV2("bb.projects.create");
const canDelete = hasWorkspacePermissionV2("bb.projects.delete");
+ useProductIntro({
+ id: CREATE_PROJECT_PRODUCT_INTRO,
+ title: t("workspace-setup-guide.intro.project-title"),
+ description: t("workspace-setup-guide.intro.project-description"),
+ disabled: !canCreate,
+ });
+
const handleCreated = useCallback((project: Project) => {
router.push(projectIssuesRoute(project));
}, []);
@@ -613,6 +624,7 @@ export function ProjectsPage() {
/>
<PermissionGuard permissions={["bb.projects.create"]}>
<Button
+ data-product-intro-target={CREATE_PROJECT_PRODUCT_INTRO}
disabled={!canCreate}
onClick={() => setShowCreateDrawer(true)}
>
diff --git a/frontend/src/routes/workspace/WorkspacePageLayout.test.ts b/frontend/src/routes/workspace/WorkspacePageLayout.test.ts
index 2eb7924405..12e6e16e55 100644
--- a/frontend/src/routes/workspace/WorkspacePageLayout.test.ts
+++ b/frontend/src/routes/workspace/WorkspacePageLayout.test.ts
@@ -131,6 +131,13 @@ describe("workspace list page layout", () => {
}
});
+ test("labels the instances page create action as connect instance", () => {
+ const source = readSettingsPage("InstancesPage.tsx");
+
+ expect(source).toContain('t("instance.connect-instance")');
+ expect(source).not.toContain('{t("common.create")}');
+ });
+
test("does not stack page top padding with general settings form sections", () => {
const source = readSettingsPage("general/GeneralPage.tsx");
diff --git a/frontend/src/stores/app/preferences.ts b/frontend/src/stores/app/preferences.ts
index 7bcb911c06..01e558e5e9 100644
--- a/frontend/src/stores/app/preferences.ts
+++ b/frontend/src/stores/app/preferences.ts
@@ -84,9 +84,8 @@ export const createPreferencesSlice: AppSliceCreator<PreferencesSlice> = (
},
// Mirrors the Pinia `useUIStateStore.getIntroStateByKey`. Reads the per-user
- // localStorage map scoped to the current workspace;
- // `introStateVersion` (read by callers' selectors) is what makes a
- // subsequent `saveIntroStateByKey` re-trigger the read.
+ // localStorage map scoped to the current workspace. React callers should use
+ // `useIntroStateByKey` so writes can trigger a fresh read.
getIntroStateByKey: (key) => {
const email = getCurrentUserEmail(get);
if (!email) return false;
diff --git a/frontend/src/stores/app/types.ts b/frontend/src/stores/app/types.ts
index 6942d8d93d..e19bf0a474 100644
--- a/frontend/src/stores/app/types.ts
+++ b/frontend/src/stores/app/types.ts
@@ -866,8 +866,8 @@ export type NotificationSlice = {
};
export type PreferencesSlice = {
- // Bumped on every intro-state write so selectors reading `getIntroStateByKey`
- // re-run (the flags live in localStorage, not Zustand state).
+ // Bumped on every intro-state write so `useIntroStateByKey` can re-read the
+ // flags, which live in localStorage rather than Zustand state.
introStateVersion: number;
setRecentProject: (name: string) => void;
recordRecentVisit: (path: string, workspaceName?: string) => void;