Version 1.6.1+ | Production Ready | Unreal Engine 5.5+
Establish your first connection to Supabase from Unreal Engine 5 with step-by-step instructions.
This guide walks you through making your very first successful connection to a Supabase backend from Unreal Engine 5. You will create a connection object, initialize the subsystem, and run a test query to verify everything is working.
Before starting, ensure you have:
In Supabase Studio, create a simple table to query:
CREATE TABLE test_connection (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
message TEXT NOT NULL,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Insert a test row
INSERT INTO test_connection (message) VALUES ('Hello from Supabase!');
Enable Row Level Security and create a permissive policy for testing:
ALTER TABLE test_connection ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Allow anon reads" ON test_connection
FOR SELECT USING (true);
The easiest way to configure your connection is to create a USupabaseConnection DataAsset:
DA_SupabaseConnection (or any name you prefer)Defaulthttps://your-project.supabase.co// In your GameInstance class (e.g., MyGameInstance.h)
#pragma once
#include "CoreMinimal.h"
#include "Engine/GameInstance.h"
#include "MyGameInstance.generated.h"
UCLASS()
class MYGAME_API UMyGameInstance : public UGameInstance
{
GENERATED_BODY()
public:
virtual void Init() override;
private:
void OnConnectionSuccess();
void OnConnectionFailure(const FString& Error);
};
// In your GameInstance class (e.g., MyGameInstance.cpp)
#include "MyGameInstance.h"
#include "SupabaseManager.h"
#include "SupabaseConnection.h"
#include "AsyncQuery.h"
void UMyGameInstance::Init()
{
Super::Init();
// Create connection configuration
USupabaseConnection* Connection = NewObject<USupabaseConnection>();
Connection->SupabaseServerUrl = TEXT("https://your-project.supabase.co");
Connection->SupabaseCredentials.AnonymousKey = TEXT("your-anon-key-here");
Connection->ConnectionName = TEXT("Default");
// Initialize the Supabase subsystem
USupabaseManager::InitializeSupabase(this, Connection);
UE_LOG(LogTemp, Log, TEXT("Supabase initialized. Testing connection..."));
}
The USupabaseSubsystem is a UGameInstanceSubsystem that provides centralized, singleton access to your Supabase connection. It includes automatic health monitoring (5-minute test interval, 55-minute token refresh), connection retry logic, and state management.
// In your GameInstance or any actor with WorldContext
USupabaseSubsystem* Supabase = GetGameInstance()->GetSubsystem<USupabaseSubsystem>();
// Initialize with a connection
Supabase->InitializeConnection(Connection);
// Test connection
Supabase->TestConnection();
// Retry connection (up to 3 attempts with exponential backoff)
Supabase->RetryConnection();
Edit → Project Settings → Maps & Modes → Game Instance)void UMyGameInstance::RunTestQuery()
{
if (!USupabaseManager::IsConnected(this))
{
UE_LOG(LogTemp, Warning, TEXT("Supabase is not connected!"));
return;
}
// Create an async query to our test table
UAsyncQuery* QueryTask = UAsyncQuery::AsyncQuery(
this,
TEXT("test_connection"), // Table name
TEXT("*"), // Select all columns
TArray<FQueryFilter>() // No filters
);
// Bind callbacks
QueryTask->OnSuccess.AddDynamic(this, &UMyGameInstance::OnConnectionSuccess);
QueryTask->OnFailure.AddDynamic(this, &UMyGameInstance::OnConnectionFailure);
// Execute the query
QueryTask->Activate();
}
void UMyGameInstance::OnConnectionSuccess()
{
UE_LOG(LogTemp, Log, TEXT("Connection successful! Supabase is working."));
// Optionally print the results via GEngine->AddOnScreenDebugMessage()
}
void UMyGameInstance::OnConnectionFailure(const FString& Error)
{
UE_LOG(LogTemp, Error, TEXT("Connection failed: %s"), *Error);
}
test_connection*"Connected to Supabase!"When successful, you should see:
Output Log:
LogTemp: Supabase initialized. Testing connection...
LogTemp: Connection successful! Supabase is working.
In-Game (Blueprint):
Connected to Supabase!
InitializeSupabase() called in GameInstance::Init()| Problem | Solution |
|---|---|
| "Plugin not found" | Verify plugin is in Plugins/Supabase/ and enabled |
| Connection timeout | Check URL format (include https://), verify firewall |
| 401 Unauthorized | Ensure Anon Key is correct (not Service Role Key) |
| Empty results | Check RLS policies allow reads for anon role |
| Blueprint node missing | Restart editor after enabling the plugin |
Once your first connection works:
Need help? Join our Discord community for support.