Repository navigation
[docs] Document REPL dashboard command for database and cache integrations #1740
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
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -284,6 +284,41 @@ await builder.addNodeApp("api", "./api", "index.js") | |
|
|
||
| When no `password` parameter is provided, Aspire generates a strong password automatically using the `CreateDefaultPasswordParameter` method. | ||
|
|
||
| ## Add Valkey resource with a REPL command | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Phase A — unverifiable against the target branch ( Accurate for 14.0: |
||
|
|
||
| The `WithRepl` method adds an opt-in **REPL** command to the Valkey resource in the Aspire dashboard. Selecting the command while the container is running opens an authenticated `valkey-cli` session in the dashboard's terminal dock—no local Valkey client installation is required: | ||
|
|
||
| <Tabs syncKey="aspire-lang"> | ||
| <TabItem id="csharp" label="C#"> | ||
| ```csharp title="AppHost.cs" | ||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| var cache = builder.AddValkey("cache") | ||
| .WithRepl(); | ||
|
Comment on lines
+296
to
+297
|
||
|
|
||
| builder.Build().Run(); | ||
| ``` | ||
| </TabItem> | ||
| <TabItem id="typescript" label="TypeScript"> | ||
| ```typescript title="apphost.mts" twoslash | ||
| import { createBuilder } from './.aspire/modules/aspire.mjs'; | ||
|
|
||
| const builder = await createBuilder(); | ||
|
|
||
| const cache = await builder.addValkey("cache"); | ||
| await cache.withRepl(); | ||
|
|
||
| await builder.build().run(); | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| The REPL command is disabled by default and is only registered in run mode—it isn't available in published applications. Use `quit` to exit `valkey-cli` cleanly before closing the terminal tab; closing the tab alone can leave `valkey-cli` running inside the container, and stopping the container ends any remaining REPL processes. The session runs inside the container using Docker (or the configured Podman runtime), and passwords are passed through environment variables rather than command-line arguments. | ||
|
|
||
| :::caution | ||
| Only enable `WithRepl()` for resources whose authenticated client access is appropriate for everyone who can access the dashboard. The shell uses the resource's configured credentials and isn't read-only. Sharing the dashboard through a tunnel, Codespaces, or VS Code remote development also exposes this capability to anyone who can execute resource commands. | ||
| ::: | ||
|
|
||
| ## Pass custom environment variables | ||
|
|
||
| By default, Aspire injects the Valkey connection information using variable names derived from the resource name (for example, `CACHE_URI`, `CACHE_HOST`, `CACHE_PORT`, `CACHE_PASSWORD`). If your consuming app expects a different set of environment variable names, pass individual connection properties from the AppHost: | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -548,6 +548,41 @@ await mongo.withLifetime("Persistent"); | |
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ## Add MongoDB resource with a REPL command | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Phase A — unverifiable against the target branch ( Accurate for 14.0: |
||
|
|
||
| The `WithRepl` method adds an opt-in **REPL** command to the MongoDB server resource in the Aspire dashboard. Selecting the command while the container is running opens the bundled `mongosh` client in the dashboard's terminal dock, authenticated against `admin` with the resource's configured credentials—no local MongoDB client installation is required: | ||
|
|
||
| <Tabs syncKey="aspire-lang"> | ||
| <TabItem id="csharp" label="C#"> | ||
| ```csharp title="AppHost.cs" | ||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| var mongo = builder.AddMongoDB("mongo") | ||
| .WithRepl(); | ||
|
Comment on lines
+560
to
+561
|
||
|
|
||
| builder.Build().Run(); | ||
| ``` | ||
| </TabItem> | ||
| <TabItem id="typescript" label="TypeScript"> | ||
| ```typescript title="apphost.mts" twoslash | ||
| import { createBuilder } from './.aspire/modules/aspire.mjs'; | ||
|
|
||
| const builder = await createBuilder(); | ||
|
|
||
| const mongo = await builder.addMongoDB("mongo"); | ||
| await mongo.withRepl(); | ||
|
|
||
| await builder.build().run(); | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| The REPL command is disabled by default and is only registered in run mode—it isn't available in published applications. Use `exit` to end the `mongosh` session cleanly before closing the terminal tab; closing the tab alone can leave `mongosh` running inside the container, and stopping the container ends any remaining REPL processes. The session connects directly to the server inside its container, including replica set members, and credentials are passed through the environment rather than command-line arguments. When TLS is enabled, the shell uses the configured certificate trust bundle and validates the server certificate for `localhost`; custom certificates must cover `localhost` and their issuing CA must be trusted through Aspire's certificate configuration. | ||
|
|
||
| :::caution | ||
| Only enable `WithRepl()` for resources whose authenticated client access is appropriate for everyone who can access the dashboard. The shell uses the resource's configured credentials and isn't read-only. Sharing the dashboard through a tunnel, Codespaces, or VS Code remote development also exposes this capability to anyone who can execute resource commands. | ||
| ::: | ||
|
|
||
| ## Pass custom environment variables | ||
|
|
||
| By default, Aspire injects the MongoDB connection information using variable names derived from the resource name (for example, `MONGODB_URI`, `MONGODB_HOST`, `MONGODB_PORT`). If your consuming app expects a different set of environment variable names, pass individual connection properties from the AppHost: | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -478,6 +478,41 @@ await builder.addNodeApp("api", "./api", "index.js") | |
|
|
||
| When no `password` parameter is provided, Aspire generates a strong password automatically using the `CreateDefaultPasswordParameter` method. For more information, see [External parameters](/get-started/resources/). | ||
|
|
||
| ## Add MySQL resource with a REPL command | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Phase A — unverifiable against the target branch ( Accurate for 14.0: |
||
|
|
||
| The `WithRepl` method adds an opt-in **REPL** command to the MySQL server resource in the Aspire dashboard. Selecting the command while the container is running opens the bundled `mysql` client in the dashboard's terminal dock, authenticated as `root` with the resource's configured password—no local MySQL client installation is required: | ||
|
|
||
| <Tabs syncKey="aspire-lang"> | ||
| <TabItem id="csharp" label="C#"> | ||
| ```csharp title="AppHost.cs" | ||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| var mysql = builder.AddMySql("mysql") | ||
| .WithRepl(); | ||
|
Comment on lines
+490
to
+491
|
||
|
|
||
| builder.Build().Run(); | ||
| ``` | ||
| </TabItem> | ||
| <TabItem id="typescript" label="TypeScript"> | ||
| ```typescript title="apphost.mts" twoslash | ||
| import { createBuilder } from './.aspire/modules/aspire.mjs'; | ||
|
|
||
| const builder = await createBuilder(); | ||
|
|
||
| const mysql = await builder.addMySql("mysql"); | ||
| await mysql.withRepl(); | ||
|
|
||
| await builder.build().run(); | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| The REPL command is disabled by default and is only registered in run mode—it isn't available in published applications. Use `quit` to exit `mysql` cleanly before closing the terminal tab; closing the tab alone can leave `mysql` running inside the container, and stopping the container ends any remaining REPL processes. The session runs inside the container using Docker (or the configured Podman runtime), and the password is passed through an environment variable rather than command-line arguments or SQL history. | ||
|
|
||
| :::caution | ||
| Only enable `WithRepl()` for resources whose authenticated client access is appropriate for everyone who can access the dashboard. The shell uses the resource's configured credentials and isn't read-only. Sharing the dashboard through a tunnel, Codespaces, or VS Code remote development also exposes this capability to anyone who can execute resource commands. | ||
| ::: | ||
|
|
||
| ## Pass custom environment variables | ||
|
|
||
| By default, Aspire injects the MySQL connection information using variable names derived from the resource name (for example, `MYSQLDB_URI`, `MYSQLDB_HOST`, `MYSQLDB_PORT`, `MYSQLDB_PASSWORD`). If your consuming app expects a different set of environment variable names, pass individual connection properties from the AppHost: | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -549,6 +549,41 @@ await builder.addNodeApp("api", "./api", "index.js") | |
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ## Add PostgreSQL resource with a REPL command | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Phase A — unverifiable against the target branch ( Accurate for 14.0: |
||
|
|
||
| The `WithRepl` method adds an opt-in **REPL** command to the PostgreSQL server resource in the Aspire dashboard. Selecting the command while the container is running opens `psql` in the dashboard's terminal dock, already connected to the `postgres` database with the resource's configured credentials—no local PostgreSQL client installation is required: | ||
|
|
||
| <Tabs syncKey="aspire-lang"> | ||
| <TabItem id="csharp" label="C#"> | ||
| ```csharp title="AppHost.cs" | ||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| var postgres = builder.AddPostgres("postgres") | ||
| .WithRepl(); | ||
|
Comment on lines
+561
to
+562
|
||
|
|
||
| builder.Build().Run(); | ||
| ``` | ||
| </TabItem> | ||
| <TabItem id="typescript" label="TypeScript"> | ||
| ```typescript title="apphost.mts" twoslash | ||
| import { createBuilder } from './.aspire/modules/aspire.mjs'; | ||
|
|
||
| const builder = await createBuilder(); | ||
|
|
||
| const postgres = await builder.addPostgres("postgres"); | ||
| await postgres.withRepl(); | ||
|
|
||
| await builder.build().run(); | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| The REPL command is disabled by default and is only registered in run mode—it isn't available in published applications. Use `\connect` to switch databases and `\q` to exit `psql` cleanly before closing the terminal tab; closing the tab alone can leave `psql` running inside the container, and stopping the container ends any remaining REPL processes. The session runs inside the container using Docker (or the configured Podman runtime), and passwords are passed through environment variables rather than command-line arguments. | ||
|
|
||
| :::caution | ||
| Only enable `WithRepl()` for resources whose authenticated client access is appropriate for everyone who can access the dashboard. The shell uses the resource's configured credentials and isn't read-only. Sharing the dashboard through a tunnel, Codespaces, or VS Code remote development also exposes this capability to anyone who can execute resource commands. | ||
| ::: | ||
|
|
||
| ## Pass custom environment variables | ||
|
|
||
| By default, Aspire injects the PostgreSQL connection information using variable names derived from the resource name (for example, `POSTGRESDB_URI`, `POSTGRESDB_HOST`, `POSTGRESDB_PORT`). If your consuming app expects a different set of environment variable names, pass individual connection properties from the AppHost: | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -416,6 +416,48 @@ await builder.build().run(); | |
|
|
||
| For a list of available tags, see [SQL Server container image tags](https://mcr.microsoft.com/en-us/artifact/mar/mssql/server/tags). | ||
|
|
||
| ## Add SQL Server resource with a REPL command | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Phase A — unverifiable against the target branch ( Accurate for 14.0: Phase B — naming inconsistency. This section names the resource |
||
|
|
||
| The `WithRepl` method adds an opt-in **REPL** command to the SQL Server resource in the Aspire dashboard. Selecting the command while the container is running opens `sqlcmd` in the dashboard's terminal dock, connected inside the container as `sa` to the `master` database—no local SQL client installation is required: | ||
|
|
||
| <Tabs syncKey="aspire-lang"> | ||
| <TabItem id="csharp" label="C#"> | ||
| ```csharp title="AppHost.cs" | ||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| var sql = builder.AddSqlServer("sqlserver") | ||
| .WithRepl(); | ||
|
Comment on lines
+428
to
+429
|
||
|
|
||
| builder.Build().Run(); | ||
| ``` | ||
| </TabItem> | ||
| <TabItem id="typescript" label="TypeScript"> | ||
| ```typescript title="apphost.mts" twoslash | ||
| import { createBuilder } from './.aspire/modules/aspire.mjs'; | ||
|
|
||
| const builder = await createBuilder(); | ||
|
|
||
| const sql = await builder.addSqlServer("sqlserver"); | ||
| await sql.withRepl(); | ||
|
|
||
| await builder.build().run(); | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| Enter SQL statements followed by `GO` on its own line to execute a batch: | ||
|
|
||
| ```sql | ||
| SELECT DB_NAME(); | ||
| GO | ||
| ``` | ||
|
|
||
| Use `USE [db];` followed by `GO` to switch databases, and `QUIT` to exit `sqlcmd` cleanly before closing the terminal tab; closing the tab alone can leave `sqlcmd` running inside the container, and stopping the container ends any remaining REPL processes. The REPL command is disabled by default and is only registered in run mode—it isn't available in published applications. It uses the configured password without putting it in command-line arguments, and trusts the local server's self-signed certificate, matching the integration's local connection string. It supports both `/opt/mssql-tools18/bin/sqlcmd` in newer SQL Server images and `/opt/mssql-tools/bin/sqlcmd` in older images; custom images must include one of these clients. | ||
|
|
||
| :::caution | ||
| Only enable `WithRepl()` for resources whose authenticated client access is appropriate for everyone who can access the dashboard. The shell runs as `sa` and can execute server-side operating system commands when enabled. Sharing the dashboard through a tunnel, Codespaces, or VS Code remote development also exposes this capability to anyone who can execute resource commands. | ||
| ::: | ||
|
|
||
| ## Pass custom environment variables | ||
|
|
||
| By default, Aspire injects the SQL Server connection information using variable names derived from the resource name (for example, `DATABASE_URI`, `DATABASE_HOST`, `DATABASE_PORT`). If your consuming app expects a different set of environment variable names, pass individual connection properties from the AppHost: | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Phase A — unverifiable against the target branch (
release/13.6).WithRepl()/withRepl()for Redis does not exist inmicrosoft/aspirerelease/13.6(SHA8536cc330b). It ships in microsoft/aspire#20231, which merged tomain(milestone 14.0); the merge commit isn't an ancestor ofrelease/13.6, and the branch has noWithRepl/WithReplCommand/CreateReplOptionsAsync.Accurate for 14.0:
src/Aspire.Hosting.Redis/RedisBuilderExtensions.csdefinesWithRepl(redis-cli,REDISCLI_AUTHenv, non-TLS loopback via the secondary endpoint when TLS is enabled). Because this PR targetsrelease/13.6, the claim is unverifiable there — please confirm the intended branch or version-gate the section.