SQLite integration

⭐ Community Toolkit

SQLite is a lightweight, serverless, self-contained SQL database engine that is widely used for local data storage in applications. The Aspire SQLite integration provides a way to use SQLite databases within your Aspire applications, and access them via the Microsoft.Data.Sqlite client.

Hosting integration

The SQLite hosting integration models a SQLite database as the SQLiteResource type and will create the database file in the specified location. To access these types and APIs, install the 📦 CommunityToolkit.Aspire.Hosting.SQLite NuGet package in the AppHost project.

aspire add communitytoolkit-sqlite

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> communitytoolkit-sqlite (CommunityToolkit.Aspire.Hosting.SQLite)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.SQLite@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.SQLite" Version="*" />

Add SQLite resource

In the AppHost project, register and consume the SQLite integration using the AddSQLite extension method to add the SQLite database to the application builder.

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSQLite("my-database");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(sqlite);

When Aspire adds a SQLite database to the AppHost, as shown in the preceding example, it creates a new SQLite database file in the users temp directory.

Alternatively, if you want to specify a custom location for the SQLite database file, provide the relevant arguments to the AddSqlite method.

var sqlite = builder.AddSQLite("my-database", "C:\\Database\\Location", "my-database.db");

Add SQLiteWeb resource

When adding the SQLite resource, you can also add the SQLiteWeb resource, which provides a web interface to interact with the SQLite database. To do this, use the WithSqliteWeb extension method.

var sqlite = builder.AddSQLite("my-database")
                    .WithSqliteWeb();

This code adds a container based on ghcr.io/coleifer/sqlite-web to the AppHost, which provides a web interface to interact with the SQLite database it is connected to. Each SQLiteWeb instance is connected to a single SQLite database, meaning that if you add multiple SQLiteWeb instances, there will be multiple SQLiteWeb containers.

Adding SQLite extensions

SQLite supports extensions that can be added to the SQLite database. Extensions can either be provided via a NuGet package, or via a location on disk. Use either the WithNuGetExtension or WithLocalExtension extension methods to add extensions to the SQLite database.

Client integration

To get started with the Aspire SQLite client integration, install the 📦 CommunityToolkit.Aspire.Microsoft.Data.Sqlite NuGet package in the client-consuming project. The SQLite client integration registers a SqliteConnection instance that you can use to interact with SQLite.

dotnet add package CommunityToolkit.Aspire.Microsoft.Data.Sqlite

#:package CommunityToolkit.Aspire.Microsoft.Data.Sqlite@*

<PackageReference Include="CommunityToolkit.Aspire.Microsoft.Data.Sqlite" Version="*" />

Add SQLite client

In the Program.cs file of your client-consuming project, call the AddSqliteConnection extension method to register a SqliteConnection for use via the dependency injection container. The method takes a connection name parameter.

builder.AddSqliteConnection(name: "sqlite");

After adding SqliteConnection to the builder, you can get the SqliteConnection instance using dependency injection. For example, to retrieve your connection object from an example service define it as a constructor parameter:

public class ExampleService(SqliteConnection connection)
{
    // Use connection...
}

Add keyed SQLite client

There might be situations where you want to register multiple SqliteConnection instances with different connection names. To register keyed SQLite clients, call the AddKeyedSqliteConnection method:

builder.AddKeyedSqliteConnection(name: "chat");
builder.AddKeyedSqliteConnection(name: "queue");

Then you can retrieve the SqliteConnection instances using dependency injection:

public class ExampleService(
    [FromKeyedServices("chat")] SqliteConnection chatConnection,
    [FromKeyedServices("queue")] SqliteConnection queueConnection)
{
    // Use connections...
}

Configuration

The SQLite client integration provides multiple configuration approaches and options to meet the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling the AddSqliteConnection method:

builder.AddSqliteConnection("sqlite");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

{
  "ConnectionStrings": {
    "sqlite": "Data Source=C:\\Database\\Location\\my-database.db"
  }
}

Use configuration providers

The SQLite client integration supports configuration. It loads the settings from configuration using the Aspire:Sqlite:Client key. Example appsettings.json that configures some of the options:

{
  "Aspire": {
    "Sqlite": {
      "Client": {
        "ConnectionString": "Data Source=C:\\Database\\Location\\my-database.db",
        "DisableHealthCheck": true
      }
    }
  }
}

FAQ Collaborate Community Discuss Watch