Get started with SQL Database Projects

⭐ Community Toolkit

The SQL Database Projects hosting integration deploys a DACPAC to a SQL Server database as part of your Aspire AppHost. Use it to keep a database schema alongside the services that depend on it during local development and testing.

How the pieces fit together

This is a hosting-only integration. Your AppHost models a SQL project resource and a target database. When the target database is ready, the integration publishes the DACPAC. The SQL project resource is a deployment task, not a connection resource; applications that need database access reference the SQL Server database directly.

architecture-beta
  group apphost(server)[AppHost]
  group app(server)[Application]

  service sqlproject(database)[SQL project resource] in apphost
  service database(database)[SQL Server database] in apphost
  service application(server)[App] in app

  sqlproject:R --> L:database
  database:R --> L:application

Prerequisites

Install the Aspire CLI and use an AppHost with the SQL Server hosting integration.
Build your database with either MSBuild.Sdk.SqlProj or Microsoft.Build.Sql. The integration deploys the resulting .dacpac file.
For a C# AppHost, you can add a project reference to the SQL project and use the generated Projects.* metadata type. For a TypeScript AppHost, supply the DACPAC path.

Add a SQL project resource

Install the Community Toolkit hosting package in the AppHost:

aspire add CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects

Then add the SQL Server database and a SQL project resource. Update the DACPAC path to match your database project’s output.

TypeScript
C#

import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();
const appHostDirectory = path.dirname(fileURLToPath(import.meta.url));
const dacpacPath = path.join(
  appHostDirectory,
  '../Database/bin/Debug/net10.0/Database.dacpac'
);

const sql = await builder.addSqlServer('sql');
const database = await sql.addDatabase('catalog');
const databaseProject = await builder.addSqlProject('catalog-schema');

await databaseProject.withDacpac(dacpacPath);
await databaseProject.withReference(database);

await builder.build().run();

var builder = DistributedApplication.CreateBuilder(args);

var database = builder.AddSqlServer("sql")
    .AddDatabase("catalog");

builder.AddSqlProject("catalog-schema")
    .WithDacpac("../Database/bin/Debug/net10.0/Database.dacpac")
    .WithReference(database);

builder.Build().Run();

For all resource APIs, deployment options, dashboard actions, and support for an existing SQL Server, see the hosting reference.

Configure SQL Database Projects in the AppHost