Get started with the SQLite integrations

このコンテンツはまだ日本語訳がありません。

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

In this introduction, you’ll see how to install and use the Aspire SQLite integrations in a simple configuration. If you already have this knowledge, see SQLite Hosting integration for full reference details.

Set up hosting integration

To begin, install the Aspire SQLite Hosting integration in your Aspire AppHost project. This integration allows you to create and manage SQLite database instances from your Aspire hosting projects:

aspire add sqlite

Aspire CLI は対話的です。求められたら適切な結果を選択してください:

Select an integration to add:

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

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

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

Next, in the AppHost project, create an instance of a SQLite database resource, then pass the database to the consuming client projects:

Select your programming language to get started

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSqlite("sqlite");

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

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSqlite("sqlite");

var exampleProject = builder.AddUvicornApp("api", "./api", "main.app")
                            .WithExternalHttpEndpoints()
                            .WithReference(sqlite);

var builder = DistributedApplication.CreateBuilder(args);

var sqlite = builder.AddSqlite("sqlite");

var api = builder.AddNodeApp("api", "./api", scriptPath: "index.js")
                 .WithExternalHttpEndpoints()
                 .WithReference(sqlite);

Use the integration in client projects

Now that the hosting integration is ready, the next step is to install and configure the client integration in any projects that need to use it.

Set up client projects

In each of these consuming client projects, install the Aspire SQLite client integration:

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

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

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

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

builder.AddSqliteConnection("sqlite");

To interact with SQLite databases in your Python consuming projects, you can use the built-in sqlite3 module (included in Python’s standard library). No additional installation is required:

import sqlite3
import os

To interact with SQLite databases in your JavaScript consuming projects, you need to include a SQLite client library. A popular option is sqlite3. You can install this library using npm:

npm install sqlite3

Ensure that you import sqlite3 in code files that interact with the database:

import sqlite3 from 'sqlite3';

Use injected SQLite properties

In the AppHost, when you used the WithReference method to pass a SQLite database resource to a consuming client project, Aspire injects the data source configuration property that you can use in the consuming project.

Aspire exposes the property as an environment variable named [RESOURCE]_DATASOURCE. For instance, the data source of a resource called sqlite becomes SQLITE_DATASOURCE.

Use the GetValue() method to obtain this environment variable in consuming projects:

string sqldatasource = builder.Configuration.GetValue<string>("SQLITE_DATASOURCE");

Use the os.getenv() method to obtain this environment variable in consuming projects:

connection_string = os.getenv("SQLITE_DATASOURCE")

Use the process.env method to obtain this environment variable in consuming projects:

const connectionString = process.env.SQLITE_DATASOURCE;

Use SQLite resources in client code

Now that you’ve added SqliteConnection to the builder in the consuming project, you can use the SQLite resource to get and store data. Get the SqliteConnection instance using dependency injection. For example, to retrieve your connection object from an example service define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

public class ExampleService(SqliteConnection connection)
{
    // Use connection to query the database...
}

Having obtained the connection, you can work with the SQLite database as you would in any other C# application.

Use the information you have obtained about the SQLite resource to connect to the database. Here is an example of how to connect using sqlite3:

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

Having obtained the connection, you can work with the SQLite database as you would in any other Python application.

Use the information you have obtained about the SQLite resource to connect to the database. Here is an example of how to connect using sqlite3:

const db = new sqlite3.Database(connectionString);

Having obtained the connection, you can work with the SQLite database as you would in any other JavaScript application.

Next steps

Now, that you have an Aspire app with SQLite integrations up and running, you can use the following reference documents to learn how to configure and interact with the SQLite resources:

Understand the SQLite hosting integration Discover how to configure custom database locations, SQLiteWeb interface, and more.

Understand the SQLite client integration Discover how to configure keyed clients, client integration health checks, and more.