activerecord-spanner-adapter 0.6.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55f265a14ddd7a176378a49090cbb3277aae66ce2c74913978ec9614289759fc
-  data.tar.gz: ae48998a381c0142063ac4499c8a0c13ece58bded34a72cbcc0371541ee02231
+  metadata.gz: bcc2624f18893422bf8ac9c23d07fff039e79cee5f51b975054314f49820b694
+  data.tar.gz: 7145b48f67236eb7ee9aac20bd1dfa907268419f262abf82cd6973acba25ab64
 SHA512:
-  metadata.gz: fa104b38f89edc91eb78d05b5f89e232fb50847953061eae4e3c9eb12bf307f9a0cf69545eb06a0682c92b2ac7bce065b8d88f8fa148570b4720b47ccccad0d5
-  data.tar.gz: 3de12a8b087940d6234ecd902ea7b109a8319960700dd323c363da266aa299f211b003e50fb01e24ff5e4632e4372b5451e0d129168cacfa3541771263dc2703
+  metadata.gz: 49aed5257b191aee1e9271c1d04e91c2ff1663c78e9b1e70e89acda430587324991a10cb1b2aabdfd9b1e9d70ab862b3a1579fda5c032023175303fa260deeed
+  data.tar.gz: 1764369d2a370d4c8d35cbbcd3b9c45130514cc6e76bac67e5a9dafbf2bf020734b973be44f354b13da9acaaffdebaba78e31046da56c6e62efe0546aca30611

data/.github/blunderbuss.yml

@@ -0,0 +1,2 @@
+assign_issues:
+  - hengfengli

data/.github/sync-repo-settings.yaml

@@ -2,7 +2,7 @@ rebaseMergeAllowed: true
 squashMergeAllowed: true
 mergeCommitAllowed: false
 branchProtectionRules:
-- pattern: master
+- pattern: main
   isAdminEnforced: true
   requiredStatusCheckContexts:
     - 'cla/google'

data/.github/workflows/acceptance-tests-on-emulator.yaml

@@ -1,7 +1,7 @@
 on:
   push:
     branches:
-      - master
+      - main
   pull_request:
 name: acceptance tests on emulator
 jobs:

data/.github/workflows/acceptance-tests-on-production.yaml

@@ -1,7 +1,7 @@
 on:
   push:
     branches:
-      - master
+      - main
   pull_request:
 name: acceptance tests on production
 jobs:
@@ -35,7 +35,7 @@ jobs:
         bundler-cache: true
         ruby-version: ${{ matrix.ruby }}
     - name: Setup GCloud
-      uses: google-github-actions/setup-gcloud@master
+      uses: google-github-actions/setup-gcloud@v0
       with:
         project_id: ${{ secrets.GCP_PROJECT_ID }}
         service_account_key: ${{ secrets.GCP_SA_KEY }}

data/.github/workflows/ci.yaml

@@ -1,7 +1,7 @@
 on:
   push:
     branches:
-      - master
+      - main
   pull_request:
 name: ci
 jobs:

data/.github/workflows/release-please-label.yml

@@ -2,21 +2,21 @@ name: release-please-label
 on:
   pull_request_target:
     branches:
-      - master
+      - main
     types:
       - opened
 jobs:
   release-please-label:
-    if: "${{ github.event.sender.login == 'yoshi-code-bot' && startsWith(github.event.pull_request.title, 'chore: release ') }}"
+    if: "${{ github.event.sender.login == 'yoshi-code-bot' && startsWith(github.event.pull_request.title, 'chore(main): release ') }}"
     runs-on: ubuntu-latest
     steps:
       - name: ReleaseLabel
-        uses: actions/github-script@v4
+        uses: actions/github-script@v6
         with:
           github-token: ${{secrets.YOSHI_APPROVER_TOKEN}}
           script: |
             core.info('Labeling release');
-            await github.issues.addLabels({
+            await github.rest.issues.addLabels({
               owner: context.repo.owner,
               repo: context.repo.repo,
               issue_number: context.payload.pull_request.number,

data/.github/workflows/release-please.yml

@@ -1,7 +1,7 @@
 name: Release-Please
 on:
   schedule:
-    - cron: '27 8 * * *'
+    - cron: '57 10 * * *'
   workflow_dispatch:
     inputs:
       gem:
@@ -21,19 +21,20 @@ jobs:
     steps:
       - name: Checkout repo
         uses: actions/checkout@v2
-      - name: Install Ruby 2.7
+      - name: Install Ruby 3.0
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "2.7"
-      - name: Install NodeJS 12.x
+          ruby-version: "3.0"
+      - name: Install NodeJS 16.x
         uses: actions/setup-node@v2
         with:
-          node-version: "12.x"
+          node-version: "16.x"
       - name: Install tools
-        run: "gem install --no-document toys && npm install release-please"
+        run: "gem install --no-document toys"
       - name: execute
         run: |
-          toys release please -v --fork \
+          toys release manifest -v \
+            --fork --skip-labeling \
             --github-event-name=${{ github.event_name }} \
-            --version-file=lib/activerecord_spanner_adapter/version.rb \
-            ${{ github.event.inputs.args }} -- ${{ github.event.inputs.gem }}
+            ${{ github.event.inputs.args }} \
+            -- ${{ github.event.inputs.gem }}

data/.github/workflows/rubocop.yaml

@@ -4,7 +4,7 @@ on:
   pull_request:
     types: [opened, synchronize]
   push:
-    branches: [ master ]
+    branches: [ main ]
 
 jobs:
   build:
@@ -18,7 +18,7 @@ jobs:
       with:
         ruby-version: '2.5'
     - name: cache gems
-      uses: actions/cache@v1
+      uses: actions/cache@v2
       with:
         path: vendor/bundle
         key: ${{ runner.os }}-rubocop-${{ hashFiles('**/Gemfile.lock') }}

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.1"
+}

data/.toys/release.rb

@@ -14,5 +14,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-load_git remote: "https://github.com/googleapis/google-cloud-ruby.git",
-         path: ".toys/release"
+load_git remote: "https://github.com/googleapis/ruby-common-tools.git",
+         path: "toys/release"

data/CHANGELOG.md

@@ -1,35 +1,58 @@
 # Changelog
 
-## [0.6.0](https://www.github.com/googleapis/ruby-spanner-activerecord/compare/activerecord-spanner-adapter/v0.5.0...activerecord-spanner-adapter/v0.6.0) (2021-09-09)
+### 1.0.1 (2022-04-21)
 
+#### Bug Fixes
 
-### Features
+* ActiveRecord::Type::Spanner::Array does not use element type
 
-* support JSON data type ([#123](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/123)) ([d177ddf](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/d177ddfc7326f02189bd4054571564b94d162b02))
-* support single stale reads ([#127](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/127)) ([a600628](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/a600628267355b808f478ed543bc505e73f95d4a))
-* support stale reads in read-only transactions ([#126](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/126)) ([8bf7730](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/8bf77300283c01e951725dd5e457270db20e98d2))
+#### Documentation
 
-## 0.5.0 (2021-08-31)
+* add limitation of interleaved tables
+* fix a couple of minor formatting issues
 
+### 1.0.0 (2021-12-07)
 
-### Features
+* GA release
 
-* Add support for NUMERIC type ([#73](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/73)) ([176cf99](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/176cf99dc8c26b3fd34d9e85d82a91dbde2b15c8))
-* Add support for ARRAY data type ([#86](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/86)) ([0c66a62](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/0c66a620cab968779de04faf48e03eec643ebea9))
-* google-cloud-spanner version upgraded to 2.2 ([#55](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/55)) ([d7581d6](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/d7581d60bd9a9e7b9989565449119f73e2caa694))
-* Support interleaved tables ([#83](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/83)) ([82265f9](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/82265f94ace79964639a2c65554714752be39724))
-* retry session not found ([#81](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/81)) ([88fd3b7](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/88fd3b70a03a90de2b667bb0f2e86efe5dc9328b))
-* support and test multiple ActiveRecord versions ([#107](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/107)) ([db9d96c](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/db9d96c44b9560f6904209df1a9aa42bf50a5844))
-* support DDL batches on connection ([#72](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/72)) ([0d18cd4](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/0d18cd49641bdb567012d6ac88b1909461d42551))
-* support generated columns ([#94](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/94)) ([68664eb](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/68664eb5c617abc2954dea274430f416e616a324))
-* support interleaved indexes + test other index features ([#101](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/101)) ([812e0f7](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/812e0f7f60b36ec26a974f6fb48266de5d840652))
-* support optimistic locking ([#92](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/92)) ([9eb71d8](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/9eb71d8a207a8df0406241bff5780593eb0afd34))
-* support PDML transactions ([#106](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/106)) ([fa0599a](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/fa0599afe986a184bb6ab26340305eeaa753dafa))
-* support prepared statements and query cache ([#74](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/74)) ([fed8258](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/fed825862c95e3e052410e3576de18fc3b7849b7))
-* support read only transactions ([#80](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/80)) ([2d6097b](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/2d6097bd8f4530634a41dcdbcbb3a02614f482b8))
-* support setting attributes to commit timestamp ([#89](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/89)) ([cdd8448](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/cdd844852da92fa4e2c43fd06eeef31310d6ff8a))
+### 0.7.1 (2021-11-21)
 
+#### Performance Improvements
 
-### Performance Improvements
+* inline BeginTransaction with first statement in the transaction
 
-* add benchmarks ([#98](https://www.github.com/googleapis/ruby-spanner-activerecord/issues/98)) ([80cbadc](https://www.github.com/googleapis/ruby-spanner-activerecord/commit/80cbadc5063f2f257ca1e6e7bf563fc376967428))
+### 0.7.0 (2021-10-03)
+
+#### Features
+
+* add support for query hints
+
+### 0.6.0 (2021-09-09)
+
+#### Features
+
+* support JSON data type
+* support single stale reads
+* support stale reads in read-only transactions
+
+### 0.5.0 (2021-08-31)
+
+#### Features
+
+* Add support for NUMERIC type
+* Add support for ARRAY data type
+* google-cloud-spanner version upgraded to 2.2
+* retry session not found
+* support and test multiple ActiveRecord versions
+* support DDL batches on connection
+* support generated columns
+* support interleaved indexes + test other index features
+* support optimistic locking
+* support PDML transactions
+* support prepared statements and query cache
+* support read only transactions
+* support setting attributes to commit timestamp
+
+#### Performance Improvements
+
+* add benchmarks

data/CONTRIBUTING.md

@@ -70,7 +70,7 @@ $ cd ruby-spanner-activerecord
 $ bundle exec rubocop
 ```
 
-The rubocop settings depend on [googleapis/ruby-style](https://github.com/googleapis/ruby-style/), in addition to [.rubocop.yml](https://github.com/googleapis/ruby-spanner-activerecord/blob/master/.rubocop.yml).
+The rubocop settings depend on [googleapis/ruby-style](https://github.com/googleapis/ruby-style/), in addition to [.rubocop.yml](https://github.com/googleapis/ruby-spanner-activerecord/blob/main/.rubocop.yml).
 
 ## Code of Conduct
 

data/Gemfile

@@ -3,7 +3,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in activerecord-spanner.gemspec
 gemspec
 
-gem "minitest", "~> 5.14.0"
+gem "minitest", "~> 5.15.0"
 gem "pry", "~> 0.13.0"
 gem "pry-byebug", "~> 3.9.0"
 

data/README.md

@@ -4,7 +4,7 @@
 
 ![rubocop](https://github.com/googleapis/ruby-spanner-activerecord/workflows/rubocop/badge.svg)
 
-This project provides a Cloud Spanner adapter for ActiveRecord. It has the __Preview__ release status and supports the following versions:
+This project provides a Cloud Spanner adapter for ActiveRecord. It supports the following versions:
 
 - ActiveRecord 6.0.x with Ruby 2.6 and 2.7.
 - ActiveRecord 6.1.x with Ruby 2.6 and higher.
@@ -69,13 +69,13 @@ Some noteworthy examples in the snippets directory:
 - [mutations](examples/snippets/mutations): Shows how you can use [mutations instead of DML](https://cloud.google.com/spanner/docs/dml-versus-mutations)
   for inserting, updating and deleting data in a Cloud Spanner database. Mutations can have a significant performance
   advantage compared to DML statements, but do not allow read-your-writes semantics during a transaction.
-- [interleaved-tables](examples/snippets/interleaved-tables): Shows how to create and work with a hierarchy of `INTERLEAVED IN` tables.
 - [array-data-type](examples/snippets/array-data-type): Shows how to work with `ARRAY` data types.
 
 ## Limitations
 
 Limitation|Comment|Resolution
 ---|---|---
+Interleaved tables are not supported|Cloud Spanner requires to use composite primary keys for interleaved tables, but Active Record does not support composite primary keys. More details: [#160](https://github.com/googleapis/ruby-spanner-activerecord/issues/160) |Use non-interleaved tables.
 Lack of DEFAULT for columns [change_column_default](https://apidock.com/rails/v5.2.3/ActiveRecord/ConnectionAdapters/SchemaStatements/change_column_default)|Cloud Spanner does not support DEFAULT values for columns. The use of default must be enforced in your controller logic| Always set a value in your model or controller logic.
 Lack of sequential and auto-assigned IDs|Cloud Spanner doesn't autogenerate IDs and this integration instead creates UUID4 to avoid [hotspotting](https://cloud.google.com/spanner/docs/schema-design#uuid_primary_key) so you SHOULD NOT rely on IDs being sorted| UUID4s are automatically generated for primary keys.
 Table without Primary Key| Cloud Spanner support does not support tables without a primary key.| Always define a primary key for your table.
@@ -93,4 +93,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Activerecord::Spanner project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/googleapis/ruby-spanner-activerecord/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Activerecord::Spanner project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/googleapis/ruby-spanner-activerecord/blob/main/CODE_OF_CONDUCT.md).

data/acceptance/cases/models/query_test.rb

@@ -142,6 +142,30 @@ module ActiveRecord
 
         assert_equal [post], posts.to_a
       end
+
+      def test_statement_hint
+        post = Post.optimizer_hints("statement_hint: @{USE_ADDITIONAL_PARALLELISM=TRUE}")
+                   .select(:title).to_a.first
+
+        assert_nil post.id
+        assert_equal "Title - 1", post.title
+      end
+
+      def test_table_hint
+        post = Post.optimizer_hints("table_hint: posts@{FORCE_INDEX=_BASE_TABLE}")
+                   .select(:title).to_a.first
+
+        assert_nil post.id
+        assert_equal "Title - 1", post.title
+      end
+
+      def test_join_hint
+        post = Post.joins("inner join @{JOIN_TYPE=HASH_JOIN} comments on posts.id=comments.post_id")
+                   .select(:title).to_a.first
+
+        assert_nil post.id
+        assert_equal "Title - 1", post.title
+      end
     end
   end
 end

data/acceptance/cases/type/all_types_test.rb

@@ -32,17 +32,18 @@ module ActiveRecord
           col_timestamp: ::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"),
           col_json: ENV["SPANNER_EMULATOR_HOST"] ? "" : { kind: "user_renamed", change: %w[jack john]},
           col_array_string: ["string1", nil, "string2"],
-          col_array_int64: [100, nil, 200],
-          col_array_float64: [3.14, nil, 2.0/3.0],
-          col_array_numeric: [6.626, nil, 3.20],
-          col_array_bool: [true, nil, false],
+          col_array_int64: [100, nil, 200, "300"],
+          col_array_float64: [3.14, nil, 2.0/3.0, "3.14"],
+          col_array_numeric: [6.626, nil, 3.20, "400"],
+          col_array_bool: [true, nil, false, "false"],
           col_array_bytes: [StringIO.new("bytes1"), nil, StringIO.new("bytes2")],
-          col_array_date: [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24)],
+          col_array_date: [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24), "2021-06-25"],
           col_array_timestamp: [::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"), nil, \
-                                ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00")],
+                                ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00"), "2021-06-25 17:08:21 +02:00"],
           col_array_json: ENV["SPANNER_EMULATOR_HOST"] ? [""] : \
                             [{ kind: "user_renamed", change: %w[jack john]}, nil, \
-                             { kind: "user_renamed", change: %w[alice meredith]}]
+                             { kind: "user_renamed", change: %w[alice meredith]},
+                             "{\"kind\":\"user_renamed\",\"change\":[\"bob\",\"carol\"]}"]
       end
 
       def test_create_record
@@ -69,20 +70,21 @@ module ActiveRecord
                        record.col_json unless ENV["SPANNER_EMULATOR_HOST"]
 
           assert_equal ["string1", nil, "string2"], record.col_array_string
-          assert_equal [100, nil, 200], record.col_array_int64
-          assert_equal [3.14, nil, 2.0/3.0], record.col_array_float64
-          assert_equal [6.626, nil, 3.20], record.col_array_numeric
-          assert_equal [true, nil, false], record.col_array_bool
+          assert_equal [100, nil, 200, 300], record.col_array_int64
+          assert_equal [3.14, nil, 2.0/3.0, 3.14], record.col_array_float64
+          assert_equal [6.626, nil, 3.20, 400], record.col_array_numeric
+          assert_equal [true, nil, false, false], record.col_array_bool
           assert_equal [StringIO.new("bytes1"), nil, StringIO.new("bytes2")].map { |bytes| bytes&.read },
                        record.col_array_bytes.map { |bytes| bytes&.read }
-          assert_equal [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24)], record.col_array_date
+          assert_equal [::Date.new(2021, 6, 23), nil, ::Date.new(2021, 6, 24), ::Date.new(2021, 06, 25)], record.col_array_date
           assert_equal [::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"), \
                             nil, \
-                            ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00")].map { |timestamp| timestamp&.utc },
+                            ::Time.new(2021, 6, 24, 17, 8, 21, "+02:00"), ::Time.new(2021, 6, 25, 17, 8, 21, "+02:00")].map { |timestamp| timestamp&.utc },
                        record.col_array_timestamp.map { |timestamp| timestamp&.utc}
           assert_equal [{"kind" => "user_renamed", "change" => %w[jack john]}, \
                         nil, \
-                        {"kind" => "user_renamed", "change" => %w[alice meredith]}],
+                        {"kind" => "user_renamed", "change" => %w[alice meredith]},
+                        {"kind" => "user_renamed", "change" => %w[bob carol]}],
                        record.col_array_json unless ENV["SPANNER_EMULATOR_HOST"]
         end
       end

data/examples/rails/README.md

@@ -99,7 +99,7 @@ If you are not familiar with Active Record, you can read more about it on [Ruby
 ### Use Cloud Spanner adapter in Gemfile
 1. Edit the Gemfile file of the `blog` app and add the `activerecord-spanner-adapter` gem:
     ```ruby
-    gem 'activerecord-spanner-adapter', git: 'https://github.com/googleapis/ruby-spanner-activerecord.git'
+    gem 'activerecord-spanner-adapter'
     ```
 1. Install gems:
 
@@ -142,17 +142,17 @@ Replace `[PROJECT_ID]` with the project id you are currently using.
 ### Create database
 
 You now can run the following command to create the database:
-    ```shell
-    ./bin/rails db:create
-    ```
-    You should see output like the following:
-    ```
-    Created database 'blog_dev'
-    ```
+
+```shell
+./bin/rails db:create
+```
+    
+You should see output like the following: `Created database 'blog_dev'`
+    
 ### Generate a Model and apply the migration
 1. Use the model generato to define a model:
     ```shell
-    bin/rails generate model Article title:string body:text
+    ./bin/rails generate model Article title:string body:text
     ```
 1. Apply the migration:
     ```shell

data/examples/snippets/generated-column/db/schema.rb

@@ -2,8 +2,8 @@
 # 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 `rails
-# db:schema:load`. When creating a new database, `rails db:schema:load` tends to
+# 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.
@@ -12,7 +12,7 @@
 
 ActiveRecord::Schema.define(version: 1) do
 
-  create_table "singers", force: :cascade do |t|
+  create_table "singers", id: { limit: 8 }, force: :cascade do |t|
     t.string "first_name", limit: 100
     t.string "last_name", limit: 200, null: false
     t.string "full_name", limit: 300, null: false

data/examples/snippets/hints/README.md

@@ -0,0 +1,19 @@
+# Sample - Query Hints
+
+This example shows how to use query hints Spanner ActiveRecord adapter. Statement hints and
+table hints can be specified using the optimizer_hints method. Join hints must be specified
+in a join string.
+
+See https://cloud.google.com/spanner/docs/query-syntax#sql_syntax for more information on
+the supported query hints.
+
+## 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 → hints}/Rakefile

@@ -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 generated columns in ActiveRecord."
 task :run do
-  Dir.chdir("..") { sh "bundle exec rake run[interleaved-tables]" }
+  Dir.chdir("..") { sh "bundle exec rake run[hints]" }
 end

data/examples/snippets/hints/application.rb

@@ -0,0 +1,47 @@
+# Copyright 2021 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"
+
+class Application
+  def self.run
+    puts ""
+    puts "Listing all singers using additional parallelism:"
+    # A statement hint must be prefixed with 'statement_hint:'
+    Singer.optimizer_hints("statement_hint: @{USE_ADDITIONAL_PARALLELISM=TRUE}")
+          .order("last_name, first_name").each do |singer|
+      puts singer.full_name
+    end
+
+    puts ""
+    puts "Listing all singers using the index on full_name:"
+    # All table hints must be prefixed with 'table_hint:'.
+    # Queries may contain multiple table hints.
+    Singer.optimizer_hints("table_hint: singers@{FORCE_INDEX=index_singers_on_full_name}")
+          .order("full_name").each do |singer|
+      puts singer.full_name
+    end
+
+    puts ""
+    puts "Listing all singers with at least one album that starts with 'blue':"
+    # Join hints cannot be specified using an optimizer_hint. Instead, the join can
+    # be specified using a string that includes the join hint.
+    Singer.joins("INNER JOIN @{JOIN_METHOD=HASH_JOIN} albums " \
+                 "on singers.id=albums.singer_id AND albums.title LIKE 'blue%'")
+          .distinct.order("last_name, first_name").each do |singer|
+      puts singer.full_name
+    end
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/hints/db/migrate/01_create_tables.rb

@@ -0,0 +1,23 @@
+# Copyright 2021 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
+    connection.ddl_batch do
+      create_table :singers do |t|
+        t.string :first_name, limit: 100
+        t.string :last_name, limit: 200, null: false
+        t.string :full_name, limit: 300, null: false, as: "COALESCE(first_name || ' ', '') || last_name", stored: true
+        t.index [:full_name], name: "index_singers_on_full_name"
+      end
+
+      create_table :albums do |t|
+        t.string :title
+        t.references :singer, index: false, foreign_key: true
+      end
+    end
+  end
+end

data/examples/snippets/{interleaved-tables → hints}/db/schema.rb

@@ -2,8 +2,8 @@
 # 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 `rails
-# db:schema:load`. When creating a new database, `rails db:schema:load` tends to
+# 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.
@@ -12,21 +12,17 @@
 
 ActiveRecord::Schema.define(version: 1) do
 
-  create_table "albums", primary_key: "albumid", force: :cascade do |t|
-    t.integer "singerid", limit: 8, null: false
+  create_table "albums", id: { limit: 8 }, force: :cascade do |t|
     t.string "title"
+    t.integer "singer_id", limit: 8
   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"
+  create_table "singers", id: { limit: 8 }, force: :cascade do |t|
+    t.string "first_name", limit: 100
+    t.string "last_name", limit: 200, null: false
+    t.string "full_name", limit: 300, null: false
+    t.index ["full_name"], name: "index_singers_on_full_name", order: { full_name: :asc }
   end
 
+  add_foreign_key "albums", "singers"
 end

data/examples/snippets/{interleaved-tables → hints}/db/seeds.rb

@@ -7,7 +7,6 @@
 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]
@@ -15,11 +14,6 @@ last_names = %w[Wendelson Allison Peterson Johnson Henderson Ericsson Aronson Te
 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 = []
@@ -32,9 +26,4 @@ ActiveRecord::Base.transaction isolation: :buffered_mutations 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/hints/models/album.rb

@@ -0,0 +1,9 @@
+# Copyright 2021 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 Album < ActiveRecord::Base
+  belongs_to :singer
+end

data/examples/snippets/hints/models/singer.rb

@@ -0,0 +1,9 @@
+# Copyright 2021 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
+  has_many :albums
+end