README.md in postgres_upsert-1.1.0 vs README.md in postgres_upsert-2.0.0
- old
+ new
@@ -17,14 +17,21 @@
## Usage
The gem will add the aditiontal class method to ActiveRecord::Base
-* pg_upsert
+* pg_upsert io_object_or_file_path, [options]
-### Using pg_upsert
+io_object_or_file_path => is a file path or an io object (StringIO, FileIO, etc.)
+options:
+:delimiter - the string to use to delimit fields. Default is ","
+:format - the format of the file (valid formats are :csv or :binary). Default is :csv
+:header => specifies if the file/io source contains a header row. Either :header option must be true, or :columns list must be passed. Default true
+:key_column => the primary key or unique key column on your ActiveRecord table, used to distinguish new records from existing records. Default is the primary_key of your ActiveRecord model class.
+:update_only => when true, postgres_upsert will ONLY update existing records, and not insert new. Default is false.
+
pg_upsert will allow you to copy data from an arbritary IO object or from a file in the database server (when you pass the path as string).
Let's first copy from a file in the database server, assuming again that we have a users table and
that we are in the Rails console:
```ruby
@@ -37,22 +44,11 @@
```ruby
User.pg_upsert "/tmp/users.csv", :map => {'name' => 'first_name'}
```
In the above example the header name in the CSV file will be mapped to the field called first_name in the users table.
-You can also manipulate and modify the values of the file being imported before they enter into the database using a block:
-```ruby
-User.pg_upsert "/tmp/users.csv" do |row|
- row[0] = "fixed string"
-end
-```
-
-The above example will always change the value of the first column to "fixed string" before storing it into the database.
-For each iteration of the block row receives an array with the same order as the columns in the CSV file.
-
-
To copy a binary formatted data file or IO object you can specify the format as binary
```ruby
User.pg_upsert "/tmp/users.dat", :format => :binary, :columns => ["id, "name"]
```
@@ -83,9 +79,10 @@
User.pg_upsert "/tmp/users.dat", :format => :binary, :key_column => ["external_twitter_id"]
```
obviously, the field you pass must be a unique key in your database (this is not enforced at the moment, but will be)
+passing :update_only = true will ensure that no new records are created, but records will be updated.
## Note on Patches/Pull Requests
* Fork the project
* add your feature/fix to your fork(rpsec tests pleaze)