SQLite Hosting integration reference

Ce contenu n’est pas encore disponible dans votre langue.

⭐ 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:

aspire add communitytoolkit-sqlite

La CLI Aspire est interactive ; choisissez le résultat approprié lorsque demandé :

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 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);

Using with non-.NET applications

When you use the WithReference method to pass a SQLite database resource to a non-.NET application (such as Python or JavaScript), 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:

import os
import sqlite3

connection_string = os.getenv("SQLITE_DATASOURCE")

connection = sqlite3.connect(connection_string)
cursor = connection.cursor()

import sqlite3 from 'sqlite3';

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.