diff --git a/docs/developer/database-access.md b/docs/developer/database-access.md new file mode 100644 index 000000000..05a9b89a3 --- /dev/null +++ b/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.