Add basic docs for troubleshooting database problemsdocs/db-debugging

2 files changed, 50 insertions, 0 deletions

diff --git a/doc/development/README.md b/doc/development/README.md
index 9b43170236f..6892838be7f 100644
--- a/doc/development/README.md
+++ b/doc/development/README.md
@@ -71,6 +71,7 @@ comments: false
 - [Iterating tables in batches](iterating_tables_in_batches.md)
 - [Ordering table columns](ordering_table_columns.md)
 - [Verifying database capabilities](verifying_database_capabilities.md)
+- [Database Debugging and Troubleshooting](database_debugging.md)
 
 ## Testing guides
 
diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md
new file mode 100644
index 00000000000..4acfbef3020
--- /dev/null
+++ b/doc/development/database_debugging.md
@@ -0,0 +1,49 @@
+# Database Debugging and Troubleshooting
+
+This section is to help give some copy-pasta you can use as a reference when you
+run into some head-banging database problems.
+
+An easy first step is to search for your error in Slack or google "GitLab <my error>".
+
+---
+
+Available `RAILS_ENV`
+
+ - `production` (not sure if in GDK)
+ - `development` (this is your main GDK db)
+ - `test` (used for tests like rspec and spinach)
+
+
+## Nuke everything and start over
+
+If you just want to delete everything and start over,
+
+ - `bundle exec rake db:drop RAILS_ENV=development`
+ - `bundle exec rake db:setup RAILS_ENV=development`
+
+
+## Migration wrangling
+
+ - `bundle exec rake db:migrate RAILS_ENV=development`: Execute any pending migrations that you may have picked up from a MR
+ - `bundle exec rake db:migrate:status RAILS_ENV=development`: Check if all migrations are `up` or `down`
+ - `bundle exec rake db:migrate:down VERSION=20170926203418 RAILS_ENV=development`: Tear down a migration
+ - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Setup a migration
+ - `bundle exec rake db:migrate:redo VERSION=20170926203418 RAILS_ENV=development`: Re-run a specific migration
+
+
+## Manually access the database
+
+Access the database via one of these commands (they all get you to the same place)
+
+```
+gdk psql -d gitlabhq_development
+bundle exec rails dbconsole RAILS_ENV=development
+bundle exec rails db RAILS_ENV=development
+```
+
+ - `\q`: Quit/exit
+ - `\dt`: List all tables
+ - `\d+ issues`: List columns for `issues` table
+ - `CREATE TABLE board_labels();`: Create a table called `board_labels`
+ - `SELECT * FROM schema_migrations WHERE version = '20170926203418';`: Check if a migration was run
+ - `DELETE FROM schema_migrations WHERE version = '20170926203418';`: Manually remove a migration