Get started with the MySQL integrations

Цей контент ще не доступний вашою мовою.

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

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

aspire add mysql

Aspire CLI інтерактивний; оберіть відповідний результат пошуку:

Select an integration to add:

> mysql (Aspire.Hosting.MySql)
> Other results listed as selectable options...

#:package Aspire.Hosting.MySql@*

<PackageReference Include="Aspire.Hosting.MySql" Version="*" />

Next, in the AppHost project, create instances of MySQL server and database resources, then pass the database to the consuming client projects:

Select your programming language to get started

var builder = DistributedApplication.CreateBuilder(args);

var mysql = builder.AddMySql("mysql");
var mysqldb = mysql.AddDatabase("mysqldb");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
                            .WaitFor(mysqldb)
                            .WithReference(mysqldb);

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);

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:

dotnet add package Aspire.MySqlConnector

#:package Aspire.MySqlConnector@*

<PackageReference Include="Aspire.MySqlConnector" Version="*" />

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.

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:

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:

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:

npm install mysql2

Ensure that you import mysql2 in code files that interact with the database. Use the mysql2 library to access the database:

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:

string hostname = builder.Configuration.GetValue<string>("MYSQLDB_HOST");
string databaseport = builder.Configuration.GetValue<string>("MYSQLDB_PORT");
string jdbcconnectionstring = builder.Configuration.GetValue<string>("MYSQLDB_JDBCCONNECTIONSTRING");
string databasename = builder.Configuration.GetValue<string>("MYSQLDB_DATABASE");

Use the os.getenv() method to obtain these environment variables in consuming projects:

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:

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:

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:

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:

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:

Understand the MySQL hosting integration Discover how to configure persistence, phpMyAdmin resources, and more.

Understand the MySQL client integration Discover how to configure keyed clients, client integration health checks, and more.

Understand the MySQL community extensions Discover how to add the DbGate management user interface, and more.