SurrealDbBuilderExtensions Methods

Docs / Reference / Search C# APIs / CommunityToolkit.Aspire.Hosting.SurrealDb / SurrealDbBuilderExtensions / Methods

Methods

Docs Reference Search C# APIs CommunityToolkit.Aspire.Hosting.SurrealDb SurrealDbBuilderExtensions Methods

Class Methods 10 members

Provides extension methods for adding SurrealDB resources to the application model.

AddDatabase(IResourceBuilder<SurrealDbNamespaceResource>, string, string?) extension IResourceBuilder<SurrealDbDatabaseResource>

Adds a SurrealDB database to the application model. This is a child resource of a SurrealDbNamespaceResource.

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbDatabaseResource> AddDatabase(
        this IResourceBuilder<SurrealDbNamespaceResource> builder,
        string name,
        string? databaseName = null)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs#L277-L311

Parameters

builder IResourceBuilder<SurrealDbNamespaceResource> The SurrealDB resource builders.

name string The name of the resource. This name will be used as the connection string name when referenced in a dependency.

databaseName string? optional The name of the database. If not provided, this defaults to the same value as name.

Returns

IResourceBuilder<SurrealDbDatabaseResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

Add a SurrealDB container to the application model and reference it in a .NET project.

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddSurrealServer("surreal")
  .AddNamespace("ns")
  .AddDatabase("db");
var api = builder.AddProject<Projects.Api>("api")
  .WithReference(db);

builder.Build().Run();

AddNamespace(IResourceBuilder<SurrealDbServerResource>, string, string?) extension IResourceBuilder<SurrealDbNamespaceResource>

Adds a SurrealDB namespace to the application model. This is a child resource of a SurrealDbServerResource.

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbNamespaceResource> AddNamespace(
        this IResourceBuilder<SurrealDbServerResource> builder,
        string name,
        string? namespaceName = null)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs#L198-L225

Parameters

builder IResourceBuilder<SurrealDbServerResource> The SurrealDB resource builders.

name string The name of the resource. This name will be used as the connection string name when referenced in a dependency.

namespaceName string? optional The name of the namespace. If not provided, this defaults to the same value as name.

Returns

IResourceBuilder<SurrealDbNamespaceResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

Add a SurrealDB container to the application model and reference it in a .NET project.

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddSurrealServer("surreal")
  .AddNamespace("ns")
  .AddDatabase("db");
var api = builder.AddProject<Projects.Api>("api")
  .WithReference(db);

builder.Build().Run();

AddSurrealServer(IDistributedApplicationBuilder, string, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>, int?, string, bool) extension IResourceBuilder<SurrealDbServerResource>

Adds a SurrealDB resource to the application model. A container is used for local development. The default image is and the tag is .

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbServerResource> AddSurrealServer(
        this IDistributedApplicationBuilder builder,
        string name,
        IResourceBuilder<ParameterResource>? userName = null,
        IResourceBuilder<ParameterResource>? password = null,
        int? port = null,
        string path = "memory",
        bool strictMode = false)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs#L64-L111

Parameters

builder IDistributedApplicationBuilder The Hosting.IDistributedApplicationBuilder.

name string The name of the resource. This name will be used as the connection string name when referenced in a dependency.

userName IResourceBuilder<ParameterResource> optional The parameter used to provide the administrator username for the SurrealDB resource.

password IResourceBuilder<ParameterResource> optional The parameter used to provide the administrator password for the SurrealDB resource. If null a random password will be generated.

port int? optional The host port for the SurrealDB instance.

path string optional Sets the path for storing data. If no argument is given, the default of memory for non-persistent storage in memory is assumed.

strictMode bool optional Whether strict mode is enabled on the server.

Returns

IResourceBuilder<SurrealDbServerResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

Add a SurrealDB container to the application model and reference it in a .NET project.

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddSurrealServer("surreal")
  .AddNamespace("ns")
  .AddDatabase("db");
var api = builder.AddProject<Projects.Api>("api")
  .WithReference(db);

builder.Build().Run();

Experimental — CTASPIRE002

WithCreationScript(IResourceBuilder<SurrealDbNamespaceResource>, string) extension IResourceBuilder<SurrealDbNamespaceResource>

Defines the SQL script used to create the namespace.

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbNamespaceResource> WithCreationScript(
        this IResourceBuilder<SurrealDbNamespaceResource> builder,
        string script)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs

Parameters

builder IResourceBuilder<SurrealDbNamespaceResource> The builder for the SurrealDbNamespaceResource.

script string The SQL script used to create the namespace.

Returns

IResourceBuilder<SurrealDbNamespaceResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

Default script is

DEFINE NAMESPACE IF NOT EXISTS `QUOTED_NAMESPACE_NAME`;

Experimental — CTASPIRE002

WithCreationScript(IResourceBuilder<SurrealDbDatabaseResource>, string) extension IResourceBuilder<SurrealDbDatabaseResource>

Defines the SQL script used to create the database.

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbDatabaseResource> WithCreationScript(
        this IResourceBuilder<SurrealDbDatabaseResource> builder,
        string script)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs

Parameters

builder IResourceBuilder<SurrealDbDatabaseResource> The builder for the SurrealDbDatabaseResource.

script string The SQL script used to create the database.

Returns

IResourceBuilder<SurrealDbDatabaseResource> A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

Default script is

DEFINE DATABASE IF NOT EXISTS `QUOTED_DATABASE_NAME`;

WithDataBindMount(IResourceBuilder<SurrealDbServerResource>, string) extension IResourceBuilder<SurrealDbServerResource>

Adds a bind mount for the data folder to a SurrealDB resource.

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbServerResource> WithDataBindMount(
        this IResourceBuilder<SurrealDbServerResource> builder,
        string source)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs#L393-L396

Parameters

builder IResourceBuilder<SurrealDbServerResource> The resource builder.

source string The source directory on the host to mount into the container.

Returns

IResourceBuilder<SurrealDbServerResource> The ApplicationModel.IResourceBuilder`1.

Remarks

Add a SurrealDB container to the application model and reference it in a .NET project. Additionally, in this example a bind mount is added to the container to allow data to be persisted across container restarts.

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddSurrealServer("surreal")
  .WithDataBindMount("./data/surreal/data")
  .AddNamespace("ns")
  .AddDatabase("db");
var api = builder.AddProject<Projects.Api>("api")
  .WithReference(db);

builder.Build().Run();

WithDataVolume(IResourceBuilder<SurrealDbServerResource>, string?) extension IResourceBuilder<SurrealDbServerResource>

Adds a named volume for the data folder to a SurrealDB resource.

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbServerResource> WithDataVolume(
        this IResourceBuilder<SurrealDbServerResource> builder,
        string? name = null)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs#L361-L363

Parameters

builder IResourceBuilder<SurrealDbServerResource> The resource builder.

name string? optional The name of the volume. Defaults to an auto-generated name based on the application and resource names.

Returns

IResourceBuilder<SurrealDbServerResource> The ApplicationModel.IResourceBuilder`1.

Remarks

Add a SurrealDB container to the application model and reference it in a .NET project. Additionally, in this example a data volume is added to the container to allow data to be persisted across container restarts.

var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddSurrealServer("surreal")
  .WithDataVolume()
  .AddNamespace("ns")
  .AddDatabase("db");
var api = builder.AddProject<Projects.Api>("api")
  .WithReference(db);

builder.Build().Run();

Experimental — CTASPIRE002

WithInitFiles(IResourceBuilder<SurrealDbServerResource>, string) extension IResourceBuilder<SurrealDbServerResource>

Copies init files into a SurrealDB container resource.

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbServerResource> WithInitFiles(
        this IResourceBuilder<SurrealDbServerResource> builder,
        string source)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs#L409-L428

Parameters

builder IResourceBuilder<SurrealDbServerResource> The resource builder.

source string The source file on the host to copy into the container.

Returns

IResourceBuilder<SurrealDbServerResource> The ApplicationModel.IResourceBuilder`1.

Exceptions

DistributedApplicationException SurrealDB only support importing a single script file.

WithLogLevel(IResourceBuilder<SurrealDbServerResource>, LogLevel) extension IResourceBuilder<SurrealDbServerResource>

Configures logging level for the SurrealDB container resource.

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbServerResource> WithLogLevel(
        this IResourceBuilder<SurrealDbServerResource> builder,
        LogLevel logLevel)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs#L442-L452

Parameters

builder IResourceBuilder<SurrealDbServerResource> The resource builder.

logLevel LogLevel The log level to set.

Returns

IResourceBuilder<SurrealDbServerResource> The ApplicationModel.IResourceBuilder`1.

WithSurrealist(IResourceBuilder<T>, Action<IResourceBuilder<SurrealistContainerResource>>, string?) extension IResourceBuilder<T>

Adds a Surrealist UI instance for SurrealDB to the application model. The default image is and the tag is .

public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<T> WithSurrealist<T>(
        this IResourceBuilder<T> builder,
        Action<IResourceBuilder<SurrealistContainerResource>>? configureContainer = null,
        string? containerName = null)
    {
        // ...
    }
}

SurrealDbBuilderExtensions.cs#L470-L517

Parameters

builder IResourceBuilder<T> The SurrealDB server resource builder.

configureContainer Action<IResourceBuilder<SurrealistContainerResource>> optional Callback to configure Surrealist container resource.

containerName string? optional The name of the container (optional).

Returns

IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1.