From 19f764e3d6240fcc9ef29375a981d2e03f1542df Mon Sep 17 00:00:00 2001
From: Tim Hansen <timbonicus@gmail.com>
Date: Fri, 19 Mar 2021 14:04:52 -0600
Subject: [PATCH] Fixes #4974.

Adds a tutorial for switching a Backstage App from SQLite to PostgreSQL

Signed-off-by: Tim Hansen <timbonicus@gmail.com>
---
 docs/tutorials/switching-sqlite-postgres.md | 61 +++++++++++++++++++++
 microsite/sidebars.json                     |  3 +-
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 docs/tutorials/switching-sqlite-postgres.md

diff --git a/docs/tutorials/switching-sqlite-postgres.md b/docs/tutorials/switching-sqlite-postgres.md
new file mode 100644
index 0000000000..dfb82ddc51
--- /dev/null
+++ b/docs/tutorials/switching-sqlite-postgres.md
@@ -0,0 +1,61 @@
+---
+id: switching-sqlite-postgres
+title: Switching Backstage from SQLite to PostgreSQL
+description:
+  How to get ready for deploying Backstage to production with PostgreSQL
+---
+
+The default `@backstage/create-app` database is SQLite, an in-memory database
+that's perfect for initial experimentation as it requires no environment setup.
+
+Once you're ready to deploy Backstage in production, or to have a more
+persistent development setup, you can switch the Backstage database to
+PostgreSQL.
+
+Backstage uses the [Knex](http://knexjs.org/) library, making it fairly easy to
+switch between database backends.
+
+## Install PostgreSQL
+
+First, swap out SQLite for PostgreSQL in your `backend` package:
+
+```shell
+cd packages/backend
+yarn remove sqlite3
+yarn add pg
+```
+
+## Add PostgreSQL configuration
+
+Next, modify `app-config.yaml` in the root folder to add PostgreSQL
+configuration for the backend:
+
+```diff
+backend:
+  database:
+-    client: sqlite3
+-    connection: ':memory:'
++    # config options: https://node-postgres.com/api/client
++    client: pg
++    connection:
++      host:
++        $env: POSTGRES_HOST
++      port:
++        $env: POSTGRES_PORT
++      user:
++        $env: POSTGRES_USER
++      password:
++        $env: POSTGRES_PASSWORD
++      # https://node-postgres.com/features/ssl
++      #ssl: require # see https://www.postgresql.org/docs/current/libpq-ssl.html Table 33.1. SSL Mode Descriptions (e.g. require)
++        #ca: # if you have a CA file and want to verify it you can uncomment this section
++        #$file: <file-path>/ca/server.crt
+
+```
+
+If you have a `app-config.local.yaml` for local development, a similar update
+should be made there. You can set the `POSTGRES_` environment variables prior to
+launching Backstage, or remove the $env keys and simply set values directly for
+development.
+
+The Backstage App is now ready to start up with a PostgreSQL backing database.
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index d7ee3ebd80..e6dba1386d 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -193,7 +193,8 @@
     "Tutorials": [
       "tutorials/journey",
       "tutorials/quickstart-app-auth",
-      "tutorials/quickstart-app-plugin"
+      "tutorials/quickstart-app-plugin",
+      "tutorials/switching-sqlite-postgres"
     ],
     "Architecture Decision Records (ADRs)": [
       "architecture-decisions/adrs-overview",