Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

[FE-4010] feat(studio): add read-only replica connection option for HA projects (#49485)

Alaister Young29493e02d0e7
diff --git a/apps/studio/components/interfaces/ConnectSheet/Connect.constants.ts b/apps/studio/components/interfaces/ConnectSheet/Connect.constants.ts
index 86071ccaef9..a588f3320dd 100644
--- a/apps/studio/components/interfaces/ConnectSheet/Connect.constants.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/Connect.constants.ts
@@ -386,6 +386,8 @@ export const PGBOUNCER_ENABLED_BUT_NO_IPV4_ADDON_TEXT =
'Purchase IPv4 add-on or use Shared Pooler if on a IPv4 network'
export const IPV4_ADDON_TEXT = 'Connections are IPv4 proxied with IPv4 add-on'
+export const CONNECTION_SOURCE_LOAD_BALANCER = 'load-balancer'
+
export type ConnectionStringMethod = 'direct' | 'transaction' | 'session'
export const connectionStringMethodOptions: Record<
diff --git a/apps/studio/components/interfaces/ConnectSheet/ConnectConfigSection.tsx b/apps/studio/components/interfaces/ConnectSheet/ConnectConfigSection.tsx
index bb21ae25718..9f96b39af66 100644
--- a/apps/studio/components/interfaces/ConnectSheet/ConnectConfigSection.tsx
+++ b/apps/studio/components/interfaces/ConnectSheet/ConnectConfigSection.tsx
@@ -126,12 +126,14 @@ export function ConnectConfigSection({
layout="horizontal"
label={field.label}
description={field.description}
+ name={`connect-${field.id}`}
>
<Select
value={String(value ?? '')}
onValueChange={(v) => onFieldChange(field.id, v)}
>
<SelectTrigger
+ id={`connect-${field.id}`}
size="small"
className="[&>span:first-child]:flex [&>span:first-child]:items-center [&>span:first-child]:gap-x-2"
>
@@ -167,6 +169,7 @@ export function ConnectConfigSection({
layout="horizontal"
label={field.label}
description={field.description}
+ name={field.id}
className="[&>div>label>span]:break-keep! [&>div>label>span]:text-balance"
>
<Switch
@@ -185,12 +188,14 @@ export function ConnectConfigSection({
layout="horizontal"
label={field.label}
description={field.description}
+ name={`connect-${field.id}`}
>
<MultiSelector
values={Array.isArray(value) ? value : []}
onValuesChange={(v) => onFieldChange(field.id, v)}
>
<MultiSelectorTrigger
+ id={`connect-${field.id}`}
className="w-full"
label="Select features"
badgeLimit="wrap"
diff --git a/apps/studio/components/interfaces/ConnectSheet/ConnectStepsSection.tsx b/apps/studio/components/interfaces/ConnectSheet/ConnectStepsSection.tsx
index 8daa1afee7e..3ebdce75e04 100644
--- a/apps/studio/components/interfaces/ConnectSheet/ConnectStepsSection.tsx
+++ b/apps/studio/components/interfaces/ConnectSheet/ConnectStepsSection.tsx
@@ -210,6 +210,7 @@ export function ConnectStepsSection({ steps, state, projectKeys }: ConnectStepsS
const { ref } = useParams()
const stepsContainerRef = useRef<HTMLDivElement | null>(null)
const deploymentMode = useDeploymentMode()
+ const isHighAvailability = useIsHighAvailability()
const connectionStringPooler = useConnectionStringPooler(deploymentMode)
const { data: ipv4Addon } = useProjectAddonsQuery(
@@ -227,6 +228,7 @@ export function ConnectStepsSection({ steps, state, projectKeys }: ConnectStepsS
connectionMethod: state.connectionMethod,
useSharedPooler: state.useSharedPooler,
hasIpv4Addon: !!ipv4Addon,
+ isHighAvailability,
})
const showSessionPoolerNotice = shouldShowSessionPoolerNotice({
isPlatform: deploymentMode.isPlatform,
diff --git a/apps/studio/components/interfaces/ConnectSheet/ConnectStepsSection.utils.ts b/apps/studio/components/interfaces/ConnectSheet/ConnectStepsSection.utils.ts
index f24bd752559..bba878c92ec 100644
--- a/apps/studio/components/interfaces/ConnectSheet/ConnectStepsSection.utils.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/ConnectStepsSection.utils.ts
@@ -28,14 +28,17 @@ export function shouldShowIpv4AddonNotice({
connectionMethod,
useSharedPooler,
hasIpv4Addon,
+ isHighAvailability,
}: {
isPlatform: boolean
mode: ConnectMode
connectionMethod: FieldValue
useSharedPooler: FieldValue
hasIpv4Addon: boolean
+ isHighAvailability: boolean
}): boolean {
- if (!isPlatform || mode !== 'direct' || hasIpv4Addon) return false
+ // The IPv4 add-on does not apply to Multigres connections
+ if (!isPlatform || mode !== 'direct' || hasIpv4Addon || isHighAvailability) return false
return connectionMethod === 'direct' || (connectionMethod === 'transaction' && !useSharedPooler)
}
diff --git a/apps/studio/components/interfaces/ConnectSheet/ConnectionString.utils.ts b/apps/studio/components/interfaces/ConnectSheet/ConnectionString.utils.ts
index 8158af03229..5f61b16404c 100644
--- a/apps/studio/components/interfaces/ConnectSheet/ConnectionString.utils.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/ConnectionString.utils.ts
@@ -108,6 +108,27 @@ export const buildJdbcString = (params: ConnectionParams) => {
return `jdbc:postgresql://${params.host}:${params.port}/${params.database}?user=${params.user}&password=${PASSWORD_PLACEHOLDER}${extraParams}`
}
+/**
+ * Ensures a connection string's query params carry `sslmode=require` without
+ * dropping params the URI already has (e.g. `options=reference%3D...` or
+ * `sslnegotiation=direct`).
+ */
+export const withRequiredSslmode = (search: string) => {
+ if (!search) return '?sslmode=require'
+ if (search.includes('sslmode=')) return search
+ return `${search}&sslmode=require`
+}
+
+export const buildDotnetConnectionString = (params: ConnectionParams) => {
+ // Multigres only accepts direct SSL negotiation; Npgsql (9+) spells it
+ // `SSL Negotiation=Direct` and throws on the parameter in older versions,
+ // so only emit it when the resolved URI carries the param.
+ const sslNegotiation = params.search.includes('sslnegotiation=direct')
+ ? ';SSL Negotiation=Direct'
+ : ''
+ return `Host=${params.host};Port=${params.port};Database=${params.database};Username=${params.user};Password=${PASSWORD_PLACEHOLDER};SSL Mode=Require;Trust Server Certificate=true${sslNegotiation}`
+}
+
export const buildConnectionStringWithPassword = (
connectionString: string,
password: string
diff --git a/apps/studio/components/interfaces/ConnectSheet/DatabaseSettings.utils.ts b/apps/studio/components/interfaces/ConnectSheet/DatabaseSettings.utils.ts
index 4233c2479ee..8f6a2112822 100644
--- a/apps/studio/components/interfaces/ConnectSheet/DatabaseSettings.utils.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/DatabaseSettings.utils.ts
@@ -17,6 +17,18 @@ export const appendHighAvailabilitySslParams = (uri: string) =>
? uri
: appendConnectionStringParams(uri, HIGH_AVAILABILITY_SSL_PARAMS)
+/**
+ * The Multigres read-only load balancer listens on this port on the same host
+ * as the primary database.
+ */
+export const HIGH_AVAILABILITY_LOAD_BALANCER_PORT = 5433
+
+export const getHighAvailabilityLoadBalancerConnectionInfo = <
+ T extends { db_port: number | string },
+>(
+ connectionInfo: T
+): T => ({ ...connectionInfo, db_port: HIGH_AVAILABILITY_LOAD_BALANCER_PORT })
+
type ConnectionStrings = {
psql: string
uri: string
diff --git a/apps/studio/components/interfaces/ConnectSheet/DirectConnectionExamples.tsx b/apps/studio/components/interfaces/ConnectSheet/DirectConnectionExamples.tsx
index 4f8ceb8b69e..32d61e39794 100644
--- a/apps/studio/components/interfaces/ConnectSheet/DirectConnectionExamples.tsx
+++ b/apps/studio/components/interfaces/ConnectSheet/DirectConnectionExamples.tsx
@@ -55,6 +55,10 @@ func main() {
},
dotnet: {
installCommands: [
+ // SSL Negotiation=Direct in the generated connection string requires Npgsql 9.0+.
+ // Concrete version: quoting a floating version breaks on Windows cmd, and
+ // floating versions fail under Central Package Management (NU1011).
+ 'dotnet add package Npgsql --version 9.0.5',
'dotnet add package Microsoft.Extensions.Configuration.Json --version YOUR_DOTNET_VERSION',
],
},
diff --git a/apps/studio/components/interfaces/ConnectSheet/__tests__/ConnectStepsSection.utils.test.ts b/apps/studio/components/interfaces/ConnectSheet/__tests__/ConnectStepsSection.utils.test.ts
index babff975249..7340051e2db 100644
--- a/apps/studio/components/interfaces/ConnectSheet/__tests__/ConnectStepsSection.utils.test.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/__tests__/ConnectStepsSection.utils.test.ts
@@ -132,6 +132,7 @@ describe('shouldShowIpv4AddonNotice', () => {
connectionMethod: 'direct',
useSharedPooler: false,
hasIpv4Addon: false,
+ isHighAvailability: false,
}
test('returns true for a direct connection with no IPv4 addon', () => {
@@ -169,6 +170,10 @@ describe('shouldShowIpv4AddonNotice', () => {
test('returns false when self-hosted (not platform)', () => {
expect(shouldShowIpv4AddonNotice({ ...BASE, isPlatform: false })).toBe(false)
})
+
+ test('returns false for high-availability projects even with a direct connection and no addon', () => {
+ expect(shouldShowIpv4AddonNotice({ ...BASE, isHighAvailability: true })).toBe(false)
+ })
})
describe('shouldShowSessionPoolerNotice', () => {
diff --git a/apps/studio/components/interfaces/ConnectSheet/__tests__/ConnectionString.utils.test.ts b/apps/studio/components/interfaces/ConnectSheet/__tests__/ConnectionString.utils.test.ts
index 5a07d913ddf..613bf998d84 100644
--- a/apps/studio/components/interfaces/ConnectSheet/__tests__/ConnectionString.utils.test.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/__tests__/ConnectionString.utils.test.ts
@@ -4,6 +4,7 @@ import {
appendConnectionStringParams,
buildConnectionParameters,
buildConnectionStringWithPassword,
+ buildDotnetConnectionString,
buildJdbcString,
buildPsqlCommand,
buildSafeConnectionString,
@@ -11,6 +12,7 @@ import {
parseConnectionParams,
PASSWORD_PLACEHOLDER,
resolveConnectionString,
+ withRequiredSslmode,
} from '../ConnectionString.utils'
describe('parseConnectionParams', () => {
@@ -236,6 +238,52 @@ describe('buildJdbcString', () => {
})
})
+describe('withRequiredSslmode', () => {
+ test('returns ?sslmode=require for an empty search', () => {
+ expect(withRequiredSslmode('')).toBe('?sslmode=require')
+ })
+
+ test('leaves a search that already sets sslmode unchanged', () => {
+ expect(withRequiredSslmode('?sslmode=require&sslnegotiation=direct')).toBe(
+ '?sslmode=require&sslnegotiation=direct'
+ )
+ })
+
+ test('appends sslmode=require to existing params without it', () => {
+ expect(withRequiredSslmode('?options=reference%3Dproj')).toBe(
+ '?options=reference%3Dproj&sslmode=require'
+ )
+ })
+})
+
+describe('buildDotnetConnectionString', () => {
+ const params = {
+ host: 'db.proj.supabase.co',
+ port: '5432',
+ user: 'postgres',
+ database: 'postgres',
+ search: '',
+ }
+
+ test('builds the base Npgsql string without SSL negotiation', () => {
+ expect(buildDotnetConnectionString(params)).toBe(
+ `Host=db.proj.supabase.co;Port=5432;Database=postgres;Username=postgres;Password=${PASSWORD_PLACEHOLDER};SSL Mode=Require;Trust Server Certificate=true`
+ )
+ })
+
+ test('appends SSL Negotiation=Direct when the URI requires direct negotiation', () => {
+ expect(
+ buildDotnetConnectionString({
+ ...params,
+ port: '5433',
+ search: '?sslmode=require&sslnegotiation=direct',
+ })
+ ).toBe(
+ `Host=db.proj.supabase.co;Port=5433;Database=postgres;Username=postgres;Password=${PASSWORD_PLACEHOLDER};SSL Mode=Require;Trust Server Certificate=true;SSL Negotiation=Direct`
+ )
+ })
+})
+
describe('buildConnectionParameters', () => {
test('produces host/port/database/user rows in display order', () => {
expect(
diff --git a/apps/studio/components/interfaces/ConnectSheet/__tests__/DatabaseSettings.utils.test.ts b/apps/studio/components/interfaces/ConnectSheet/__tests__/DatabaseSettings.utils.test.ts
index dcfb2b95deb..b710553ba70 100644
--- a/apps/studio/components/interfaces/ConnectSheet/__tests__/DatabaseSettings.utils.test.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/__tests__/DatabaseSettings.utils.test.ts
@@ -3,8 +3,11 @@ import { describe, expect, test } from 'vitest'
import {
appendHighAvailabilitySslParams,
buildConnectionStringPooler,
+ getConnectionStrings,
+ getHighAvailabilityLoadBalancerConnectionInfo,
getSelfHostedDirectStrings,
getSelfHostedPoolerStrings,
+ HIGH_AVAILABILITY_LOAD_BALANCER_PORT,
HIGH_AVAILABILITY_SSL_PARAMS,
} from '../DatabaseSettings.utils'
import type { DeploymentMode } from '@/hooks/misc/useDeploymentMode'
@@ -239,3 +242,45 @@ describe('appendHighAvailabilitySslParams', () => {
expect(appendHighAvailabilitySslParams('')).toBe('')
})
})
+
+describe('getHighAvailabilityLoadBalancerConnectionInfo', () => {
+ test('swaps the port for the load balancer port and preserves the other fields', () => {
+ const connectionInfo = {
+ db_user: 'postgres',
+ db_port: 5432,
+ db_host: 'db.proj.supabase.co',
+ db_name: 'postgres',
+ }
+
+ expect(getHighAvailabilityLoadBalancerConnectionInfo(connectionInfo)).toEqual({
+ db_user: 'postgres',
+ db_port: HIGH_AVAILABILITY_LOAD_BALANCER_PORT,
+ db_host: 'db.proj.supabase.co',
+ db_name: 'postgres',
+ })
+ })
+
+ test('builds a read-only load balancer connection string on port 5433 with SSL params', () => {
+ const loadBalancerInfo = getHighAvailabilityLoadBalancerConnectionInfo({
+ db_user: 'postgres',
+ db_port: 5432,
+ db_host: 'db.proj.supabase.co',
+ db_name: 'postgres',
+ })
+
+ const result = buildConnectionStringPooler({
+ deploymentMode: platform,
+ connectionInfo: loadBalancerInfo,
+ connectionStringsShared: getConnectionStrings({
+ connectionInfo: loadBalancerInfo,
+ metadata: { projectRef: 'proj' },
+ }),
+ ipv4Addon: false,
+ isHighAvailability: true,
+ })
+
+ expect(result.direct).toBe(
+ `postgresql://postgres:[YOUR-PASSWORD]@db.proj.supabase.co:5433/postgres?${HIGH_AVAILABILITY_SSL_PARAMS}`
+ )
+ })
+})
diff --git a/apps/studio/components/interfaces/ConnectSheet/__tests__/useConnectState.test.ts b/apps/studio/components/interfaces/ConnectSheet/__tests__/useConnectState.test.ts
index 8b6a5b21b67..02cda9fc3a1 100644
--- a/apps/studio/components/interfaces/ConnectSheet/__tests__/useConnectState.test.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/__tests__/useConnectState.test.ts
@@ -7,8 +7,11 @@ vi.mock('common', () => ({
useParams: () => ({ ref: 'test-ref' }),
}))
+const readReplicasMock: {
+ data: Array<{ identifier: string; region: string; inserted_at: string }>
+} = { data: [] }
vi.mock('@/data/read-replicas/replicas-query', () => ({
- useReadReplicasQuery: () => ({ data: [] }),
+ useReadReplicasQuery: () => readReplicasMock,
}))
vi.mock('@/hooks/misc/useCheckEntitlements', () => ({
@@ -498,9 +501,67 @@ describe('useConnectState', () => {
// ============================================================================
describe('high availability projects', () => {
+ const PRIMARY_DATABASE = {
+ identifier: 'test-ref',
+ region: 'ap-southeast-1',
+ inserted_at: '2024-01-01T00:00:00Z',
+ }
+ const REPLICA_DATABASE = {
+ identifier: 'test-ref-rr-abcdefgh',
+ region: 'ap-southeast-1',
+ inserted_at: '2024-01-02T00:00:00Z',
+ }
+
afterEach(async () => {
const { useIsHighAvailability } = await import('@/hooks/misc/useSelectedProject')
vi.mocked(useIsHighAvailability).mockReturnValue(false)
+ readReplicasMock.data = []
+ })
+
+ test('should offer only the primary and the load balancer as sources for HA projects', async () => {
+ const { useIsHighAvailability } = await import('@/hooks/misc/useSelectedProject')
+ vi.mocked(useIsHighAvailability).mockReturnValue(true)
+ readReplicasMock.data = [PRIMARY_DATABASE, REPLICA_DATABASE]
+
+ const { result } = renderHook(() => useConnectState({ mode: 'direct' }))
+
+ const options = result.current.getFieldOptions('connectionSource')
+ expect(options).toEqual([
+ { value: 'test-ref', label: 'Primary database' },
+ { value: 'load-balancer', label: 'Replica (read-only)' },
+ ])
+ })
+
+ test('should keep replicas as sources and omit the load balancer for non-HA projects', () => {
+ readReplicasMock.data = [PRIMARY_DATABASE, REPLICA_DATABASE]
+
+ const { result } = renderHook(() => useConnectState({ mode: 'direct' }))
+
+ const options = result.current.getFieldOptions('connectionSource')
+ expect(options.map((o) => o.value)).toEqual(['test-ref', 'test-ref-rr-abcdefgh'])
+ expect(options.some((o) => o.value === 'load-balancer')).toBe(false)
+ })
+
+ test('should coerce a replica connection source to the primary for HA projects', async () => {
+ const { useIsHighAvailability } = await import('@/hooks/misc/useSelectedProject')
+ vi.mocked(useIsHighAvailability).mockReturnValue(true)
+
+ const { result } = renderHook(() =>
+ useConnectState({ mode: 'direct', connectionSource: 'test-ref-rr-abcdefgh' })
+ )
+
+ expect(result.current.state.connectionSource).toBe('test-ref')
+ })
+
+ test('should preserve the load balancer as a valid connection source for HA projects', async () => {
+ const { useIsHighAvailability } = await import('@/hooks/misc/useSelectedProject')
+ vi.mocked(useIsHighAvailability).mockReturnValue(true)
+
+ const { result } = renderHook(() =>
+ useConnectState({ mode: 'direct', connectionSource: 'load-balancer' })
+ )
+
+ expect(result.current.state.connectionSource).toBe('load-balancer')
})
test('should hide connectionMethod field for HA projects', async () => {
diff --git a/apps/studio/components/interfaces/ConnectSheet/content/steps/direct-connection/content.tsx b/apps/studio/components/interfaces/ConnectSheet/content/steps/direct-connection/content.tsx
index b7ab7b99d61..3f519fe7969 100644
--- a/apps/studio/components/interfaces/ConnectSheet/content/steps/direct-connection/content.tsx
+++ b/apps/studio/components/interfaces/ConnectSheet/content/steps/direct-connection/content.tsx
@@ -1,19 +1,17 @@
-import { useParams } from 'common'
import { Check, KeyRound } from 'lucide-react'
import { useMemo, useState } from 'react'
+import { cn } from 'ui'
import { CodeBlock } from 'ui-patterns/CodeBlock'
import { GenericSkeletonLoader } from 'ui-patterns/ShimmeringLoader'
-import { buildConnectionStringPooler, getConnectionStrings } from '../../../DatabaseSettings.utils'
-import { getAddons } from '@/components/interfaces/Billing/Subscription/Subscription.utils'
import {
+ CONNECTION_SOURCE_LOAD_BALANCER,
DATABASE_CONNECTION_TYPES,
type ConnectionStringMethod,
type DatabaseConnectionType,
} from '@/components/interfaces/ConnectSheet/Connect.constants'
import type {
ConnectionStringPooler,
- DeploymentMode,
StepContentProps,
} from '@/components/interfaces/ConnectSheet/Connect.types'
import { ConnectionParameters } from '@/components/interfaces/ConnectSheet/ConnectionParameters'
@@ -28,114 +26,14 @@ import {
resolveConnectionString,
} from '@/components/interfaces/ConnectSheet/ConnectionString.utils'
import { PasswordEncodingNote } from '@/components/interfaces/ConnectSheet/PasswordEncodingNote'
+import { useConnectionStringDatabases } from '@/components/interfaces/ConnectSheet/useConnectionStringDatabases'
import { ResetDbPasswordDialog } from '@/components/interfaces/Settings/Database/DatabaseSettings/ResetDbPasswordDialog'
import { InlineLink } from '@/components/ui/InlineLink'
-import { usePgbouncerConfigQuery } from '@/data/database/pgbouncer-config-query'
-import { useSupavisorConfigurationQuery } from '@/data/database/supavisor-configuration-query'
-import { useReadReplicasQuery } from '@/data/read-replicas/replicas-query'
-import { useProjectAddonsQuery } from '@/data/subscriptions/project-addons-query'
import { useCheckEntitlements } from '@/hooks/misc/useCheckEntitlements'
import { useIsHighAvailability } from '@/hooks/misc/useSelectedProject'
import { DOCS_URL } from '@/lib/constants'
-import { pluckObjectFields } from '@/lib/helpers'
import { useTrack } from '@/lib/telemetry/track'
-/**
- * [Joshen] ConnectStepsSection does something similar but since only this page needs to consider connection strings
- * from all databases (including read replicas), am opting to separate the logic for retrieving connection strings here
- *
- * We can however, consider to shift this logic into ConnectStepsSection, such that we can consider read replicas for
- * the other tabs like "Framework" and "ORM" too. However, leaving them out for now and only updating "Direct"
- */
-const useConnectionStringDatabases = (deploymentMode: DeploymentMode) => {
- const { ref: projectRef } = useParams()
- const { hasAccess: allowPgBouncerSelection } = useCheckEntitlements('dedicated_pooler')
- const isHighAvailability = useIsHighAvailability()
-
- const { data: databases = [] } = useReadReplicasQuery({ projectRef })
- // Multigres has no pooler, so the pooler config endpoints don't apply
- const { data: pgbouncerConfig } = usePgbouncerConfigQuery(
- { projectRef },
- { enabled: !isHighAvailability }
- )
- const { data: supavisorConfig } = useSupavisorConfigurationQuery(
- { projectRef },
- { enabled: !isHighAvailability }
- )
- const { data: addons } = useProjectAddonsQuery({ projectRef })
- const { ipv4: ipv4Addon } = getAddons(addons?.selected_addons ?? [])
-
- // Memoized so the per-database pooler bag (consumed by resolveConnectionString
- // downstream) keeps a stable identity across renders. Without this the inner
- // pluckObjectFields/getConnectionStrings calls would mint fresh objects every
- // render and ripple through the resolveConnectionString useMemo below.
- return useMemo(() => {
- const DB_FIELDS = ['db_host', 'db_name', 'db_port', 'db_user', 'inserted_at']
- const emptyState = { db_user: '', db_host: '', db_port: '', db_name: '' }
-
- return Object.fromEntries(
- databases.map((db) => {
- const connectionInfo = pluckObjectFields(db || emptyState, DB_FIELDS)
- const poolingConfigurationShared = supavisorConfig?.find(
- (x) => x.identifier === db.identifier
- )
- const poolingConfigurationDedicated = allowPgBouncerSelection ? pgbouncerConfig : undefined
-
- const connectionStringsShared = getConnectionStrings({
- connectionInfo,
- poolingInfo: {
- connectionString: poolingConfigurationShared?.connection_string ?? '',
- db_host: poolingConfigurationShared?.db_host ?? '',
- db_name: poolingConfigurationShared?.db_name ?? '',
- db_port: poolingConfigurationShared?.db_port ?? 0,
- db_user: poolingConfigurationShared?.db_user ?? '',
- },
- metadata: { projectRef: db.identifier },
- })
-
- const connectionStringsDedicated =
- poolingConfigurationDedicated !== undefined
- ? getConnectionStrings({
- connectionInfo,
- poolingInfo: {
- connectionString: poolingConfigurationDedicated.connection_string.replace(
- projectRef ?? '_',
- db.identifier
- ),
- db_host: poolingConfigurationDedicated.db_host,
- db_name: poolingConfigurationDedicated.db_name,
- db_port: poolingConfigurationDedicated.db_port,
- db_user: poolingConfigurationDedicated.db_user,
- },
- metadata: { projectRef: db.identifier },
- })
- : undefined
-
- return [
- db.identifier,
- buildConnectionStringPooler({
- deploymentMode,
- connectionInfo,
- connectionStringsShared,
- connectionStringsDedicated,
- ipv4Addon: !!ipv4Addon,
- isHighAvailability,
- }),
- ]
- })
- )
- }, [
- databases,
- pgbouncerConfig,
- supavisorConfig,
- allowPgBouncerSelection,
- ipv4Addon,
- projectRef,
- deploymentMode,
- isHighAvailability,
- ])
-}
-
const CONNECTION_METHOD_TO_TELEMETRY: Record<
ConnectionStringMethod,
'direct' | 'transaction_pooler' | 'session_pooler'
@@ -156,6 +54,8 @@ function DirectConnectionContent({ state, deploymentMode }: StepContentProps) {
const [temporaryDatabasePassword, setTemporaryDatabasePassword] = useState('')
const connectionSource = state.connectionSource
+ const isLoadBalancerSelected =
+ isHighAvailability && connectionSource === CONNECTION_SOURCE_LOAD_BALANCER
const connectionType = (state.connectionType as DatabaseConnectionType) ?? 'uri'
const connectionMethod = (state.connectionMethod as ConnectionStringMethod) ?? 'direct'
const useSharedPooler = Boolean(state.useSharedPooler)
@@ -239,17 +139,19 @@ function DirectConnectionContent({ state, deploymentMode }: StepContentProps) {
const showPasswordPlaceholder = connectionString.includes(PASSWORD_PLACEHOLDER)
const showSelfHostedDirectNotice = deploymentMode.isSelfHosted && connectionMethod === 'direct'
const showPoolerTitle = deploymentMode.isPlatform && !!poolerBadge && !isHighAvailability
+ const titleBadge = isLoadBalancerSelected ? 'Read-only' : poolerBadge
+ const showTitleBadge = isLoadBalancerSelected || showPoolerTitle
const showResetInTitle =
deploymentMode.isPlatform && showPasswordPlaceholder && !temporaryDatabasePassword
- const showStringTitleRow = showPoolerTitle || showResetInTitle
+ const showStringTitleRow = showTitleBadge || showResetInTitle
return (
<div className="flex flex-col gap-3">
<div className="overflow-hidden rounded-lg border bg-surface-75">
{showStringTitleRow && (
<div className="flex items-center justify-between gap-2 border-b bg-surface-100 py-2 pl-4 pr-2">
- {showPoolerTitle ? (
- <span className="text-xs text-foreground-light">{poolerBadge}</span>
+ {showTitleBadge ? (
+ <span className="text-xs text-foreground-light">{titleBadge}</span>
) : (
<span />
)}
@@ -282,6 +184,15 @@ function DirectConnectionContent({ state, deploymentMode }: StepContentProps) {
)}
</div>
{showPasswordPlaceholder && <PasswordEncodingNote />}
+ {/* Persistent live region so screen readers announce the read-only state
+ when the load balancer is selected */}
+ <p
+ role="status"
+ className={cn('text-sm text-foreground-lighter', !isLoadBalancerSelected && 'sr-only')}
+ >
+ {isLoadBalancerSelected &&
+ 'Replica connections are read-only. Connect to the primary database for writes.'}
+ </p>
{showSelfHostedDirectNotice && (
<p className="text-sm text-foreground-lighter">
Manually{' '}
diff --git a/apps/studio/components/interfaces/ConnectSheet/content/steps/direct-files/content.tsx b/apps/studio/components/interfaces/ConnectSheet/content/steps/direct-files/content.tsx
index eaf3d943483..d6b97731e03 100644
--- a/apps/studio/components/interfaces/ConnectSheet/content/steps/direct-files/content.tsx
+++ b/apps/studio/components/interfaces/ConnectSheet/content/steps/direct-files/content.tsx
@@ -1,8 +1,10 @@
import { useEffect, useMemo, useState } from 'react'
+import { cn } from 'ui'
import { MultipleCodeBlock } from 'ui-patterns/MultipleCodeBlock'
import { GenericSkeletonLoader } from 'ui-patterns/ShimmeringLoader'
import {
+ CONNECTION_SOURCE_LOAD_BALANCER,
type ConnectionStringMethod,
type DatabaseConnectionType,
} from '@/components/interfaces/ConnectSheet/Connect.constants'
@@ -10,12 +12,16 @@ import type { StepContentProps } from '@/components/interfaces/ConnectSheet/Conn
import { ConnectionParameters } from '@/components/interfaces/ConnectSheet/ConnectionParameters'
import {
buildConnectionParameters,
+ buildDotnetConnectionString,
buildSafeConnectionString,
parseConnectionParams,
PASSWORD_PLACEHOLDER,
resolveConnectionString,
+ withRequiredSslmode,
} from '@/components/interfaces/ConnectSheet/ConnectionString.utils'
import { PasswordEncodingNote } from '@/components/interfaces/ConnectSheet/PasswordEncodingNote'
+import { useConnectionStringDatabases } from '@/components/interfaces/ConnectSheet/useConnectionStringDatabases'
+import { useIsHighAvailability } from '@/hooks/misc/useSelectedProject'
type DirectFilesConfig = {
files: {
@@ -28,11 +34,20 @@ type DirectFilesConfig = {
passwordInUrl?: boolean
}
-function DirectFilesContent({ state, connectionStringPooler }: StepContentProps) {
+function DirectFilesContent({ state, deploymentMode }: StepContentProps) {
+ const isHighAvailability = useIsHighAvailability()
+
+ const connectionSource = state.connectionSource
+ const isLoadBalancerSelected =
+ isHighAvailability && connectionSource === CONNECTION_SOURCE_LOAD_BALANCER
const connectionType = (state.connectionType as DatabaseConnectionType) ?? 'uri'
const connectionMethod = (state.connectionMethod as ConnectionStringMethod) ?? 'direct'
const useSharedPooler = Boolean(state.useSharedPooler)
+ const connectionStrings = useConnectionStringDatabases(deploymentMode)
+ const connectionStringPooler =
+ connectionStrings[connectionSource as keyof typeof connectionStrings]
+
const resolvedConnectionString = useMemo(
() =>
resolveConnectionString({
@@ -125,7 +140,7 @@ func main() {
language: 'json',
code: `{
"ConnectionStrings": {
- "DefaultConnection": "Host=${connectionParams.host};Database=${connectionParams.database};Username=${connectionParams.user};Password=${PASSWORD_PLACEHOLDER};SSL Mode=Require;Trust Server Certificate=true"
+ "DefaultConnection": "${buildDotnetConnectionString(connectionParams)}"
}
}`,
},
@@ -180,7 +195,7 @@ PORT = os.getenv("port")
DBNAME = os.getenv("dbname")
# Construct the SQLAlchemy connection string
-DATABASE_URL = f"postgresql+psycopg2://{USER}:{PASSWORD}@{HOST}:{PORT}/{DBNAME}?sslmode=require"
+DATABASE_URL = f"postgresql+psycopg2://{USER}:{PASSWORD}@{HOST}:{PORT}/{DBNAME}${withRequiredSslmode(connectionParams.search)}"
# Create the SQLAlchemy engine
engine = create_engine(DATABASE_URL)
@@ -235,10 +250,37 @@ except Exception as e:
return null
}
+ const codeBlock = (
+ <MultipleCodeBlock
+ files={config.files}
+ value={activeFile}
+ onValueChange={setActiveFile}
+ className={isLoadBalancerSelected ? 'rounded-none border-0' : undefined}
+ />
+ )
+
return (
<div className="flex flex-col gap-3">
- <MultipleCodeBlock files={config.files} value={activeFile} onValueChange={setActiveFile} />
+ {isLoadBalancerSelected ? (
+ <div className="overflow-hidden rounded-lg border">
+ <div className="flex items-center border-b bg-surface-100 py-2 pl-4 pr-2">
+ <span className="text-xs text-foreground-light">Read-only</span>
+ </div>
+ {codeBlock}
+ </div>
+ ) : (
+ codeBlock
+ )}
{config.passwordInUrl && <PasswordEncodingNote />}
+ {/* Persistent live region so screen readers announce the read-only state
+ when the load balancer is selected */}
+ <p
+ role="status"
+ className={cn('text-sm text-foreground-lighter', !isLoadBalancerSelected && 'sr-only')}
+ >
+ {isLoadBalancerSelected &&
+ 'Replica connections are read-only. Connect to the primary database for writes.'}
+ </p>
<ConnectionParameters parameters={buildConnectionParameters(connectionParams)} />
</div>
)
diff --git a/apps/studio/components/interfaces/ConnectSheet/useConnectState.ts b/apps/studio/components/interfaces/ConnectSheet/useConnectState.ts
index 82dbe3966de..dd460d9fa48 100644
--- a/apps/studio/components/interfaces/ConnectSheet/useConnectState.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/useConnectState.ts
@@ -3,6 +3,7 @@ import { useCallback, useMemo, useState } from 'react'
import { MCP_CLIENTS } from 'ui-patterns/McpUrlBuilder'
import {
+ CONNECTION_SOURCE_LOAD_BALANCER,
connectionStringMethodOptions,
DATABASE_CONNECTION_TYPES,
FRAMEWORKS,
@@ -50,11 +51,15 @@ function getFieldOptionsFromSource({
state,
databases,
deploymentMode,
+ isHighAvailability,
+ projectRef,
}: {
source: string
state: ConnectState
databases: Database[]
deploymentMode: DeploymentMode
+ isHighAvailability: boolean
+ projectRef?: string
}): FieldOption[] {
switch (source) {
case 'frameworks':
@@ -135,15 +140,23 @@ function getFieldOptionsFromSource({
}))
}
- case 'connectionSources':
- return databases.map((db) => {
+ case 'connectionSources': {
+ const options = databases.map((db) => {
const region = formatDatabaseRegion(db?.region ?? '')
const id = formatDatabaseID(db.identifier ?? '')
const label = db.identifier.includes('-rr-')
- ? `Read Replica (${region} - ${id})`
- : 'Primary Database'
+ ? `Read replica (${region} - ${id})`
+ : 'Primary database'
return { value: db.identifier, label }
})
+ if (!isHighAvailability) return options
+ // Multigres replicas are only reachable through the read-only load
+ // balancer, so the sources are the primary and the load balancer.
+ return [
+ ...options.filter((option) => option.value === projectRef),
+ { value: CONNECTION_SOURCE_LOAD_BALANCER, label: 'Replica (read-only)' },
+ ]
+ }
case 'connectionTypes':
return DATABASE_CONNECTION_TYPES.map((t) => ({
@@ -185,11 +198,15 @@ function resolveFieldOptionsWithSource({
state,
databases,
deploymentMode,
+ isHighAvailability,
+ projectRef,
}: {
field: ResolvedField
state: ConnectState
databases: Database[]
deploymentMode: DeploymentMode
+ isHighAvailability: boolean
+ projectRef?: string
}): FieldOption[] {
// If already resolved (from conditional resolution)
if (field.resolvedOptions.length > 0) {
@@ -204,6 +221,8 @@ function resolveFieldOptionsWithSource({
state,
databases,
deploymentMode,
+ isHighAvailability,
+ projectRef,
})
}
@@ -361,12 +380,21 @@ export function useConnectState(initialState?: Partial<ConnectState>): UseConnec
// Multigres has no pooler, so pooler-flavored selections restored from the
// URL or localStorage (shared across projects) must never leak into an HA
- // project — every consumer sees the direct connection method.
- const resolvedState = useMemo(
- () =>
- isHighAvailability ? { ...state, connectionMethod: 'direct', useSharedPooler: false } : state,
- [state, isHighAvailability]
- )
+ // project — every consumer sees the direct connection method. Likewise a
+ // stale connection source (e.g. a replica identifier restored from the URL)
+ // falls back to the primary, since HA sources are only the primary and the
+ // load balancer.
+ const resolvedState = useMemo(() => {
+ if (!isHighAvailability) return state
+
+ const next: ConnectState = { ...state, connectionMethod: 'direct', useSharedPooler: false }
+ const hasValidSource =
+ state.connectionSource === undefined ||
+ state.connectionSource === projectRef ||
+ state.connectionSource === CONNECTION_SOURCE_LOAD_BALANCER
+ if (!hasValidSource) next.connectionSource = projectRef ?? '_'
+ return next
+ }, [state, isHighAvailability, projectRef])
const activeFields = useMemo(() => {
let fields = getActiveFields(connectSchema, resolvedState)
@@ -394,9 +422,11 @@ export function useConnectState(initialState?: Partial<ConnectState>): UseConnec
state: resolvedState,
databases,
deploymentMode,
+ isHighAvailability,
+ projectRef,
})
},
- [activeFields, resolvedState, databases, deploymentMode]
+ [activeFields, resolvedState, databases, deploymentMode, isHighAvailability, projectRef]
)
return {
diff --git a/apps/studio/components/interfaces/ConnectSheet/useConnectionStringDatabases.ts b/apps/studio/components/interfaces/ConnectSheet/useConnectionStringDatabases.ts
new file mode 100644
index 00000000000..5909a068144
--- /dev/null
+++ b/apps/studio/components/interfaces/ConnectSheet/useConnectionStringDatabases.ts
@@ -0,0 +1,137 @@
+import { useParams } from 'common'
+import { useMemo } from 'react'
+
+import { CONNECTION_SOURCE_LOAD_BALANCER } from './Connect.constants'
+import type { DeploymentMode } from './Connect.types'
+import {
+ buildConnectionStringPooler,
+ getConnectionStrings,
+ getHighAvailabilityLoadBalancerConnectionInfo,
+} from './DatabaseSettings.utils'
+import { getAddons } from '@/components/interfaces/Billing/Subscription/Subscription.utils'
+import { usePgbouncerConfigQuery } from '@/data/database/pgbouncer-config-query'
+import { useSupavisorConfigurationQuery } from '@/data/database/supavisor-configuration-query'
+import { useReadReplicasQuery } from '@/data/read-replicas/replicas-query'
+import { useProjectAddonsQuery } from '@/data/subscriptions/project-addons-query'
+import { useCheckEntitlements } from '@/hooks/misc/useCheckEntitlements'
+import { useIsHighAvailability } from '@/hooks/misc/useSelectedProject'
+import { pluckObjectFields } from '@/lib/helpers'
+
+/**
+ * [Joshen] ConnectStepsSection does something similar but since only this page needs to consider connection strings
+ * from all databases (including read replicas), am opting to separate the logic for retrieving connection strings here
+ *
+ * We can however, consider to shift this logic into ConnectStepsSection, such that we can consider read replicas for
+ * the other tabs like "Framework" and "ORM" too. However, leaving them out for now and only updating "Direct"
+ */
+export const useConnectionStringDatabases = (deploymentMode: DeploymentMode) => {
+ const { ref: projectRef } = useParams()
+ const { hasAccess: allowPgBouncerSelection } = useCheckEntitlements('dedicated_pooler')
+ const isHighAvailability = useIsHighAvailability()
+
+ const { data: databases = [] } = useReadReplicasQuery({ projectRef })
+ // Multigres has no pooler, so the pooler config endpoints don't apply
+ const { data: pgbouncerConfig } = usePgbouncerConfigQuery(
+ { projectRef },
+ { enabled: !isHighAvailability }
+ )
+ const { data: supavisorConfig } = useSupavisorConfigurationQuery(
+ { projectRef },
+ { enabled: !isHighAvailability }
+ )
+ const { data: addons } = useProjectAddonsQuery({ projectRef })
+ const { ipv4: ipv4Addon } = getAddons(addons?.selected_addons ?? [])
+
+ // Memoized so the per-database pooler bag (consumed by resolveConnectionString
+ // downstream) keeps a stable identity across renders. Without this the inner
+ // pluckObjectFields/getConnectionStrings calls would mint fresh objects every
+ // render and ripple through the resolveConnectionString useMemo below.
+ return useMemo(() => {
+ const DB_FIELDS = ['db_host', 'db_name', 'db_port', 'db_user', 'inserted_at']
+ const emptyState = { db_user: '', db_host: '', db_port: '', db_name: '' }
+
+ const connectionStringsByIdentifier = Object.fromEntries(
+ databases.map((db) => {
+ const connectionInfo = pluckObjectFields(db || emptyState, DB_FIELDS)
+ const poolingConfigurationShared = supavisorConfig?.find(
+ (x) => x.identifier === db.identifier
+ )
+ const poolingConfigurationDedicated = allowPgBouncerSelection ? pgbouncerConfig : undefined
+
+ const connectionStringsShared = getConnectionStrings({
+ connectionInfo,
+ poolingInfo: {
+ connectionString: poolingConfigurationShared?.connection_string ?? '',
+ db_host: poolingConfigurationShared?.db_host ?? '',
+ db_name: poolingConfigurationShared?.db_name ?? '',
+ db_port: poolingConfigurationShared?.db_port ?? 0,
+ db_user: poolingConfigurationShared?.db_user ?? '',
+ },
+ metadata: { projectRef: db.identifier },
+ })
+
+ const connectionStringsDedicated =
+ poolingConfigurationDedicated !== undefined
+ ? getConnectionStrings({
+ connectionInfo,
+ poolingInfo: {
+ connectionString: poolingConfigurationDedicated.connection_string.replace(
+ projectRef ?? '_',
+ db.identifier
+ ),
+ db_host: poolingConfigurationDedicated.db_host,
+ db_name: poolingConfigurationDedicated.db_name,
+ db_port: poolingConfigurationDedicated.db_port,
+ db_user: poolingConfigurationDedicated.db_user,
+ },
+ metadata: { projectRef: db.identifier },
+ })
+ : undefined
+
+ return [
+ db.identifier,
+ buildConnectionStringPooler({
+ deploymentMode,
+ connectionInfo,
+ connectionStringsShared,
+ connectionStringsDedicated,
+ ipv4Addon: !!ipv4Addon,
+ isHighAvailability,
+ }),
+ ]
+ })
+ )
+
+ // The Multigres load balancer is not a database row — it shares the
+ // primary's host on a dedicated read-only port.
+ const primaryDatabase = isHighAvailability
+ ? databases.find((db) => db.identifier === projectRef)
+ : undefined
+ if (primaryDatabase) {
+ const loadBalancerInfo = getHighAvailabilityLoadBalancerConnectionInfo(
+ pluckObjectFields(primaryDatabase, DB_FIELDS)
+ )
+ connectionStringsByIdentifier[CONNECTION_SOURCE_LOAD_BALANCER] = buildConnectionStringPooler({
+ deploymentMode,
+ connectionInfo: loadBalancerInfo,
+ connectionStringsShared: getConnectionStrings({
+ connectionInfo: loadBalancerInfo,
+ metadata: { projectRef },
+ }),
+ ipv4Addon: false,
+ isHighAvailability,
+ })
+ }
+
+ return connectionStringsByIdentifier
+ }, [
+ databases,
+ pgbouncerConfig,
+ supavisorConfig,
+ allowPgBouncerSelection,
+ ipv4Addon,
+ projectRef,
+ deploymentMode,
+ isHighAvailability,
+ ])
+}
diff --git a/packages/ui-patterns/src/MultipleCodeBlock/index.tsx b/packages/ui-patterns/src/MultipleCodeBlock/index.tsx
index 76030116265..901be3a7f86 100644
--- a/packages/ui-patterns/src/MultipleCodeBlock/index.tsx
+++ b/packages/ui-patterns/src/MultipleCodeBlock/index.tsx
@@ -1,5 +1,5 @@
import { useEffect, useState } from 'react'
-import { Tabs, TabsContent, TabsList, TabsTrigger } from 'ui'
+import { cn, Tabs, TabsContent, TabsList, TabsTrigger } from 'ui'
import { CodeBlock, type CodeBlockLang } from 'ui-patterns/CodeBlock'
interface MultipleCodeBlockFile {
@@ -12,6 +12,7 @@ interface MultipleCodeBlockProps {
files: MultipleCodeBlockFile[]
value?: string
onValueChange?: (value: string) => void
+ className?: string
}
const languageAliases: Record<string, CodeBlockLang> = {
@@ -91,7 +92,12 @@ const resolveLanguage = (language: string | undefined, name: string): CodeBlockL
return inferLanguageFromName(name) ?? 'js'
}
-export const MultipleCodeBlock = ({ files, value, onValueChange }: MultipleCodeBlockProps) => {
+export const MultipleCodeBlock = ({
+ files,
+ value,
+ onValueChange,
+ className,
+}: MultipleCodeBlockProps) => {
if (!files?.length) {
return null
}
@@ -128,7 +134,7 @@ export const MultipleCodeBlock = ({ files, value, onValueChange }: MultipleCodeB
<Tabs
value={activeValue}
onValueChange={handleValueChange}
- className="border rounded-lg gap-0 space-y-0 overflow-hidden"
+ className={cn('border rounded-lg gap-0 space-y-0 overflow-hidden', className)}
>
<TabsList className="bg-surface-75 px-5 gap-5 overflow-x-auto border-0 border-b">
{files.map((file) => (