Use suffixed index names by default to prevent alias creation conflicts

Updated index creation logic to use a suffixed index name (e.g., `users_<timestamp-suffix>`) by default.

Previously, during index reset, the old index (e.g., `users`) was deleted, and a new suffixed index (e.g., `users_<timestamp-suffix>`) was created and aliased to the old index name. This caused a race condition, where another job could recreate the unsuffixed `users` index before the alias was applied, leading to a conflict when trying to create the alias.

Author: dmeremyanin

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## master (unreleased)
+
+### New Features
+
+### Changes
+
+* [#973](https://github.com/toptal/chewy/pull/973): **(Potentially Breaking)** Indexes now use suffixed physical names from first creation (e.g., `users_1700000000000`) with an unsuffixed alias (`users`), instead of switching to this layout only after an index reset. This reduces the risk of a race condition during index reset. Existing unsuffixed indexes are not auto-migrated and continue to work, but direct ES operations that expect unsuffixed concrete index names may need updates. To migrate existing unsuffixed indexes to the alias-based layout, perform a one-time `chewy:reset` in a controlled window (pause jobs/writes that can recreate the unsuffixed index name). ([@dmeremyanin][])
+
 ## 8.0.0 (2026-02-25)
 
 ### New Features
@@ -827,6 +835,7 @@
 [@davekaro]: https://github.com/davekaro
 [@dck]: https://github.com/dck
 [@dm1try]: https://github.com/dm1try
+[@dmeremyanin]: https://github.com/dmeremyanin
 [@dmitry]: https://github.com/dmitry
 [@dnd]: https://github.com/dnd
 [@DNNX]: https://github.com/DNNX

lib/chewy/index.rb

@@ -197,6 +197,16 @@ def scopes
         public_methods - Chewy::Index.public_methods
       end
 
+      # Generates an automatic suffix for index names. By default, the method
+      # returns a timestamp-based suffix, using the current time in milliseconds (e.g., 1638947285000).
+      #
+      # It is used to differentiate indexes for zero-downtime deployments.
+      #
+      # @return [Object] an object that can be cast to a string (e.g., integer, timestamp, etc.)
+      def auto_suffix
+        (Time.now.to_f * 1000).round
+      end
+
       def settings_hash
         _settings.to_hash
       end

lib/chewy/index/actions.rb

@@ -7,12 +7,13 @@ module Actions
       extend ActiveSupport::Concern
 
       module ClassMethods
-        # Checks index existance. Returns true or false
+        # Checks index existance. Supports suffixes. Returns true or false
         #
         #   UsersIndex.exists? #=> true
+        #   UsersIndex.exists?('11-2024') #=> false
         #
-        def exists?
-          client.indices.exists(index: index_name)
+        def exists?(suffix = nil)
+          client.indices.exists(index: index_name(suffix: suffix))
         end
 
         # Creates index and applies mappings and settings.

lib/chewy/index/import/routine.rb

@@ -67,7 +67,10 @@ def create_indexes!
           Chewy::Stash::Journal.create if @options[:journal] && !Chewy.configuration[:skip_journal_creation_on_import]
           return if Chewy.configuration[:skip_index_creation_on_import]
 
-          @index.create!(**@bulk_options.slice(:suffix)) unless @index.exists?
+          suffix = @bulk_options[:suffix] || @index.auto_suffix
+          index_exists = @bulk_options[:suffix] ? @index.exists?(suffix) : @index.exists?
+
+          @index.create!(suffix) unless index_exists
         end
 
         # The main process method. Converts passed objects to the bulk request body,

lib/chewy/rake_helper.rb

@@ -279,7 +279,7 @@ def create_missing_indexes!(output: $stdout, env: ENV)
               next
             end
 
-            index.create!
+            index.create!(index.auto_suffix)
 
             output.puts "#{index.name} index successfully created"
           end
@@ -336,7 +336,9 @@ def human_duration(seconds)
 
       def reset_one(index, output, parallel: false)
         output.puts "Resetting #{index}"
-        index.reset!((Time.now.to_f * 1000).round, parallel: parallel, apply_journal: journal_exists?)
+
+        suffix = index.auto_suffix
+        index.reset!(suffix, parallel: parallel, apply_journal: journal_exists?)
       end
 
       def warn_missing_index(output)

lib/chewy/stash.rb

@@ -6,15 +6,20 @@ module Chewy
   #
   # @see Chewy::Index::Specification
   module Stash
-    class Specification < Chewy::Index
-      index_name 'chewy_specifications'
-
+    class Index < Chewy::Index
       default_import_options journal: false
 
+      # Disable automatic suffixes for specification and journal indexes
+      def self.auto_suffix; end
+    end
+
+    class Specification < Index
+      index_name 'chewy_specifications'
+
       field :specification, type: 'binary'
     end
 
-    class Journal < Chewy::Index
+    class Journal < Index
       index_name 'chewy_journal'
 
       # Loads all entries since the specified time.
@@ -51,8 +56,6 @@ def self.for(*something)
         scope
       end
 
-      default_import_options journal: false
-
       field :index_name, type: 'keyword'
       field :action, type: 'keyword'
       field :references, type: 'binary'

spec/chewy/index/actions_spec.rb

@@ -15,6 +15,18 @@
       before { DummiesIndex.create }
       specify { expect(DummiesIndex.exists?).to eq(true) }
     end
+
+    context do
+      before { DummiesIndex.create('2024') }
+      specify { expect(DummiesIndex.exists?).to eq(true) }
+      specify { expect(DummiesIndex.exists?('2024')).to eq(true) }
+    end
+
+    context do
+      before { DummiesIndex.create('2024', alias: false) }
+      specify { expect(DummiesIndex.exists?).to eq(false) }
+      specify { expect(DummiesIndex.exists?('2024')).to eq(true) }
+    end
   end
 
   describe '.create' do

spec/chewy/index/import_spec.rb

@@ -32,13 +32,38 @@ def subscribe_notification
 
   describe 'index creation on import' do
     let(:dummy_city) { City.create }
+    let(:dummy_auto_suffix) { (Time.now.to_f * 1000).round }
+
+    before do
+      allow(Chewy::Index).to receive(:auto_suffix).and_return(dummy_auto_suffix)
+    end
 
     specify 'lazy (default)' do
-      expect(CitiesIndex).to receive(:exists?).and_call_original
-      expect(CitiesIndex).to receive(:create!).and_call_original
+      expect(CitiesIndex).to receive(:exists?).with(no_args).and_call_original
+      expect(CitiesIndex).to receive(:create!).with(dummy_auto_suffix).and_call_original
+      CitiesIndex.import(dummy_city)
+    end
+
+    specify 'lazy when index is already created' do
+      CitiesIndex.create!
+      expect(CitiesIndex).to receive(:exists?).with(no_args).and_call_original
+      expect(CitiesIndex).not_to receive(:create!)
       CitiesIndex.import(dummy_city)
     end
 
+    specify 'lazy when index is already created and suffix is given' do
+      CitiesIndex.create!(dummy_auto_suffix)
+      expect(CitiesIndex).to receive(:exists?).with(dummy_auto_suffix).and_call_original
+      expect(CitiesIndex).not_to receive(:create!)
+      CitiesIndex.import(dummy_city, suffix: dummy_auto_suffix)
+    end
+
+    specify 'lazy when suffix is given' do
+      expect(CitiesIndex).to receive(:exists?).with(dummy_auto_suffix).and_call_original
+      expect(CitiesIndex).to receive(:create!).with(dummy_auto_suffix).and_call_original
+      CitiesIndex.import(dummy_city, suffix: dummy_auto_suffix)
+    end
+
     specify 'lazy without objects' do
       expect(CitiesIndex).not_to receive(:exists?)
       expect(CitiesIndex).not_to receive(:create!)

spec/chewy/index_spec.rb

@@ -246,6 +246,16 @@ def self.by_id; end
     specify { expect(subject.specification).to equal(subject.specification) }
   end
 
+  describe '.auto_suffix' do
+    subject { stub_index(:documents) }
+
+    around do |spec|
+      Timecop.freeze { spec.run }
+    end
+
+    specify { expect(subject.auto_suffix).to eq((Time.now.to_f * 1000).round) }
+  end
+
   context 'index call inside index', :orm do
     before do
       stub_index(:cities) do

spec/chewy/search/request_spec.rb

@@ -755,12 +755,13 @@
         expect(subject.limit(5).source(:name).pluck(:id, :age)).to eq([[1, 10], [2, 20], [3, 30], [4, 40], [5, 50]])
       end
       specify do
+        index_name = ProductsIndex.indexes[0]
         expect(subject.limit(5).pluck(:_index, :name)).to eq([
-          %w[products Name1],
-          %w[products Name2],
-          %w[products Name3],
-          %w[products Name4],
-          %w[products Name5]
+          [index_name, 'Name1'],
+          [index_name, 'Name2'],
+          [index_name, 'Name3'],
+          [index_name, 'Name4'],
+          [index_name, 'Name5']
         ])
       end