Documentation on accessing cloud.gov databases

docs/developer/database-access.md

@@ -0,0 +1,61 @@
+# Working with Cloud.gov Databases
+
+You can connect to a Cloud.gov database using the
+[cf-service-connect](https://github.com/cloud-gov/cf-service-connect) plugin.
+After installing it, use the command
+
+```shell
+cf connect-to-service getgov-unstable getgov-unstable-databse
+```
+
+to get a `psql` shell on the `unstable` environment's database.
+
+## Dropping and re-creating the database
+
+For `unstable`, it might be necessary to start the database over from scratch.
+The easiest way to do that is `DROP DATABASE ...` followed by `CREATE DATABASE
+...`. In the `psql` shell, first run the `\l` command to see all of the
+databases that are present:
+
+```shell
+cgawsbrokerprodyaobv93n2g3me5i=> \l
+                                                        List of databases
+              Name              |      Owner       | Encoding |   Collate   |    Ctype    |           Access privileges
+--------------------------------+------------------+----------+-------------+-------------+---------------------------------------
+ cgawsbrokerprodyaobv93n2g3me5i | ugsyn42g56vtykfr | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
+ postgres                       | ugsyn42g56vtykfr | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
+...
+```
+
+You will need the name of the database beginning with `cgawsbroker...` for the
+next step. To drop that database, you first have to connect to a different
+database (you can't drop the database that you are connected to). We connect to
+the default `postgres` database instead
+
+```shell
+cgawsbrokerprodyaobv93n2g3me5i=> \c postgres;
+psql (14.4, server 12.11)
+SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
+You are now connected to database "postgres" as user "ugsyn42g56vtykfr".
+```
+
+Now drop and create the database with the name above.
+
+```shell
+postgres=> DROP DATABASE cgawsbrokerprodyaobv93n2g3me5i;
+DROP DATABASE
+postgres=> CREATE DATABASE cgawsbrokerprodyaobv93n2g3me5i;
+CREATE DATABASE
+```
+
+Now the database is empty and Django will need to re-run all of its migrations
+in order for the app to start again.
+
+### Warnings
+
+This is a very intrusive procedure and it can go wrong in a number of ways.
+For example, if the running cloud.gov application goes down, the
+`connect-to-service` SSH tunnel will go away and if the app can't come back up
+(say, because the database has been dropped but not created) then it isn't
+possible to SSH back into the database to fix it and the Cloudfoundry
+resources may have to be completely deleted and re-created.