PolarDB:PolarDB Supabase Best Practices - Web Applications

Enable Realtime on each table

Add all tables to the supabase_realtime publication:

ALTER PUBLICATION supabase_realtime ADD TABLE meetings;
ALTER PUBLICATION supabase_realtime ADD TABLE notes;
ALTER PUBLICATION supabase_realtime ADD TABLE user_presence;
ALTER PUBLICATION supabase_realtime ADD TABLE tags;
ALTER PUBLICATION supabase_realtime ADD TABLE tasks;
ALTER PUBLICATION supabase_realtime ADD TABLE meeting_activities;
ALTER PUBLICATION supabase_realtime ADD TABLE meeting_files;

Subscribe from the client

Use one dedicated channel per business concern to keep logic decoupled. The following example creates a custom React hook that manages channel subscriptions and cleanup:

// Create a custom Hook to manage Realtime subscriptions
export function useRealtime(meetingId: string, callbacks: RealtimeCallbacks) {

  const channelsRef = useRef<any[]>([])

  const cleanup = useCallback(() => {
    channelsRef.current.forEach((channel) => {
      supabase.removeChannel(channel)
    })
    channelsRef.current = []
  }, [])

  useEffect(() => {
    if (!meetingId) return

    // Clean up previous connections
    cleanup()

    // Subscribe to user presence changes for this meeting
    const presenceChannel = supabase
      .channel(`presence:${meetingId}`)
      .on(
        "postgres_changes",
        {
          event: "*",
          schema: "public",
          table: "user_presence",
          filter: `meeting_id=eq.${meetingId}`,
        },
        (payload) => {
          console.log("User presence change:", payload)
          if (callbacks.onUserPresenceChange) {
            loadOnlineUsers()
          }
        },
      )
      .subscribe()

    // Save channel references for cleanup
    channelsRef.current = [presenceChannel, /* other channels */]
  }, [meetingId, callbacks])

  return { cleanup }
}

Design principles for Realtime subscriptions:

• Isolate by business concern: Create one channel per scenario (presence, document edits, task notifications) to keep logic decoupled.

• Filter events: Use the filter parameter (for example, meeting_id=eq.${meetingId}) to limit events to relevant rows and reduce unnecessary traffic.

• Release resources: Call removeChannel when a component unmounts or the user navigates away. The useEffect cleanup above handles this automatically.

• Handle errors gracefully: Monitor channel status and implement retry or graceful degradation for disconnections and timeouts.

Initialize the Supabase client

Create a shared client instance in lib/supabase.ts:

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!

export const supabase = createClient(supabaseUrl, supabaseAnonKey)

// Type definition
export interface Meeting {
  id: string
  created_at: string
  title: string
  description: string | null
}

Configure environment variables

Create .env.local in the project root:

NEXT_PUBLIC_SUPABASE_URL=<YOUR_SUPABASE_PUBLIC_URL>
NEXT_PUBLIC_SUPABASE_ANON_KEY=<YOUR_SUPABASE_ANON_KEY>

Replace the placeholders with values from your PolarDB Supabase application:

Add user authentication

The following example shows sign-in and user profile mapping:

const login = useCallback(async (email: string, password: string) => {
  try {
    const { data, error } = await supabase.auth.signInWithPassword({ email, password })
    if (error) throw error
    if (data.user) {
      const userData = transformSupabaseUser(data.user)
      setUser(userData)
      localStorage.setItem("meeting_user", JSON.stringify(userData))
      return { success: true, user: userData }
    }
    return { success: false, error: 'Login failed' }
  } catch (error: any) {
    return { success: false, error: error.message || 'Login failed' }
  }
}, [])

const transformSupabaseUser = (supabaseUser: SupabaseUser): User => ({
  id: supabaseUser.id,
  email: supabaseUser.email || null,
  name: supabaseUser.user_metadata?.name || supabaseUser.email?.split('@')[0] || 'User',
  avatar_url: supabaseUser.user_metadata?.avatar_url || null,
  created_at: supabaseUser.created_at,
  is_anonymous: supabaseUser.user_metadata?.is_anonymous || false,
})