Supabase Client Factory
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Supabase Client Factory is a core utility within the MoodTune backend responsible for initializing and providing Supabase client instances. It abstracts the connection logic to the Supabase Postgres database, ensuring that the application can interact with the data layer without relying on traditional ORMs like SQLAlchemy. The factory provides two distinct types of clients: a standard client using an anonymous key for general operations and a service role client for administrative tasks that require bypassing Row Level Security (RLS).
This module serves as the primary gateway for all CRUD operations, including Spotify connection management and song analysis storage. By centralizing client creation, the project maintains consistent configuration management through environment variables and provides a thread-safe way to execute database queries within FastAPI's asynchronous environment.
Sources: app/core/supabase.py:1-12, README.md:1-25, CLAUDE.md:1-15
Architecture and Configuration
The factory relies on the pydantic-settings based configuration system to retrieve the necessary credentials for Supabase connectivity. It utilizes the official Supabase Python client to establish these connections.
Client Types
The factory distinguishes between two permission levels:
- Standard Client: Initialized with
SUPABASE_KEY(anon key). Primarily intended for operations governed by RLS. - Service Client: Initialized with
SUPABASE_SERVICE_KEY(service role key). Used by the backend to perform administrative writes and bypass RLS constraints when necessary.
Sources: app/core/supabase.py:5-12, app/core/config.py:44-47
Configuration Parameters
| Parameter | Source Variable | Description |
|---|---|---|
| URL | SUPABASE_URL | The unique API URL for the Supabase project instance. |
| Anon Key | SUPABASE_KEY | Public key used for standard authenticated requests. |
| Service Key | SUPABASE_SERVICE_KEY | Secret key for backend administrative operations. |
Sources: app/core/config.py:44-47, README.md:5-10
Implementation Logic
The factory implementation is straightforward, providing two functional entry points.
from supabase import create_client, Client
from app.core.config import settings
def get_supabase_client() -> Client:
"""Get Supabase client with anon key"""
return create_client(settings.SUPABASE_URL, settings.SUPABASE_KEY)
def get_supabase_service_client() -> Client:
"""Get Supabase client with service role key (for admin operations)"""
return create_client(settings.SUPABASE_URL, settings.SUPABASE_SERVICE_KEY)
Sources: app/core/supabase.py:1-12
Initialization Flow
The following diagram illustrates how the factory interacts with the configuration settings to produce a functional client.
This diagram shows the relationship between configuration, the factory functions, and their eventual consumption by the CRUD and dependency layers.
Sources: app/core/supabase.py:1-12, CLAUDE.md:25-35
Usage in CRUD Operations
The Supabase Service Client is the primary tool used in the app/crud/ layer. Because these operations often involve writing to tables where RLS might be enabled (such as spotify_connections or song_analyses), the service role key is required for the backend to function correctly.
Data Flow in CRUD
CRUD functions wrap the Supabase client's fluent interface within asynchronous wrappers. Since the Supabase Python client is synchronous, the backend uses loop.run_in_executor to prevent blocking the FastAPI event loop.
This sequence represents the standard flow for a database insertion using the factory-provided client.
Sources: app/crud/song_analysis.py:9-30, app/crud/spotify.py:7-10
Key CRUD Modules Utilizing the Factory
| Module | Purpose | Database Table |
|---|---|---|
app/crud/spotify.py | Manages OAuth tokens and connection status. | spotify_connections |
app/crud/analysis.py | Manages playlist-level mood results. | playlist_analyses |
app/crud/song_analysis.py | Manages individual track analysis results. | song_analyses |
Sources: app/crud/spotify.py:1, app/crud/analysis.py:1, app/crud/song_analysis.py:1
Conclusion
The Supabase Client Factory is a vital architectural component that enables the MoodTune backend to operate as a "database-connected" application without the overhead of a heavy ORM. By providing differentiated access levels (Anon vs. Service Role), it ensures the backend can safely perform administrative tasks while respecting the security model of the Supabase platform. Its integration with the project's configuration and asynchronous execution patterns allows for scalable and maintainable data access.
Sources: CLAUDE.md:5-10, README.md:15-20