feat(surrealdb): ensures ns/db are created in strict mode

Odonno · Odonno · commit ff37de25709f · 2025-08-06T18:16:51.000+02:00
diff --git a/examples/surrealdb/CommunityToolkit.Aspire.Hosting.SurrealDb.AppHost/Program.cs b/examples/surrealdb/CommunityToolkit.Aspire.Hosting.SurrealDb.AppHost/Program.cs
@@ -2,11 +2,34 @@
 
 var builder = DistributedApplication.CreateBuilder(args);
 
-var db = builder.AddSurrealServer("surreal")
+bool strictMode = true;
+
+var db = builder.AddSurrealServer("surreal", strictMode: strictMode)
     .WithSurrealist()
     .AddNamespace("ns")
     .AddDatabase("db");
 
+if (strictMode)
+{
+    db.WithCreationScript(
+        $"""
+        DEFINE DATABASE IF NOT EXISTS {nameof(db)};
+        USE DATABASE {nameof(db)};
+        
+        DEFINE TABLE todo;
+        DEFINE FIELD title ON todo TYPE string;
+        DEFINE FIELD dueBy ON todo TYPE datetime;
+        DEFINE FIELD isComplete ON todo TYPE bool;
+        
+        DEFINE TABLE weatherForecast;
+        DEFINE FIELD date ON weatherForecast TYPE datetime;
+        DEFINE FIELD country ON weatherForecast TYPE string;
+        DEFINE FIELD temperatureC ON weatherForecast TYPE number;
+        DEFINE FIELD summary ON weatherForecast TYPE string;
+        """
+    );
+}
+
 builder.AddProject<CommunityToolkit_Aspire_Hosting_SurrealDb_ApiService>("apiservice")
     .WithReference(db)
     .WaitFor(db);
diff --git a/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs b/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs
@@ -5,7 +5,9 @@
 using CommunityToolkit.Aspire.SurrealDb;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Diagnostics.HealthChecks;
+using Microsoft.Extensions.Logging;
 using SurrealDb.Net;
+using SurrealDb.Net.Models.Response;
 using System.Text;
 using System.Text.Json;
 
@@ -80,6 +82,59 @@ public static IResourceBuilder<SurrealDbServerResource> AddSurrealServer(
             : SurrealDbContainerImageTags.Tag;
         
         var surrealServer = new SurrealDbServerResource(name, userName?.Resource, passwordParameter);
+        
+        string? connectionString = null;
+
+        builder.Eventing.Subscribe<ConnectionStringAvailableEvent>(surrealServer, async (_, ct) =>
+        {
+            connectionString = await surrealServer.GetConnectionStringAsync(ct).ConfigureAwait(false);
+
+            if (connectionString == null)
+            {
+                throw new DistributedApplicationException($"ConnectionStringAvailableEvent was published for the '{surrealServer.Name}' resource but the connection string was null.");
+            }
+        });
+
+        builder.Eventing.Subscribe<ResourceReadyEvent>(surrealServer, async (@event, ct) =>
+        {
+            if (connectionString is null)
+            {
+                throw new DistributedApplicationException($"ResourceReadyEvent was published for the '{surrealServer.Name}' resource but the connection string was null.");
+            }
+
+            if (!strictMode)
+            {
+                return;
+            }
+
+            var options = new SurrealDbOptionsBuilder().FromConnectionString(connectionString).Build();
+            await using var surrealClient = new SurrealDbClient(options);
+
+            foreach (var nsResourceName in surrealServer.Namespaces.Keys)
+            {
+                if (builder.Resources.FirstOrDefault(n =>
+                        string.Equals(n.Name, nsResourceName, StringComparison.OrdinalIgnoreCase)) is
+                    SurrealDbNamespaceResource surrealDbNamespace)
+                {
+                    await CreateNamespaceAsync(surrealClient, surrealDbNamespace, @event.Services, ct)
+                        .ConfigureAwait(false);
+                
+                    await surrealClient.Use(surrealDbNamespace.NamespaceName, null!, ct).ConfigureAwait(false);
+
+                    foreach (var dbResourceName in surrealDbNamespace.Databases.Keys)
+                    {
+                        if (builder.Resources.FirstOrDefault(n =>
+                                string.Equals(n.Name, dbResourceName, StringComparison.OrdinalIgnoreCase)) is
+                            SurrealDbDatabaseResource surrealDbDatabase)
+                        {
+                            await CreateDatabaseAsync(surrealClient, surrealDbDatabase, @event.Services, ct)
+                                .ConfigureAwait(false);
+                        }
+                    }
+                }
+            }
+        });
+        
         return builder.AddResource(surrealServer)
                       .WithEndpoint(port: port, targetPort: SurrealDbPort, name: SurrealDbServerResource.PrimaryEndpointName)
                       .WithImage(SurrealDbContainerImageTags.Image, imageTag)
@@ -132,6 +187,25 @@ public static IResourceBuilder<SurrealDbNamespaceResource> AddNamespace(
         var surrealServerNamespace = new SurrealDbNamespaceResource(name, namespaceName, builder.Resource);
         return builder.ApplicationBuilder.AddResource(surrealServerNamespace);
     }
+    
+    /// <summary>
+    /// Defines the SQL script used to create the namespace.
+    /// </summary>
+    /// <param name="builder">The builder for the <see cref="SurrealDbNamespaceResource"/>.</param>
+    /// <param name="script">The SQL script used to create the namespace.</param>
+    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
+    /// <remarks>
+    /// <value>Default script is <code>DEFINE NAMESPACE IF NOT EXISTS `QUOTED_NAMESPACE_NAME`;</code></value>
+    /// </remarks>
+    public static IResourceBuilder<SurrealDbNamespaceResource> WithCreationScript(this IResourceBuilder<SurrealDbNamespaceResource> builder, string script)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(script);
+
+        builder.WithAnnotation(new SurrealDbCreateNamespaceScriptAnnotation(script));
+
+        return builder;
+    }
 
     /// <summary>
     /// Adds a SurrealDB database to the application model. This is a child resource of a <see cref="SurrealDbNamespaceResource"/>.
@@ -202,6 +276,25 @@ public static IResourceBuilder<SurrealDbDatabaseResource> AddDatabase(
         return builder.ApplicationBuilder.AddResource(surrealServerDatabase)
             .WithHealthCheck(healthCheckKey);
     }
+    
+    /// <summary>
+    /// Defines the SQL script used to create the database.
+    /// </summary>
+    /// <param name="builder">The builder for the <see cref="SurrealDbDatabaseResource"/>.</param>
+    /// <param name="script">The SQL script used to create the database.</param>
+    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
+    /// <remarks>
+    /// <value>Default script is <code>DEFINE DATABASE IF NOT EXISTS `QUOTED_DATABASE_NAME`;</code></value>
+    /// </remarks>
+    public static IResourceBuilder<SurrealDbDatabaseResource> WithCreationScript(this IResourceBuilder<SurrealDbDatabaseResource> builder, string script)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(script);
+
+        builder.WithAnnotation(new SurrealDbCreateDatabaseScriptAnnotation(script));
+
+        return builder;
+    }
 
     /// <summary>
     /// Adds a named volume for the data folder to a SurrealDB resource.
@@ -447,4 +540,62 @@ CancellationToken cancellationToken
         
         return Encoding.UTF8.GetString(stream.ToArray());
     }
+    
+    private static async Task CreateNamespaceAsync(
+        SurrealDbClient surrealClient, 
+        SurrealDbNamespaceResource namespaceResource, 
+        IServiceProvider serviceProvider, 
+        CancellationToken cancellationToken
+    )
+    {
+        var scriptAnnotation = namespaceResource.Annotations.OfType<SurrealDbCreateNamespaceScriptAnnotation>().LastOrDefault();
+
+        var logger = serviceProvider.GetRequiredService<ResourceLoggerService>().GetLogger(namespaceResource.Parent);
+        logger.LogDebug("Creating namespace '{NamespaceName}'", namespaceResource.NamespaceName);
+
+        try
+        {
+            var response = await surrealClient.RawQuery(
+                scriptAnnotation?.Script ?? $"DEFINE NAMESPACE IF NOT EXISTS `{namespaceResource.NamespaceName}`;", 
+                cancellationToken: cancellationToken
+            ).ConfigureAwait(false);
+
+            response.EnsureAllOks();
+
+            logger.LogDebug("Namespace '{NamespaceName}' created successfully", namespaceResource.NamespaceName);
+        }
+        catch (Exception e)
+        {
+            logger.LogError(e, "Failed to create namespace '{NamespaceName}'", namespaceResource.NamespaceName);
+        }
+    }
+    
+    private static async Task CreateDatabaseAsync(
+        SurrealDbClient surrealClient, 
+        SurrealDbDatabaseResource databaseResource, 
+        IServiceProvider serviceProvider, 
+        CancellationToken cancellationToken
+    )
+    {
+        var scriptAnnotation = databaseResource.Annotations.OfType<SurrealDbCreateDatabaseScriptAnnotation>().LastOrDefault();
+
+        var logger = serviceProvider.GetRequiredService<ResourceLoggerService>().GetLogger(databaseResource.Parent.Parent);
+        logger.LogDebug("Creating database '{DatabaseName}'", databaseResource.DatabaseName);
+
+        try
+        {
+            var response = await surrealClient.RawQuery(
+                scriptAnnotation?.Script ?? $"DEFINE DATABASE IF NOT EXISTS `{databaseResource.DatabaseName}`;", 
+                cancellationToken: cancellationToken
+            ).ConfigureAwait(false);
+
+            response.EnsureAllOks();
+
+            logger.LogDebug("Database '{DatabaseName}' created successfully", databaseResource.DatabaseName);
+        }
+        catch (Exception e)
+        {
+            logger.LogError(e, "Failed to create database '{DatabaseName}'", databaseResource.DatabaseName);
+        }
+    }
 }
diff --git a/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbCreateDatabaseScriptAnnotation.cs b/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbCreateDatabaseScriptAnnotation.cs
@@ -0,0 +1,27 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting;
+
+/// <summary>
+/// Represents an annotation for defining a script to create a database in SurrealDB.
+/// </summary>
+internal sealed class SurrealDbCreateDatabaseScriptAnnotation : IResourceAnnotation
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SurrealDbCreateDatabaseScriptAnnotation"/> class.
+    /// </summary>
+    /// <param name="script">The script used to create the database.</param>
+    public SurrealDbCreateDatabaseScriptAnnotation(string script)
+    {
+        ArgumentNullException.ThrowIfNull(script);
+        Script = script;
+    }
+
+    /// <summary>
+    /// Gets the script used to create the database.
+    /// </summary>
+    public string Script { get; }
+}
diff --git a/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbCreateNamespaceScriptAnnotation.cs b/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbCreateNamespaceScriptAnnotation.cs
@@ -0,0 +1,27 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting;
+
+/// <summary>
+/// Represents an annotation for defining a script to create a namespace in SurrealDB.
+/// </summary>
+internal sealed class SurrealDbCreateNamespaceScriptAnnotation : IResourceAnnotation
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SurrealDbCreateNamespaceScriptAnnotation"/> class.
+    /// </summary>
+    /// <param name="script">The script used to create the namespace.</param>
+    public SurrealDbCreateNamespaceScriptAnnotation(string script)
+    {
+        ArgumentNullException.ThrowIfNull(script);
+        Script = script;
+    }
+
+    /// <summary>
+    /// Gets the script used to create the namespace.
+    /// </summary>
+    public string Script { get; }
+}
diff --git a/tests/CommunityToolkit.Aspire.Hosting.SurrealDb.Tests/SurrealDbFunctionalTests.cs b/tests/CommunityToolkit.Aspire.Hosting.SurrealDb.Tests/SurrealDbFunctionalTests.cs
@@ -334,6 +334,55 @@ await pipeline.ExecuteAsync(async token =>
             }
         }
     }
+    
+    [Fact]
+    public async Task AddDatabaseCreatesDatabaseWithCustomScript()
+    {
+        using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));
+
+        using var builder = TestDistributedApplicationBuilder.Create(testOutputHelper);
+        
+        var surrealNsName = "ns1";
+        var surrealDbName = "db1";
+
+        var surreal = builder.AddSurrealServer("surreal", strictMode: true);
+
+        var db = surreal
+            .AddNamespace(surrealNsName)
+            .AddDatabase(surrealDbName)
+            .WithCreationScript(
+                $"""
+                DEFINE DATABASE IF NOT EXISTS {surrealDbName};
+                USE DATABASE {surrealDbName};
+                
+                DEFINE TABLE todo;
+                DEFINE FIELD Title ON todo TYPE string;
+                DEFINE FIELD DueBy ON todo TYPE datetime;
+                DEFINE FIELD IsComplete ON todo TYPE bool;
+                """
+            );
+
+        using var app = builder.Build();
+
+        await app.StartAsync(cts.Token);
+
+        var hb = Host.CreateApplicationBuilder();
+
+        hb.Configuration[$"ConnectionStrings:{db.Resource.Name}"] = await db.Resource.ConnectionStringExpression.GetValueAsync(default);
+
+        hb.AddSurrealClient(db.Resource.Name);
+
+        using var host = hb.Build();
+
+        await host.StartAsync();
+
+        await app.ResourceNotifications.WaitForResourceHealthyAsync(db.Resource.Name, cts.Token);
+
+        await using var client = host.Services.GetRequiredService<SurrealDbClient>();
+
+        await CreateTestData(client, cts.Token);
+        await AssertTestData(client, cts.Token);
+    }
 
     private static async Task CreateTestData(SurrealDbClient surrealDbClient, CancellationToken ct)
     {
