Version 1.34.2 | Production Ready | Unreal Engine 5.5+
The Supabase UE5 Plugin provides a comprehensive suite of asynchronous operations designed for production environments. All async operations follow thread-safe patterns with automatic memory management, comprehensive error handling, and seamless Blueprint integration.
Thread-Safe Operations: All async operations use proper mutex locking and safe delegate handling to prevent race conditions and ensure stability in multi-threaded environments.
Memory Management: Every async operation implements automatic cleanup via SafeCleanup() methods, preventing memory leaks even when operations are interrupted or canceled.
Subsystem Integration: Operations default to using the centralized USupabaseSubsystem for consistent connection state while providing advanced direct connection options.
Error Recovery: Comprehensive input validation, retry mechanisms, and detailed error reporting ensure robust operation in production environments.
Handles user authentication with comprehensive session management.
// Basic login using subsystem
UAsyncLogin* LoginTask = UAsyncLogin::LoginAsync(
this,
TEXT("user@example.com"),
TEXT("password123")
);
LoginTask->OnSuccess.AddDynamic(this, &AMyClass::OnLoginSuccess);
LoginTask->OnFailure.AddDynamic(this, &AMyClass::OnLoginFailure);
Features:
User registration with built-in validation and email confirmation support.
UAsyncRegister* RegisterTask = UAsyncRegister::RegisterAsync(
this,
TEXT("newuser@example.com"),
TEXT("securePassword123"),
UserMetadata
);
Execute custom SQL queries with advanced security features and parameter binding.
// Basic SQL execution
UAsyncExecuteSQL* SQLTask = UAsyncExecuteSQL::ExecuteSQLAsync(
this,
TEXT("SELECT * FROM users WHERE active = true LIMIT 10")
);
// Stored procedure execution with parameters
TMap<FString, FString> Params;
Params.Add(TEXT("user_id"), TEXT("123"));
Params.Add(TEXT("status"), TEXT("active"));
UAsyncExecuteSQL* ProcTask = UAsyncExecuteSQL::ExecuteStoredProcedureAsync(
this,
TEXT("get_user_data"),
Params
);
Security Features:
Enhanced row update operations with optimistic locking and conflict resolution.
TMap<FString, FString> UpdateData;
UpdateData.Add(TEXT("name"), TEXT("Updated Name"));
UpdateData.Add(TEXT("status"), TEXT("active"));
UAsyncUpdateRow* UpdateTask = UAsyncUpdateRow::UpdateRowAsync(
this,
TEXT("users"),
TEXT("id=123"),
UpdateData
);
Safe row deletion with cascade handling and constraint validation.
UAsyncDeleteRow* DeleteTask = UAsyncDeleteRow::DeleteRowAsync(
this,
TEXT("users"),
TEXT("id=123")
);
Thread-safe WebSocket operations with automatic reconnection and channel management.
// Subscribe to table changes
UAsyncRealtime* RealtimeTask = UAsyncRealtime::SubscribeToTableAsync(
this,
TEXT("users"),
ERealtimeEvent::All
);
// Subscribe to specific row changes
UAsyncRealtime* RowTask = UAsyncRealtime::SubscribeToRowAsync(
this,
TEXT("users"),
TEXT("id=123"),
ERealtimeEvent::Update
);
Features:
Secure file upload with progress tracking and metadata support.
UAsyncUploadFile* UploadTask = UAsyncUploadFile::UploadFileAsync(
this,
TEXT("avatars/user123.jpg"),
FileData,
TEXT("image/jpeg")
);
UploadTask->OnProgress.AddDynamic(this, &AMyClass::OnUploadProgress);
Efficient file download with caching and integrity verification.
UAsyncDownloadFile* DownloadTask = UAsyncDownloadFile::DownloadFileAsync(
this,
TEXT("avatars/user123.jpg"),
LocalFilePath
);
Convert Unreal actors to JSON with flexible serialization options.
// Basic actor serialization
UAsyncParseActorToJson* ParseTask = UAsyncParseActorToJson::ParseActorToJsonAsync(
this,
MyActor,
EActorSerializationMode::Complete
);
// Multiple actors serialization
TArray<AActor*> Actors = {Actor1, Actor2, Actor3};
UAsyncParseActorToJson* MultiTask = UAsyncParseActorToJson::ParseActorsToJsonAsync(
this,
Actors,
EActorSerializationMode::Transform
);
Serialization Modes:
Basic - Transform + Name onlyTransform - Transform data onlyProperties - All exposed propertiesComponents - Component hierarchyComplete - Everything including custom dataSecure JSON parsing with schema validation and type safety.
// Basic JSON parsing with validation
UAsyncParseJSON* ParseTask = UAsyncParseJSON::ParseJSONValidatedAsync(
this,
JSONString,
EJSONValidationLevel::Strict
);
// Array parsing with size limits
UAsyncParseJSON* ArrayTask = UAsyncParseJSON::ParseJSONArrayAsync(
this,
JSONArrayString,
MyStructType::StaticStruct(),
500 // Maximum 500 elements
);
Dynamic table creation with comprehensive schema definition.
FTableSchema Schema;
FTableColumn IdColumn;
IdColumn.Name = TEXT("id");
IdColumn.Type = TEXT("serial");
IdColumn.bPrimaryKey = true;
Schema.Columns.Add(IdColumn);
UAsyncCreateTable* CreateTask = UAsyncCreateTable::CreateTableAsync(
this,
TEXT("dynamic_table"),
Schema
);
Generic HTTP API request handling with advanced configuration options.
TMap<FString, FString> Headers;
Headers.Add(TEXT("X-Custom-Header"), TEXT("MyValue"));
UAsyncApiRequest* ApiTask = UAsyncApiRequest::ApiRequestAdvanced(
this,
TEXT("https://api.example.com/data"),
EHttpMethod::POST,
Headers,
TEXT("{\"key\":\"value\"}"),
60.0f, // 60 second timeout
true, // Validate SSL
TEXT("application/json")
);
All async operations follow this consistent pattern:
// Header (.h file)
UCLASS()
class SUPABASE_API UAsyncOperation : public USupabaseAsyncBase
{
GENERATED_BODY()
public:
// Blueprint-accessible static factory methods
UFUNCTION(BlueprintCallable, Category = "Supabase", meta = (BlueprintInternalUseOnly = "true"))
static UAsyncOperation* OperationAsync(UObject* WorldContext, /* parameters */);
UFUNCTION(BlueprintCallable, Category = "Supabase", meta = (BlueprintInternalUseOnly = "true"))
static UAsyncOperation* OperationAdvanced(UObject* WorldContext, USupabaseConnection* Connection, /* parameters */);
// Event delegates
UPROPERTY(BlueprintAssignable)
FOnOperationSuccess OnSuccess;
UPROPERTY(BlueprintAssignable)
FOnOperationFailure OnFailure;
protected:
virtual void Activate() override;
virtual void BeginDestroy() override;
private:
void SafeCleanup();
bool ValidateInputs();
void ProcessResponse(const FString& ResponseContent);
};
Every async operation implements automatic cleanup:
void UAsyncOperation::BeginDestroy()
{
SafeCleanup();
Super::BeginDestroy();
}
void UAsyncOperation::SafeCleanup()
{
if (HttpRequest.IsValid())
{
HttpRequest->CancelRequest();
HttpRequest.Reset();
}
// Unbind all delegates
OnSuccess.Clear();
OnFailure.Clear();
// Clear any cached data
ResponseData.Empty();
}
Comprehensive error handling with detailed reporting:
bool UAsyncOperation::ValidateInputs()
{
if (Parameter.IsEmpty())
{
BroadcastError(TEXT("Parameter cannot be empty"), 400);
return false;
}
if (!IsValid(WorldContext))
{
BroadcastError(TEXT("Invalid world context"), 500);
return false;
}
return true;
}
Recommended: Use Subsystem (Default)
// Automatically uses centralized subsystem connection
UAsyncLogin* LoginTask = UAsyncLogin::LoginAsync(this, Email, Password);
Advanced: Direct Connection
// Use when you need multiple Supabase project connections
UAsyncLogin* LoginTask = UAsyncLogin::LoginAdvanced(this, CustomConnection, Email, Password);
Always bind both success and failure events:
LoginTask->OnSuccess.AddDynamic(this, &AMyClass::OnLoginSuccess);
LoginTask->OnFailure.AddDynamic(this, &AMyClass::OnLoginFailure);
Async operations automatically clean up, but you can manually trigger cleanup if needed:
// Optional: Manual cleanup before destruction
if (IsValid(AsyncTask))
{
AsyncTask->ConditionalBeginDestroy();
}
All operations are thread-safe, but UI updates must occur on the game thread:
UFUNCTION()
void OnDataReceived(const FString& Data)
{
// This callback is automatically executed on the game thread
// Safe to update UI elements here
UpdateUIWithData(Data);
}
Configure async operation behavior through project settings:
// DefaultEngine.ini
[/Script/Supabase.SupabaseSettings]
DefaultRequestTimeout=30.0
MaxRetryAttempts=3
RetryDelayMultiplier=2.0
EnableRequestLogging=true
EnableMemoryLeakDetection=true
Most operations support advanced configuration:
FAsyncOperationConfig Config;
Config.TimeoutSeconds = 60.0f;
Config.MaxRetryAttempts = 3;
Config.bValidateSSL = true;
Config.bEnableLogging = true;
UAsyncOperation* Task = UAsyncOperation::OperationWithConfig(this, Config, Parameters);
The subsystem manages connection pooling automatically:
Async operations are designed for minimal memory footprint:
Monitor async operation performance through built-in metrics:
// Access performance data
USupabaseSubsystem* Subsystem = USupabaseManager::GetSupabaseSubsystem(this);
FSupabaseMetrics Metrics = Subsystem->GetPerformanceMetrics();
UE_LOG(LogSupabase, Log, TEXT("Average Request Time: %f seconds"), Metrics.AverageRequestTime);
UE_LOG(LogSupabase, Log, TEXT("Active Connections: %d"), Metrics.ActiveConnections);
Memory Leaks
Connection Issues
Thread Safety
Enable comprehensive logging for troubleshooting:
// Enable in DefaultEngine.ini
[Core.Log]
LogSupabase=Verbose
LogSupabaseAsync=Verbose
LogSupabaseRealtime=Verbose
Use Unreal’s built-in profiling tools:
// Profile async operations
SCOPE_CYCLE_COUNTER(STAT_SupabaseAsyncOperation);
If upgrading from earlier plugin versions:
Replace Direct USupabaseClient Usage:
// Old
USupabaseClient* Client = NewObject<USupabaseClient>();
// New
USupabaseSubsystem* Subsystem = USupabaseManager::GetSupabaseSubsystem(this);
Update Async Operation Calls:
// Old
UAsyncQuery* Task = UAsyncQuery::Query(Client, Parameters);
// New
UAsyncQuery* Task = UAsyncQuery::QueryAsync(this, Parameters);
Handle New Error Delegate:
// Add failure handling
Task->OnFailure.AddDynamic(this, &AMyClass::OnOperationFailure);
This documentation is maintained for Supabase UE5 Plugin v1.34.2. For the latest updates and community support, visit our Discord community.