docs(upgrade+changelog) 0.8.0rc1 changes and instructions

CHANGELOG.md

@@ -1,17 +1,31 @@
 ## [Unreleased][unreleased]
 
+This release includes support for PostgreSQL as Kong's primary datastore!
+
 ### Breaking changes
 
 - Remove support for the long deprecated `/consumers/:consumer/keyauth/` and `/consumers/:consumer/basicauth/` routes (deprecated in `0.5.0`). The new routes (available since `0.5.0` too) use the real name of the plugin: `/consumers/:consumer/key-auth` and `/consumers/:consumer/basic-auth`.
 
 ### Added
 
-- Support for PostgreSQL as Kong's primary datastore. [#331](https://github.com/Mashape/kong/issues/331) [#1054](https://github.com/Mashape/kong/issues/1054)
+- Support for PostgreSQL 9.4+ as Kong's primary datastore. [#331](https://github.com/Mashape/kong/issues/331) [#1054](https://github.com/Mashape/kong/issues/1054)
 - Configurable Cassandra reading/writing consistency. [#1026](https://github.com/Mashape/kong/pull/1026)
-- Admin API: oncluding pending and running timers count in the response to `/`. [#992](https://github.com/Mashape/kong/pull/992)
+- Admin API: including pending and running timers count in the response to `/`. [#992](https://github.com/Mashape/kong/pull/992)
 - Plugins
-  - JWT
-    - Add support for RS256 signed tokens thanks to [@kdstew](https://github.com/kdstew)! [#1053](https://github.com/Mashape/kong/pull/1053)
+  - JWT: add support for RS256 signed tokens thanks to [@kdstew](https://github.com/kdstew)! [#1053](https://github.com/Mashape/kong/pull/1053)
+  - Galileo (mashape-analytics): increase batch sending timeout to 30s. [#1091](https://github.com/Mashape/kong/pull/1091)
+
+### Fixed
+
+- Plugins
+  - Request/Response Transformer: add missing migrations for upgrades from ` <= 0.5.x`. [#1064](https://github.com/Mashape/kong/issues/1064)
+  - OAuth2
+    - Error responses comply to RFC 6749. [#1017](https://github.com/Mashape/kong/issues/1017)
+    - Handle multipart requests. [#1067](https://github.com/Mashape/kong/issues/1067)
+    - Make access_tokens correctly expire. [#1089](https://github.com/Mashape/kong/issues/1089)
+
+> **internal**
+> - replace globals with singleton pattern thanks to [@mars](https://github.com/mars).
 
 ## [0.7.0] - 2016/02/24
 

UPGRADE.md

@@ -22,6 +22,46 @@ $ kong reload [-c configuration_file]
 
 **Reminder**: `kong reload` leverages the Nginx `reload` signal and seamlessly starts new workers taking over the old ones until they all have been terminated. This will guarantee you no drop in your current incoming traffic.
 
+## Upgrade to `0.8.x`
+
+No important breaking changes for this release, just be careful to not use the long deprecated routes `/consumers/:consumer/keyauth/` and `/consumers/:consumer/basicauth/` as instructed in the Changelog. As always, also make sure to check the configuration file for new properties (this release allows you to configure the read/write consistency of Cassandra).
+
+Let's talk about **PostgreSQL**. To use it instead of Cassandra, follow those steps:
+
+* Get your hands on a 9.4+ server (being compatible with Postgres 9.4 allows you to use [Amazon RDS](https://aws.amazon.com/rds/))
+* Create a database, (maybe a user too?), let's say `kong`
+* Update your Kong configuration:
+
+```yaml
+# as always, be careful about your YAML formatting
+database: postgres
+postgres:
+  host: "127.0.0.1"
+  port: 5432
+  user: kong
+  password: kong
+  database: kong
+```
+
+As usual, migrations should run from kong start, but as a reminder and just in case, here are some tips:
+
+Reset the database with (careful, you'll lose all data):
+```
+$ kong migrations reset --config kong.yml
+```
+
+Run the migrations manually with:
+```
+$ kong migrations up --config kong.yml
+```
+
+If needed, list your migrations for debug purposes with:
+```
+$ kong migrations list --config kong.yml
+```
+
+**Note**: This release does not provide a mean to migrate from Cassandra to PostgreSQL. Additionally, we recommend that you **do not** use `kong reload` if you switch your cluster from Cassandra to PostgreSQL. Instead, we recommend that you migrate by spawning a new cluster and gradually redirect your traffic before decomissioning your old nodes.
+
 ## Upgrade to `0.7.x`
 
 If you are running a source installation, you will need to upgrade OpenResty to its `1.9.7.*` version. The good news is that this family of releases does not need to patch the NGINX core anymore to enable SSL support. If you install Kong from one of the distribution packages, they already include the appropriate OpenResty, simply download and install the appropriate package for your platform.