# SurrealDbBuilderExtensions Methods

- Package: [CommunityToolkit.Aspire.Hosting.SurrealDb](/reference/api/csharp/communitytoolkit.aspire.hosting.surrealdb.md)
- Type: [SurrealDbBuilderExtensions](/reference/api/csharp/communitytoolkit.aspire.hosting.surrealdb/surrealdbbuilderextensions.md)
- Kind: `Methods`
- Members: `11`

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

## AddDatabase(IResourceBuilder<SurrealDbNamespaceResource>, string, string?)

- Name: `AddDatabase(IResourceBuilder<SurrealDbNamespaceResource>, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbDatabaseResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L283-L317)

Adds a SurrealDB database to the application model. This is a child resource of a [SurrealDbNamespaceResource](/reference/api/csharp/communitytoolkit.aspire.hosting.surrealdb/surrealdbnamespaceresource.md).

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

## 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.

```csharp
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();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## AddNamespace(IResourceBuilder<SurrealDbServerResource>, string, string?)

- Name: `AddNamespace(IResourceBuilder<SurrealDbServerResource>, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbNamespaceResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L201-L228)

Adds a SurrealDB namespace to the application model. This is a child resource of a [SurrealDbServerResource](/reference/api/csharp/communitytoolkit.aspire.hosting.surrealdb/surrealdbserverresource.md).

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

## 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.

```csharp
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();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `AddSurrealServer(IDistributedApplicationBuilder, string, IResourceBuilder<ParameterResource>, IResourceBuilder<ParameterResource>, int?, string, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbServerResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L65-L112)

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

```csharp
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)
    {
        // ...
    }
}
```

## 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.

```csharp
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();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithCreationScript(IResourceBuilder<SurrealDbNamespaceResource>, string)

> **Experimental:** CTASPIRE002 - [Learn more](/diagnostics/ctaspire002/)

- Name: `WithCreationScript(IResourceBuilder<SurrealDbNamespaceResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbNamespaceResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs)

Defines the SQL script used to create the namespace.

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

## Parameters

- `builder` (`IResourceBuilder<SurrealDbNamespaceResource>`)
  The builder for the [SurrealDbNamespaceResource](/reference/api/csharp/communitytoolkit.aspire.hosting.surrealdb/surrealdbnamespaceresource.md).
- `script` (`string`)
  The SQL script used to create the namespace.

## Returns

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

## Remarks

Default script is

```csharp
DEFINE NAMESPACE IF NOT EXISTS `QUOTED_NAMESPACE_NAME`;
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithCreationScript(IResourceBuilder<SurrealDbDatabaseResource>, string)

> **Experimental:** CTASPIRE002 - [Learn more](/diagnostics/ctaspire002/)

- Name: `WithCreationScript(IResourceBuilder<SurrealDbDatabaseResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbDatabaseResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs)

Defines the SQL script used to create the database.

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

## Parameters

- `builder` (`IResourceBuilder<SurrealDbDatabaseResource>`)
  The builder for the [SurrealDbDatabaseResource](/reference/api/csharp/communitytoolkit.aspire.hosting.surrealdb/surrealdbdatabaseresource.md).
- `script` (`string`)
  The SQL script used to create the database.

## Returns

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

## Remarks

Default script is

```csharp
DEFINE DATABASE IF NOT EXISTS `QUOTED_DATABASE_NAME`;
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithDataBindMount(IResourceBuilder<SurrealDbServerResource>, string)

- Name: `WithDataBindMount(IResourceBuilder<SurrealDbServerResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbServerResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L402-L405)

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

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

## 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.

```csharp
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();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithDataVolume(IResourceBuilder<SurrealDbServerResource>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbServerResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L369-L371)

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

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

## 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.

```csharp
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();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithInitFiles(IResourceBuilder<SurrealDbServerResource>, string)

> **Experimental:** CTASPIRE002 - [Learn more](/diagnostics/ctaspire002/)

- Name: `WithInitFiles(IResourceBuilder<SurrealDbServerResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbServerResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L419-L438)

Copies init files into a SurrealDB container resource.

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

## 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.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithLogLevel(IResourceBuilder<SurrealDbServerResource>, LogLevel)

- Name: `WithLogLevel(IResourceBuilder<SurrealDbServerResource>, LogLevel)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbServerResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L454-L464)

Configures logging level for the SurrealDB container resource.

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

## Parameters

- `builder` (`IResourceBuilder<SurrealDbServerResource>`)
  The resource builder.
- `logLevel` (`LogLevel`)
  The log level to set.

## Returns

`IResourceBuilder<SurrealDbServerResource>` -- The `ApplicationModel.IResourceBuilder`1`.

## Remarks

This overload is not available in polyglot app hosts. Use the exported string-based overload instead.

## ATS metadata

### Ignored by ATS

- Excluded from automatic Polyglot export.

## WithOtlpExporter(IResourceBuilder<SurrealDbServerResource>)

- Name: `WithOtlpExporter(IResourceBuilder<SurrealDbServerResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<SurrealDbServerResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L497-L502)

Injects the appropriate environment variables to allow the resource to enable sending telemetry to the dashboard. 1. It sets the OTLP endpoint to the value of the DOTNET_DASHBOARD_OTLP_ENDPOINT_URL environment variable. 2. It sets the service name and instance id to the resource name and UID. Values are injected by the orchestrator. 3. It sets a small batch schedule delay in development. This reduces the delay that OTLP exporter waits to sends telemetry and makes the dashboard telemetry pages responsive.

```csharp
public static class SurrealDbBuilderExtensions
{
    public static IResourceBuilder<SurrealDbServerResource> WithOtlpExporter(
        this IResourceBuilder<SurrealDbServerResource> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<SurrealDbServerResource>`)
  The resource builder.

## Returns

`IResourceBuilder<SurrealDbServerResource>` -- The `ApplicationModel.IResourceBuilder`1`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

- Name: `WithSurrealist(IResourceBuilder<T>, Action<IResourceBuilder<SurrealistContainerResource>>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d9dc6fc02412d7398c5722840513d99965a6e98f/src/CommunityToolkit.Aspire.Hosting.SurrealDb/SurrealDbBuilderExtensions.cs#L522-L569)

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

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

## 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`.

## Remarks

This overload is not available in polyglot app hosts. Use the exported overload instead.

## ATS metadata

### Ignored by ATS

- Excluded from automatic Polyglot export.