Update and restructure SQLite integration docs #149

alistairmatthews · 2025-12-11T16:11:50Z

The existing SQLite integration document is comprehensive but difficult for beginners. This PR is intended to keep the comprehensive information but make it easier for those who want to get going quickly. I've used Copilot to propagate changes from the new PostgreSQL documents to the SQLite ones.

This PR:

Splits the large integration doc into two: Hosting and Client.
Adds a getting started short tutorial.
Adds a Properties of the SQLite resources section to the client reference docs. This describes what configuration values are injected by the WithReference() method.

…docs

Copilot

Pull request overview

This PR restructures the SQLite integration documentation to improve accessibility for beginners while maintaining comprehensive information. The single monolithic SQLite documentation file has been split into three focused documents: a getting started guide, a hosting integration reference, and a client integration reference.

Key changes:

Split comprehensive SQLite docs into three separate files for better organization
Added a new getting started tutorial with C#, Python, and JavaScript examples
Added detailed "Properties of the SQLite resources" section documenting environment variables injected by WithReference()

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/frontend/src/data/integration-docs.json	Updates package-to-documentation URL mappings for the new split structure
src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-host.mdx	New hosting integration reference documenting SQLite resource creation, SQLiteWeb, and extensions
src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-get-started.mdx	New getting started guide with multi-language examples for quick onboarding
src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-client.mdx	New client integration reference documenting connection configuration and usage
src/frontend/src/content/docs/integrations/databases/sqlite.mdx	Removed original monolithic documentation file
src/frontend/config/sidebar/integrations.topics.ts	Updates navigation structure to show collapsible SQLite section with three sub-pages

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-19T15:35:35Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-get-started.mdx

+Aspire exposes the property as an environment variable named `[RESOURCE]_DATASOURCE`. For instance, the data source of a resource called `sqlite` becomes `SQLITE_DATASOURCE`.
+
+<Pivot id="csharp">
+
+Use the `GetValue()` method to obtain this environment variable in consuming projects:
+
+```csharp title="C# - Obtain configuration properties"
+string sqldatasource = builder.Configuration.GetValue<string>("SQLITE_DATASOURCE");


The description states that the property is exposed as an environment variable named [RESOURCE]_DATASOURCE, but this naming convention is inconsistent with the description in sqlite-host.mdx line 123 which refers to ConnectionStrings__sqlite. These two environment variable naming conventions appear to be different - one uses underscores with DATASOURCE suffix, the other uses double underscores with ConnectionStrings prefix. Please clarify which convention is actually used or if both are available.

Suggested change

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

<Pivot id="csharp">

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

```csharp title="C# - Obtain configuration properties"

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

Aspire exposes this value via the standard .NET configuration key `ConnectionStrings:[RESOURCE]`. For instance, the data source of a resource called `sqlite` is available as the configuration key `ConnectionStrings:sqlite`, which corresponds to the environment variable name `ConnectionStrings__sqlite`.

<Pivot id="csharp">

Use the `GetConnectionString()` method to obtain this value in consuming projects:

```csharp title="C# - Obtain configuration properties"

string sqliteConnectionString = builder.Configuration.GetConnectionString("sqlite");

Copilot · 2025-12-19T15:35:35Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-client.mdx

+When you use the `WithReference` method to pass a SQLite database resource from the AppHost project to a consuming client project, Aspire exposes the data source as an environment variable with a standardized naming convention:
+
+| Property Name | Description | Environment Variable Format |
+|---------------|-------------|----------------------------|
+| `DataSource` | The data source path containing the database file path. | `C:\{Path}\{Databasefile}.db` |
+
+<Aside type="note">
+  Aspire exposes the data source as an environment variable named `{ResourceName}_DATASOURCE`. For instance, a resource called `sqlite` would have its data source string available as `SQLITE_DATASOURCE`.


The table in this section describes only the DataSource property, but the documentation in sqlite-get-started.mdx (line 158) and sqlite-host.mdx (line 123) references environment variables with different naming conventions ({ResourceName}_DATASOURCE vs ConnectionStrings__sqlite). The documentation should clarify all environment variables that are injected by WithReference, not just DataSource, to provide complete information for non-.NET applications.

Suggested change

When you use the `WithReference` method to pass a SQLite database resource from the AppHost project to a consuming client project, Aspire exposes the data source as an environment variable with a standardized naming convention:

| Property Name | Description | Environment Variable Format |

|---------------|-------------|----------------------------|

| `DataSource` | The data source path containing the database file path. | `C:\{Path}\{Databasefile}.db` |

<Aside type="note">

Aspire exposes the data source as an environment variable named `{ResourceName}_DATASOURCE`. For instance, a resource called `sqlite` would have its data source string available as `SQLITE_DATASOURCE`.

When you use the `WithReference` method to pass a SQLite database resource from the AppHost project to a consuming client project, Aspire exposes the SQLite connection information via environment variables with standardized naming conventions:

| Property Name | Description | Environment Variable |

|---------------|-------------|----------------------|

| `DataSource` | The SQLite connection string or data source path containing the database file path (for example, `Data Source=C:\{Path}\{Databasefile}.db`). | - `{RESOURCE_NAME}_DATASOURCE`<br />- `ConnectionStrings__{ResourceName}` |

<Aside type="note">

Aspire exposes the same `DataSource` value under multiple environment variable names:

<ul>

<li><code>{RESOURCE_NAME}_DATASOURCE</code> — a generic environment variable that can be used by any consumer (for example, a resource called <code>sqlite</code> would have <code>SQLITE_DATASOURCE</code>).</li>

<li><code>ConnectionStrings__{ResourceName}</code> — the conventional .NET configuration key for the connection string (for example, <code>ConnectionStrings__sqlite</code>).</li>

</ul>

Non-.NET applications will typically read <code>{RESOURCE_NAME}_DATASOURCE</code> directly, while .NET applications can use the <code>ConnectionStrings</code> configuration section.

Copilot · 2025-12-19T15:35:35Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-get-started.mdx

+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`:
+
+```javascript title="JavaScript - Connect to SQLite"
+const db = new sqlite3.Database(connectionString);


This code uses 'sqlite3.Database()' which matches the 'sqlite3' package mentioned earlier, but this conflicts with sqlite-host.mdx which uses 'better-sqlite3'. The code should be consistent across all documentation files. Additionally, if using the 'sqlite3' package, the code should account for its asynchronous callback-based API rather than the synchronous API shown here.

Suggested change

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

```javascript title="JavaScript - Connect to SQLite"

const db = new sqlite3.Database(connectionString);

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

```javascript title="JavaScript - Connect to SQLite"

import Database from 'better-sqlite3';

const db = new Database(connectionString);

Copilot · 2025-12-19T15:35:36Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-client.mdx

+```
+
+<Aside type="caution">
+When using keyed services, it's expected that your SQLite resource configured two named databases, one for the `chat` and one for the `queue`.


The sentence "it's expected that your SQLite resource configured two named databases" is grammatically awkward. It should clarify that the AppHost project should have configured two resources.

Suggested change

When using keyed services, it's expected that your SQLite resource configured two named databases, one for the `chat` and one for the `queue`.

When using keyed services, your AppHost project is expected to configure two SQLite resources (or named databases), one for `chat` and one for `queue`.

Copilot · 2025-12-19T15:35:36Z

src/frontend/src/data/integration-docs.json

  {
    "match": "CommunityToolkit.Aspire.Microsoft.EntityFrameworkCore.Sqlite",
-    "href": "/integrations/databases/sqlite/"
+    "href": "/integrations/databases/sqlite/sqlite-host/"


The link for the Entity Framework SQLite package points to the hosting integration page (sqlite-host), but it should point to the client integration page (sqlite-client) since Entity Framework is a client-side library.

Suggested change

"href": "/integrations/databases/sqlite/sqlite-host/"

"href": "/integrations/databases/sqlite/sqlite-client/"

Copilot · 2025-12-19T15:35:36Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-get-started.mdx

+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:
+
+```bash
+npm install sqlite3
+```
+
+Ensure that you `import sqlite3` in code files that interact with the database:
+
+```javascript title="JavaScript - Import sqlite3"
+import sqlite3 from 'sqlite3';
+```


The JavaScript examples show inconsistent package usage. Here it recommends installing 'sqlite3' and using 'sqlite3.Database()', but sqlite-host.mdx line 141 imports from 'better-sqlite3' and uses 'Database' directly. These are different packages with different APIs: 'sqlite3' is asynchronous and uses callbacks, while 'better-sqlite3' is synchronous. The documentation should use the same package consistently, or clearly explain when to use each package.

Copilot · 2025-12-19T15:35:37Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-host.mdx

+- `ConnectionStrings__sqlite` - The connection string containing the database file path
+


The environment variable naming shown here is 'ConnectionStrings__sqlite', which differs from the 'SQLITE_DATASOURCE' convention mentioned in sqlite-get-started.mdx line 158 and sqlite-client.mdx line 93. These appear to be different environment variables with different purposes, but the documentation should clarify which variables are available and when to use each one.

Suggested change

- `ConnectionStrings__sqlite` - The connection string containing the database file path

- `ConnectionStrings__sqlite` - The connection string for the `sqlite` resource, containing the database file path

This environment variable is distinct from the `SQLITE_DATASOURCE` variable mentioned in the other SQLite documentation pages. Use `ConnectionStrings__<resource-name>` when consuming a SQLite resource from non-.NET applications via `.WithReference`, and use `SQLITE_DATASOURCE` (or the corresponding `ConnectionStrings:` configuration entry) when using the SQLite client integration from .NET applications, as described in the [getting started](../sqlite-get-started/) and [client](../sqlite-client/) guides.

Copilot · 2025-12-19T15:35:37Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-host.mdx

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


Should be "user's temp directory" (possessive) rather than "users temp directory".

Suggested change

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.

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.

Copilot · 2025-12-19T15:35:37Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-host.mdx

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


The method name is inconsistent - the text says "AddSQLite" (all caps "SQL") but the code example on line 40 uses "AddSqlite" (title case "Sql"). The code example is correct based on C# naming conventions, so the text should be updated to match.

Suggested change

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

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

Copilot · 2025-12-19T15:35:37Z

src/frontend/src/content/docs/integrations/databases/sqlite/sqlite-get-started.mdx

+                            .WaitFor(sqlite)
+                            .WithReference(sqlite);
+```
+
+</Pivot>
+
+<Pivot id="python">
+
+```csharp title="C# — AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var sqlite = builder.AddSqlite("sqlite");
+
+var exampleProject = builder.AddUvicornApp("api", "./api", "main.app")
+                            .WithExternalHttpEndpoints()
+                            .WaitFor(sqlite)
+                            .WithReference(sqlite);
+```
+
+</Pivot>
+
+<Pivot id="javascript">
+
+```csharp title="C# — AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var sqlite = builder.AddSqlite("sqlite");
+
+var api = builder.AddNodeApp("api", "./api", scriptPath: "index.js")
+                 .WithExternalHttpEndpoints()
+                 .WaitFor(sqlite)
+                 .WithReference(sqlite);


The use of WaitFor(sqlite) with a SQLite database resource may not be necessary. Unlike server-based databases that need to start up, SQLite is a file-based database that is immediately available. The WaitFor method is typically used for resources that have a startup time. Consider removing this or adding a note explaining why it's used here.

alistairmatthews added 6 commits December 11, 2025 15:07

Claude's initial changes.

9ad7026

My corrections.

81a692b

Fixed conflict and updated links.

389adfb

Fixed out-of-date links to SQLite docs.

c7e1414

Corrected environment variables.

76206ce

Merge remote-tracking branch 'upstream/main' into restructure-sqlite-…

9a3845f

…docs

alistairmatthews marked this pull request as ready for review December 19, 2025 15:29

alistairmatthews requested review from IEvangelist, aaronpowell and eerhardt as code owners December 19, 2025 15:29

Copilot AI review requested due to automatic review settings December 19, 2025 15:29

Copilot started reviewing on behalf of alistairmatthews December 19, 2025 15:29 View session

Copilot AI reviewed Dec 19, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update and restructure SQLite integration docs #149

Update and restructure SQLite integration docs #149

Uh oh!

alistairmatthews commented Dec 11, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Copilot AI Dec 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

-When you use the `WithReference` method to pass a SQLite database resource from the AppHost project to a consuming client project, Aspire exposes the data source as an environment variable with a standardized naming convention:
-| Property Name | Description | Environment Variable Format |
-|---------------|-------------|----------------------------|
-| `DataSource` | The data source path containing the database file path. | `C:\{Path}\{Databasefile}.db` |
-<Aside type="note">
-  Aspire exposes the data source as an environment variable named `{ResourceName}_DATASOURCE`. For instance, a resource called `sqlite` would have its data source string available as `SQLITE_DATASOURCE`.
+When you use the `WithReference` method to pass a SQLite database resource from the AppHost project to a consuming client project, Aspire exposes the SQLite connection information via environment variables with standardized naming conventions:
+| Property Name | Description | Environment Variable |
+|---------------|-------------|----------------------|
+| `DataSource`  | The SQLite connection string or data source path containing the database file path (for example, `Data Source=C:\{Path}\{Databasefile}.db`). | - `{RESOURCE_NAME}_DATASOURCE`<br />- `ConnectionStrings__{ResourceName}` |
+<Aside type="note">
+  Aspire exposes the same `DataSource` value under multiple environment variable names:
+  <ul>
+    <li><code>{RESOURCE_NAME}_DATASOURCE</code> &mdash; a generic environment variable that can be used by any consumer (for example, a resource called <code>sqlite</code> would have <code>SQLITE_DATASOURCE</code>).</li>
+    <li><code>ConnectionStrings__{ResourceName}</code> &mdash; the conventional .NET configuration key for the connection string (for example, <code>ConnectionStrings__sqlite</code>).</li>
+  </ul>
+  Non-.NET applications will typically read <code>{RESOURCE_NAME}_DATASOURCE</code> directly, while .NET applications can use the <code>ConnectionStrings</code> configuration section.

	When using keyed services, it's expected that your SQLite resource configured two named databases, one for the `chat` and one for the `queue`.
	When using keyed services, your AppHost project is expected to configure two SQLite resources (or named databases), one for `chat` and one for `queue`.

	"href": "/integrations/databases/sqlite/sqlite-host/"
	"href": "/integrations/databases/sqlite/sqlite-client/"

		- `ConnectionStrings__sqlite` - The connection string containing the database file path

-- `ConnectionStrings__sqlite` - The connection string containing the database file path
+- `ConnectionStrings__sqlite` - The connection string for the `sqlite` resource, containing the database file path
+This environment variable is distinct from the `SQLITE_DATASOURCE` variable mentioned in the other SQLite documentation pages. Use `ConnectionStrings__<resource-name>` when consuming a SQLite resource from non-.NET applications via `.WithReference`, and use `SQLITE_DATASOURCE` (or the corresponding `ConnectionStrings:` configuration entry) when using the SQLite client integration from .NET applications, as described in the [getting started](../sqlite-get-started/) and [client](../sqlite-client/) guides.

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


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

Update and restructure SQLite integration docs #149

Are you sure you want to change the base?

Update and restructure SQLite integration docs #149

Uh oh!

Conversation

alistairmatthews commented Dec 11, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant