diff --git a/src/frontend/config/sidebar/integrations.topics.ts b/src/frontend/config/sidebar/integrations.topics.ts index 7916f562..8a4d0bd0 100644 --- a/src/frontend/config/sidebar/integrations.topics.ts +++ b/src/frontend/config/sidebar/integrations.topics.ts @@ -539,11 +539,19 @@ export const integrationTopics: StarlightSidebarTopicsUserConfig = { items: [ { label: 'Integration overview', - slug: 'integrations/databases/mysql', + slug: 'integrations/databases/mysql/mysql-get-started', + }, + { + label: 'Hosting integration (AppHost)', + slug: 'integrations/databases/mysql/mysql-host', + }, + { + label: 'Client integration (Your app)', + slug: 'integrations/databases/mysql/mysql-client', }, { label: 'Community extensions', - slug: 'integrations/databases/mysql-extensions', + slug: 'integrations/databases/mysql/mysql-extensions', }, ], }, diff --git a/src/frontend/src/content/docs/integrations/databases/mysql.mdx b/src/frontend/src/content/docs/integrations/databases/mysql.mdx deleted file mode 100644 index b967a0d5..00000000 --- a/src/frontend/src/content/docs/integrations/databases/mysql.mdx +++ /dev/null @@ -1,353 +0,0 @@ ---- -title: MySQL integration -description: Learn how to use the MySQL integration, which includes both hosting and client integrations. ---- - -import { Aside } from '@astrojs/starlight/components'; -import InstallPackage from '@components/InstallPackage.astro'; -import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; -import { Image } from 'astro:assets'; -import mysqlIcon from '@assets/icons/mysqlconnector-icon.png'; - -MySQL logo - -[MySQL](https://www.mysql.com/) is an open-source Relational Database Management System (RDBMS) that uses Structured Query Language (SQL) to manage and manipulate data. It's employed in a many different environments, from small projects to large-scale enterprise systems and it's a popular choice to host data that underpins microservices in a cloud-native application. The Aspire MySQL database integration enables you to connect to existing MySQL databases or create new instances from .NET with the [`mysql` container image](https://hub.docker.com/_/mysql). - -## Hosting integration - -The MySQL hosting integration models the server as the `MySqlServerResource` type and the database as the `MySqlDatabaseResource` type. To access these types and APIs, add the [📦 Aspire.Hosting.MySql](https://www.nuget.org/packages/Aspire.Hosting.MySql) NuGet package in your AppHost project: - - - -### Add MySQL server resource and database resource - -In your AppHost project, call `AddMySql` to add and return a MySQL resource builder. Chain a call to the returned resource builder to `AddDatabase`, to add a MySQL database resource: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var mysql = builder.AddMySql("mysql") - .WithLifetime(ContainerLifetime.Persistent); - -var mysqldb = mysql.AddDatabase("mysqldb"); - -var myService = builder.AddProject() - .WithReference(mysqldb) - .WaitFor(mysqldb); -``` - - - -When Aspire adds a container image to the AppHost, it creates a new MySQL instance on your local machine. The MySQL resource includes default credentials with a `username` of `root` and a random password generated using the default password parameter. - -When the AppHost runs, the password is stored in the AppHost's secret store in the `Parameters` section: - -```json -{ - "Parameters:mysql-password": "" -} -``` - -The `WithReference` method configures a connection in the `ExampleProject` named `mysqldb`. - - - -### Add a MySQL resource with a data volume - -To add a data volume to the MySQL resource, call the `WithDataVolume` method on the MySQL resource: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var mysql = builder.AddMySql("mysql") - .WithDataVolume(); - -var mysqldb = mysql.AddDatabase("mysqldb"); - -var myService = builder.AddProject() - .WithReference(mysqldb) - .WaitFor(mysqldb); -``` - -The data volume is used to persist the MySQL server data outside the lifecycle of its container. The data volume is mounted at the `/var/lib/mysql` path in the MySQL container and when a `name` parameter isn't provided, the name is generated at random. For more information on data volumes and details on why they're preferred over bind mounts, see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes). - - - - - -### Add a MySQL resource with a data bind mount - -To add a data bind mount to the MySQL resource, call the `WithDataBindMount` method: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var mysql = builder.AddMySql("mysql") - .WithDataBindMount(source: @"C:\MySql\Data"); - -var mysqldb = mysql.AddDatabase("mysqldb"); - -var myService = builder.AddProject() - .WithReference(mysqldb) - .WaitFor(mysqldb); -``` - - - -Data bind mounts rely on the host machine's filesystem to persist the MySQL data across container restarts. For more information on data bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts). - -### Add MySQL resource with parameters - -When you want to provide a root MySQL password explicitly, you can pass it as a parameter: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var password = builder.AddParameter("password", secret: true); - -var mysql = builder.AddMySql("mysql", password) - .WithLifetime(ContainerLifetime.Persistent); - -var mysqldb = mysql.AddDatabase("mysqldb"); - -var myService = builder.AddProject() - .WithReference(mysqldb) - .WaitFor(mysqldb); -``` - -For more information, see [External parameters](/get-started/resources/). - -### Add a PhpMyAdmin resource - -[**phpMyAdmin**](https://www.phpmyadmin.net/) is a popular web-based administration tool for MySQL. To use phpMyAdmin within your Aspire solution, call the `WithPhpMyAdmin` method. This method adds a new container resource that hosts phpMyAdmin and connects it to the MySQL container: - -```csharp title="C# — AppHost.cs" -var builder = DistributedApplication.CreateBuilder(args); - -var mysql = builder.AddMySql("mysql") - .WithPhpMyAdmin(); - -var mysqldb = mysql.AddDatabase("mysqldb"); - -var myService = builder.AddProject() - .WithReference(mysqldb) - .WaitFor(mysqldb); -``` - -When you run the solution, the Aspire dashboard displays the phpMyAdmin resources with an endpoint. Select the link to the endpoint to view phpMyAdmin in a new browser tab. - - -### Connection properties - -When you reference a MySQL resource using `WithReference`, the following connection properties are made available to the consuming project: - -#### MySQL server - -The MySQL server resource exposes the following connection properties: - -| Property Name | Description | -|---------------|-------------| -| `Host` | The hostname or IP address of the MySQL server | -| `Port` | The port number the MySQL server is listening on | -| `Username` | The username for authentication | -| `Password` | The password for authentication | -| `Uri` | The connection URI, with the format `mysql://root:{Password}@{Host}:{Port}` | -| `JdbcConnectionString` | The JDBC connection string for MySQL, with the format `jdbc:mysql://{Host}:{Port}`. User and password credentials are provided as separate `Username` and `Password` properties. | - -**Example connection strings:** - -``` -Uri: mysql://root:p%40ssw0rd1@localhost:3306 -JdbcConnectionString: jdbc:mysql://localhost:3306 -``` - -#### MySQL database - -The MySQL database resource combines the server properties above and adds the following connection properties: - -| Property Name | Description | -|---------------|-------------| -| `Database` | The MySQL database name | -| `Uri` | The database-specific URI, with the format `mysql://root:{Password}@{Host}:{Port}/{Database}` | -| `JdbcConnectionString` | The database-specific JDBC connection string, with the format `jdbc:mysql://{Host}:{Port}/{Database}`. User and password credentials are provided as separate `Username` and `Password` properties. | - -**Example connection strings:** - -``` -Uri: mysql://root:p%40ssw0rd1@localhost:3306/catalog -JdbcConnectionString: jdbc:mysql://localhost:3306/catalog -``` - - - -### Hosting integration health checks - -The MySQL hosting integration automatically adds a health check for the MySQL resource. The health check verifies that the MySQL server is running and that a connection can be established to it. - -The hosting integration relies on the [📦 AspNetCore.HealthChecks.MySql](https://www.nuget.org/packages/AspNetCore.HealthChecks.MySql) NuGet package. - -## Client integration - -To get started with the Aspire MySQL client integration, install the [📦 Aspire.MySqlConnector](https://www.nuget.org/packages/Aspire.MySqlConnector) NuGet package: - - - -The MySQL client integration registers a `MySqlConnector.MySqlDataSource` instance that you can use to interact with the MySQL server. - -### Add a MySQL data source - -In the `Program.cs` file of your client-consuming project, call the `AddMySqlDataSource` extension method to register a `MySqlDataSource` for use via the dependency injection container: - -```csharp -builder.AddMySqlDataSource(connectionName: "mysqldb"); -``` - - - -You can then retrieve the `MySqlConnector.MySqlDataSource` instance using dependency injection: - -```csharp -public class ExampleService(MySqlDataSource dataSource) -{ - // Use dataSource... -} -``` - -### Add keyed MySQL data source - -There might be situations where you want to register multiple `MySqlDataSource` instances with different connection names. To register keyed MySQL data sources, call the `AddKeyedMySqlDataSource` method: - -```csharp -builder.AddKeyedMySqlDataSource(name: "mainDb"); -builder.AddKeyedMySqlDataSource(name: "loggingDb"); -``` - - - -Then you can retrieve the `MySqlDataSource` instances using dependency injection: - -```csharp -public class ExampleService( - [FromKeyedServices("mainDb")] MySqlDataSource mainDataSource, - [FromKeyedServices("loggingDb")] MySqlDataSource loggingDataSource) -{ - // Use data sources... -} -``` - -For more information on keyed services, see [.NET dependency injection: Keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). - -### Configuration - -The MySQL database integration provides multiple options to configure the connection based on the requirements and conventions of your project. - -#### Use a connection string - -When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddMySqlDataSource`: - -```csharp -builder.AddMySqlDataSource(connectionName: "mysql"); -``` - -Then the connection string is retrieved from the `ConnectionStrings` configuration section: - -```json -{ - "ConnectionStrings": { - "mysql": "Server=mysql;Database=mysqldb" - } -} -``` - -For more information on how to format this connection string, see [MySqlConnector: ConnectionString documentation](https://mysqlconnector.net/connection-options/). - -#### Use configuration providers - -The MySQL database integration supports `Microsoft.Extensions.Configuration`. It loads the `MySqlConnectorSettings` from configuration using the `Aspire:MySqlConnector` key. Example `appsettings.json`: - -```json -{ - "Aspire": { - "MySqlConnector": { - "ConnectionString": "YOUR_CONNECTIONSTRING", - "DisableHealthChecks": true, - "DisableTracing": true - } - } -} -``` - -#### Use inline delegates - -You can pass the `Action` delegate to set up some or all the options inline: - -```csharp -builder.AddMySqlDataSource( - "mysql", - static settings => settings.DisableHealthChecks = true); -``` - -### Client integration health checks - -By default, Aspire integrations enable health checks for all services. The MySQL database integration: - -- Adds the health check when `DisableHealthChecks` is `false`, which verifies that a connection can be made and commands can be run against the MySQL database -- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic - -### Observability and telemetry - -#### Logging - -The MySQL integration uses the following log categories: - -- `MySqlConnector.ConnectionPool` -- `MySqlConnector.MySqlBulkCopy` -- `MySqlConnector.MySqlCommand` -- `MySqlConnector.MySqlConnection` -- `MySqlConnector.MySqlDataSource` - -#### Tracing - -The MySQL integration emits the following tracing activities using OpenTelemetry: - -- `MySqlConnector` - -#### Metrics - -The MySQL integration will emit the following metrics using OpenTelemetry: - -- MySqlConnector - - `db.client.connections.create_time` - - `db.client.connections.use_time` - - `db.client.connections.wait_time` - - `db.client.connections.idle.max` - - `db.client.connections.idle.min` - - `db.client.connections.max` - - `db.client.connections.pending_requests` - - `db.client.connections.timeouts` - - `db.client.connections.usage` diff --git a/src/frontend/src/content/docs/integrations/databases/mysql/mysql-client.mdx b/src/frontend/src/content/docs/integrations/databases/mysql/mysql-client.mdx new file mode 100644 index 00000000..587f6190 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/databases/mysql/mysql-client.mdx @@ -0,0 +1,199 @@ +--- +title: MySQL Client integration reference +description: Learn how to use the Aspire MySQL Client integration to query MySQL databases from your Aspire projects. +--- + +import { Image } from 'astro:assets'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Aside, Code, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; +import mysqlIcon from '@assets/icons/mysqlconnector-icon.png'; + +MySQL logo + +To get started with the Aspire MySQL integrations, follow the [Get started with MySQL integrations](../mysql-get-started/) guide. + +This article includes full details about the Aspire MySQL Client integration, which allows you to connect to and interact with MySQL databases from your Aspire consuming projects. + +## Installation + +To get started with the Aspire MySQL client integration, install the [📦 Aspire.MySqlConnector](https://www.nuget.org/packages/Aspire.MySqlConnector) NuGet package in the client-consuming project, that is, the project for the application that uses the MySQL client. The MySQL client integration registers a `MySqlConnector.MySqlDataSource` instance that you can use to interact with MySQL. + + + +## Add a MySQL data source + +In the `Program.cs` file of your client-consuming project, call the `AddMySqlDataSource` extension method to register a `MySqlDataSource` for use via the dependency injection container: + +```csharp title="C# — Program.cs" +builder.AddMySqlDataSource(connectionName: "mysqldb"); +``` + + + +You can then retrieve the `MySqlConnector.MySqlDataSource` instance using dependency injection: + +```csharp title="C# — ExampleService.cs" +public class ExampleService(MySqlDataSource dataSource) +{ + // Use dataSource... +} +``` + +## Add keyed MySQL data source + +There might be situations where you want to register multiple `MySqlDataSource` instances with different connection names. To register keyed MySQL data sources, call the `AddKeyedMySqlDataSource` method: + +```csharp title="C# — Program.cs" +builder.AddKeyedMySqlDataSource(name: "mainDb"); +builder.AddKeyedMySqlDataSource(name: "loggingDb"); +``` + + + +Then you can retrieve the `MySqlDataSource` instances using dependency injection: + +```csharp title="C# — ExampleService.cs" +public class ExampleService( + [FromKeyedServices("mainDb")] MySqlDataSource mainDataSource, + [FromKeyedServices("loggingDb")] MySqlDataSource loggingDataSource) +{ + // Use data sources... +} +``` + +For more information on keyed services, see [.NET dependency injection: Keyed services](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection#keyed-services). + +## Properties of the MySQL resources + +When you use the `WithReference` method to pass a MySQL server or database resource from the AppHost project to a consuming client project, several properties are available to use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `mysqldb` becomes `MYSQLDB_URI`. + +### MySQL server resource + +The MySQL server resource exposes the following connection properties: + +| Property Name | Description | +|---------------|-------------| +| `Host` | The hostname or IP address of the MySQL server | +| `Port` | The port number the MySQL server is listening on | +| `Username` | The username for authentication | +| `Password` | The password for authentication | +| `Uri` | The connection URI in mysql:// format, with the format `mysql://{Username}:{Password}@{Host}:{Port}` | +| `JdbcConnectionString` | JDBC-format connection string, with the format `jdbc:mysql://{Host}:{Port}`. User and password credentials are provided as separate `Username` and `Password` properties. | + +### MySQL database resource + +The MySQL database resource inherits all properties from its parent `MySqlServerResource` and adds: + +| Property Name | Description | +|---------------|-------------| +| `Uri` | The connection URI with the database name, with the format `mysql://{Username}:{Password}@{Host}:{Port}/{DatabaseName}` | +| `JdbcConnectionString` | JDBC connection string with database name, with the format `jdbc:mysql://{Host}:{Port}/{DatabaseName}`. User and password credentials are provided as separate `Username` and `Password` properties. | +| `DatabaseName` | The name of the database | + +## Configuration + +The MySQL database integration provides multiple options to configure the connection based on the requirements and conventions of your project. + +### Use a connection string + +When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `AddMySqlDataSource`: + +```csharp title="C# — Program.cs" +builder.AddMySqlDataSource(connectionName: "mysql"); +``` + +Then the connection string is retrieved from the `ConnectionStrings` configuration section: + +```json title="JSON — appsettings.json" +{ + "ConnectionStrings": { + "mysql": "Server=mysql;Database=mysqldb" + } +} +``` + +For more information on how to format this connection string, see [MySqlConnector: ConnectionString documentation](https://mysqlconnector.net/connection-options/). + +### Use configuration providers + +The MySQL database integration supports `Microsoft.Extensions.Configuration`. It loads the `MySqlConnectorSettings` from configuration using the `Aspire:MySqlConnector` key. Example `appsettings.json`: + +```json title="JSON — appsettings.json" +{ + "Aspire": { + "MySqlConnector": { + "ConnectionString": "YOUR_CONNECTIONSTRING", + "DisableHealthChecks": true, + "DisableTracing": true + } + } +} +``` + +For the complete MySQL client integration JSON schema, see [Aspire.MySqlConnector/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/main/src/Components/Aspire.MySqlConnector/ConfigurationSchema.json). + +### Use inline delegates + +You can pass the `Action` delegate to set up some or all the options inline: + +```csharp title="C# — Program.cs" +builder.AddMySqlDataSource( + "mysql", + static settings => settings.DisableHealthChecks = true); +``` + +## Client integration health checks + +By default, Aspire integrations enable health checks for all services. The MySQL database integration: + +- Adds the health check when `DisableHealthChecks` is `false`, which verifies that a connection can be made and commands can be run against the MySQL database +- Integrates with the `/health` HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic + +## Observability and telemetry + +Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as *the pillars of observability*. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the [Configuration](#configuration) section. + +### Logging + +The MySQL integration uses the following log categories: + +- `MySqlConnector.ConnectionPool` +- `MySqlConnector.MySqlBulkCopy` +- `MySqlConnector.MySqlCommand` +- `MySqlConnector.MySqlConnection` +- `MySqlConnector.MySqlDataSource` + +### Tracing + +The MySQL integration emits the following tracing activities using OpenTelemetry: + +- `MySqlConnector` + +### Metrics + +The MySQL integration will emit the following metrics using OpenTelemetry: + +- MySqlConnector + - `db.client.connections.create_time` + - `db.client.connections.use_time` + - `db.client.connections.wait_time` + - `db.client.connections.idle.max` + - `db.client.connections.idle.min` + - `db.client.connections.max` + - `db.client.connections.pending_requests` + - `db.client.connections.timeouts` + - `db.client.connections.usage` diff --git a/src/frontend/src/content/docs/integrations/databases/mysql-extensions.mdx b/src/frontend/src/content/docs/integrations/databases/mysql/mysql-extensions.mdx similarity index 97% rename from src/frontend/src/content/docs/integrations/databases/mysql-extensions.mdx rename to src/frontend/src/content/docs/integrations/databases/mysql/mysql-extensions.mdx index 3ae180d7..ffc1a534 100644 --- a/src/frontend/src/content/docs/integrations/databases/mysql-extensions.mdx +++ b/src/frontend/src/content/docs/integrations/databases/mysql/mysql-extensions.mdx @@ -1,5 +1,6 @@ --- title: MySQL hosting extensions +next: false --- import { Badge } from '@astrojs/starlight/components'; @@ -91,7 +92,6 @@ builder.AddProject() - [Adminer documentation](https://www.adminer.org/) - [DbGate documentation](https://dbgate.org/) -- [MySQL integration](mysql.md) - [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire) -- [Aspire integrations overview](overview.md) +- [Aspire integrations overview](../../../overview/) - [Aspire GitHub repo](https://github.com/dotnet/aspire) diff --git a/src/frontend/src/content/docs/integrations/databases/mysql/mysql-get-started.mdx b/src/frontend/src/content/docs/integrations/databases/mysql/mysql-get-started.mdx new file mode 100644 index 00000000..629a8ec1 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/databases/mysql/mysql-get-started.mdx @@ -0,0 +1,288 @@ +--- +title: Get started with the MySQL integrations +description: Learn how to set up the Aspire MySQL Hosting and Client integrations simply. +prev: false +--- + +import { Image } from 'astro:assets'; +import { Kbd } from 'starlight-kbd/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import InstallDotNetPackage from '@components/InstallDotNetPackage.astro'; +import { Aside, CardGrid, LinkCard, Code, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; +import PivotSelector from '@components/PivotSelector.astro'; +import Pivot from '@components/Pivot.astro'; +import ThemeImage from '@components/ThemeImage.astro'; +import mysqlIcon from '@assets/icons/mysqlconnector-icon.png'; + +MySQL logo + +[MySQL](https://www.mysql.com/) is an open-source Relational Database Management System (RDBMS) that uses Structured Query Language (SQL) to manage and manipulate data. It's employed in many different environments, from small projects to large-scale enterprise systems and it's a popular choice to host data that underpins microservices in a cloud-native application. The Aspire MySQL integration provides a way to connect to existing MySQL databases, or create new instances from the [`mysql` container image](https://hub.docker.com/_/mysql). + +In this introduction, you'll see how to install and use the Aspire MySQL integrations in a simple configuration. If you already have this knowledge, see [MySQL Hosting integration](../mysql-host/) for full reference details. + + + +## Set up hosting integration + +To begin, install the Aspire MySQL Hosting integration in your Aspire AppHost project. This integration allows you to create and manage MySQL database instances from your Aspire hosting projects: + + + +Next, in the AppHost project, create instances of MySQL server and database resources, then pass the database to the consuming client projects: + + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var mysql = builder.AddMySql("mysql"); +var mysqldb = mysql.AddDatabase("mysqldb"); + +var exampleProject = builder.AddProject("apiservice") + .WaitFor(mysqldb) + .WithReference(mysqldb); +``` + + + + + +```csharp title="apphost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var mysql = builder.AddMySql("mysql"); +var mysqldb = mysql.AddDatabase("mysqldb"); + +var exampleProject = builder.AddUvicornApp("api", "./api", "main.app") + .WithExternalHttpEndpoints() + .WaitFor(mysqldb) + .WithReference(mysqldb); +``` + + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var mysql = builder.AddMySql("mysql"); +var mysqldb = mysql.AddDatabase("mysqldb"); + +var api = builder.AddNodeApp("api", "./api", scriptPath: "index.js") + .WithExternalHttpEndpoints() + .WaitFor(mysqldb) + .WithReference(mysqldb); +``` + + + + + +## 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 MySQL client integration: + + + +In the `Program.cs` file of your client-consuming project, call the `AddMySqlDataSource` extension method on any `IHostApplicationBuilder` to register a `MySqlDataSource` for use via the dependency injection container. The method takes a connection name parameter. + +```csharp title="C# — Program.cs" +builder.AddMySqlDataSource(connectionName: "mysqldb"); +``` + + + + + + + +To interact with MySQL databases in your Python consuming projects, you need to include a MySQL adapter library. A popular option is `mysql-connector-python` (the official Oracle connector). You can install this library using pip: + +```bash +pip install mysql-connector-python +``` + +Ensure that you import both `mysql.connector` and `os` in code files that interact with the database. Use `mysql.connector` to interact with the database and `os` to access environment variables: + +```python title="Python - Import mysql.connector and os" +import mysql.connector +import os +``` + + + + + +To interact with MySQL databases in your JavaScript consuming projects, you need to include a MySQL client library. A popular option is `mysql2` (a fast, modern MySQL client). You can install this library using npm: + +```bash +npm install mysql2 +``` + +Ensure that you import `mysql2` in code files that interact with the database. Use the `mysql2` library to access the database: + +```javascript title="JavaScript - Import mysql2" +import mysql from 'mysql2/promise'; +``` + + + +### Use injected MySQL properties + +In the AppHost, when you used the `WithReference` method to pass a MySQL server or database resource to a consuming client project, Aspire injects several configuration properties that you can use in the consuming project. + +Aspire exposes each property as an environment variable named `[RESOURCE]_[PROPERTY]`. For instance, the `Uri` property of a resource called `mysqldb` becomes `MYSQLDB_URI`. + + + +Use the `GetValue()` method to obtain these environment variables in consuming projects: + +```csharp title="C# - Obtain configuration properties" +string hostname = builder.Configuration.GetValue("MYSQLDB_HOST"); +string databaseport = builder.Configuration.GetValue("MYSQLDB_PORT"); +string jdbcconnectionstring = builder.Configuration.GetValue("MYSQLDB_JDBCCONNECTIONSTRING"); +string databasename = builder.Configuration.GetValue("MYSQLDB_DATABASE"); +``` + + + + + +Use the `os.getenv()` method to obtain these environment variables in consuming projects: + +```python title="Python - Obtain configuration properties" +mysql_host = os.getenv("MYSQLDB_HOST") +mysql_port = os.getenv("MYSQLDB_PORT") +mysql_user = os.getenv("MYSQLDB_USERNAME") +mysql_password = os.getenv("MYSQLDB_PASSWORD") +mysql_database = os.getenv("MYSQLDB_DATABASE") +mysql_uri = os.getenv("MYSQLDB_URI") +mysql_name = os.getenv("MYSQLDB_DATABASE", "mysqldb") +``` + + + + + +Use the `process.env` method to obtain these environment variables in consuming projects: + +```javascript title="JavaScript - Obtain configuration properties" +const mysqlHost = process.env.MYSQLDB_HOST; +const mysqlPort = process.env.MYSQLDB_PORT; +const mysqlUser = process.env.MYSQLDB_USERNAME; +const mysqlPassword = process.env.MYSQLDB_PASSWORD; +const mysqlDatabase = process.env.MYSQLDB_DATABASE; +``` + + + + + +### Use MySQL resources in client code + + + +Now that you've added `MySqlDataSource` to the builder in the consuming project, you can use the MySQL resource to get and store data. Get the `MySqlDataSource` instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: + +```csharp title="C# — ExampleService.cs" +public class ExampleService(MySqlDataSource dataSource) +{ + // Use dataSource to query the database... +} +``` + +Having obtained the data source, you can work with the MySQL database as you would in any other C# application. + + + + + +Use the information you have obtained about the MySQL resource to connect to the database. Here is an example of how to connect using `mysql-connector-python`: + +```python title="Python - Connect to MySQL" +connection = mysql.connector.connect( + host=mysql_host, + port=mysql_port, + user=mysql_user, + password=mysql_password, + database=mysql_database +) + +cursor = connection.cursor() +``` + +Having obtained the connection, you can work with the MySQL database as you would in any other Python application. + + + + + +Use the information you have obtained about the MySQL resource to connect to the database. Here is an example of how to connect using `mysql2`: + +```javascript title="JavaScript - Connect to MySQL" +const connection = await mysql.createConnection({ + host: mysqlHost, + port: mysqlPort, + user: mysqlUser, + password: mysqlPassword, + database: mysqlDatabase +}); +``` + +Having obtained the connection, you can work with the MySQL database as you would in any other JavaScript application. + + + +## Next steps + +Now, that you have an Aspire app with MySQL integrations up and running, you can use the following reference documents to learn how to configure and interact with the MySQL resources: + + + + + + diff --git a/src/frontend/src/content/docs/integrations/databases/mysql/mysql-host.mdx b/src/frontend/src/content/docs/integrations/databases/mysql/mysql-host.mdx new file mode 100644 index 00000000..cf904d86 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/databases/mysql/mysql-host.mdx @@ -0,0 +1,192 @@ +--- +title: MySQL Hosting integration reference +description: Learn how to use the Aspire MySQL Hosting integration to create and manage MySQL server and database resources in your Aspire projects. +--- + +import { Aside } from '@astrojs/starlight/components'; +import InstallPackage from '@components/InstallPackage.astro'; +import { Image } from 'astro:assets'; +import { Steps } from '@astrojs/starlight/components'; +import mysqlIcon from '@assets/icons/mysqlconnector-icon.png'; + +MySQL logo + +To get started with the Aspire MySQL integrations, follow the [Get started with MySQL integrations](../mysql-get-started/) guide. + +This article includes full details about the Aspire MySQL Hosting integration, which models the server as the `MySqlServerResource` type and the database as the `MySqlDatabaseResource` type. To access these types and APIs, you need to install the MySQL Hosting integration in your AppHost project. + +## Installation + +To get started with the Aspire MySQL hosting integration, install the [📦 Aspire.Hosting.MySql](https://www.nuget.org/packages/Aspire.Hosting.MySql) NuGet package in your AppHost project: + + + +## Add MySQL server resource and database resource + +In your AppHost project, call `AddMySql` to add and return a MySQL resource builder. Chain a call to the returned resource builder to `AddDatabase`, to add a MySQL database resource: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var mysql = builder.AddMySql("mysql") + .WithLifetime(ContainerLifetime.Persistent); + +var mysqldb = mysql.AddDatabase("mysqldb"); + +var myService = builder.AddProject() + .WithReference(mysqldb) + .WaitFor(mysqldb); +``` + + + +When Aspire adds a container image to the AppHost, it creates a new MySQL instance on your local machine. The MySQL resource includes default credentials with a `username` of `root` and a random password generated using the default password parameter. + +When the AppHost runs, the password is stored in the AppHost's secret store in the `Parameters` section: + +```json +{ + "Parameters:mysql-password": "" +} +``` + +The `WithReference` method configures a connection in the `ExampleProject` named `mysqldb`. + + + +## Add MySQL server resource with database scripts + +You can use the `WithCreationScript` method to execute SQL scripts when the database is created. This is useful for initializing database schema or seeding data: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var mysql = builder.AddMySql("mysql") + .WithLifetime(ContainerLifetime.Persistent); + +var mysqldb = mysql.AddDatabase("mysqldb") + .WithCreationScript(""" + CREATE TABLE IF NOT EXISTS users ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(255) NOT NULL, + email VARCHAR(255) NOT NULL + ); + """); + +var myService = builder.AddProject() + .WithReference(mysqldb) + .WaitFor(mysqldb); +``` + + + +## Add a MySQL resource with a data volume + +To add a data volume to the MySQL resource, call the `WithDataVolume` method on the MySQL resource: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var mysql = builder.AddMySql("mysql") + .WithDataVolume(); + +var mysqldb = mysql.AddDatabase("mysqldb"); + +var myService = builder.AddProject() + .WithReference(mysqldb) + .WaitFor(mysqldb); +``` + +The data volume is used to persist the MySQL server data outside the lifecycle of its container. The data volume is mounted at the `/var/lib/mysql` path in the MySQL container and when a `name` parameter isn't provided, the name is generated at random. For more information on data volumes and details on why they're preferred over bind mounts, see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes). + + + + + +## Add a MySQL resource with a data bind mount + +To add a data bind mount to the MySQL resource, call the `WithDataBindMount` method: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var mysql = builder.AddMySql("mysql") + .WithDataBindMount(source: @"C:\MySql\Data"); + +var mysqldb = mysql.AddDatabase("mysqldb"); + +var myService = builder.AddProject() + .WithReference(mysqldb) + .WaitFor(mysqldb); +``` + + + +Data bind mounts rely on the host machine's filesystem to persist the MySQL data across container restarts. For more information on data bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts). + +## Add MySQL resource with parameters + +When you want to provide a root MySQL password explicitly, you can pass it as a parameter: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var password = builder.AddParameter("password", secret: true); + +var mysql = builder.AddMySql("mysql", password) + .WithLifetime(ContainerLifetime.Persistent); + +var mysqldb = mysql.AddDatabase("mysqldb"); + +var myService = builder.AddProject() + .WithReference(mysqldb) + .WaitFor(mysqldb); +``` + +For more information, see [External parameters](/get-started/resources/). + +## Add a PhpMyAdmin resource + +[**phpMyAdmin**](https://www.phpmyadmin.net/) is a popular web-based administration tool for MySQL. To use phpMyAdmin within your Aspire solution, call the `WithPhpMyAdmin` method. This method adds a new container resource that hosts phpMyAdmin and connects it to the MySQL container: + +```csharp title="C# — AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var mysql = builder.AddMySql("mysql") + .WithPhpMyAdmin(); + +var mysqldb = mysql.AddDatabase("mysqldb"); + +var myService = builder.AddProject() + .WithReference(mysqldb) + .WaitFor(mysqldb); +``` + +When you run the solution, the Aspire dashboard displays the phpMyAdmin resources with an endpoint. Select the link to the endpoint to view phpMyAdmin in a new browser tab. + +### Hosting integration health checks + +The MySQL hosting integration automatically adds a health check for the MySQL resource. The health check verifies that the MySQL server is running and that a connection can be established to it. + +The hosting integration relies on the [📦 AspNetCore.HealthChecks.MySql](https://www.nuget.org/packages/AspNetCore.HealthChecks.MySql) NuGet package. diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 6d8473c8..b7dd924b 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -193,7 +193,7 @@ }, { "match": "Aspire.Hosting.MySql", - "href": "/integrations/databases/mysql/" + "href": "/integrations/databases/mysql/mysql-get-started/" }, { "match": "Aspire.Hosting.Nats", @@ -293,7 +293,7 @@ }, { "match": "Aspire.MySqlConnector", - "href": "/integrations/databases/mysql/" + "href": "/integrations/databases/mysql/mysql-get-started/" }, { "match": "Aspire.NATS.Net", @@ -317,7 +317,7 @@ }, { "match": "Aspire.Pomelo.EntityFrameworkCore.MySql", - "href": "/integrations/databases/mysql/" + "href": "/integrations/databases/mysql/mysql-get-started/" }, { "match": "Aspire.Qdrant.Client", @@ -413,7 +413,7 @@ }, { "match": "CommunityToolkit.Aspire.Hosting.MySql.Extensions", - "href": "/integrations/databases/mysql-extensions/" + "href": "/integrations/databases/mysql/mysql-extensions/" }, { "match": "CommunityToolkit.Aspire.Hosting.NodeJS.Extensions",