feat(auth): allow opting in to creating indexes on auth.users (supabase#40955)

issuedat · web-flow · commit cb25d2383a6a · 2025-12-08T10:42:18.000+01:00
* feat(auth): allow opting in to creating indexes on `auth.users`

* chore: organize imports. use alert above table.

* chore: use default type to avoid 2 primary actions
diff --git a/apps/studio/components/interfaces/Auth/Users/UsersV2.tsx b/apps/studio/components/interfaces/Auth/Users/UsersV2.tsx
@@ -1,12 +1,21 @@
 import { useQueryClient } from '@tanstack/react-query'
 import AwesomeDebouncePromise from 'awesome-debounce-promise'
-import { RefreshCw, Trash, Users, X } from 'lucide-react'
+import {
+  ExternalLinkIcon,
+  InfoIcon,
+  RefreshCw,
+  Trash,
+  Users,
+  WandSparklesIcon,
+  X,
+} from 'lucide-react'
 import { UIEvent, useEffect, useMemo, useRef, useState } from 'react'
 import DataGrid, { Column, DataGridHandle, Row } from 'react-data-grid'
 import { toast } from 'sonner'
+import pgMeta from '@supabase/pg-meta'
 
 import type { OptimizedSearchColumns } from '@supabase/pg-meta/src/sql/studio/get-users-types'
-import { LOCAL_STORAGE_KEYS, useParams } from 'common'
+import { LOCAL_STORAGE_KEYS, useFlag, useParams } from 'common'
 import { useIsAPIDocsSidePanelEnabled } from 'components/interfaces/App/FeaturePreview/FeaturePreviewContext'
 import AlertError from 'components/ui/AlertError'
 import { APIDocsButton } from 'components/ui/APIDocsButton'
@@ -26,6 +35,9 @@ import { useSelectedProjectQuery } from 'hooks/misc/useSelectedProject'
 import { cleanPointerEventsNoneOnBody, isAtBottom } from 'lib/helpers'
 import { parseAsArrayOf, parseAsString, parseAsStringEnum, useQueryState } from 'nuqs'
 import {
+  Alert_Shadcn_,
+  AlertDescription_Shadcn_,
+  AlertTitle_Shadcn_,
   Button,
   cn,
   LoadingLine,
@@ -57,8 +69,23 @@ import {
 import { formatUserColumns, formatUsersData } from './Users.utils'
 import { UsersFooter } from './UsersFooter'
 import { UsersSearch } from './UsersSearch'
+import { useAuthConfigQuery } from 'data/auth/auth-config-query'
+import { useUserIndexStatusesQuery } from 'data/auth/user-search-indexes-query'
+import { useAuthConfigUpdateMutation } from 'data/auth/auth-config-update-mutation'
+import { useIndexWorkerStatusQuery } from 'data/auth/index-worker-status-query'
+import { InlineLink } from 'components/ui/InlineLink'
+import Link from 'next/link'
 
 const SORT_BY_VALUE_COUNT_THRESHOLD = 10_000
+const IMPROVED_SEARCH_COUNT_THRESHOLD = 10_000
+
+const INDEX_WORKER_LOGS_SEARCH_STRING = `select id, auth_logs.timestamp, metadata.level, event_message, metadata.msg as msg, metadata.error
+from auth_logs
+cross join unnest(metadata) as metadata
+where metadata.worker_type = 'apiworker_index_worker'
+  and auth_logs.timestamp >= timestamp_sub(current_timestamp(), interval 3 hour)
+order by timestamp desc
+limit 100`
 
 export const UsersV2 = () => {
   const queryClient = useQueryClient()
@@ -149,6 +176,7 @@ export const UsersV2 = () => {
   const [showDeleteModal, setShowDeleteModal] = useState(false)
   const [isDeletingUsers, setIsDeletingUsers] = useState(false)
   const [showFreeformWarning, setShowFreeformWarning] = useState(false)
+  const [showCreateIndexesModal, setShowCreateIndexesModal] = useState(false)
 
   const { data: totalUsersCountData, isSuccess: isCountLoaded } = useUsersCountQuery(
     {
@@ -325,6 +353,74 @@ export const UsersV2 = () => {
     }
   }
 
+  const isImprovedUserSearchEnabled = useFlag('improvedUserSearch')
+  const { data: authConfig } = useAuthConfigQuery({ projectRef })
+  const {
+    data: userSearchIndexes,
+    isError: isUserSearchIndexesError,
+    isLoading: isUserSearchIndexesLoading,
+  } = useUserIndexStatusesQuery({ projectRef, connectionString: project?.connectionString })
+  const { data: indexWorkerStatus } = useIndexWorkerStatusQuery({
+    projectRef,
+    connectionString: project?.connectionString,
+  })
+  const { mutate: updateAuthConfig, isPending: isUpdatingAuthConfig } = useAuthConfigUpdateMutation(
+    {
+      onSuccess: () => {
+        toast.success('Initiated creation of user search indexes')
+      },
+      onError: (error) => {
+        toast.error(`Failed to initiate creation of user search indexes: ${error?.message}`)
+      },
+    }
+  )
+
+  const handleEnableUserSearchIndexes = () => {
+    if (!projectRef) return console.error('Project ref is required')
+    updateAuthConfig({
+      projectRef: projectRef,
+      config: { INDEX_WORKER_ENSURE_USER_SEARCH_INDEXES_EXIST: true },
+    })
+  }
+
+  const userSearchIndexesAreValidAndReady =
+    !isUserSearchIndexesError &&
+    !isUserSearchIndexesLoading &&
+    userSearchIndexes?.length === pgMeta.USER_SEARCH_INDEXES.length &&
+    userSearchIndexes?.every((index) => index.is_valid && index.is_ready)
+
+  /**
+   * We want to show the improved search when:
+   * 1. The feature flag is enabled for them
+   * 2. The user has opted in (authConfig.INDEX_WORKER_ENSURE_USER_SEARCH_INDEXES_EXIST is true)
+   * 3. The required indexes are valid and ready
+   */
+  const _showImprovedSearch =
+    isImprovedUserSearchEnabled &&
+    authConfig?.INDEX_WORKER_ENSURE_USER_SEARCH_INDEXES_EXIST === true &&
+    userSearchIndexesAreValidAndReady
+
+  /**
+   * We want to show users the improved search opt-in only if:
+   * 1. The feature flag is enabled for them
+   * 2. They have not opted in yet (authConfig.INDEX_WORKER_ENSURE_USER_SEARCH_INDEXES_EXIST is false)
+   * 3. They have < threshold number of users
+   */
+  const isCountWithinThresholdForOptIn = totalUsers <= IMPROVED_SEARCH_COUNT_THRESHOLD
+  const showImprovedSearchOptIn =
+    isImprovedUserSearchEnabled &&
+    authConfig?.INDEX_WORKER_ENSURE_USER_SEARCH_INDEXES_EXIST === false &&
+    isCountWithinThresholdForOptIn
+
+  /**
+   * We want to show an "in progress" state when:
+   * 1. The user has opted in (authConfig.INDEX_WORKER_ENSURE_USER_SEARCH_INDEXES_EXIST is true)
+   * 2. The index worker is currently in progress
+   */
+  const indexWorkerInProgress =
+    authConfig?.INDEX_WORKER_ENSURE_USER_SEARCH_INDEXES_EXIST === true &&
+    indexWorkerStatus?.is_in_progress === true
+
   useEffect(() => {
     if (
       !isRefetching &&
@@ -378,6 +474,50 @@ export const UsersV2 = () => {
     <>
       <div className="h-full flex flex-col">
         <FormHeader className="py-4 px-6 !mb-0" title="Users" />
+
+        {showImprovedSearchOptIn && (
+          <Alert_Shadcn_ className="rounded-none mb-0 border-0 border-t">
+            <InfoIcon className="size-4" />
+            <AlertTitle_Shadcn_>Opt-in to an improved search experience</AlertTitle_Shadcn_>
+            <AlertDescription_Shadcn_ className="flex justify-between items-center">
+              <div>
+                Creating the necessary indexes will provide a safer and more performant search
+                experience.
+              </div>
+              <Button
+                icon={<WandSparklesIcon />}
+                onClick={() => setShowCreateIndexesModal(true)}
+                loading={isUpdatingAuthConfig}
+                type="default"
+              >
+                Create indexes
+              </Button>
+            </AlertDescription_Shadcn_>
+          </Alert_Shadcn_>
+        )}
+
+        {indexWorkerInProgress && (
+          <Alert_Shadcn_ className="rounded-none mb-0 border-0 border-t">
+            <InfoIcon className="size-4" />
+            <AlertTitle_Shadcn_>Index creation is in progress</AlertTitle_Shadcn_>
+            <AlertDescription_Shadcn_ className="flex justify-between items-center">
+              <div>
+                The indexes are currently being created. This process may take some time depending
+                on the number of users in your project.
+              </div>
+
+              <Button type="link" iconRight={<ExternalLinkIcon />} asChild>
+                <Link
+                  href={`/project/${projectRef}/logs/explorer?q=${encodeURI(INDEX_WORKER_LOGS_SEARCH_STRING)}`}
+                  target="_blank"
+                >
+                  View logs
+                </Link>
+              </Button>
+            </AlertDescription_Shadcn_>
+          </Alert_Shadcn_>
+        )}
+
         <div className="bg-surface-200 py-3 px-4 md:px-6 flex flex-col lg:flex-row lg:items-start justify-between gap-2 border-t">
           {selectedUsers.size > 0 ? (
             <div className="flex items-center gap-x-2">
@@ -753,6 +893,47 @@ export const UsersV2 = () => {
         </p>
       </ConfirmationModal>
 
+      <ConfirmationModal
+        size="medium"
+        visible={showCreateIndexesModal}
+        confirmLabel="Create indexes"
+        title="Create user search indexes"
+        onConfirm={() => {
+          handleEnableUserSearchIndexes()
+          setShowCreateIndexesModal(false)
+        }}
+        onCancel={() => setShowCreateIndexesModal(false)}
+        alert={{
+          title: 'Create user search indexes',
+          description:
+            'This process will create indexes on the auth.users table to improve search performance and enable better sorting and filtering capabilities.',
+        }}
+      >
+        <ul className="text-sm list-disc pl-4 my-3 flex flex-col gap-2">
+          <li className="marker:text-foreground-light">
+            Creating these indexes may temporarily impact database performance.
+          </li>
+          <li className="marker:text-foreground-light">
+            Depending on the size of your `auth.users` table, this operation may take some time to
+            complete.
+          </li>
+          <li className="marker:text-foreground-light">
+            You may continue to use the Auth Users page while the indexes are being created, but
+            search performance improvements will only take effect once the process is complete.
+          </li>
+          <li className="marker:text-foreground-light">
+            You can monitor the progress in the{' '}
+            <InlineLink
+              href={`/project/${projectRef}/logs/explorer?q=${encodeURI(INDEX_WORKER_LOGS_SEARCH_STRING)}`}
+              target="_blank"
+            >
+              project logs
+            </InlineLink>
+            . If you encounter any issues, please contact Supabase support for assistance.
+          </li>
+        </ul>
+      </ConfirmationModal>
+
       {/* [Joshen] For deleting via context menu, the dialog above is dependent on the selectedUsers state */}
       <DeleteUserModal
         visible={!!selectedUserToDelete}
diff --git a/apps/studio/data/auth/index-worker-status-query.ts b/apps/studio/data/auth/index-worker-status-query.ts
@@ -0,0 +1,55 @@
+import pgMeta from '@supabase/pg-meta'
+import { useQuery } from '@tanstack/react-query'
+
+import { executeSql, type ExecuteSqlError } from 'data/sql/execute-sql-query'
+import { UseCustomQueryOptions } from 'types'
+import { authKeys } from './keys'
+
+type IndexWorkerStatusVariables = {
+  projectRef?: string
+  connectionString?: string | null
+}
+type IndexWorkerStatusData = {
+  is_in_progress: boolean
+}
+export type IndexWorkerStatusError = ExecuteSqlError
+
+export async function getIndexWorkerStatus(
+  { projectRef, connectionString }: IndexWorkerStatusVariables,
+  signal?: AbortSignal
+): Promise<IndexWorkerStatusData> {
+  const sql = pgMeta.getIndexWorkerStatusSQL()
+
+  const { result } = await executeSql<IndexWorkerStatusData[]>(
+    {
+      projectRef,
+      connectionString,
+      sql,
+      queryKey: ['index-worker-status'],
+    },
+    signal
+  )
+
+  return result[0]
+}
+
+export const useIndexWorkerStatusQuery = <TData = IndexWorkerStatusData>(
+  { projectRef, connectionString }: IndexWorkerStatusVariables,
+  {
+    enabled = true,
+    ...options
+  }: UseCustomQueryOptions<IndexWorkerStatusData, IndexWorkerStatusError, TData> = {}
+) =>
+  useQuery<IndexWorkerStatusData, IndexWorkerStatusError, TData>({
+    queryKey: authKeys.indexWorkerStatus(projectRef),
+    queryFn: ({ signal }) =>
+      getIndexWorkerStatus(
+        {
+          projectRef,
+          connectionString,
+        },
+        signal
+      ),
+    enabled: enabled && typeof projectRef !== 'undefined',
+    ...options,
+  })
diff --git a/apps/studio/data/auth/keys.ts b/apps/studio/data/auth/keys.ts
@@ -40,6 +40,10 @@ export const authKeys = {
     }
   ) => ['projects', projectRef, 'users-count', params] as const,
 
+  usersIndexStatuses: (projectRef: string | undefined) =>
+    ['projects', projectRef, 'users-index-statuses'] as const,
+  indexWorkerStatus: (projectRef: string | undefined) =>
+    ['projects', projectRef, 'index-worker-status'] as const,
   authConfig: (projectRef: string | undefined) => ['projects', projectRef, 'auth-config'] as const,
   accessToken: () => ['access-token'] as const,
   overviewMetrics: (projectRef: string | undefined) =>
diff --git a/apps/studio/data/auth/user-search-indexes-query.ts b/apps/studio/data/auth/user-search-indexes-query.ts
@@ -0,0 +1,57 @@
+import pgMeta from '@supabase/pg-meta'
+import { useQuery } from '@tanstack/react-query'
+
+import { executeSql, type ExecuteSqlError } from 'data/sql/execute-sql-query'
+import { UseCustomQueryOptions } from 'types'
+import { authKeys } from './keys'
+
+type UsersIndexStatusesVariables = {
+  projectRef?: string
+  connectionString?: string | null
+}
+type UsersIndexStatusesData = {
+  index_name: string
+  is_valid: boolean
+  is_ready: boolean
+}[]
+export type UsersIndexStatusesError = ExecuteSqlError
+
+export async function getUserIndexStatuses(
+  { projectRef, connectionString }: UsersIndexStatusesVariables,
+  signal?: AbortSignal
+): Promise<UsersIndexStatusesData> {
+  const sql = pgMeta.getIndexStatusesSQL()
+
+  const { result } = await executeSql<UsersIndexStatusesData>(
+    {
+      projectRef,
+      connectionString,
+      sql,
+      queryKey: ['index-statuses'],
+    },
+    signal
+  )
+
+  return result
+}
+
+export const useUserIndexStatusesQuery = <TData = UsersIndexStatusesData>(
+  { projectRef, connectionString }: UsersIndexStatusesVariables,
+  {
+    enabled = true,
+    ...options
+  }: UseCustomQueryOptions<UsersIndexStatusesData, UsersIndexStatusesError, TData> = {}
+) =>
+  useQuery<UsersIndexStatusesData, UsersIndexStatusesError, TData>({
+    queryKey: authKeys.usersIndexStatuses(projectRef),
+    queryFn: ({ signal }) =>
+      getUserIndexStatuses(
+        {
+          projectRef,
+          connectionString,
+        },
+        signal
+      ),
+    enabled: enabled && typeof projectRef !== 'undefined',
+    ...options,
+  })
diff --git a/packages/pg-meta/src/index.ts b/packages/pg-meta/src/index.ts
@@ -17,6 +17,8 @@ import version from './pg-meta-version'
 import indexes from './pg-meta-indexes'
 import columnPrivileges from './pg-meta-column-privileges'
 import * as query from './query/index'
+import { getIndexStatusesSQL, USER_SEARCH_INDEXES } from './sql/studio/get-index-statuses'
+import { getIndexWorkerStatusSQL } from './sql/studio/get-index-worker-status'
 
 export default {
   roles,
@@ -38,4 +40,7 @@ export default {
   indexes,
   columnPrivileges,
   query,
+  getIndexWorkerStatusSQL,
+  getIndexStatusesSQL,
+  USER_SEARCH_INDEXES,
 }
diff --git a/packages/pg-meta/src/sql/studio/get-index-statuses.ts b/packages/pg-meta/src/sql/studio/get-index-statuses.ts
diff --git a/packages/pg-meta/src/sql/studio/get-index-worker-status.ts b/packages/pg-meta/src/sql/studio/get-index-worker-status.ts
