activerecord-spanner-adapter 1.5.0 → 1.6.0

data/acceptance/cases/tasks/database_tasks_test.rb

@@ -14,6 +14,10 @@ module ActiveRecord
     class DatabaseTasksTest < SpannerAdapter::TestCase
       attr_reader :connector_config, :connection
 
+      def is_7_1_or_higher?
+        ActiveRecord::gem_version >= Gem::Version.create('7.1.0')
+      end
+
       def setup
         @database_id = "ar-tasks-test-#{SecureRandom.hex 4}"
         @connector_config = {
@@ -87,8 +91,12 @@ module ActiveRecord
         end
         ActiveRecord::Tasks::DatabaseTasks.dump_schema db_config, :sql
         sql = File.read(filename)
-        if ENV["SPANNER_EMULATOR_HOST"]
+        if ENV["SPANNER_EMULATOR_HOST"] && is_7_1_or_higher?
+          assert_equal expected_schema_sql_on_emulator_7_1, sql, msg = sql
+        elsif ENV["SPANNER_EMULATOR_HOST"]
           assert_equal expected_schema_sql_on_emulator, sql, msg = sql
+        elsif is_7_1_or_higher?
+          assert_equal expected_schema_sql_on_production_7_1, sql, msg = sql
         else
           assert_equal expected_schema_sql_on_production, sql, msg = sql
         end
@@ -235,6 +243,168 @@ CREATE TABLE tracks (
 ) PRIMARY KEY(singerid, albumid, trackid),
   INTERLEAVE IN PARENT albums ON DELETE CASCADE;
 CREATE NULL_FILTERED INDEX index_tracks_on_singerid_and_albumid_and_title ON tracks(singerid, albumid, title), INTERLEAVE IN albums;
+CREATE TABLE table_with_sequence (
+  id INT64 NOT NULL DEFAULT (FARM_FINGERPRINT(GENERATE_UUID())),
+  name STRING(MAX) NOT NULL,
+  age INT64 NOT NULL,
+) PRIMARY KEY(id);
+CREATE TABLE schema_migrations (
+  version STRING(MAX) NOT NULL,
+) PRIMARY KEY(version);
+CREATE TABLE ar_internal_metadata (
+  key STRING(MAX) NOT NULL,
+  value STRING(MAX),
+  created_at TIMESTAMP NOT NULL,
+  updated_at TIMESTAMP NOT NULL,
+) PRIMARY KEY(key);
+INSERT INTO `schema_migrations` (version) VALUES
+('1');
+
+"
+      end
+
+      def expected_schema_sql_on_emulator_7_1
+        "CREATE TABLE all_types (
+  id INT64 NOT NULL,
+  col_string STRING(MAX),
+  col_int64 INT64,
+  col_float64 FLOAT64,
+  col_numeric NUMERIC,
+  col_bool BOOL,
+  col_bytes BYTES(MAX),
+  col_date DATE,
+  col_timestamp TIMESTAMP,
+  col_json JSON,
+  col_array_string ARRAY<STRING(MAX)>,
+  col_array_int64 ARRAY<INT64>,
+  col_array_float64 ARRAY<FLOAT64>,
+  col_array_numeric ARRAY<NUMERIC>,
+  col_array_bool ARRAY<BOOL>,
+  col_array_bytes ARRAY<BYTES(MAX)>,
+  col_array_date ARRAY<DATE>,
+  col_array_timestamp ARRAY<TIMESTAMP>,
+  col_array_json ARRAY<JSON>,
+) PRIMARY KEY(id);
+CREATE TABLE firms (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+  rating INT64,
+  description STRING(MAX),
+  account_id INT64,
+) PRIMARY KEY(id);
+CREATE INDEX index_firms_on_account_id ON firms(account_id);
+CREATE TABLE customers (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+) PRIMARY KEY(id);
+CREATE TABLE accounts (
+  id INT64 NOT NULL,
+  customer_id INT64,
+  firm_id INT64,
+  name STRING(MAX),
+  credit_limit INT64,
+  transactions_count INT64,
+) PRIMARY KEY(id);
+CREATE TABLE transactions (
+  id INT64 NOT NULL,
+  amount FLOAT64,
+  account_id INT64,
+) PRIMARY KEY(id);
+CREATE TABLE departments (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+  resource_type STRING(255),
+  resource_id INT64,
+) PRIMARY KEY(id);
+CREATE INDEX index_departments_on_resource ON departments(resource_type, resource_id);
+CREATE TABLE member_types (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+) PRIMARY KEY(id);
+CREATE TABLE members (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+  member_type_id INT64,
+  admittable_type STRING(255),
+  admittable_id INT64,
+) PRIMARY KEY(id);
+CREATE TABLE memberships (
+  id INT64 NOT NULL,
+  joined_on TIMESTAMP,
+  club_id INT64,
+  member_id INT64,
+  favourite BOOL,
+) PRIMARY KEY(id);
+CREATE TABLE clubs (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+) PRIMARY KEY(id);
+CREATE TABLE authors (
+  id INT64 NOT NULL,
+  name STRING(MAX) NOT NULL,
+  registered_date DATE,
+  organization_id INT64,
+) PRIMARY KEY(id);
+CREATE TABLE posts (
+  id INT64 NOT NULL,
+  title STRING(MAX),
+  content STRING(MAX),
+  author_id INT64,
+  comments_count INT64,
+  post_date DATE,
+  published_time TIMESTAMP,
+) PRIMARY KEY(id);
+CREATE INDEX index_posts_on_author_id ON posts(author_id);
+CREATE TABLE comments (
+  id INT64 NOT NULL,
+  comment STRING(MAX),
+  post_id INT64,
+  CONSTRAINT fk_rails_2fd19c0db7 FOREIGN KEY(post_id) REFERENCES posts(id),
+) PRIMARY KEY(id);
+CREATE TABLE addresses (
+  id INT64 NOT NULL,
+  line1 STRING(MAX),
+  postal_code STRING(MAX),
+  city STRING(MAX),
+  author_id INT64,
+) PRIMARY KEY(id);
+CREATE TABLE organizations (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+  last_updated TIMESTAMP OPTIONS (
+    allow_commit_timestamp = true
+  ),
+) PRIMARY KEY(id);
+CREATE TABLE singers (
+  singerid INT64 NOT NULL,
+  first_name STRING(200),
+  last_name STRING(MAX),
+  tracks_count INT64,
+  lock_version INT64,
+  full_name STRING(MAX) AS (COALESCE(first_name || ' ', '') || last_name) STORED,
+) PRIMARY KEY(singerid);
+CREATE TABLE albums (
+  singerid INT64 NOT NULL,
+  albumid INT64 NOT NULL,
+  title STRING(MAX),
+  lock_version INT64,
+) PRIMARY KEY(singerid, albumid),
+  INTERLEAVE IN PARENT singers ON DELETE NO ACTION;
+CREATE TABLE tracks (
+  singerid INT64 NOT NULL,
+  albumid INT64 NOT NULL,
+  trackid INT64 NOT NULL,
+  title STRING(MAX),
+  duration NUMERIC,
+  lock_version INT64,
+) PRIMARY KEY(singerid, albumid, trackid),
+  INTERLEAVE IN PARENT albums ON DELETE CASCADE;
+CREATE NULL_FILTERED INDEX index_tracks_on_singerid_and_albumid_and_title ON tracks(singerid, albumid, title), INTERLEAVE IN albums;
+CREATE TABLE table_with_sequence (
+  id INT64 NOT NULL DEFAULT (FARM_FINGERPRINT(GENERATE_UUID())),
+  name STRING(MAX) NOT NULL,
+  age INT64 NOT NULL,
+) PRIMARY KEY(id);
 CREATE TABLE schema_migrations (
   version STRING(MAX) NOT NULL,
 ) PRIMARY KEY(version);
@@ -251,7 +421,10 @@ INSERT INTO `schema_migrations` (version) VALUES
       end
 
       def expected_schema_sql_on_production
-        "CREATE TABLE accounts (
+        "CREATE SEQUENCE test_sequence OPTIONS (
+  sequence_kind = 'bit_reversed_positive'
+);
+CREATE TABLE accounts (
   id INT64 NOT NULL,
   customer_id INT64,
   firm_id INT64,
@@ -391,6 +564,171 @@ CREATE TABLE tracks (
 ) PRIMARY KEY(singerid, albumid, trackid),
   INTERLEAVE IN PARENT albums ON DELETE CASCADE;
 CREATE NULL_FILTERED INDEX index_tracks_on_singerid_and_albumid_and_title ON tracks(singerid, albumid, title), INTERLEAVE IN albums;
+CREATE TABLE table_with_sequence (
+  id INT64 NOT NULL DEFAULT (GET_NEXT_SEQUENCE_VALUE(SEQUENCE test_sequence)),
+  name STRING(MAX) NOT NULL,
+  age INT64 NOT NULL,
+) PRIMARY KEY(id);
+CREATE TABLE transactions (
+  id INT64 NOT NULL,
+  amount FLOAT64,
+  account_id INT64,
+) PRIMARY KEY(id);
+INSERT INTO `schema_migrations` (version) VALUES
+('1');
+
+"
+      end
+
+      def expected_schema_sql_on_production_7_1
+        "CREATE SEQUENCE test_sequence OPTIONS (
+  sequence_kind = 'bit_reversed_positive'
+);
+CREATE TABLE accounts (
+  id INT64 NOT NULL,
+  customer_id INT64,
+  firm_id INT64,
+  name STRING(MAX),
+  credit_limit INT64,
+  transactions_count INT64,
+) PRIMARY KEY(id);
+CREATE TABLE addresses (
+  id INT64 NOT NULL,
+  line1 STRING(MAX),
+  postal_code STRING(MAX),
+  city STRING(MAX),
+  author_id INT64,
+) PRIMARY KEY(id);
+CREATE TABLE all_types (
+  id INT64 NOT NULL,
+  col_string STRING(MAX),
+  col_int64 INT64,
+  col_float64 FLOAT64,
+  col_numeric NUMERIC,
+  col_bool BOOL,
+  col_bytes BYTES(MAX),
+  col_date DATE,
+  col_timestamp TIMESTAMP,
+  col_json JSON,
+  col_array_string ARRAY<STRING(MAX)>,
+  col_array_int64 ARRAY<INT64>,
+  col_array_float64 ARRAY<FLOAT64>,
+  col_array_numeric ARRAY<NUMERIC>,
+  col_array_bool ARRAY<BOOL>,
+  col_array_bytes ARRAY<BYTES(MAX)>,
+  col_array_date ARRAY<DATE>,
+  col_array_timestamp ARRAY<TIMESTAMP>,
+  col_array_json ARRAY<JSON>,
+) PRIMARY KEY(id);
+CREATE TABLE ar_internal_metadata (
+  key STRING(MAX) NOT NULL,
+  value STRING(MAX),
+  created_at TIMESTAMP NOT NULL,
+  updated_at TIMESTAMP NOT NULL,
+) PRIMARY KEY(key);
+CREATE TABLE authors (
+  id INT64 NOT NULL,
+  name STRING(MAX) NOT NULL,
+  registered_date DATE,
+  organization_id INT64,
+) PRIMARY KEY(id);
+CREATE TABLE clubs (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+) PRIMARY KEY(id);
+CREATE TABLE comments (
+  id INT64 NOT NULL,
+  comment STRING(MAX),
+  post_id INT64,
+) PRIMARY KEY(id);
+CREATE TABLE customers (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+) PRIMARY KEY(id);
+CREATE TABLE departments (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+  resource_type STRING(255),
+  resource_id INT64,
+) PRIMARY KEY(id);
+CREATE INDEX index_departments_on_resource ON departments(resource_type, resource_id);
+CREATE TABLE firms (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+  rating INT64,
+  description STRING(MAX),
+  account_id INT64,
+) PRIMARY KEY(id);
+CREATE INDEX index_firms_on_account_id ON firms(account_id);
+CREATE TABLE member_types (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+) PRIMARY KEY(id);
+CREATE TABLE members (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+  member_type_id INT64,
+  admittable_type STRING(255),
+  admittable_id INT64,
+) PRIMARY KEY(id);
+CREATE TABLE memberships (
+  id INT64 NOT NULL,
+  joined_on TIMESTAMP,
+  club_id INT64,
+  member_id INT64,
+  favourite BOOL,
+) PRIMARY KEY(id);
+CREATE TABLE organizations (
+  id INT64 NOT NULL,
+  name STRING(MAX),
+  last_updated TIMESTAMP OPTIONS (
+    allow_commit_timestamp = true
+  ),
+) PRIMARY KEY(id);
+CREATE TABLE posts (
+  id INT64 NOT NULL,
+  title STRING(MAX),
+  content STRING(MAX),
+  author_id INT64,
+  comments_count INT64,
+  post_date DATE,
+  published_time TIMESTAMP,
+) PRIMARY KEY(id);
+ALTER TABLE comments ADD CONSTRAINT fk_rails_2fd19c0db7 FOREIGN KEY(post_id) REFERENCES posts(id);
+CREATE INDEX index_posts_on_author_id ON posts(author_id);
+CREATE TABLE schema_migrations (
+  version STRING(MAX) NOT NULL,
+) PRIMARY KEY(version);
+CREATE TABLE singers (
+  singerid INT64 NOT NULL,
+  first_name STRING(200),
+  last_name STRING(MAX),
+  tracks_count INT64,
+  lock_version INT64,
+  full_name STRING(MAX) AS (COALESCE(first_name || ' ', '') || last_name) STORED,
+) PRIMARY KEY(singerid);
+CREATE TABLE albums (
+  singerid INT64 NOT NULL,
+  albumid INT64 NOT NULL,
+  title STRING(MAX),
+  lock_version INT64,
+) PRIMARY KEY(singerid, albumid),
+  INTERLEAVE IN PARENT singers ON DELETE NO ACTION;
+CREATE TABLE tracks (
+  singerid INT64 NOT NULL,
+  albumid INT64 NOT NULL,
+  trackid INT64 NOT NULL,
+  title STRING(MAX),
+  duration NUMERIC,
+  lock_version INT64,
+) PRIMARY KEY(singerid, albumid, trackid),
+  INTERLEAVE IN PARENT albums ON DELETE CASCADE;
+CREATE NULL_FILTERED INDEX index_tracks_on_singerid_and_albumid_and_title ON tracks(singerid, albumid, title), INTERLEAVE IN albums;
+CREATE TABLE table_with_sequence (
+  id INT64 NOT NULL DEFAULT (GET_NEXT_SEQUENCE_VALUE(SEQUENCE test_sequence)),
+  name STRING(MAX) NOT NULL,
+  age INT64 NOT NULL,
+) PRIMARY KEY(id);
 CREATE TABLE transactions (
   id INT64 NOT NULL,
   amount FLOAT64,

data/acceptance/cases/transactions/optimistic_locking_test.rb

@@ -6,6 +6,12 @@
 
 # frozen_string_literal: true
 
+# ActiveRecord 7.1 introduced native support for composite primary keys.
+# This deprecates the https://github.com/composite-primary-keys/composite_primary_keys gem that was previously used in
+# this library to support composite primary keys, which again are needed for interleaved tables. These tests use the
+# third-party composite primary key gem and are therefore not executed for Rails 7.1 and higher.
+return if ActiveRecord::gem_version >= Gem::Version.create('7.1.0')
+
 require "test_helper"
 require "models/singer"
 require "models/album"

data/acceptance/cases/transactions/read_write_transactions_test.rb

@@ -11,6 +11,7 @@ require "models/author"
 require "models/post"
 require "models/comment"
 require "models/organization"
+require "models/table_with_sequence"
 
 module ActiveRecord
   module Transactions
@@ -243,6 +244,29 @@ module ActiveRecord
 
         assert_equal 0, Comment.count
       end
+
+      def test_create_record_with_sequence
+        record = TableWithSequence.create name: "Some name", age: 40
+        assert record.id, "ID should be generated and returned by the database"
+        assert record.id > 0, "ID should be positive" unless ENV["SPANNER_EMULATOR_HOST"]
+      end
+
+      def test_create_record_with_sequence_in_transaction
+        record = TableWithSequence.transaction do
+          TableWithSequence.create name: "Some name", age: 40
+        end
+        assert record.id, "ID should be generated and returned by the database"
+        assert record.id > 0, "ID should be positive" unless ENV["SPANNER_EMULATOR_HOST"]
+      end
+
+      def test_create_record_with_sequence_using_mutations
+        err = assert_raises ActiveRecord::StatementInvalid do
+          TableWithSequence.transaction isolation: :buffered_mutations do
+            TableWithSequence.create name: "Foo", age: 50
+          end
+        end
+        assert_equal "Mutations cannot be used to create records that use a sequence to generate the primary key. TableWithSequence uses test_sequence.", err.message
+      end
     end
   end
 end

data/acceptance/models/table_with_sequence.rb

@@ -0,0 +1,10 @@
+# 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 TableWithSequence < ActiveRecord::Base
+  self.table_name = :table_with_sequence
+  self.sequence_name = :test_sequence
+end

data/acceptance/schema/schema.rb

@@ -6,6 +6,11 @@
 
 # frozen_string_literal: true
 
+
+def is_7_1_or_higher?
+  ActiveRecord::gem_version >= Gem::Version.create('7.1.0')
+end
+
 def create_tables_in_test_schema
   ActiveRecord::Schema.define(version: 1) do
     ActiveRecord::Base.connection.ddl_batch do
@@ -122,29 +127,70 @@ def create_tables_in_test_schema
         t.virtual :full_name, type: :string, as: "COALESCE(first_name || ' ', '') || last_name", stored: true
       end
 
-      create_table :albums, id: false do |t|
-        t.interleave_in :singers
-        t.primary_key :albumid
-        # `singerid` is part of the primary key in the table definition, but it is not visible to ActiveRecord as part of
-        # the primary key, to prevent ActiveRecord from considering this to be an entity with a composite primary key.
-        t.parent_key :singerid
-        t.string :title
-        t.integer :lock_version
-      end
-
-      create_table :tracks, id: false do |t|
-        # `:cascade` causes all tracks that belong to an album to automatically be deleted when an album is deleted.
-        t.interleave_in :albums, :cascade
-        t.primary_key :trackid
-        t.parent_key :singerid
-        t.parent_key :albumid
-        t.string :title
-        t.numeric :duration
-        t.integer :lock_version
+      if is_7_1_or_higher?
+        create_table :albums, primary_key: [:singerid, :albumid] do |t|
+          t.interleave_in :singers
+          t.integer :singerid, null: false
+          t.integer :albumid, null: false
+          t.string :title
+          t.integer :lock_version
+        end
+      else
+        create_table :albums, id: false do |t|
+          t.interleave_in :singers
+          t.primary_key :albumid
+          # `singerid` is part of the primary key in the table definition, but it is not visible to ActiveRecord as part of
+          # the primary key, to prevent ActiveRecord from considering this to be an entity with a composite primary key.
+          t.parent_key :singerid
+          t.string :title
+          t.integer :lock_version
+        end
+      end
+
+      if is_7_1_or_higher?
+        create_table :tracks, primary_key: [:singerid, :albumid, :trackid] do |t|
+          # `:cascade` causes all tracks that belong to an album to automatically be deleted when an album is deleted.
+          t.interleave_in :albums, :cascade
+          t.integer :singerid, null: false
+          t.integer :albumid, null: false
+          t.integer :trackid, null: false
+          t.string :title
+          t.numeric :duration
+          t.integer :lock_version
+        end
+      else
+        create_table :tracks, id: false do |t|
+          # `:cascade` causes all tracks that belong to an album to automatically be deleted when an album is deleted.
+          t.interleave_in :albums, :cascade
+          t.primary_key :trackid
+          t.parent_key :singerid
+          t.parent_key :albumid
+          t.string :title
+          t.numeric :duration
+          t.integer :lock_version
+        end
       end
 
       add_index :tracks, [:singerid, :albumid, :title], interleave_in: :albums, null_filtered: true, unique: false
 
+      if ENV["SPANNER_EMULATOR_HOST"]
+        create_table :table_with_sequence, id: false do |t|
+          # The emulator does not yet support bit-reversed sequences, so we emulate a sequence value
+          # by hashing a UUID instead.
+          t.integer :id, primary_key: true, null: false, default: -> { "FARM_FINGERPRINT(GENERATE_UUID())" }
+          t.string :name, null: false
+          t.integer :age, null: false
+        end
+      else
+        connection.execute "create sequence test_sequence OPTIONS (sequence_kind = 'bit_reversed_positive')"
+
+        create_table :table_with_sequence, id: false do |t|
+          t.integer :id, primary_key: true, null: false, default: -> { "GET_NEXT_SEQUENCE_VALUE(SEQUENCE test_sequence)" }
+          t.string :name, null: false
+          t.integer :age, null: false
+        end
+      end
+
     end
   end
 end

data/acceptance/test_helper.rb

@@ -15,7 +15,7 @@ require "active_support/testing/stream"
 require "activerecord-spanner-adapter"
 require "active_record/connection_adapters/spanner_adapter"
 require "securerandom"
-require "composite_primary_keys"
+require "composite_primary_keys" if ActiveRecord::gem_version < Gem::Version.create('7.1.0')
 
 # rubocop:disable Style/GlobalVars
 

data/activerecord-spanner-adapter.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.7"
 
   spec.add_dependency "google-cloud-spanner", "~> 2.18"
-  spec.add_runtime_dependency "activerecord", [">= 6.0.0", "< 7.1"]
+  spec.add_runtime_dependency "activerecord", [">= 6.0.0", "< 7.2"]
 
   spec.add_development_dependency "autotest-suffix", "~> 1.1"
   spec.add_development_dependency "bundler", "~> 2.0"

data/examples/snippets/bit-reversed-sequence/README.md

@@ -0,0 +1,103 @@
+# Sample - Bit-reversed Sequence
+
+This example shows how to use a bit-reversed sequence to generate the primary key of a model.
+
+See https://cloud.google.com/spanner/docs/primary-key-default-value#bit-reversed-sequence for more information
+about bit-reversed sequences in Cloud Spanner.
+
+## Creating Tables with Bit-Reversed Sequences in ActiveRecord
+You can create bit-reversed sequences using migrations in ActiveRecord by executing a SQL statement using the underlying
+connection.
+
+```ruby
+connection.execute "create sequence singer_sequence OPTIONS (sequence_kind = 'bit_reversed_positive')"
+```
+
+The sequence can be used to generate a default value for the primary key column of a table:
+
+```ruby
+create_table :singers, id: false do |t|
+  t.integer :singerid, primary_key: true, null: false, default: -> { "GET_NEXT_SEQUENCE_VALUE(SEQUENCE singer_sequence)" }
+  t.string :first_name
+  t.string :last_name
+end
+```
+
+## Example Data Model
+This example uses the following table schema:
+
+```sql
+CREATE SEQUENCE singer_sequence (OPTIONS sequence_kind="bit_reversed_positive")
+
+CREATE TABLE singers (
+    singerid INT64 NOT NULL DEFAULT GET_NEXT_SEQUENCE_VALUE(SEQUENCE singer_sequence),
+    first_name STRING(MAX),
+    last_name STRING(MAX)
+) PRIMARY KEY (singerid);
+
+CREATE TABLE albums (
+    singerid INT64 NOT NULL,
+    albumid INT64 NOT NULL,
+    title STRING(MAX)
+) PRIMARY KEY (singerid, albumid), INTERLEAVE IN PARENT singers;
+```
+
+This schema can be created in ActiveRecord 7.1 and later as follows:
+
+```ruby
+# Execute the entire migration as one DDL batch.
+connection.ddl_batch do
+  connection.execute "create sequence singer_sequence OPTIONS (sequence_kind = 'bit_reversed_positive')"
+  
+  # Explicitly define the primary key.
+  create_table :singers, id: false, primary_key: :singerid do |t|
+    t.integer :singerid, primary_key: true, null: false, default: -> { "GET_NEXT_SEQUENCE_VALUE(SEQUENCE singer_sequence)" } 
+    t.string :first_name
+    t.string :last_name
+  end
+
+  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.integer :singerid
+    t.integer :albumid
+    t.string :title
+  end
+end
+```
+
+## Models for Tables with a Sequence
+The models for tables that use a sequence to generate the primary key must include the sequence name. This instructs
+the Cloud Spanner ActiveRecord provider to let the database generate the primary key value, instead of generating one
+in memory.
+
+### Example Models
+
+```ruby
+class Singer < ActiveRecord::Base
+  self.sequence_name = :singer_sequence
+  
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`.
+  # The primary key of `albums` is (`singerid`, `albumid`).
+  has_many :albums, foreign_key: :singerid
+end
+
+class Album < ActiveRecord::Base
+  # `albums` is defined as INTERLEAVE IN PARENT `singers`.
+  # The primary key of `singers` is `singerid`.
+  belongs_to :singer, foreign_key: :singerid
+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 following commands:
+
+```bash
+export AR_VERSION="~> 7.1.2"
+bundle install
+bundle exec rake run
+```

data/examples/snippets/bit-reversed-sequence/Rakefile

@@ -0,0 +1,13 @@
+# 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_relative "../config/environment"
+require "sinatra/activerecord/rake"
+
+desc "Sample showing how to work with bit-reversed sequences."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[bit-reversed-sequence]" }
+end