From 4a3fb7ad6ee889f14797da12fac159c53d3a1216 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Thu, 2 Jul 2026 11:19:53 +0200
Subject: [PATCH 1/3] feat(app): add commands to link, unlink and replace an
 app's database

Adds `mw app database link | unlink | replace` so managing an app
installation's linked database no longer requires calling the raw HTTP
API.

- `link` wraps the `app-link-database` operation and always sends
  `databaseUserIds.admin`, which the API requires in practice.
- `unlink` wraps `app-unlink-database`.
- `replace` wraps `app-replace-database`.

Closes #1969

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/app.md                             | 156 ++++++++++++++++++++++++
 src/commands/app/database/link.tsx      |  80 ++++++++++++
 src/commands/app/database/replace.tsx   |  85 +++++++++++++
 src/commands/app/database/unlink.ts     |  43 +++++++
 src/lib/resources/app/database/flags.ts |  17 +++
 5 files changed, 381 insertions(+)
 create mode 100644 src/commands/app/database/link.tsx
 create mode 100644 src/commands/app/database/replace.tsx
 create mode 100644 src/commands/app/database/unlink.ts
 create mode 100644 src/lib/resources/app/database/flags.ts

diff --git a/docs/app.md b/docs/app.md
index 0b5b7e11c..d973f8cf5 100644
--- a/docs/app.md
+++ b/docs/app.md
@@ -9,6 +9,9 @@ Manage apps, and app installations in your projects
 * [`mw app create php-worker`](#mw-app-create-php-worker)
 * [`mw app create python`](#mw-app-create-python)
 * [`mw app create static`](#mw-app-create-static)
+* [`mw app database link [INSTALLATION-ID]`](#mw-app-database-link-installation-id)
+* [`mw app database replace [INSTALLATION-ID]`](#mw-app-database-replace-installation-id)
+* [`mw app database unlink [INSTALLATION-ID]`](#mw-app-database-unlink-installation-id)
 * [`mw app dependency list`](#mw-app-dependency-list)
 * [`mw app dependency update [INSTALLATION-ID]`](#mw-app-dependency-update-installation-id)
 * [`mw app dependency versions SYSTEMSOFTWARE`](#mw-app-dependency-versions-systemsoftware)
@@ -411,6 +414,159 @@ FLAG DESCRIPTIONS
 ```
 
 
+## `mw app database link [INSTALLATION-ID]`
+
+Link a database to an app installation.
+
+```
+USAGE
+  $ mw app database link [INSTALLATION-ID] --database-id <value> --purpose primary|cache|custom --admin-user-id <value>
+    [--token <value>] [-q]
+
+ARGUMENTS
+  [INSTALLATION-ID]  ID or short ID of an app installation; this argument is optional if a default app installation is
+                     set in the context.
+
+FLAGS
+  -q, --quiet                  suppress process output and only display a machine-readable summary
+      --admin-user-id=<value>  (required) the ID of the database user to link as the administrative user.
+      --database-id=<value>    (required) the ID of the database to link to the app installation.
+      --purpose=<option>       (required) [default: primary] the purpose the database serves for the app installation.
+                               <options: primary|cache|custom>
+
+AUTHENTICATION FLAGS
+  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
+                   tokens passed via this flag might be logged in your shell history.
+
+DESCRIPTION
+  Link a database to an app installation.
+
+  Creates a linkage between an app installation and an existing database, so the app can use it for the given purpose.
+
+EXAMPLES
+  Link a database as the primary database of an app
+
+    $ mw app database link a-XXXXXX --database-id d-XXXXXX --admin-user-id dbu-XXXXXX
+
+FLAG DESCRIPTIONS
+  -q, --quiet  suppress process output and only display a machine-readable summary
+
+    This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
+    scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  --admin-user-id=<value>  the ID of the database user to link as the administrative user.
+
+    The ID of the database user that should be used as the administrative ('admin') user for the linked database. This
+    is required by the API even though it is not marked as such in the API schema.
+
+  --database-id=<value>  the ID of the database to link to the app installation.
+
+    The ID (UUID) of an existing database that should be linked to the app installation.
+
+  --purpose=primary|cache|custom  the purpose the database serves for the app installation.
+
+    Describes how the app installation uses the linked database. Must be one of 'primary', 'cache' or 'custom'.
+```
+
+
+## `mw app database replace [INSTALLATION-ID]`
+
+Replace the database linked to an app installation.
+
+```
+USAGE
+  $ mw app database replace [INSTALLATION-ID] --old-database-id <value> --new-database-id <value> --admin-user-id <value>
+    [--token <value>] [-q]
+
+ARGUMENTS
+  [INSTALLATION-ID]  ID or short ID of an app installation; this argument is optional if a default app installation is
+                     set in the context.
+
+FLAGS
+  -q, --quiet                    suppress process output and only display a machine-readable summary
+      --admin-user-id=<value>    (required) the ID of the database user to link as the administrative user.
+      --new-database-id=<value>  (required) the ID of the database to link instead.
+      --old-database-id=<value>  (required) the ID of the database that is currently linked.
+
+AUTHENTICATION FLAGS
+  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
+                   tokens passed via this flag might be logged in your shell history.
+
+DESCRIPTION
+  Replace the database linked to an app installation.
+
+  Replaces a database that is currently linked to an app installation with another one, keeping the same purpose.
+
+EXAMPLES
+  Replace the linked database of an app installation
+
+    $ mw app database replace a-XXXXXX --old-database-id d-OLDXXX --new-database-id d-NEWXXX --admin-user-id \
+      dbu-XXXXXX
+
+FLAG DESCRIPTIONS
+  -q, --quiet  suppress process output and only display a machine-readable summary
+
+    This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
+    scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  --admin-user-id=<value>  the ID of the database user to link as the administrative user.
+
+    The ID of the database user that should be used as the administrative ('admin') user for the linked database. This
+    is required by the API even though it is not marked as such in the API schema.
+
+  --new-database-id=<value>  the ID of the database to link instead.
+
+    The ID (UUID) of the database that should replace the currently linked database.
+
+  --old-database-id=<value>  the ID of the database that is currently linked.
+
+    The ID (UUID) of the database that is currently linked to the app installation and should be replaced.
+```
+
+
+## `mw app database unlink [INSTALLATION-ID]`
+
+Unlink a database from an app installation.
+
+```
+USAGE
+  $ mw app database unlink [INSTALLATION-ID] --database-id <value> [--token <value>] [-q] [-f]
+
+ARGUMENTS
+  [INSTALLATION-ID]  ID or short ID of an app installation; this argument is optional if a default app installation is
+                     set in the context.
+
+FLAGS
+  -f, --force                do not ask for confirmation
+  -q, --quiet                suppress process output and only display a machine-readable summary
+      --database-id=<value>  (required) the ID of the database to unlink from the app installation.
+
+AUTHENTICATION FLAGS
+  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
+                   tokens passed via this flag might be logged in your shell history.
+
+DESCRIPTION
+  Unlink a database from an app installation.
+
+  Removes the linkage between an app installation and a database. The database itself is not deleted.
+
+EXAMPLES
+  Unlink a database from an app installation
+
+    $ mw app database unlink a-XXXXXX --database-id d-XXXXXX
+
+FLAG DESCRIPTIONS
+  -q, --quiet  suppress process output and only display a machine-readable summary
+
+    This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
+    scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  --database-id=<value>  the ID of the database to unlink from the app installation.
+
+    The ID (UUID) of the database that should be unlinked from the app installation.
+```
+
+
 ## `mw app dependency list`
 
 Get all available dependencies
diff --git a/src/commands/app/database/link.tsx b/src/commands/app/database/link.tsx
new file mode 100644
index 000000000..713ec65aa
--- /dev/null
+++ b/src/commands/app/database/link.tsx
@@ -0,0 +1,80 @@
+import { ExecRenderBaseCommand } from "../../../lib/basecommands/ExecRenderBaseCommand.js";
+import { Flags } from "@oclif/core";
+import { ReactNode } from "react";
+import {
+  makeProcessRenderer,
+  processFlags,
+} from "../../../rendering/process/process_flags.js";
+import { Success } from "../../../rendering/react/components/Success.js";
+import assertSuccess from "../../../lib/apiutil/assert_success.js";
+import { appInstallationArgs } from "../../../lib/resources/app/flags.js";
+import {
+  adminUserIdFlag,
+  databasePurposeFlag,
+} from "../../../lib/resources/app/database/flags.js";
+
+export default class Link extends ExecRenderBaseCommand<typeof Link, void> {
+  static summary = "Link a database to an app installation.";
+  static description =
+    "Creates a linkage between an app installation and an existing database, so the app can use it for the given purpose.";
+
+  static examples = [
+    {
+      description: "Link a database as the primary database of an app",
+      command:
+        "<%= config.bin %> <%= command.id %> a-XXXXXX --database-id d-XXXXXX --admin-user-id dbu-XXXXXX",
+    },
+  ];
+
+  static args = {
+    ...appInstallationArgs,
+  };
+
+  static flags = {
+    ...processFlags,
+    "database-id": Flags.string({
+      summary: "the ID of the database to link to the app installation.",
+      description:
+        "The ID (UUID) of an existing database that should be linked to the app installation.",
+      required: true,
+    }),
+    purpose: databasePurposeFlag,
+    "admin-user-id": adminUserIdFlag,
+  };
+
+  protected async exec(): Promise<void> {
+    const process = makeProcessRenderer(
+      this.flags,
+      "Linking database to app installation",
+    );
+
+    const appInstallationId = await this.withAppInstallationId(Link);
+    const {
+      "database-id": databaseId,
+      purpose,
+      "admin-user-id": adminUserId,
+    } = this.flags;
+
+    await process.runStep("linking database", async () => {
+      const response = await this.apiClient.app.linkDatabase({
+        appInstallationId,
+        data: {
+          databaseId,
+          purpose: purpose as "primary" | "cache" | "custom",
+          databaseUserIds: {
+            admin: adminUserId,
+          },
+        },
+      });
+      assertSuccess(response);
+    });
+
+    await process.complete(
+      <Success>The database was successfully linked to the app.</Success>,
+    );
+  }
+
+  protected render(): ReactNode {
+    return null;
+  }
+}
diff --git a/src/commands/app/database/replace.tsx b/src/commands/app/database/replace.tsx
new file mode 100644
index 000000000..5af202bb7
--- /dev/null
+++ b/src/commands/app/database/replace.tsx
@@ -0,0 +1,85 @@
+import { ExecRenderBaseCommand } from "../../../lib/basecommands/ExecRenderBaseCommand.js";
+import { Flags } from "@oclif/core";
+import { ReactNode } from "react";
+import {
+  makeProcessRenderer,
+  processFlags,
+} from "../../../rendering/process/process_flags.js";
+import { Success } from "../../../rendering/react/components/Success.js";
+import assertSuccess from "../../../lib/apiutil/assert_success.js";
+import { appInstallationArgs } from "../../../lib/resources/app/flags.js";
+import { adminUserIdFlag } from "../../../lib/resources/app/database/flags.js";
+
+export default class Replace extends ExecRenderBaseCommand<
+  typeof Replace,
+  void
+> {
+  static summary = "Replace the database linked to an app installation.";
+  static description =
+    "Replaces a database that is currently linked to an app installation with another one, keeping the same purpose.";
+
+  static examples = [
+    {
+      description: "Replace the linked database of an app installation",
+      command:
+        "<%= config.bin %> <%= command.id %> a-XXXXXX --old-database-id d-OLDXXX --new-database-id d-NEWXXX --admin-user-id dbu-XXXXXX",
+    },
+  ];
+
+  static args = {
+    ...appInstallationArgs,
+  };
+
+  static flags = {
+    ...processFlags,
+    "old-database-id": Flags.string({
+      summary: "the ID of the database that is currently linked.",
+      description:
+        "The ID (UUID) of the database that is currently linked to the app installation and should be replaced.",
+      required: true,
+    }),
+    "new-database-id": Flags.string({
+      summary: "the ID of the database to link instead.",
+      description:
+        "The ID (UUID) of the database that should replace the currently linked database.",
+      required: true,
+    }),
+    "admin-user-id": adminUserIdFlag,
+  };
+
+  protected async exec(): Promise<void> {
+    const process = makeProcessRenderer(
+      this.flags,
+      "Replacing linked database of app installation",
+    );
+
+    const appInstallationId = await this.withAppInstallationId(Replace);
+    const {
+      "old-database-id": oldDatabaseId,
+      "new-database-id": newDatabaseId,
+      "admin-user-id": adminUserId,
+    } = this.flags;
+
+    await process.runStep("replacing database", async () => {
+      const response = await this.apiClient.app.replaceDatabase({
+        appInstallationId,
+        data: {
+          oldDatabaseId,
+          newDatabaseId,
+          databaseUserIds: {
+            admin: adminUserId,
+          },
+        },
+      });
+      assertSuccess(response);
+    });
+
+    await process.complete(
+      <Success>The linked database was successfully replaced.</Success>,
+    );
+  }
+
+  protected render(): ReactNode {
+    return null;
+  }
+}
diff --git a/src/commands/app/database/unlink.ts b/src/commands/app/database/unlink.ts
new file mode 100644
index 000000000..03bbfea95
--- /dev/null
+++ b/src/commands/app/database/unlink.ts
@@ -0,0 +1,43 @@
+import { Flags } from "@oclif/core";
+import { DeleteBaseCommand } from "../../../lib/basecommands/DeleteBaseCommand.js";
+import assertSuccess from "../../../lib/apiutil/assert_success.js";
+import { appInstallationArgs } from "../../../lib/resources/app/flags.js";
+
+export default class Unlink extends DeleteBaseCommand<typeof Unlink> {
+  static summary = "Unlink a database from an app installation.";
+  static description =
+    "Removes the linkage between an app installation and a database. The database itself is not deleted.";
+  static resourceName = "database link";
+
+  static examples = [
+    {
+      description: "Unlink a database from an app installation",
+      command:
+        "<%= config.bin %> <%= command.id %> a-XXXXXX --database-id d-XXXXXX",
+    },
+  ];
+
+  static args = {
+    ...appInstallationArgs,
+  };
+
+  static flags = {
+    ...DeleteBaseCommand.baseFlags,
+    "database-id": Flags.string({
+      summary: "the ID of the database to unlink from the app installation.",
+      description:
+        "The ID (UUID) of the database that should be unlinked from the app installation.",
+      required: true,
+    }),
+  };
+
+  protected async deleteResource(): Promise<void> {
+    const appInstallationId = await this.withAppInstallationId(Unlink);
+    const response = await this.apiClient.app.unlinkDatabase({
+      appInstallationId,
+      databaseId: this.flags["database-id"],
+    });
+
+    assertSuccess(response);
+  }
+}
diff --git a/src/lib/resources/app/database/flags.ts b/src/lib/resources/app/database/flags.ts
new file mode 100644
index 000000000..94eeef521
--- /dev/null
+++ b/src/lib/resources/app/database/flags.ts
@@ -0,0 +1,17 @@
+import { Flags } from "@oclif/core";
+
+export const databasePurposeFlag = Flags.string({
+  summary: "the purpose the database serves for the app installation.",
+  description:
+    "Describes how the app installation uses the linked database. Must be one of 'primary', 'cache' or 'custom'.",
+  options: ["primary", "cache", "custom"],
+  default: "primary",
+  required: true,
+});
+
+export const adminUserIdFlag = Flags.string({
+  summary: "the ID of the database user to link as the administrative user.",
+  description:
+    "The ID of the database user that should be used as the administrative ('admin') user for the linked database. This is required by the API even though it is not marked as such in the API schema.",
+  required: true,
+});

From 85f9fe60f0c59bf609b666903a6dc74f43c637f0 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Thu, 2 Jul 2026 22:24:20 +0200
Subject: [PATCH 2/3] feat(app): resolve database names and linked database
 automatically

The app database commands no longer require full database UUIDs:

- link/replace now accept a database name (resolved against the
  project's MySQL and Redis databases) in addition to a UUID.
- unlink and replace determine the currently linked database from the
  app installation automatically, so the old database ID no longer has
  to be supplied. An optional --purpose flag disambiguates when several
  databases are linked.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/commands/app/database/link.tsx       | 23 ++++++--
 src/commands/app/database/replace.tsx    | 52 ++++++++++++-----
 src/commands/app/database/unlink.ts      | 29 ++++++----
 src/lib/resources/app/database/flags.ts  | 10 +++-
 src/lib/resources/app/database/lookup.ts | 72 ++++++++++++++++++++++++
 5 files changed, 156 insertions(+), 30 deletions(-)
 create mode 100644 src/lib/resources/app/database/lookup.ts

diff --git a/src/commands/app/database/link.tsx b/src/commands/app/database/link.tsx
index 713ec65aa..927c623cf 100644
--- a/src/commands/app/database/link.tsx
+++ b/src/commands/app/database/link.tsx
@@ -8,10 +8,12 @@ import {
 import { Success } from "../../../rendering/react/components/Success.js";
 import assertSuccess from "../../../lib/apiutil/assert_success.js";
 import { appInstallationArgs } from "../../../lib/resources/app/flags.js";
+import { getAppInstallationFromUuid } from "../../../lib/resources/app/uuid.js";
 import {
   adminUserIdFlag,
   databasePurposeFlag,
 } from "../../../lib/resources/app/database/flags.js";
+import { resolveDatabaseId } from "../../../lib/resources/app/database/lookup.js";
 
 export default class Link extends ExecRenderBaseCommand<typeof Link, void> {
   static summary = "Link a database to an app installation.";
@@ -22,7 +24,7 @@ export default class Link extends ExecRenderBaseCommand<typeof Link, void> {
     {
       description: "Link a database as the primary database of an app",
       command:
-        "<%= config.bin %> <%= command.id %> a-XXXXXX --database-id d-XXXXXX --admin-user-id dbu-XXXXXX",
+        "<%= config.bin %> <%= command.id %> a-XXXXXX --database-id my-database --admin-user-id dbu-XXXXXX",
     },
   ];
 
@@ -33,9 +35,10 @@ export default class Link extends ExecRenderBaseCommand<typeof Link, void> {
   static flags = {
     ...processFlags,
     "database-id": Flags.string({
-      summary: "the ID of the database to link to the app installation.",
+      summary:
+        "the ID or name of the database to link to the app installation.",
       description:
-        "The ID (UUID) of an existing database that should be linked to the app installation.",
+        "The ID (UUID) or name of an existing database that should be linked to the app installation. When a name is given, it is resolved against the databases of the app installation's project.",
       required: true,
     }),
     purpose: databasePurposeFlag,
@@ -50,11 +53,23 @@ export default class Link extends ExecRenderBaseCommand<typeof Link, void> {
 
     const appInstallationId = await this.withAppInstallationId(Link);
     const {
-      "database-id": databaseId,
+      "database-id": databaseIdentifier,
       purpose,
       "admin-user-id": adminUserId,
     } = this.flags;
 
+    const databaseId = await process.runStep("resolving database", async () => {
+      const appInstallation = await getAppInstallationFromUuid(
+        this.apiClient,
+        appInstallationId,
+      );
+      return resolveDatabaseId(
+        this.apiClient,
+        appInstallation.projectId,
+        databaseIdentifier,
+      );
+    });
+
     await process.runStep("linking database", async () => {
       const response = await this.apiClient.app.linkDatabase({
         appInstallationId,
diff --git a/src/commands/app/database/replace.tsx b/src/commands/app/database/replace.tsx
index 5af202bb7..a77e02683 100644
--- a/src/commands/app/database/replace.tsx
+++ b/src/commands/app/database/replace.tsx
@@ -8,7 +8,15 @@ import {
 import { Success } from "../../../rendering/react/components/Success.js";
 import assertSuccess from "../../../lib/apiutil/assert_success.js";
 import { appInstallationArgs } from "../../../lib/resources/app/flags.js";
-import { adminUserIdFlag } from "../../../lib/resources/app/database/flags.js";
+import { getAppInstallationFromUuid } from "../../../lib/resources/app/uuid.js";
+import {
+  adminUserIdFlag,
+  databasePurposeSelectorFlag,
+} from "../../../lib/resources/app/database/flags.js";
+import {
+  resolveDatabaseId,
+  selectLinkedDatabase,
+} from "../../../lib/resources/app/database/lookup.js";
 
 export default class Replace extends ExecRenderBaseCommand<
   typeof Replace,
@@ -16,13 +24,13 @@ export default class Replace extends ExecRenderBaseCommand<
 > {
   static summary = "Replace the database linked to an app installation.";
   static description =
-    "Replaces a database that is currently linked to an app installation with another one, keeping the same purpose.";
+    "Replaces the database that is currently linked to an app installation with another one, keeping the same purpose. The currently linked database is determined automatically.";
 
   static examples = [
     {
       description: "Replace the linked database of an app installation",
       command:
-        "<%= config.bin %> <%= command.id %> a-XXXXXX --old-database-id d-OLDXXX --new-database-id d-NEWXXX --admin-user-id dbu-XXXXXX",
+        "<%= config.bin %> <%= command.id %> a-XXXXXX --new-database-id my-new-database --admin-user-id dbu-XXXXXX",
     },
   ];
 
@@ -32,16 +40,11 @@ export default class Replace extends ExecRenderBaseCommand<
 
   static flags = {
     ...processFlags,
-    "old-database-id": Flags.string({
-      summary: "the ID of the database that is currently linked.",
-      description:
-        "The ID (UUID) of the database that is currently linked to the app installation and should be replaced.",
-      required: true,
-    }),
+    purpose: databasePurposeSelectorFlag,
     "new-database-id": Flags.string({
-      summary: "the ID of the database to link instead.",
+      summary: "the ID or name of the database to link instead.",
       description:
-        "The ID (UUID) of the database that should replace the currently linked database.",
+        "The ID (UUID) or name of the database that should replace the currently linked database. When a name is given, it is resolved against the databases of the app installation's project.",
       required: true,
     }),
     "admin-user-id": adminUserIdFlag,
@@ -55,11 +58,34 @@ export default class Replace extends ExecRenderBaseCommand<
 
     const appInstallationId = await this.withAppInstallationId(Replace);
     const {
-      "old-database-id": oldDatabaseId,
-      "new-database-id": newDatabaseId,
+      "new-database-id": newDatabaseIdentifier,
       "admin-user-id": adminUserId,
+      purpose,
     } = this.flags;
 
+    const { oldDatabaseId, newDatabaseId } = await process.runStep(
+      "resolving databases",
+      async () => {
+        const appInstallation = await getAppInstallationFromUuid(
+          this.apiClient,
+          appInstallationId,
+        );
+        const linkedDatabase = selectLinkedDatabase(
+          appInstallation.linkedDatabases,
+          purpose,
+        );
+        const resolvedNewDatabaseId = await resolveDatabaseId(
+          this.apiClient,
+          appInstallation.projectId,
+          newDatabaseIdentifier,
+        );
+        return {
+          oldDatabaseId: linkedDatabase.databaseId,
+          newDatabaseId: resolvedNewDatabaseId,
+        };
+      },
+    );
+
     await process.runStep("replacing database", async () => {
       const response = await this.apiClient.app.replaceDatabase({
         appInstallationId,
diff --git a/src/commands/app/database/unlink.ts b/src/commands/app/database/unlink.ts
index 03bbfea95..ad264b7e8 100644
--- a/src/commands/app/database/unlink.ts
+++ b/src/commands/app/database/unlink.ts
@@ -1,19 +1,20 @@
-import { Flags } from "@oclif/core";
 import { DeleteBaseCommand } from "../../../lib/basecommands/DeleteBaseCommand.js";
 import assertSuccess from "../../../lib/apiutil/assert_success.js";
 import { appInstallationArgs } from "../../../lib/resources/app/flags.js";
+import { getAppInstallationFromUuid } from "../../../lib/resources/app/uuid.js";
+import { databasePurposeSelectorFlag } from "../../../lib/resources/app/database/flags.js";
+import { selectLinkedDatabase } from "../../../lib/resources/app/database/lookup.js";
 
 export default class Unlink extends DeleteBaseCommand<typeof Unlink> {
   static summary = "Unlink a database from an app installation.";
   static description =
-    "Removes the linkage between an app installation and a database. The database itself is not deleted.";
+    "Removes the linkage between an app installation and its database. The currently linked database is determined automatically; the database itself is not deleted.";
   static resourceName = "database link";
 
   static examples = [
     {
-      description: "Unlink a database from an app installation",
-      command:
-        "<%= config.bin %> <%= command.id %> a-XXXXXX --database-id d-XXXXXX",
+      description: "Unlink the database from an app installation",
+      command: "<%= config.bin %> <%= command.id %> a-XXXXXX",
     },
   ];
 
@@ -23,19 +24,23 @@ export default class Unlink extends DeleteBaseCommand<typeof Unlink> {
 
   static flags = {
     ...DeleteBaseCommand.baseFlags,
-    "database-id": Flags.string({
-      summary: "the ID of the database to unlink from the app installation.",
-      description:
-        "The ID (UUID) of the database that should be unlinked from the app installation.",
-      required: true,
-    }),
+    purpose: databasePurposeSelectorFlag,
   };
 
   protected async deleteResource(): Promise<void> {
     const appInstallationId = await this.withAppInstallationId(Unlink);
+    const appInstallation = await getAppInstallationFromUuid(
+      this.apiClient,
+      appInstallationId,
+    );
+    const linkedDatabase = selectLinkedDatabase(
+      appInstallation.linkedDatabases,
+      this.flags.purpose,
+    );
+
     const response = await this.apiClient.app.unlinkDatabase({
       appInstallationId,
-      databaseId: this.flags["database-id"],
+      databaseId: linkedDatabase.databaseId,
     });
 
     assertSuccess(response);
diff --git a/src/lib/resources/app/database/flags.ts b/src/lib/resources/app/database/flags.ts
index 94eeef521..b4a7d01f0 100644
--- a/src/lib/resources/app/database/flags.ts
+++ b/src/lib/resources/app/database/flags.ts
@@ -9,9 +9,17 @@ export const databasePurposeFlag = Flags.string({
   required: true,
 });
 
+export const databasePurposeSelectorFlag = Flags.string({
+  summary: "the purpose of the linked database to act on.",
+  description:
+    "Selects which linked database to act on by its purpose ('primary', 'cache' or 'custom'). Only needed when the app installation has more than one linked database.",
+  options: ["primary", "cache", "custom"],
+  required: false,
+});
+
 export const adminUserIdFlag = Flags.string({
   summary: "the ID of the database user to link as the administrative user.",
   description:
-    "The ID of the database user that should be used as the administrative ('admin') user for the linked database. This is required by the API even though it is not marked as such in the API schema.",
+    "The ID of the database user that should be used as the administrative ('admin') user for the linked database.",
   required: true,
 });
diff --git a/src/lib/resources/app/database/lookup.ts b/src/lib/resources/app/database/lookup.ts
new file mode 100644
index 000000000..fbf1485da
--- /dev/null
+++ b/src/lib/resources/app/database/lookup.ts
@@ -0,0 +1,72 @@
+import { MittwaldAPIV2, MittwaldAPIV2Client } from "@mittwald/api-client";
+import { assertStatus } from "@mittwald/api-client-commons";
+import { validate as validateUuid } from "uuid";
+
+type AppLinkedDatabase = MittwaldAPIV2.Components.Schemas.AppLinkedDatabase;
+
+/**
+ * Resolves a database identifier, which may be either a full UUID or a database
+ * name, to the database's UUID. Names are looked up among the project's MySQL
+ * and Redis databases.
+ */
+export async function resolveDatabaseId(
+  apiClient: MittwaldAPIV2Client,
+  projectId: string,
+  candidate: string,
+): Promise<string> {
+  if (validateUuid(candidate)) {
+    return candidate;
+  }
+
+  const mysql = await apiClient.database.listMysqlDatabases({ projectId });
+  assertStatus(mysql, 200);
+  const mysqlMatch = mysql.data.find((db) => db.name === candidate);
+  if (mysqlMatch) {
+    return mysqlMatch.id;
+  }
+
+  const redis = await apiClient.database.listRedisDatabases({ projectId });
+  assertStatus(redis, 200);
+  const redisMatch = redis.data.find((db) => db.name === candidate);
+  if (redisMatch) {
+    return redisMatch.id;
+  }
+
+  throw new Error(
+    `No database named "${candidate}" was found in this project.`,
+  );
+}
+
+/**
+ * Picks the linked database to act on from an app installation's linked
+ * databases. When a purpose is given, the matching database is returned;
+ * otherwise the sole linked database is used, and an ambiguous selection raises
+ * an error.
+ */
+export function selectLinkedDatabase(
+  linkedDatabases: AppLinkedDatabase[],
+  purpose?: string,
+): AppLinkedDatabase {
+  if (linkedDatabases.length === 0) {
+    throw new Error("This app installation has no linked database.");
+  }
+
+  if (purpose) {
+    const match = linkedDatabases.find((db) => db.purpose === purpose);
+    if (!match) {
+      throw new Error(
+        `This app installation has no linked database with purpose "${purpose}".`,
+      );
+    }
+    return match;
+  }
+
+  if (linkedDatabases.length > 1) {
+    const purposes = linkedDatabases.map((db) => db.purpose).join(", ");
+    throw new Error(
+      `This app installation has multiple linked databases (${purposes}); use --purpose to select one.`,
+    );
+  }
+
+  return linkedDatabases[0];
+}

From 112ded398df8e0a59ac2e62ab24f1bbf5e50d8f8 Mon Sep 17 00:00:00 2001
From: martin-helmich <2538958+martin-helmich@users.noreply.github.com>
Date: Thu, 2 Jul 2026 20:25:23 +0000
Subject: [PATCH 3/3] chore: re-generate README

---
 docs/app.md | 61 +++++++++++++++++++++++++++++------------------------
 1 file changed, 33 insertions(+), 28 deletions(-)

diff --git a/docs/app.md b/docs/app.md
index d973f8cf5..44b7d7900 100644
--- a/docs/app.md
+++ b/docs/app.md
@@ -430,7 +430,7 @@ ARGUMENTS
 FLAGS
   -q, --quiet                  suppress process output and only display a machine-readable summary
       --admin-user-id=<value>  (required) the ID of the database user to link as the administrative user.
-      --database-id=<value>    (required) the ID of the database to link to the app installation.
+      --database-id=<value>    (required) the ID or name of the database to link to the app installation.
       --purpose=<option>       (required) [default: primary] the purpose the database serves for the app installation.
                                <options: primary|cache|custom>
 
@@ -446,7 +446,7 @@ DESCRIPTION
 EXAMPLES
   Link a database as the primary database of an app
 
-    $ mw app database link a-XXXXXX --database-id d-XXXXXX --admin-user-id dbu-XXXXXX
+    $ mw app database link a-XXXXXX --database-id my-database --admin-user-id dbu-XXXXXX
 
 FLAG DESCRIPTIONS
   -q, --quiet  suppress process output and only display a machine-readable summary
@@ -456,12 +456,12 @@ FLAG DESCRIPTIONS
 
   --admin-user-id=<value>  the ID of the database user to link as the administrative user.
 
-    The ID of the database user that should be used as the administrative ('admin') user for the linked database. This
-    is required by the API even though it is not marked as such in the API schema.
+    The ID of the database user that should be used as the administrative ('admin') user for the linked database.
 
-  --database-id=<value>  the ID of the database to link to the app installation.
+  --database-id=<value>  the ID or name of the database to link to the app installation.
 
-    The ID (UUID) of an existing database that should be linked to the app installation.
+    The ID (UUID) or name of an existing database that should be linked to the app installation. When a name is given,
+    it is resolved against the databases of the app installation's project.
 
   --purpose=primary|cache|custom  the purpose the database serves for the app installation.
 
@@ -475,8 +475,8 @@ Replace the database linked to an app installation.
 
 ```
 USAGE
-  $ mw app database replace [INSTALLATION-ID] --old-database-id <value> --new-database-id <value> --admin-user-id <value>
-    [--token <value>] [-q]
+  $ mw app database replace [INSTALLATION-ID] --new-database-id <value> --admin-user-id <value> [--token <value>] [-q]
+    [--purpose primary|cache|custom]
 
 ARGUMENTS
   [INSTALLATION-ID]  ID or short ID of an app installation; this argument is optional if a default app installation is
@@ -485,8 +485,9 @@ ARGUMENTS
 FLAGS
   -q, --quiet                    suppress process output and only display a machine-readable summary
       --admin-user-id=<value>    (required) the ID of the database user to link as the administrative user.
-      --new-database-id=<value>  (required) the ID of the database to link instead.
-      --old-database-id=<value>  (required) the ID of the database that is currently linked.
+      --new-database-id=<value>  (required) the ID or name of the database to link instead.
+      --purpose=<option>         the purpose of the linked database to act on.
+                                 <options: primary|cache|custom>
 
 AUTHENTICATION FLAGS
   --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
@@ -495,13 +496,13 @@ AUTHENTICATION FLAGS
 DESCRIPTION
   Replace the database linked to an app installation.
 
-  Replaces a database that is currently linked to an app installation with another one, keeping the same purpose.
+  Replaces the database that is currently linked to an app installation with another one, keeping the same purpose. The
+  currently linked database is determined automatically.
 
 EXAMPLES
   Replace the linked database of an app installation
 
-    $ mw app database replace a-XXXXXX --old-database-id d-OLDXXX --new-database-id d-NEWXXX --admin-user-id \
-      dbu-XXXXXX
+    $ mw app database replace a-XXXXXX --new-database-id my-new-database --admin-user-id dbu-XXXXXX
 
 FLAG DESCRIPTIONS
   -q, --quiet  suppress process output and only display a machine-readable summary
@@ -511,16 +512,17 @@ FLAG DESCRIPTIONS
 
   --admin-user-id=<value>  the ID of the database user to link as the administrative user.
 
-    The ID of the database user that should be used as the administrative ('admin') user for the linked database. This
-    is required by the API even though it is not marked as such in the API schema.
+    The ID of the database user that should be used as the administrative ('admin') user for the linked database.
 
-  --new-database-id=<value>  the ID of the database to link instead.
+  --new-database-id=<value>  the ID or name of the database to link instead.
 
-    The ID (UUID) of the database that should replace the currently linked database.
+    The ID (UUID) or name of the database that should replace the currently linked database. When a name is given, it is
+    resolved against the databases of the app installation's project.
 
-  --old-database-id=<value>  the ID of the database that is currently linked.
+  --purpose=primary|cache|custom  the purpose of the linked database to act on.
 
-    The ID (UUID) of the database that is currently linked to the app installation and should be replaced.
+    Selects which linked database to act on by its purpose ('primary', 'cache' or 'custom'). Only needed when the app
+    installation has more than one linked database.
 ```
 
 
@@ -530,16 +532,17 @@ Unlink a database from an app installation.
 
 ```
 USAGE
-  $ mw app database unlink [INSTALLATION-ID] --database-id <value> [--token <value>] [-q] [-f]
+  $ mw app database unlink [INSTALLATION-ID] [--token <value>] [-q] [-f] [--purpose primary|cache|custom]
 
 ARGUMENTS
   [INSTALLATION-ID]  ID or short ID of an app installation; this argument is optional if a default app installation is
                      set in the context.
 
 FLAGS
-  -f, --force                do not ask for confirmation
-  -q, --quiet                suppress process output and only display a machine-readable summary
-      --database-id=<value>  (required) the ID of the database to unlink from the app installation.
+  -f, --force             do not ask for confirmation
+  -q, --quiet             suppress process output and only display a machine-readable summary
+      --purpose=<option>  the purpose of the linked database to act on.
+                          <options: primary|cache|custom>
 
 AUTHENTICATION FLAGS
   --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
@@ -548,12 +551,13 @@ AUTHENTICATION FLAGS
 DESCRIPTION
   Unlink a database from an app installation.
 
-  Removes the linkage between an app installation and a database. The database itself is not deleted.
+  Removes the linkage between an app installation and its database. The currently linked database is determined
+  automatically; the database itself is not deleted.
 
 EXAMPLES
-  Unlink a database from an app installation
+  Unlink the database from an app installation
 
-    $ mw app database unlink a-XXXXXX --database-id d-XXXXXX
+    $ mw app database unlink a-XXXXXX
 
 FLAG DESCRIPTIONS
   -q, --quiet  suppress process output and only display a machine-readable summary
@@ -561,9 +565,10 @@ FLAG DESCRIPTIONS
     This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
     scripts), you can use this flag to easily get the IDs of created resources for further processing.
 
-  --database-id=<value>  the ID of the database to unlink from the app installation.
+  --purpose=primary|cache|custom  the purpose of the linked database to act on.
 
-    The ID (UUID) of the database that should be unlinked from the app installation.
+    Selects which linked database to act on by its purpose ('primary', 'cache' or 'custom'). Only needed when the app
+    installation has more than one linked database.
 ```