SQLite Hosting integration reference

⭐ Community Toolkit

To get started with the Aspire SQLite integrations, follow the Get started with SQLite integrations guide.

This article includes full details about the Aspire SQLite Hosting integration, which models a SQLite database as the SQLiteResource type. To access these types and APIs, you need to install the SQLite Hosting integration in your AppHost project.

Installation

The SQLite hosting integration models a SQLite database as the SQLiteResource type and will create the database file in the specified location. To get started with the Aspire SQLite hosting integration, install the 📦 CommunityToolkit.Aspire.Hosting.SQLite NuGet package in your AppHost project:

dotnet add package CommunityToolkit.Aspire.Hosting.SQLite

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 user's 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 builder = DistributedApplication.CreateBuilder(args);
  
var sqlite = builder.AddSqlite("my-database", "C:\\Database\\Location", "my-database.db");
  
var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(sqlite);

The preceding code creates a SQLite database file at C:\Database\Location\my-database.db. The database file is created if it doesn't already exist.

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 builder = DistributedApplication.CreateBuilder(args);
  
var sqlite = builder.AddSqlite("my-database")
                    .WithSqliteWeb();
  
var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(sqlite);

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.

When you run the solution, the Aspire dashboard displays the SQLiteWeb resource with an endpoint. Select the link to the endpoint to view SQLiteWeb in a new browser tab.

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.

var builder = DistributedApplication.CreateBuilder(args);
  
var sqlite = builder.AddSqlite("my-database")
                    .WithNuGetExtension("SQLitePCLRaw.lib.e_sqlite3");
  
var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(sqlite);

var builder = DistributedApplication.CreateBuilder(args);
  
var sqlite = builder.AddSqlite("my-database")
                    .WithLocalExtension("C:\\Extensions\\my-extension.dll");
  
var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(sqlite);

Pass connection information to app resources

When you use the WithReference method to pass a SQLite database resource to an app resource such as a Python or JavaScript app, Aspire automatically injects environment variables that describe the connection information.

For example, if you reference a SQLite database resource named sqlite:

var sqlite = builder.AddSqlite("sqlite");
  
var pythonApp = builder.AddUvicornApp("api", "./api", "main:app")
    .WithReference(sqlite);

The following environment variable is available in the Python application:

• SQLITE_DATASOURCE - The connection string for the sqlite resource, containing the database file path

You can access this environment variable in your application code:

const connectionString = process.env.SQLITE_DATASOURCE;
  
const db = new sqlite3.Database(connectionString);

For the complete list of properties available, see Properties of the SQLite resources.