Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
fix(frontend): explain instance connection test timeouts (#21385)
p0ny000085ad35ac
diff --git a/frontend/src/components/instance/InstanceFormContext.test.tsx b/frontend/src/components/instance/InstanceFormContext.test.tsxindex 287970d0e6..9a4cb2321a 100644--- a/frontend/src/components/instance/InstanceFormContext.test.tsx+++ b/frontend/src/components/instance/InstanceFormContext.test.tsx@@ -1,4 +1,5 @@import { create } from "@bufbuild/protobuf";+import { Code, ConnectError } from "@connectrpc/connect";import type { ReactElement } from "react";import { act } from "react";import { createRoot } from "react-dom/client";@@ -162,13 +163,25 @@ const Probe = () => {);};-const ConnectionProbe = ({ host }: { host: string }) => {+const ConnectionProbe = ({+ host,+ silent = false,+ onResult,+}: {+ host: string;+ silent?: boolean;+ onResult?: (result: { message: string; failureCategory: string }) => void;+}) => {const ctx = useInstanceFormContext();return (<buttontype="button"onClick={async () => {- await ctx.testConnection({ ...ctx.adminDataSource, host });+ const result = await ctx.testConnection(+ { ...ctx.adminDataSource, host },+ silent+ );+ onResult?.(result);}}>Test@@ -243,6 +256,107 @@ describe("InstanceFormProvider", () => {harness.unmount();});+ test.each([+ ["HTTP 504", Code.Unavailable, false, false],+ ["HTTP 504", Code.Unavailable, true, false],+ ["the operation timed out", Code.DeadlineExceeded, false, false],+ ["HTTP 504", Code.Unavailable, false, true],+ ])(+ "explains %s (code %s, cloud %s, silent %s)",+ async (message, code, cloud, silent) => {+ mocks.isSaaSMode = cloud;+ mocks.createInstance.mockRejectedValue(new ConnectError(message, code));+ const onResult = vi.fn();+ const harness = renderIntoContainer();+ await harness.render(+ <InstanceFormProvider>+ <ConnectionProbe+ host="db.example.com"+ silent={silent}+ onResult={onResult}+ />+ </InstanceFormProvider>+ );+ await act(async () => {+ (harness.container.firstElementChild as HTMLButtonElement).click();+ });++ expect(onResult).toHaveBeenCalledWith(+ expect.objectContaining({+ success: false,+ failureCategory: "timeout",+ message: expect.stringContaining(message),+ })+ );+ if (silent) {+ expect(mocks.pushNotification).not.toHaveBeenCalled();+ } else {+ expect(mocks.pushNotification).toHaveBeenCalledWith(+ expect.objectContaining({+ title: "instance.connection-recovery.timeout.test-title",+ description: expect.stringContaining(+ cloud+ ? "instance.connection-recovery.timeout.description-saas"+ : "instance.connection-recovery.timeout.description-self-hosted"+ ),+ })+ );+ expect(mocks.pushNotification).toHaveBeenCalledWith(+ expect.objectContaining({+ description: expect.stringContaining(+ `error-page.error-details: ${message}`+ ),+ })+ );+ }+ harness.unmount();+ }+ );++ test.each([+ ["HTTP 503", Code.Unavailable, undefined, "unknown"],+ ["invalid password", Code.Unauthenticated, "auth_failed", "auth_failed"],+ ["HTTP 504", Code.Unavailable, "ssl_tls_failed", "ssl_tls_failed"],+ ])(+ "preserves the category for %s (code %s, metadata %s)",+ async (message, code, category, expected) => {+ mocks.createInstance.mockRejectedValue(+ new ConnectError(+ message,+ code,+ category+ ? {+ "bytebase-connection-failure-category": category,+ }+ : undefined+ )+ );+ const onResult = vi.fn();+ const harness = renderIntoContainer();+ await harness.render(+ <InstanceFormProvider>+ <ConnectionProbe host="db.example.com" onResult={onResult} />+ </InstanceFormProvider>+ );+ await act(async () => {+ (harness.container.firstElementChild as HTMLButtonElement).click();+ });+ expect(onResult).toHaveBeenCalledWith(+ expect.objectContaining({+ failureCategory: expected,+ message,+ })+ );+ expect(mocks.pushNotification).toHaveBeenCalledWith(+ expect.objectContaining({+ title: "instance.failed-to-connect-instance",+ description: message,+ })+ );+ harness.unmount();+ }+ );+test("explains local-only hosts in Bytebase Cloud without Docker advice", async () => {mocks.isSaaSMode = true;mocks.createInstance.mockRejectedValue(new Error("connection refused"));diff --git a/frontend/src/components/instance/InstanceFormContext.tsx b/frontend/src/components/instance/InstanceFormContext.tsxindex 91309a6632..58c02c4665 100644--- a/frontend/src/components/instance/InstanceFormContext.tsx+++ b/frontend/src/components/instance/InstanceFormContext.tsx@@ -1,5 +1,5 @@import { create } from "@bufbuild/protobuf";-import { ConnectError } from "@connectrpc/connect";+import { Code, ConnectError } from "@connectrpc/connect";import { cloneDeep, isEqual, omit } from "lodash-es";import {createContext,@@ -536,11 +536,20 @@ export function InstanceFormProvider({return { success: true, message: "", failureCategory: "unknown" };};const fail = (host: string, err: unknown): TestConnectionResult => {- const failureCategory = normalizeConnectionFailureCategory(+ let failureCategory = normalizeConnectionFailureCategory(err instanceof ConnectError? err.metadata.get(connectionFailureCategoryHeader): undefined);+ // Gateways may return a bare HTTP error without Bytebase's category.+ // Connect maps 504 to Unavailable, which also covers non-timeout errors.+ if (+ failureCategory === "unknown" &&+ err instanceof ConnectError &&+ (err.code === Code.DeadlineExceeded || err.rawMessage === "HTTP 504")+ ) {+ failureCategory = "timeout";+ }let error =err instanceof ConnectError? err.rawMessage@@ -561,8 +570,18 @@ export function InstanceFormProvider({pushNotification({module: "bytebase",style: "CRITICAL",- title: t("instance.failed-to-connect-instance"),- description: error,+ title:+ failureCategory === "timeout"+ ? t("instance.connection-recovery.timeout.test-title")+ : t("instance.failed-to-connect-instance"),+ description:+ failureCategory === "timeout"+ ? `${t(+ isSaaSMode+ ? "instance.connection-recovery.timeout.description-saas"+ : "instance.connection-recovery.timeout.description-self-hosted"+ )}\n\n${t("error-page.error-details")}: ${error}`+ : error,manualHide: true,});}diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.jsonindex 1e3a3eff70..c1c8ba0169 100644--- a/frontend/src/locales/en-US.json+++ b/frontend/src/locales/en-US.json@@ -1023,13 +1023,14 @@"title": "Check database permissions"},"timeout": {- "description-saas": "The database did not respond in time. Check firewall rules, port settings, network routing, and whether the database allows connections from Bytebase Cloud.",- "description-self-hosted": "The database did not respond in time. Check firewall rules, port settings, network routing, and whether the database allows connections from your Bytebase deployment.",+ "description-saas": "The connection test did not complete in time. Check firewall rules, port settings, network routing, and whether the database allows connections from Bytebase Cloud.",+ "description-self-hosted": "The connection test did not complete in time. Check firewall rules, port settings, network routing, and whether the database allows connections from your Bytebase deployment.","steps": {"load": "Confirm the database is online and accepts new connections.","retry": "If the database is behind a firewall, finish the allowlist or tunnel setup before retrying.","route": "Check routing, proxy, tunnel, port, and connection timeout settings."},+ "test-title": "Connection test timed out","title": "Check firewall and routing"},"tls": {diff --git a/frontend/src/locales/es-ES.json b/frontend/src/locales/es-ES.jsonindex 5c17a68bcf..548f994540 100644--- a/frontend/src/locales/es-ES.json+++ b/frontend/src/locales/es-ES.json@@ -1023,13 +1023,14 @@"title": "Revisar permisos de base de datos"},"timeout": {- "description-saas": "La base de datos no respondió a tiempo. Revisa reglas de firewall, configuración de puertos, rutas de red y si la base de datos permite conexiones desde Bytebase Cloud.",- "description-self-hosted": "La base de datos no respondió a tiempo. Revisa las reglas de firewall, los puertos, las rutas de red y si la base de datos permite conexiones desde tu despliegue de Bytebase.",+ "description-saas": "La prueba de conexión no se completó a tiempo. Revisa reglas de firewall, configuración de puertos, rutas de red y si la base de datos permite conexiones desde Bytebase Cloud.",+ "description-self-hosted": "La prueba de conexión no se completó a tiempo. Revisa las reglas de firewall, los puertos, las rutas de red y si la base de datos permite conexiones desde tu despliegue de Bytebase.","steps": {"load": "Confirma que la base de datos esté en línea y acepte nuevas conexiones.","retry": "Si la base de datos está detrás de un firewall, completa primero la lista permitida o el túnel.","route": "Revisa rutas, proxy, túnel, puerto y configuración de tiempo de espera."},+ "test-title": "La prueba de conexión agotó el tiempo de espera","title": "Revisar firewall y rutas"},"tls": {diff --git a/frontend/src/locales/ja-JP.json b/frontend/src/locales/ja-JP.jsonindex e70bad3e61..7b6effd49a 100644--- a/frontend/src/locales/ja-JP.json+++ b/frontend/src/locales/ja-JP.json@@ -1023,13 +1023,14 @@"title": "データベース権限を確認"},"timeout": {- "description-saas": "データベースが時間内に応答しませんでした。ファイアウォールルール、ポート設定、ネットワークルーティング、および Bytebase Cloud からの接続が許可されているかを確認してください。",- "description-self-hosted": "データベースが時間内に応答しませんでした。ファイアウォールルール、ポート設定、ネットワークルーティング、および Bytebase のデプロイ環境からの接続が許可されているかを確認してください。",+ "description-saas": "接続テストが時間内に完了しませんでした。ファイアウォールルール、ポート設定、ネットワークルーティング、および Bytebase Cloud からの接続が許可されているかを確認してください。",+ "description-self-hosted": "接続テストが時間内に完了しませんでした。ファイアウォールルール、ポート設定、ネットワークルーティング、および Bytebase のデプロイ環境からの接続が許可されているかを確認してください。","steps": {"load": "データベースがオンラインで、新しい接続を受け付けていることを確認してください。","retry": "データベースがファイアウォールの背後にある場合は、許可リストまたはトンネル設定を完了してから再試行してください。","route": "ルーティング、プロキシ、トンネル、ポート、接続タイムアウト設定を確認してください。"},+ "test-title": "接続テストがタイムアウトしました","title": "ファイアウォールとルーティングを確認"},"tls": {diff --git a/frontend/src/locales/vi-VN.json b/frontend/src/locales/vi-VN.jsonindex bc84d26663..be769026b0 100644--- a/frontend/src/locales/vi-VN.json+++ b/frontend/src/locales/vi-VN.json@@ -1023,13 +1023,14 @@"title": "Kiểm tra quyền cơ sở dữ liệu"},"timeout": {- "description-saas": "Cơ sở dữ liệu không phản hồi kịp thời. Kiểm tra firewall, cấu hình port, định tuyến mạng và liệu cơ sở dữ liệu có cho phép kết nối từ Bytebase Cloud hay không.",- "description-self-hosted": "Cơ sở dữ liệu không phản hồi kịp thời. Kiểm tra firewall, cấu hình port, định tuyến mạng và liệu cơ sở dữ liệu có cho phép kết nối từ môi trường triển khai Bytebase hay không.",+ "description-saas": "Kiểm tra kết nối không hoàn tất kịp thời. Kiểm tra firewall, cấu hình port, định tuyến mạng và liệu cơ sở dữ liệu có cho phép kết nối từ Bytebase Cloud hay không.",+ "description-self-hosted": "Kiểm tra kết nối không hoàn tất kịp thời. Kiểm tra firewall, cấu hình port, định tuyến mạng và liệu cơ sở dữ liệu có cho phép kết nối từ môi trường triển khai Bytebase hay không.","steps": {"load": "Xác nhận cơ sở dữ liệu đang online và nhận kết nối mới.","retry": "Nếu cơ sở dữ liệu nằm sau firewall, hãy hoàn tất allowlist hoặc tunnel trước khi thử lại.","route": "Kiểm tra định tuyến, proxy, tunnel, port và cấu hình timeout kết nối."},+ "test-title": "Kiểm tra kết nối đã hết thời gian chờ","title": "Kiểm tra firewall và định tuyến"},"tls": {diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.jsonindex 30a349bb51..4730e85fa9 100644--- a/frontend/src/locales/zh-CN.json+++ b/frontend/src/locales/zh-CN.json@@ -1023,13 +1023,14 @@"title": "检查数据库权限"},"timeout": {- "description-saas": "数据库未及时响应。请检查防火墙规则、端口设置、网络路由,以及数据库是否允许来自 Bytebase Cloud 的连接。",- "description-self-hosted": "数据库未及时响应。请检查防火墙规则、端口设置、网络路由,以及数据库是否允许来自 Bytebase 部署网络的连接。",+ "description-saas": "连接测试未能在规定时间内完成。请检查防火墙规则、端口设置、网络路由,以及数据库是否允许来自 Bytebase Cloud 的连接。",+ "description-self-hosted": "连接测试未能在规定时间内完成。请检查防火墙规则、端口设置、网络路由,以及数据库是否允许来自 Bytebase 部署网络的连接。","steps": {"load": "确认数据库在线并接受新连接。","retry": "如果数据库位于防火墙后,请先完成允许列表或隧道配置再重试。","route": "检查路由、代理、隧道、端口和连接超时设置。"},+ "test-title": "连接测试超时","title": "检查防火墙和路由"},"tls": {