Skip to content

Fix incorrect XML documentation in database AddDatabase methods for PostgreSQL, MySQL, and SQL Server #10866

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Aug 7, 2025

The XML documentation for database AddDatabase methods across PostgreSQL, MySQL, and SQL Server extensions contained misleading or incomplete information about automatic database creation behavior.

The Issue

The PostgreSQL documentation incorrectly stated:

Note that by default calling AddDatabase(IResourceBuilder{PostgresServerResource}, string, string?) does not result in the database being created on the Postgres server. It is expected that code within your solution will create the database.

Meanwhile, MySQL and SQL Server had minimal documentation that didn't explain the database creation behavior at all.

However, the actual implementation in all three providers shows that databases ARE created automatically:

  1. All providers subscribe to ResourceReadyEvent/OnResourceReady
  2. When the database server becomes ready, they automatically call CreateDatabaseAsync for each database
  3. The CreateDatabaseAsync methods execute CREATE DATABASE commands

This is also confirmed by functional tests which successfully connect to databases that were added via AddDatabase.

The Fix

Updated the XML documentation across all three database providers to accurately reflect the actual behavior:

  • PostgreSQL: Corrected the misleading documentation
  • MySQL: Added comprehensive documentation explaining automatic database creation
  • SQL Server: Added comprehensive documentation explaining automatic database creation

All three now consistently document:

Note that calling AddDatabase(...) will result in the database being created on the server when the server becomes ready. The database creation happens automatically as part of the resource lifecycle.

This ensures developers have correct and consistent information about how databases are handled across all .NET Aspire database providers.

Fixes #10858.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

@davidfowl davidfowl marked this pull request as ready for review August 7, 2025 05:21
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR fixes incorrect XML documentation in the PostgreSQL extension's AddDatabase method. The documentation previously stated that databases are NOT automatically created, which was misleading since the implementation actually does create databases when the server becomes ready.

  • Updates XML documentation to correctly reflect that databases WILL be automatically created
  • Removes misleading guidance about requiring manual database creation
  • Corrects the waitFor behavior documentation

/// is used with this resource it will wait indefinitely until the database exists.
/// Note that calling <see cref="AddDatabase(IResourceBuilder{PostgresServerResource}, string, string?)"/>
/// will result in the database being created on the Postgres server when the server becomes ready.
/// The database creation happens automatically as part of the resource lifecycle.
Copy link
Preview

Copilot AI Aug 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The updated documentation should clarify when exactly the database creation occurs. Consider adding that it happens during the ResourceReadyEvent to be more specific about the timing.

Suggested change
/// The database creation happens automatically as part of the resource lifecycle.
/// Specifically, the database creation occurs during the <c>ResourceReadyEvent</c> as part of the resource lifecycle.

Copilot uses AI. Check for mistakes.

@davidfowl
Copy link
Member

@copilot do the same for MySQL and SQL Server

@Copilot Copilot AI changed the title [WIP] Incorrect XML documentation in PostgresBuilderExtensions.AddDatabase Fix incorrect XML documentation in PostgresBuilderExtensions.AddDatabase Aug 7, 2025
Copilot finished work on behalf of davidfowl August 7, 2025 05:22
@Copilot Copilot AI requested a review from davidfowl August 7, 2025 05:22
Copy link
Contributor Author

Copilot AI commented Aug 7, 2025

@copilot do the same for MySQL and SQL Server

I've updated the XML documentation for both MySQL and SQL Server AddDatabase methods to match the PostgreSQL fix. Both now include comprehensive documentation explaining that databases are automatically created when the server becomes ready, just like PostgreSQL. All three database providers now have consistent and accurate documentation about automatic database creation behavior. Changes committed in c60a51f.

@Copilot Copilot AI changed the title Fix incorrect XML documentation in PostgresBuilderExtensions.AddDatabase Fix incorrect XML documentation in database AddDatabase methods for PostgreSQL, MySQL, and SQL Server Aug 7, 2025
Copilot finished work on behalf of davidfowl August 7, 2025 05:30
@davidfowl davidfowl enabled auto-merge (squash) August 7, 2025 16:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Incorrect XML documentation in PostgresBuilderExtensions.AddDatabase
2 participants