Create database for Sql Server resource #8022

sebastienros · 2025-03-12T00:43:59Z

Description

Support database creation for AddDatabase in Sql Server container resource. If the database already exists nothing is done. Custom scripts can be provided, using an annotation internally.

Part of #7101

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
  - If yes, did you have an API Review for it?
    - Yes
    - No
  - Did you add <remarks /> and <code /> elements on your triple slash comments?
    - Yes
    - No
- No
Does the change make any security assumptions or guarantees?
- Yes
  - If yes, have you done a threat model and had a security review?
    - Yes
    - No
- No
Does the change require an update in our Aspire docs?
- Yes
  - Is this introducing a breaking change?
    - Yes
      - Link to aspire-docs issue (please use this breaking-change template):
    - No
      - Link to aspire-docs issue (please use this doc-idea template):
- No

Copilot

Pull Request Overview

This pull request adds support for creating a database for the Sql Server resource with the option to run a custom creation script. Key changes include:

Adding a new ScriptAnnotation class used to attach custom creation scripts.
Updating tests to verify database creation and custom script execution.
Refactoring extension methods to support improved database resource registration.

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Aspire.Hosting/ApplicationModel/ScriptAnnotation.cs	Introduces the ScriptAnnotation class to encapsulate custom script logic.
tests/Aspire.Hosting.SqlServer.Tests/SqlServerFunctionalTests.cs	Updates tests to use explicit database names and verify custom script functionality.
src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs	Refactors the AddDatabase extension to use a database resource instance; however, a faulty dictionary initialization is observed.
src/Aspire.Hosting.SqlServer/SqlServerServerResource.cs	Adjusts database resource addition to use a list and dictionary; the list initialization syntax appears incorrect.
playground/SqlServerEndToEnd/SqlServerEndToEnd.AppHost/Program.cs	Comments out a setup block related to an external project dependency.

tests/Aspire.Hosting.SqlServer.Tests/SqlServerFunctionalTests.cs

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs

src/Aspire.Hosting.SqlServer/SqlServerServerResource.cs

sebastienros · 2025-03-12T00:47:57Z

tests/Aspire.Hosting.SqlServer.Tests/SqlServerFunctionalTests.cs


            var sqlserver1 = builder1.AddSqlServer("sqlserver");
-            var masterdb1 = sqlserver1.AddDatabase("master");
+            var db1 = sqlserver1.AddDatabase(databaseName);


Not using master updates this test to ensure the database is created. master was used since it's a default one in sql server.

sebastienros · 2025-03-12T01:20:25Z

tests/Aspire.Hosting.SqlServer.Tests/SqlServerFunctionalTests.cs

+    [RequiresDocker]
+    public async Task AddDatabaseCreatesDatabaseWithSpecialNames()
+    {
+        const string databaseName = "!'][\"";


@eerhardt this one might itch a bit. This was to ensure the name is correctly encoded in the default script. But I needed to change the connection string creation to encode it too.

tests/Aspire.Hosting.SqlServer.Tests/SqlServerFunctionalTests.cs

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs

davidfowl · 2025-03-12T05:05:49Z

src/Aspire.Hosting.SqlServer/SqlServerDatabaseResource.cs

+    public ReferenceExpression ConnectionStringExpression {
+        get
+        {
+            var connectionStringBuilder = new SqlConnectionStringBuilder();
+            connectionStringBuilder["Database"] = DatabaseName;
+            var connectionString = connectionStringBuilder.ToString();
+
+            return ReferenceExpression.Create($"{Parent};{connectionString}");
+        }
+    }


Formatting. Why the change?

The database name was passed directly in the connection string, so if it contains special chars conflicting with the connection string format (=";) it could break the client.

In this PR we are executing a SQL script which will have to encode the database name. I created a test for that and obviously it will fail if it's not handled at this location too.

davidfowl · 2025-03-12T06:41:18Z

This generally looks good; I wonder if we should also think about publish mode (maybe not in this PR).

eerhardt · 2025-03-12T17:00:51Z

I wonder if we should also think about publish mode (maybe not in this PR).

What does this mean exactly? For Azure SQL, we will create the DB with bicep. Are you thinking of some sort of "startup" command that runs on publish of a SQL container?

eerhardt · 2025-03-12T17:03:24Z

src/Aspire.Hosting/ApplicationModel/ScriptAnnotation.cs

+/// <summary>
+/// Represents an annotation for defining a script to create a resource.
+/// </summary>
+public sealed class ScriptAnnotation : IResourceAnnotation


I wonder if we should give this a more specific name. ScriptAnnotation sounds really general.

I was torn between a database specific name or not. But in the end it's only a string. Could have been all the way to StringAnnotation, so I understand why a more specific one would make sense. If we tell users they can add one or change it. Another advantage of a specific name is that it won't conflict with another annotation that would use the same type for something else, and we would be screwed. So I agree with that: DatabaseCreationScriptAnnotation for instance.

NB: To go all the way meta we could have general annotation like KeyValuePairAnnotation which would also have a key/value ("databasecreationscript"/"create database [foo]"). But that's why we have custom type for ;)

Given the summary of the class "for defining a script to create a resource." I thought the class would be named more specific.

Changed to CreationScriptAnnotation since there should be only on in a resource, whatever resource is using it, so there can't be a conflict.

eerhardt · 2025-03-12T17:05:25Z

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs

+
+                    using var command = sqlConnection.CreateCommand();
+                    command.CommandText = scriptAnnotation?.Script ??
+                        $"IF ( NOT EXISTS ( SELECT 1 FROM sys.databases WHERE name = @DatabaseName ) ) CREATE DATABASE {quotedDatabaseIdentifier};";


Why the difference between the name in the WHERE and the name used on the Create Database? Shouldn't they both use the same SqlParameter?

Parameters can't be used for object names (such as database names, table names, or column names).
It's used in the query part because in that case it's a string value.

eerhardt · 2025-03-12T17:07:05Z

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs

+                }
+                catch (Exception e)
+                {
+                    @event.Services.GetRequiredService<ILogger<SqlServerServerResource>>().LogError(e, "Failed to create database '{DatabaseName}'", sqlDatabase.DatabaseName);


Can we log this to resource's logger? Where does this currently log? To the console of the AppHost?

It currently shows up in the console. Would it be nice if it were in the database resource log in the dashboard? If so what is the way to do it?

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs

eerhardt

Can we also update the playground app to no longer ensure the DB is created?

aspire/playground/SqlServerEndToEnd/SqlServerEndToEnd.ApiService/Program.cs

Lines 19 to 23 in 8d2aac4

    
           // You wouldn't normally do this on every call, 
        
           // but doing it here just to make this simple. 
        
           await db1Context.Database.EnsureCreatedAsync(); 
        
           await db2Context.Database.EnsureCreatedAsync();

eerhardt · 2025-03-12T17:27:57Z

src/Aspire.Hosting/ApplicationModel/ScriptAnnotation.cs

+/// <summary>
+/// Represents an annotation for defining a script to create a resource.
+/// </summary>
+public sealed class ScriptAnnotation : IResourceAnnotation


Thinking more about this, we also have a sample for how to customize the initial database:

https://github.com/dotnet/aspire-samples/blob/fc7aa13409821eb1d7b7ccd374b465c97dca5591/samples/DatabaseContainers/DatabaseContainers.AppHost/Program.cs#L38-L45

Does this feature work well with this example?

I wonder if we really need to support a custom create database script, and instead point people to this route. (possibly with an option for turning this feature off).

cc @DamianEdwards

As a user I would definitely prefer this extension method (and annotation) to customize the create database script than having to deal with bind mounts and understand how the container is configured. The same way we have WithDataVolume extensions. Or should we provide (in addition maybe) a method to configure this "/usr/config/entrypoint.sh" script in sql server container to make it easier?

Though I would understand if we say we skip this feature (customizing CREATE DATABASE) since there is already a way to do it in the container itself.

sebastienros · 2025-03-13T01:15:51Z

Currently adding GO statements support such that we can use more complex scripts like the one referenced from the samples. This will be with conditions, like it has to be on a single line, e.g.:

-- Create the AddressBook database
IF NOT EXISTS (SELECT * FROM sys.databases WHERE name = N'AddressBook')
BEGIN
  CREATE DATABASE AddressBook;
END;
GO

USE AddressBook;
GO

-- Create the Contacts table
IF OBJECT_ID(N'Contacts', N'U') IS NULL
BEGIN
    CREATE TABLE Contacts
    (
        Id        INT PRIMARY KEY IDENTITY(1,1) ,
        FirstName VARCHAR(255) NOT NULL,
        LastName  VARCHAR(255) NOT NULL,
        Email     VARCHAR(255) NULL,
        Phone     VARCHAR(255) NULL
    );
END;
GO

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs

Co-authored-by: Dan Moseley <[email protected]>

DamianEdwards · 2025-03-15T00:17:11Z

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs

+        }
+        catch (Exception e)
+        {
+            var logger = serviceProvider.GetRequiredService<ILogger<DistributedApplicationBuilder>>();


Are we going to update this to write the log to the resource instead?

I just got taught how to, yes I will change that right away.

ErikEJ · 2025-03-26T14:40:36Z

@sebastienros This is amazing, love the script support. Together with a SQL project, This allows full lifecycle support for a persisted local database.

ErikEJ · 2025-03-28T16:32:34Z

@sebastienros @davidfowl When will this be in the latest "daily" ?? Not in 9.2.0-preview.1.25178.1

davidfowl · 2025-03-28T16:47:23Z

It should be there.

ErikEJ · 2025-03-28T16:58:33Z

@davidfowl Found it - I will show myself out!

sebastienros added 4 commits March 11, 2025 10:38

Create SQL Server database automatically

f50d0f6

Update tests to ensure new dbs are created

93efeb2

Create SQL Server container folders on Windows

8b88f42

Test custom creation script annotations

4dda707

Copilot AI review requested due to automatic review settings March 12, 2025 00:44

github-actions bot added the area-app-model Issues pertaining to the APIs in Aspire.Hosting, e.g. DistributedApplication label Mar 12, 2025

sebastienros mentioned this pull request Mar 12, 2025

[New article]: AddDatabase creates actual database dotnet/docs-aspire#2789

Closed

sebastienros requested review from davidfowl and removed request for Copilot March 12, 2025 00:45

Copilot AI reviewed Mar 12, 2025

View reviewed changes

tests/Aspire.Hosting.SqlServer.Tests/SqlServerFunctionalTests.cs Outdated Show resolved Hide resolved

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs Outdated Show resolved Hide resolved

src/Aspire.Hosting.SqlServer/SqlServerServerResource.cs Show resolved Hide resolved

sebastienros requested a review from eerhardt March 12, 2025 00:45

Revert playground changes

37a9720

sebastienros commented Mar 12, 2025

View reviewed changes

Ensure special names are encoded in the creation script

ab9548d

sebastienros commented Mar 12, 2025

View reviewed changes

danmoseley reviewed Mar 12, 2025

View reviewed changes

tests/Aspire.Hosting.SqlServer.Tests/SqlServerFunctionalTests.cs Outdated Show resolved Hide resolved

davidfowl reviewed Mar 12, 2025

View reviewed changes

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs Outdated Show resolved Hide resolved

davidfowl reviewed Mar 12, 2025

View reviewed changes

sebastienros added 2 commits March 12, 2025 09:31

PR feedback

fa47903

Formatting

c3761c2

eerhardt reviewed Mar 12, 2025

View reviewed changes

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs Outdated Show resolved Hide resolved

eerhardt reviewed Mar 12, 2025

View reviewed changes

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs Outdated Show resolved Hide resolved

eerhardt reviewed Mar 12, 2025

View reviewed changes

sebastienros requested a review from DamianEdwards March 12, 2025 17:40

Feedback

1d8456c

eerhardt approved these changes Mar 12, 2025

View reviewed changes

sebastienros added 3 commits March 12, 2025 18:49

Add support for multi-statements scripts

0a97670

Improve GO separator support

8ef42a6

Fix build

b9d281c

danmoseley reviewed Mar 13, 2025

View reviewed changes

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs Outdated Show resolved Hide resolved

Regex feedback and tests

61875ef

danmoseley reviewed Mar 14, 2025

View reviewed changes

src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs Show resolved Hide resolved

sebastienros and others added 2 commits March 14, 2025 14:33

Update src/Aspire.Hosting.SqlServer/SqlServerBuilderExtensions.cs

c5e6841

Co-authored-by: Dan Moseley <[email protected]>

Fix test and remove private reflection

98780b4

sebastienros merged commit 7810fc4 into main Mar 14, 2025
162 checks passed

sebastienros deleted the sebros/sqldatabase branch March 14, 2025 22:37

DamianEdwards reviewed Mar 15, 2025

View reviewed changes

This was referenced Mar 25, 2025

AddDatabase should create database for MySql resource #8294

Closed

Database container with multiple database schema #3799

Closed

davidfowl mentioned this pull request Apr 6, 2025

What's new in .NET Aspire 9.2 dotnet/docs-aspire#2877

Merged

RussKie mentioned this pull request Apr 22, 2025

MySql.AddDatabase creates database for resource #8912

Merged

16 tasks

RussKie added area-integrations Issues pertaining to Aspire Integrations packages and removed area-app-model Issues pertaining to the APIs in Aspire.Hosting, e.g. DistributedApplication labels Apr 22, 2025

github-actions bot locked and limited conversation to collaborators May 22, 2025

	// You wouldn't normally do this on every call,
	// but doing it here just to make this simple.

	await db1Context.Database.EnsureCreatedAsync();
	await db2Context.Database.EnsureCreatedAsync();

Create database for Sql Server resource #8022

Create database for Sql Server resource #8022

Uh oh!

Conversation

sebastienros commented Mar 12, 2025

Description

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidfowl commented Mar 12, 2025

Uh oh!

eerhardt commented Mar 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

eerhardt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sebastienros commented Mar 13, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ErikEJ commented Mar 26, 2025

Uh oh!

ErikEJ commented Mar 28, 2025

Uh oh!

davidfowl commented Mar 28, 2025

Uh oh!

ErikEJ commented Mar 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants