From 4d17ececc53f76a9fe68991208523daf6ad42dc6 Mon Sep 17 00:00:00 2001
From: Minn Soe <contributions@minn.io>
Date: Mon, 17 May 2021 19:38:57 +0100
Subject: [PATCH] docs: fix typo in db manager changeset and clarify

Signed-off-by: Minn Soe <contributions@minn.io>
---
 .changeset/five-donkeys-brake.md              |  2 +-
 .../tutorials/configuring-plugin-databases.md | 44 +++++++++++++------
 2 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/.changeset/five-donkeys-brake.md b/.changeset/five-donkeys-brake.md
index c9db3112a9..15d2cf7381 100644
--- a/.changeset/five-donkeys-brake.md
+++ b/.changeset/five-donkeys-brake.md
@@ -27,7 +27,7 @@ backend:
           database: 'database_name_overriden'
       scaffolder:
         client: 'sqlite3'
-        connection: ':inmemory'
+        connection: ':inmemory:'
 ```
 
 Existing backstage installations can be migrated by swapping out the database
diff --git a/docs/tutorials/configuring-plugin-databases.md b/docs/tutorials/configuring-plugin-databases.md
index b6281cb0ae..b65addd7a8 100644
--- a/docs/tutorials/configuring-plugin-databases.md
+++ b/docs/tutorials/configuring-plugin-databases.md
@@ -9,12 +9,19 @@ There are occasions where it may be difficult to deploy Backstage with
 automatically created databases in production due to access control or other
 restrictions. For example, your infrastructure might be defined as code using
 tools such as Terraform or AWS CloudFormation where the name of each database is
-defined, created and assigned explicitly.
+defined, created and assigned explicitly. You may also need to use different
+credentials for each database or use a set of credentials without the
+permissions needed to create databases.
 
-`@backstage/backend-common` provides an alternate database manager which allows
-you to set the client and database connection on a per plugin basis. This means
-that you can do selectively run certain plugins in memory with `sqlite3`, set
-different connection config including the name of the database and more.
+`@backstage/backend-common` provides an alternate database manager,
+`PluginConnectionDatabaseManager`, which allows the developer to set the client
+and database connection on a per plugin basis in addition to the default client
+and connection configuration. This means that you can use a `sqlite3` in memory
+database for a specific plugin whilst using `postgres` for everything else and
+so on.
+
+The database manager also allows you to change the database name prefix which is
+used when a plugin database isn't explicitly configured.
 
 There are two additional configuration options for this database manager:
 
@@ -41,12 +48,20 @@ yarn add pg
 yarn add sqlite3
 ```
 
+From an operational perspective, you only need to install drivers for clients
+that are actively used.
+
 ## Add Configuration
 
-To override the default prefix, `backstage_plugin_`, set
-`backend.database.prefix` as shown below. This will use databases such as
-`my_company_catalog` and `my_company_auth` instead of `backstage_plugin_catalog`
-and `backstage_plugin_auth`.
+You can set the same type of values for `backend.database.<pluginId>.client` and
+`backend.database.<pluginId>.connection` which are also accepted at the top
+level.
+
+It is possible to override the default database name prefix,
+`backstage_plugin_`, which is used when a name isn't explicitly defined. Set
+`backend.database.prefix` as shown below. The database names for plugins such as
+`catalog` and `auth` would now be `my_company_catalog` and `my_company_auth`
+instead of `backstage_plugin_catalog` and `backstage_plugin_auth`.
 
 ```yaml
 backend:
@@ -94,11 +109,12 @@ function makeCreateEnv(config: Config) {
 
 The `PluginConnectionDatabaseManager` preserves the behaviour of the
 `SingleConnectionDatabaseManager`. If the database does not exist, it will
-attempt to create it. You should ensure the databases that you configure exists
-and that the connection details have the appropriate permissions to work with
-each of the given databases if you are using this database manager to set the
-database name upfront. If each database needs its own connection username,
-password or host - you may set them under the plugin's `connection` block.
+attempt to create it.
+
+If you are using this database manager to set the database name upfront because
+the credentials do not have permissions to create databases, you must ensure
+they exist before starting the service. The service will not be able to create
+them, it can only use them.
 
 `sqlite3` databases do not need to be created upfront as with the existing
 database manager.