activerecord-spanner-adapter 1.5.1 → 1.6.0

data/examples/snippets/interleaved-tables/Rakefile

@@ -1,4 +1,4 @@
-# Copyright 2022 Google LLC
+# Copyright 2023 Google LLC
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -7,7 +7,7 @@
 require_relative "../config/environment"
 require "sinatra/activerecord/rake"
 
-desc "Sample showing how to work with interleaved tables in ActiveRecord."
+desc "Sample showing how to work with interleaved tables in ActiveRecord 7.1 and later."
 task :run do
   Dir.chdir("..") { sh "bundle exec rake run[interleaved-tables]" }
 end

data/examples/snippets/interleaved-tables/application.rb

@@ -1,4 +1,4 @@
-# Copyright 2022 Google LLC
+# Copyright 2023 Google LLC
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -49,7 +49,7 @@ class Application
     puts "Found album: #{album.title}"
   end
 
-  def self.list_singers_albums_tracks
+  def self.list_singers_albums
     puts ""
     puts "Listing all singers with corresponding albums and tracks"
     Singer.all.order("last_name, first_name").each do |singer|

data/examples/snippets/interleaved-tables/db/migrate/01_create_tables.rb

@@ -1,41 +1,35 @@
-# Copyright 2022 Google LLC
+# Copyright 2023 Google LLC
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 
-class CreateTables < ActiveRecord::Migration[6.0]
+class CreateTables < ActiveRecord::Migration[7.1]
   def change
     # Execute the entire migration as one DDL batch.
     connection.ddl_batch do
-      create_table :singers, id: false do |t|
-        # Explicitly define the primary key with a custom name to prevent all primary key columns from being named `id`.
-        t.primary_key :singerid
+      # Explicitly define the primary key.
+      create_table :singers, id: false, primary_key: :singerid do |t|
+        t.integer :singerid
         t.string :first_name
         t.string :last_name
       end
 
-      create_table :albums, id: false do |t|
+      create_table :albums, primary_key: [:singerid, :albumid], id: false do |t|
         # Interleave the `albums` table in the parent table `singers`.
         t.interleave_in :singers
-        t.primary_key :albumid
-        # `singerid` is defined as a `parent_key` which makes it a part of the primary key in the table definition, but
-        # it is not presented to ActiveRecord as part of the primary key, to prevent ActiveRecord from considering this
-        # to be an entity with a composite primary key (which is not supported by ActiveRecord).
-        t.parent_key :singerid
+        t.integer :singerid
+        t.integer :albumid
         t.string :title
       end
 
-      create_table :tracks, id: false do |t|
+      create_table :tracks, primary_key: [:singerid, :albumid, :trackid], id: false do |t|
         # Interleave the `tracks` table in the parent table `albums` and cascade delete all tracks that belong to an
         # album when an album is deleted.
         t.interleave_in :albums, :cascade
-        # `trackid` is considered the only primary key column by ActiveRecord.
-        t.primary_key :trackid
-        # `singerid` and `albumid` form the parent key of `tracks`. These are part of the primary key definition in the
-        # database, but are presented as parent keys to ActiveRecord.
-        t.parent_key :singerid
-        t.parent_key :albumid
+        t.integer :singerid
+        t.integer :albumid
+        t.integer :trackid
         t.string :title
         t.numeric :duration
       end

data/examples/snippets/interleaved-tables/db/schema.rb

@@ -10,22 +10,24 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 1) do
+ActiveRecord::Schema[7.1].define(version: 1) do
   connection.start_batch_ddl
 
-  create_table "albums", primary_key: "albumid", id: { limit: 8 }, force: :cascade do |t|
-    t.integer "singerid", limit: 8, null: false
+  create_table "albums", primary_key: ["singerid", "albumid"], force: :cascade do |t|
+    t.integer "singerid", limit: 8
+    t.integer "albumid", limit: 8
     t.string "title"
   end
 
-  create_table "singers", primary_key: "singerid", id: { limit: 8 }, force: :cascade do |t|
+  create_table "singers", primary_key: "singerid", force: :cascade do |t|
     t.string "first_name"
     t.string "last_name"
   end
 
-  create_table "tracks", primary_key: "trackid", id: { limit: 8 }, force: :cascade do |t|
-    t.integer "singerid", limit: 8, null: false
-    t.integer "albumid", limit: 8, null: false
+  create_table "tracks", primary_key: ["singerid", "albumid", "trackid"], force: :cascade do |t|
+    t.integer "singerid", limit: 8
+    t.integer "albumid", limit: 8
+    t.integer "trackid", limit: 8
     t.string "title"
     t.decimal "duration"
   end

data/examples/snippets/interleaved-tables/db/seeds.rb

@@ -1,4 +1,4 @@
-# Copyright 2022 Google LLC
+# Copyright 2023 Google LLC
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/examples/snippets/interleaved-tables/models/album.rb

@@ -1,20 +1,16 @@
-# Copyright 2022 Google LLC
+# Copyright 2023 Google LLC
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 
-require "composite_primary_keys"
-
 class Album < ActiveRecord::Base
-  # Use the `composite_primary_key` gem to create a composite primary key definition for the model.
-  self.primary_keys = :singerid, :albumid
-
   # `albums` is defined as INTERLEAVE IN PARENT `singers`.
   # The primary key of `singers` is `singerid`.
   belongs_to :singer, foreign_key: :singerid
 
   # `tracks` is defined as INTERLEAVE IN PARENT `albums`.
   # The primary key of `albums` is (`singerid`, `albumid`).
-  has_many :tracks, foreign_key: [:singerid, :albumid]
+  # Rails 7.1 requires using query_constraints to define a composite foreign key.
+  has_many :tracks, query_constraints: [:singerid, :albumid]
 end

data/examples/snippets/interleaved-tables/models/singer.rb

@@ -1,4 +1,4 @@
-# Copyright 2022 Google LLC
+# Copyright 2023 Google LLC
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/examples/snippets/interleaved-tables/models/track.rb

@@ -1,17 +1,16 @@
-# Copyright 2022 Google LLC
+# Copyright 2023 Google LLC
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
 # https://opensource.org/licenses/MIT.
 
 class Track < ActiveRecord::Base
-  # Use the `composite_primary_key` gem to create a composite primary key definition for the model.
-  self.primary_keys = :singerid, :albumid, :trackid
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`.
+  # The primary key of `albums` is (`singerid`, `albumid`).
+  # Rails 7.1 requires a composite primary key in a belongs_to relationship to be specified as query_constraints.
+  belongs_to :album, query_constraints: [:singerid, :albumid]
 
-  # `tracks` is defined as INTERLEAVE IN PARENT `albums`. The primary key of `albums` is ()`singerid`, `albumid`).
-  belongs_to :album, foreign_key: [:singerid, :albumid]
-
-  # `tracks` also has a `singerid` column should be used to associate a Track with a Singer.
+  # `tracks` also has a `singerid` column that can be used to associate a Track with a Singer.
   belongs_to :singer, foreign_key: :singerid
 
   # Override the default initialize method to automatically set the singer attribute when an album is given.

data/examples/snippets/interleaved-tables-before-7.1/README.md

@@ -0,0 +1,167 @@
+# Sample - Interleaved Tables - Before Rails 7.1.0
+
+__NOTE__: This example uses the third-party gem `composite_primary_keys`. This is only supported with
+Rails version < `7.1.0`.
+
+This example shows how to use interleaved tables with the Spanner ActiveRecord adapter.
+Interleaved tables use composite primary keys. This is not natively supported by ActiveRecord.
+It is therefore necessary to use the `composite_primary_keys` (https://github.com/composite-primary-keys/composite_primary_keys)
+gem to enable the use of interleaved tables.
+
+See https://cloud.google.com/spanner/docs/schema-and-data-model#creating-interleaved-tables for more information
+on interleaved tables if you are not familiar with this concept.
+
+## Creating Interleaved Tables in ActiveRecord
+You can create interleaved tables using migrations in ActiveRecord by using the following Spanner ActiveRecord specific
+methods that are defined on `TableDefinition`:
+* `interleave_in`: Specifies which parent table a child table should be interleaved in and optionally whether
+  deletes of a parent record should automatically cascade delete all child records.
+* `parent_key`: Creates a column that is a reference to (a part of) the primary key of the parent table. Each child
+  table must include all the primary key columns of the parent table as a `parent_key`.
+
+Cloud Spanner requires a child table to include the exact same primary key columns as the parent table in addition to
+the primary key column(s) of the child table. This means that the default `id` primary key column of ActiveRecord is
+not usable in combination with interleaved tables. Instead each primary key column should be prefixed with the table
+name of the table that it references, or use some other unique name.
+
+## Example Data Model
+This example uses the following table schema:
+
+```sql
+CREATE TABLE singers (
+    singerid INT64 NOT NULL,
+    first_name STRING(MAX),
+    last_name STRING(MAX)
+) PRIMARY KEY (singerid);
+
+CREATE TABLE albums (
+    albumid INT64 NOT NULL,
+    singerid INT64 NOT NULL,
+    title STRING(MAX)
+) PRIMARY KEY (singerid, albumid), INTERLEAVE IN PARENT singers;
+
+CREATE TABLE tracks (
+    trackid INT64 NOT NULL,
+    singerid INT64 NOT NULL,
+    albumid INT64 NOT NULL,
+    title STRING(MAX),
+    duration NUMERIC
+) PRIMARY KEY (singerid, albumid, trackid), INTERLEAVE IN PARENT albums ON DELETE CASCADE;
+```
+
+This schema can be created in ActiveRecord as follows:
+
+```ruby
+create_table :singers, id: false do |t|
+  # Explicitly define the primary key with a custom name to prevent all primary key columns from being named `id`.
+  t.primary_key :singerid
+  t.string :first_name
+  t.string :last_name
+end
+
+create_table :albums, id: false do |t|
+  # Interleave the `albums` table in the parent table `singers`.
+  t.interleave_in :singers
+  t.primary_key :albumid
+  # `singerid` is defined as a `parent_key` which makes it a part of the primary key in the table definition, but
+  # it is not presented to ActiveRecord as part of the primary key, to prevent ActiveRecord from considering this
+  # to be an entity with a composite primary key (which is not supported by ActiveRecord).
+  t.parent_key :singerid
+  t.string :title
+end
+
+create_table :tracks, id: false do |t|
+  # Interleave the `tracks` table in the parent table `albums` and cascade delete all tracks that belong to an
+  # album when an album is deleted.
+  t.interleave_in :albums, :cascade
+  # Add `trackid` as the primary key in the table definition. Add the other key parts as
+  # a `parent_key`.
+  t.primary_key :trackid
+  # `singerid` and `albumid` form the parent key of `tracks`. These are part of the primary key definition in the
+  # database, but are presented as parent keys to ActiveRecord.
+  t.parent_key :singerid
+  t.parent_key :albumid
+  t.string :title
+  t.numeric :duration
+end
+```
+
+## Models for Interleaved Tables
+The model definition for an interleaved table (a child table) must use the `primary_keys=col1, col2, ...`
+function from the `composite_primary_keys` gem.
+
+An interleaved table parent/child relationship must be modelled as a `belongs_to`/`has_many` association in
+ActiveRecord. As the columns that are used to reference a parent record use a custom column name, it is required to also
+include the custom column name(s) in the `belongs_to` and `has_many` definitions.
+
+Instances of these models can be used in the same way as any other association in ActiveRecord, but with a couple of
+inherent limitations:
+* It is not possible to change the parent record of a child record. For instance, changing the singer of an album in the
+  above example is impossible, as Cloud Spanner does not allow such an update.
+* It is not possible to de-reference a parent record by setting it to null.
+* It is only possible to delete a parent record with existing child records, if the child records are also deleted. This
+  can be done by enabling ON DELETE CASCADE in Cloud Spanner, or by deleting the child records using ActiveRecord.
+
+### Example Models
+
+```ruby
+class Singer < ActiveRecord::Base
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`.
+  # The primary key of `albums` is (`singerid`, `albumid`).
+  has_many :albums, foreign_key: :singerid
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`.
+  # The primary key of `tracks` is (`singerid`, `albumid`, `trackid`).
+  # The `singerid` column can be used to associate tracks with a singer without the need to go through albums.
+  # Note also that the inclusion of `singerid` as a column in `tracks` is required in order to make `tracks` a child
+  # table of `albums` which has primary key (`singerid`, `albumid`).
+  has_many :tracks, foreign_key: :singerid
+end
+
+class Album < ActiveRecord::Base
+  # Use the `composite_primary_key` gem to create a composite primary key definition for the model.
+  self.primary_keys = :singerid, :albumid
+
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`.
+  # The primary key of `singers` is `singerid`.
+  belongs_to :singer, foreign_key: :singerid
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`.
+  # The primary key of `albums` is (`singerid`, `albumid`).
+  has_many :tracks, foreign_key: [:singerid, :albumid]
+end
+
+class Track < ActiveRecord::Base
+  # Use the `composite_primary_key` gem to create a composite primary key definition for the model.
+  self.primary_keys = :singerid, :albumid, :trackid
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`. The primary key of `albums` is (`singerid`, `albumid`).
+  belongs_to :album, foreign_key: [:singerid, :albumid]
+
+  # `tracks` also has a `singerid` column that can be used to associate a Track with a Singer.
+  belongs_to :singer, foreign_key: :singerid
+
+  # Override the default initialize method to automatically set the singer attribute when an album is given.
+  def initialize attributes = nil
+    super
+    self.singer ||= album&.singer
+  end
+
+  def album=value
+    super
+    # Ensure the singer of this track is equal to the singer of the album that is set.
+    self.singer = value&.singer
+  end
+end
+```
+
+## Running the Sample
+
+The sample will automatically start a Spanner Emulator in a docker container and execute the sample
+against that emulator. The emulator will automatically be stopped when the application finishes.
+
+Run the application with the command
+
+```bash
+bundle exec rake run
+```

data/examples/snippets/interleaved-tables-before-7.1/Rakefile

@@ -0,0 +1,13 @@
+# Copyright 2022 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require_relative "../config/environment"
+require "sinatra/activerecord/rake"
+
+desc "Sample showing how to work with interleaved tables in ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[interleaved-tables-before-7.1]" }
+end

data/examples/snippets/interleaved-tables-before-7.1/application.rb

@@ -0,0 +1,126 @@
+# Copyright 2022 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require "io/console"
+require_relative "../config/environment"
+require_relative "models/singer"
+require_relative "models/album"
+require_relative "models/track"
+
+class Application
+  def self.run
+    # List all singers, albums and tracks.
+    list_singers_albums_tracks
+
+    # Create a new album with some tracks.
+    create_new_album
+
+    # Try to update the singer of an album. This is not possible as albums are interleaved in singers.
+    update_singer_of_album
+
+    # Try to delete a singer that has at least one album. This is NOT possible as albums is NOT marked with
+    # ON DELETE CASCADE.
+    delete_singer_with_albums
+
+    # Try to delete an album that has at least one track. This IS possible as tracks IS marked with
+    # ON DELETE CASCADE.
+    delete_album_with_tracks
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+
+  def self.find_singer
+    singerid = Singer.all.sample.singerid
+
+    singer = Singer.find singerid
+    puts "Found singer: #{singer.first_name} #{singer.last_name}"
+  end
+
+  def self.find_album
+    singer = Singer.all.sample
+    albumid = singer.albums.sample.albumid
+
+    album = Album.find [singer.singerid, albumid]
+    puts "Found album: #{album.title}"
+  end
+
+  def self.list_singers_albums
+    puts ""
+    puts "Listing all singers with corresponding albums and tracks"
+    Singer.all.order("last_name, first_name").each do |singer|
+      puts "#{singer.first_name} #{singer.last_name} has #{singer.albums.count} albums:"
+      singer.albums.order("title").each do |album|
+        puts "  #{album.title} has #{album.tracks.count} tracks:"
+        album.tracks.each do |track|
+          puts "    #{track.title}"
+        end
+      end
+    end
+  end
+
+  def self.create_new_album
+    # Create a new album with some tracks.
+    puts ""
+    singer = Singer.all.sample
+    puts "Creating a new album for #{singer.first_name} #{singer.last_name}"
+    album = singer.albums.build title: "New Title"
+    # NOTE: When adding multiple elements to a collection, you *MUST* set the primary key value (i.e. trackid).
+    # Otherwise, ActiveRecord thinks that you are adding the same record multiple times and will only add one.
+    album.tracks.build title: "Track 1", duration: 3.5, singer: singer, trackid: Track.next_sequence_value
+    album.tracks.build title: "Track 2", duration: 3.6, singer: singer, trackid: Track.next_sequence_value
+    # This will save the album and corresponding tracks in one transaction.
+    album.save!
+
+    album.reload
+    puts "Album #{album.title} has #{album.tracks.count} tracks:"
+    album.tracks.order("title").each do |track|
+      puts "  #{track.title} with duration #{track.duration}"
+    end
+  end
+
+  def self.update_singer_of_album
+    # It is not possible to change the singer of an album or the album of a track. This is because the associations
+    # between these are not traditional foreign keys, but an immutable parent-child relationship.
+    album = Album.all.sample
+    new_singer = Singer.all.where.not(singerid: album.singer).sample
+    # This will fail as we cannot assign a new singer to an album as it is an INTERLEAVE IN PARENT relationship.
+    begin
+      album.update! singer: new_singer
+      raise StandardError, "Unexpected error: Updating the singer of an album should not be possible."
+    rescue ActiveRecord::StatementInvalid
+      puts ""
+      puts "Failed to update the singer of an album. This is expected."
+    end
+  end
+
+  def self.delete_singer_with_albums
+    # Deleting a singer that has albums is not possible, as the INTERLEAVE IN PARENT of albums is not marked with
+    # ON DELETE CASCADE.
+    singer = Album.all.sample.singer
+    begin
+      singer.delete
+      raise StandardError, "Unexpected error: Updating the singer of an album should not be possible."
+    rescue ActiveRecord::StatementInvalid
+      puts ""
+      puts "Failed to delete a singer that has #{singer.albums.count} albums. This is expected."
+    end
+  end
+
+  def self.delete_album_with_tracks
+    # Deleting an album with tracks is supported, as the INTERLEAVE IN PARENT relationship between tracks and albums is
+    # marked with ON DELETE CASCADE.
+    puts ""
+    puts "Total track count: #{Track.count}"
+    album = Track.all.sample.album
+    puts "Deleting album #{album.title} with #{album.tracks.count} tracks"
+    album.delete
+    puts "Total track count after deletion: #{Track.count}"
+  end
+end
+
+Application.run

data/examples/snippets/interleaved-tables-before-7.1/config/database.yml

@@ -0,0 +1,8 @@
+development:
+  adapter: spanner
+  emulator_host: localhost:9010
+  project: test-project
+  instance: test-instance
+  database: testdb
+  pool: 5
+  timeout: 5000

data/examples/snippets/interleaved-tables-before-7.1/db/migrate/01_create_tables.rb

@@ -0,0 +1,44 @@
+# Copyright 2022 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+class CreateTables < ActiveRecord::Migration[6.0]
+  def change
+    # Execute the entire migration as one DDL batch.
+    connection.ddl_batch do
+      create_table :singers, id: false do |t|
+        # Explicitly define the primary key with a custom name to prevent all primary key columns from being named `id`.
+        t.primary_key :singerid
+        t.string :first_name
+        t.string :last_name
+      end
+
+      create_table :albums, id: false do |t|
+        # Interleave the `albums` table in the parent table `singers`.
+        t.interleave_in :singers
+        t.primary_key :albumid
+        # `singerid` is defined as a `parent_key` which makes it a part of the primary key in the table definition, but
+        # it is not presented to ActiveRecord as part of the primary key, to prevent ActiveRecord from considering this
+        # to be an entity with a composite primary key (which is not supported by ActiveRecord).
+        t.parent_key :singerid
+        t.string :title
+      end
+
+      create_table :tracks, id: false do |t|
+        # Interleave the `tracks` table in the parent table `albums` and cascade delete all tracks that belong to an
+        # album when an album is deleted.
+        t.interleave_in :albums, :cascade
+        # `trackid` is considered the only primary key column by ActiveRecord.
+        t.primary_key :trackid
+        # `singerid` and `albumid` form the parent key of `tracks`. These are part of the primary key definition in the
+        # database, but are presented as parent keys to ActiveRecord.
+        t.parent_key :singerid
+        t.parent_key :albumid
+        t.string :title
+        t.numeric :duration
+      end
+    end
+  end
+end

data/examples/snippets/interleaved-tables-before-7.1/db/schema.rb

@@ -0,0 +1,37 @@
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+# be faster and is potentially less error prone than running all of your
+# migrations from scratch. Old migrations may fail to apply correctly if those
+# migrations use external dependencies or application code.
+#
+# It's strongly recommended that you check this file into your version control system.
+
+ActiveRecord::Schema.define(version: 1) do
+  connection.start_batch_ddl
+
+  create_table "albums", primary_key: "albumid", force: :cascade do |t|
+    t.integer "singerid", limit: 8, null: false
+    t.string "title"
+  end
+
+  create_table "singers", primary_key: "singerid", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+  end
+
+  create_table "tracks", primary_key: "trackid", force: :cascade do |t|
+    t.integer "singerid", limit: 8, null: false
+    t.integer "albumid", limit: 8, null: false
+    t.string "title"
+    t.decimal "duration"
+  end
+
+  connection.run_batch
+rescue
+  abort_batch
+  raise
+end

data/examples/snippets/interleaved-tables-before-7.1/db/seeds.rb

@@ -0,0 +1,40 @@
+# Copyright 2022 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require_relative "../../config/environment.rb"
+require_relative "../models/singer"
+require_relative "../models/album"
+require_relative "../models/track"
+
+first_names = %w[Pete Alice John Ethel Trudy Naomi Wendy Ruben Thomas Elly]
+last_names = %w[Wendelson Allison Peterson Johnson Henderson Ericsson Aronson Tennet Courtou]
+
+adjectives = %w[daily happy blue generous cooked bad open]
+nouns = %w[windows potatoes bank street tree glass bottle]
+
+verbs = %w[operate waste package chew yield express polish stress slip want cough campaign cultivate report park refer]
+adverbs = %w[directly right hopefully personally economically privately supposedly consequently fully later urgently]
+
+durations = [3.14, 5.4, 3.3, 4.1, 5.0, 3.2, 3.0, 3.5, 4.0, 4.5, 5.5, 6.0]
+
+# This ensures all the records are inserted using one read/write transaction that will use mutations instead of DML.
+ActiveRecord::Base.transaction isolation: :buffered_mutations do
+  singers = []
+  5.times do
+    singers << Singer.create(first_name: first_names.sample, last_name: last_names.sample)
+  end
+
+  albums = []
+  20.times do
+    singer = singers.sample
+    albums << Album.create(title: "#{adjectives.sample} #{nouns.sample}", singer: singer)
+  end
+
+  200.times do
+    album = albums.sample
+    Track.create title: "#{verbs.sample} #{adverbs.sample}", duration: durations.sample, album: album
+  end
+end

data/examples/snippets/interleaved-tables-before-7.1/models/album.rb

@@ -0,0 +1,20 @@
+# Copyright 2022 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+require "composite_primary_keys"
+
+class Album < ActiveRecord::Base
+  # Use the `composite_primary_key` gem to create a composite primary key definition for the model.
+  self.primary_keys = :singerid, :albumid
+
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`.
+  # The primary key of `singers` is `singerid`.
+  belongs_to :singer, foreign_key: :singerid
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`.
+  # The primary key of `albums` is (`singerid`, `albumid`).
+  has_many :tracks, foreign_key: [:singerid, :albumid]
+end

data/examples/snippets/interleaved-tables-before-7.1/models/singer.rb

@@ -0,0 +1,18 @@
+# Copyright 2022 Google LLC
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+class Singer < ActiveRecord::Base
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`.
+  # The primary key of `albums` is (`singerid`, `albumid`).
+  has_many :albums, foreign_key: :singerid
+
+  # `tracks` is defined as INTERLEAVE IN PARENT `albums`.
+  # The primary key of `tracks` is [`singerid`, `albumid`, `trackid`].
+  # The `singerid` column can be used to associate tracks with a singer without the need to go through albums.
+  # Note also that the inclusion of `singerid` as a column in `tracks` is required in order to make `tracks` a child
+  # table of `albums` which has primary key (`singerid`, `albumid`).
+  has_many :tracks, foreign_key: :singerid
+end