Improve README

Author: tbuehlmann

README.md

@@ -1,28 +1,62 @@
 # ActiveRecord::ReturningAttributes
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/active_record/returning_attributes`. To experiment with that code, run `bin/console` for an interactive prompt.
+ReturningAttributes provides a way to populate model attributes with database-backed default values or values set via database triggers when creating or updating single records without executing additional database queries.
 
-TODO: Delete this and the text above, and describe your gem
+#### Slightly Longer Description
+
+When having database-backed default values (like `NOW()`) or values set via database triggers, we don't get to see them when creating or updating records in Rails. This is because when inserting records, the PostgreSQL `RETURNING` clause only states the `id` (or a different primary key) column, other columns are not returned back to Rails-land. Similar to inserts, updates don't get to see those values because there's no `RETURNING` clause involved at all.
+
+Internally this library changes the `RETURNING` clause for inserts and adds it for updates so we don't have to reload records.
+
+Caveats:
+
+- PostgreSQL only
+- Only tested in Rails 5.2.0
+- Overrides ActiveRecord core code
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'active_record-returning_attributes'
+gem 'active_record-returning_attributes', github: 'tbuehlmann/active_record-returning_attributes'
 ```
 
 And then execute:
 
-    $ bundle
+```sh
+$ bundle install
+```
 
-Or install it yourself as:
+## Usage
 
-    $ gem install active_record-returning_attributes
+Assume having a database-backed default value for the `uuid` column or a trigger that sets the value.
 
-## Usage
+Before:
+
+```ruby
+class Project < ApplicationRecord
+end
+
+project = Project.create
+project.uuid # => nil
+
+project.reload
+project.uuid # => '2b57df54-3768-45c6-ad10-aeec028e7735'
+```
+
+After:
+
+```ruby
+class Project < ApplicationRecord
+  self.returning_attributes = [:uuid]
+end
+
+project = Project.create
+project.uuid # => '2b57df54-3768-45c6-ad10-aeec028e7735'
+```
 
-TODO: Write usage instructions here
+By setting `self.returning_attributes`, ActiveRecord will request those columns via the `RETURNING` clause and populate the corresponding attributes in your model.
 
 ## Development