Skip to content

Commit

Permalink
Add options table for import to README
Browse files Browse the repository at this point in the history
Closes zdennis#318
Closes zdennis#397
  • Loading branch information
dillonwelch committed Nov 29, 2018
1 parent 0c9eeb3 commit 73bbdd2
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 31 deletions.
22 changes: 17 additions & 5 deletions README.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,6 @@ The gem provides the following high-level features:
* [Options](#options)
* [Duplicate Key Ignore](#duplicate-key-ignore)
* [Duplicate Key Update](#duplicate-key-update)
* [Uniqueness Validation](#uniqueness-validation)
* [Return Info](#return-info)
* [Counter Cache](#counter-cache)
* [ActiveRecord Timestamps](#activerecord-timestamps)
Expand Down Expand Up @@ -247,10 +246,25 @@ Book.import books, recursive: true

### Options

Key | Options | Default | Description
----------------------- | --------------------- | ------------------ | -----------
:validate | `true`/`false` | `true` | Whether or not to run `ActiveRecord` validations (uniqueness skipped).
:validate_uniqueness | `true`/`false` | `false` | Whether or not to run uniqueness validations, has potential pitfalls, use with caution (requires `>= v0.27.0`).
:on_duplicate_key_ignore| `true`/`false` | `false` | Allows skipping records with duplicate keys. See [here](https://github.com/zdennis/activerecord-import/#duplicate-key-ignore) for more details.
:ignore | `true`/`false` | `false` | Alias for :on_duplicate_key_ignore.
:on_duplicate_key_update| :all, `Array`, `Hash` | N/A | Allows upsert logic to be used. See [here](https://github.com/zdennis/activerecord-import/#duplicate-key-update) for more details.
:synchronize | `Array` | N/A | An array of ActiveRecord instances. This synchronizes existing instances in memory with updates from the import.
:timestamps | `true`/`false` | `true` | Enables/disables timestamps on imported records.
:recursive | `true`/`false` | `false` | Imports has_many/has_one associations (PostgreSQL only).
:batch_size | `Integer` | total # of records | Max number of records to insert per import


#### Duplicate Key Ignore

[MySQL](http://dev.mysql.com/doc/refman/5.0/en/insert-on-duplicate.html), [SQLite](https://www.sqlite.org/lang_insert.html), and [PostgreSQL](https://www.postgresql.org/docs/current/static/sql-insert.html#SQL-ON-CONFLICT) (9.5+) support `on_duplicate_key_ignore` which allows you to skip records if a primary or unique key constraint is violated.

For Postgres 9.5+ it adds `ON CONFLICT DO NOTHING`, for MySQL it uses `INSERT IGNORE`, and for SQLite it uses `INSERT OR IGNORE`. Cannot be enabled on a recursive import. For database adapters that normally support setting primary keys on imported objects, this option prevents that from occurring.

```ruby
book = Book.create! title: "Book1", author: "FooManChu"
book.title = "Updated Book Title"
Expand All @@ -270,6 +284,8 @@ MySQL, PostgreSQL (9.5+), and SQLite (3.24.0+) support `on duplicate key update`

One big difference between MySQL and PostgreSQL support is that MySQL will handle any conflict that happens, but PostgreSQL requires that you specify which columns the conflict would occur over. SQLite models its upsert support after PostgreSQL.

This will use MySQL's `ON DUPLICATE KEY UPDATE` or Postgres/SQLite `ON CONFLICT DO UPDATE` to do upsert.

Basic Update

```ruby
Expand Down Expand Up @@ -351,10 +367,6 @@ book.reload.edition # => 3 (stayed the same)
book.reload.published_at # => 2017-10-09 (changed)
```

#### Uniqueness Validation

By default, `activerecord-import` will not validate for uniquness when importing records. Starting with `v0.27.0`, there is a parameter called `validate_uniqueness` that can be passed in to trigger this behavior. This option is provided with caution as there are many potential pitfalls. Please use with caution.

```ruby
Book.import books, validate_uniqueness: true
```
Expand Down
27 changes: 1 addition & 26 deletions lib/activerecord-import/import.rb
Original file line number Diff line number Diff line change
Expand Up @@ -285,32 +285,7 @@ def supports_setting_primary_key_of_imported_objects?
# below for what +options+ are available.
#
# == Options
# * +validate+ - true|false, tells import whether or not to use
# ActiveRecord validations. Validations are enforced by default.
# It skips the uniqueness validation for performance reasons.
# You can find more details here:
# https://github.com/zdennis/activerecord-import/issues/228
# * +ignore+ - true|false, an alias for on_duplicate_key_ignore.
# * +on_duplicate_key_ignore+ - true|false, tells import to discard
# records that contain duplicate keys. For Postgres 9.5+ it adds
# ON CONFLICT DO NOTHING, for MySQL it uses INSERT IGNORE, and for
# SQLite it uses INSERT OR IGNORE. Cannot be enabled on a
# recursive import. For database adapters that normally support
# setting primary keys on imported objects, this option prevents
# that from occurring.
# * +on_duplicate_key_update+ - :all, an Array, or Hash, tells import to
# use MySQL's ON DUPLICATE KEY UPDATE or Postgres/SQLite ON CONFLICT
# DO UPDATE ability. See On Duplicate Key Update below.
# * +synchronize+ - an array of ActiveRecord instances for the model
# that you are currently importing data into. This synchronizes
# existing model instances in memory with updates from the import.
# * +timestamps+ - true|false, tells import to not add timestamps
# (if false) even if record timestamps is disabled in ActiveRecord::Base
# * +recursive+ - true|false, tells import to import all has_many/has_one
# associations if the adapter supports setting the primary keys of the
# newly imported objects. PostgreSQL only.
# * +batch_size+ - an integer value to specify the max number of records to
# include per insert. Defaults to the total number of records to import.
# See https://github.com/zdennis/activerecord-import/#options
#
# == Examples
# class BlogPost < ActiveRecord::Base ; end
Expand Down

0 comments on commit 73bbdd2

Please sign in to comment.