From 73bbdd210f2c73350a36493ec75dab7376581ee4 Mon Sep 17 00:00:00 2001 From: Dillon Welch Date: Wed, 28 Nov 2018 20:28:26 -0800 Subject: [PATCH] Add options table for import to README Closes https://github.com/zdennis/activerecord-import/issues/318 Closes https://github.com/zdennis/activerecord-import/issues/397 --- README.markdown | 22 +++++++++++++++++----- lib/activerecord-import/import.rb | 27 +-------------------------- 2 files changed, 18 insertions(+), 31 deletions(-) diff --git a/README.markdown b/README.markdown index 88d8b4de..e9a1860b 100644 --- a/README.markdown +++ b/README.markdown @@ -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) @@ -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" @@ -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 @@ -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 ``` diff --git a/lib/activerecord-import/import.rb b/lib/activerecord-import/import.rb index 0c726302..f182aa31 100644 --- a/lib/activerecord-import/import.rb +++ b/lib/activerecord-import/import.rb @@ -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