activerecord-spanner-adapter 0.3.0 → 0.5.0

data/examples/snippets/array-data-type/Rakefile

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

data/examples/snippets/array-data-type/application.rb

@@ -0,0 +1,45 @@
+# 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/entity_with_array_types"
+
+class Application
+  def self.run # rubocop:disable Metrics/AbcSize
+    # Create a record with all array types.
+    record = EntityWithArrayTypes.create \
+      col_array_string: ["value1", "value2", "value3"],
+      col_array_int64: [100, 200, 300],
+      col_array_float64: [3.14, 2.0 / 3.0],
+      col_array_numeric: [6.626, 3.20],
+      # All arrays can contain null elements.
+      col_array_bool: [true, false, nil, true],
+      col_array_bytes: [StringIO.new("value1"), StringIO.new("value2")],
+      col_array_date: [::Date.new(2021, 6, 23), ::Date.new(2021, 6, 28)],
+      # Timestamps can be specified in any timezone, but Cloud Spanner will always convert and store them in UTC.
+      col_array_timestamp: [::Time.new(2021, 6, 23, 17, 8, 21, "+02:00"), ::Time.utc(2021, 6, 23, 17, 8, 21)]
+
+    # Reload the record from Cloud Spanner and print out the values.
+    record = record.reload
+    puts ""
+    puts "Saved record #{record.id} with array values: "
+    puts "String array: #{record.col_array_string}"
+    puts "Int64 array: #{record.col_array_int64}"
+    puts "Float64 array: #{record.col_array_float64}"
+    puts "Numeric array: #{record.col_array_numeric}"
+    puts "Bool array: #{record.col_array_bool}"
+    puts "Bytes array: #{record.col_array_bytes.map(&:read)}"
+    puts "Date array: #{record.col_array_date}"
+    puts "Timestamp array: #{record.col_array_timestamp}"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/array-data-type/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/array-data-type/db/migrate/01_create_tables.rb

@@ -0,0 +1,24 @@
+# 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
+    # Execute the entire migration as one DDL batch.
+    connection.ddl_batch do
+      create_table :entity_with_array_types do |t|
+        # Create a table with a column with each possible array type.
+        t.column :col_array_string, :string, array: true
+        t.column :col_array_int64, :bigint, array: true
+        t.column :col_array_float64, :float, array: true
+        t.column :col_array_numeric, :numeric, array: true
+        t.column :col_array_bool, :boolean, array: true
+        t.column :col_array_bytes, :binary, array: true
+        t.column :col_array_date, :date, array: true
+        t.column :col_array_timestamp, :datetime, array: true
+      end
+    end
+  end
+end

data/examples/snippets/array-data-type/db/schema.rb

@@ -0,0 +1,26 @@
+# 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 `rails
+# db:schema:load`. When creating a new database, `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
+
+  create_table "entity_with_array_types", force: :cascade do |t|
+    t.string "col_array_string"
+    t.integer "col_array_int64", limit: 8
+    t.float "col_array_float64"
+    t.decimal "col_array_numeric"
+    t.boolean "col_array_bool"
+    t.binary "col_array_bytes"
+    t.date "col_array_date"
+    t.time "col_array_timestamp"
+  end
+
+end

data/examples/snippets/array-data-type/db/seeds.rb

@@ -0,0 +1,5 @@
+# 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.

data/examples/snippets/array-data-type/models/entity_with_array_types.rb

@@ -0,0 +1,18 @@
+# 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 EntityWithArrayTypes < ActiveRecord::Base
+  # This entity has one attribute for each possible ARRAY data type in Cloud Spanner.
+  # 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>
+  #
+end

data/examples/snippets/bin/create_emulator_instance.rb

@@ -0,0 +1,18 @@
+# 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 "google/cloud/spanner"
+
+spanner = Google::Cloud::Spanner.new project: "test-project", emulator_host: "localhost:9010"
+job = spanner.create_instance "test-instance",
+                              name: "Test Instance",
+                              config: "emulator-config",
+                              nodes: 1
+job.wait_until_done!
+
+instance = spanner.instance "test-instance"
+job = instance.create_database "testdb", statements: []
+job.wait_until_done!

data/examples/snippets/bulk-insert/README.md

@@ -0,0 +1,21 @@
+# Sample - Bulk Insert
+
+It is important to use the correct strategy when bulk creating new records in Spanner using ActiveRecord.
+ActiveRecord will by default create a separate insert statement for each entity that you create. The Spanner
+ActiveRecord adapter is able to translate this into a set of insert Mutations instead of a list of insert DML
+statements, which will execute a lot faster.
+
+There are two ways to achieve this:
+1. Create a batch of entities without an explicit transaction.
+2. Use a read/write transaction with isolation level `:buffered_mutations`
+
+See also the `Mutations` sample in this repository.
+
+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/bulk-insert/Rakefile

@@ -0,0 +1,13 @@
+# 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_relative "../config/environment"
+require "sinatra/activerecord/rake"
+
+desc "Sample showing how to best bulk insert new records in Spanner using ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[bulk-insert]" }
+end

data/examples/snippets/bulk-insert/application.rb

@@ -0,0 +1,64 @@
+# 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 # rubocop:disable Metrics/AbcSize
+    # Creating multiple records without an explicit transaction will automatically save all the records using
+    # one Spanner transaction and return the ids of the created records. The implicit transaction that is created
+    # by the Spanner ActiveRecord adapter will automatically use Mutations for the bulk insert. This is a lot more
+    # efficient than a list of DML statements.
+    singers = Singer.create [
+      { first_name: "Alice", last_name: "Wendelson" },
+      { first_name: "Nick", last_name: "Rainbow" },
+      { first_name: "Elena", last_name: "Quick" }
+    ]
+    puts ""
+    puts "Created a batch of #{singers.length} singers using an implicit transaction:"
+    singers.each do |s|
+      puts "  Created singer #{s.first_name} #{s.last_name} with id #{s.id}"
+    end
+
+    # If you need to create multiple records of different types, you can use an explicit transaction with isolation
+    # level `:buffered_mutations`. This Spanner-specific isolation level will instruct the read/write transaction to
+    # use Mutations instead of DML.
+    singers = nil
+    albums = nil
+    ActiveRecord::Base.transaction isolation: :buffered_mutations do
+      singers = Singer.create [
+        { first_name: "Boris", last_name: "Carelia" },
+        { first_name: "Yvonne", last_name: "McKenzie" },
+        { first_name: "Wendy", last_name: "Bravo" }
+      ]
+      albums = Album.create [
+        { title: "Hot Potatoes", singer: singers[0] },
+        { title: "Lazy Street", singer: singers[0] },
+        { title: "Daily Glass", singer: singers[1] },
+        { title: "Happy Windows", singer: singers[2] },
+        { title: "Generous Street", singer: singers[2] }
+      ]
+    end
+    puts ""
+    puts "Created a batch of #{singers.length} singers and #{albums.length} "\
+         "albums using a transaction with buffered mutations:"
+    singers.each do |s|
+      puts "  Created singer #{s.first_name} #{s.last_name} with id #{s.id}"
+      s.albums.each do |a|
+        puts "    with album #{a.title} with id #{a.id}"
+      end
+    end
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/bulk-insert/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/bulk-insert/db/migrate/01_create_tables.rb

@@ -0,0 +1,21 @@
+# 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
+        t.string :last_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/bulk-insert/db/schema.rb

@@ -0,0 +1,26 @@
+# 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 `rails
+# db:schema:load`. When creating a new database, `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
+
+  create_table "albums", force: :cascade do |t|
+    t.string "title"
+    t.integer "singer_id", limit: 8
+  end
+
+  create_table "singers", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+  end
+
+  add_foreign_key "albums", "singers"
+end

data/examples/snippets/bulk-insert/db/seeds.rb

@@ -0,0 +1,5 @@
+# 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.

data/examples/snippets/bulk-insert/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/bulk-insert/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

data/examples/snippets/commit-timestamp/README.md

@@ -0,0 +1,18 @@
+# Sample - Commit Timestamps
+
+This example shows how to set an attribute to the [commit timestamp of a transaction](https://cloud.google.com/spanner/docs/commit-timestamp)
+using the Spanner ActiveRecord adapter. Setting the commit timestamp is different from the built-in
+`created_at`/`updated_at` [feature](https://guides.rubyonrails.org/active_record_basics.html#schema-conventions) of
+ActiveRecord. A `created_at`/`updated_at` column that is managed by ActiveRecord will be set to the date/time of the
+__client__ when the record is created/updated. The commit timestamp of a transaction is generated by Cloud Spanner and
+is set by the server when the transaction is committed. All records that are created or updated in the same transaction
+will be assigned the exact same commit timestamp.
+
+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/commit-timestamp/Rakefile

@@ -0,0 +1,13 @@
+# 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_relative "../config/environment"
+require "sinatra/activerecord/rake"
+
+desc "Sample showing how to fill a commit timestamp column in Spanner with ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[commit-timestamp]" }
+end

data/examples/snippets/commit-timestamp/application.rb

@@ -0,0 +1,53 @@
+# 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 # rubocop:disable Metrics/AbcSize
+    format = "%Y-%m-%dT%k:%M:%S.%N"
+    singer = nil
+    album = nil
+    ActiveRecord::Base.transaction do
+      # Create a singer and album with a commit timestamp that is set by Cloud Spanner.
+      # Use the `:commit_timestamp` symbol to instruct the Spanner ActiveRecord adapter to update the attribute to the
+      # commit timestamp of the transaction. Note that the value is not readable before the transaction has been
+      # committed. The commit timestamp of the following two records will be equal, as they are created in the same
+      # transaction.
+      singer = Singer.create first_name: "Pete", last_name: "Allison", last_updated: :commit_timestamp
+      album = singer.albums.create title: "Dear Repayment", last_updated: :commit_timestamp
+    end
+    # Reload the records to get the actual commit timestamp values.
+    singer.reload
+    album.reload
+
+    puts ""
+    puts "Singer and album created:"
+    puts "#{singer.first_name} #{singer.last_name} (Last updated: #{singer.last_updated.strftime format})"
+    puts "   #{album.title} (Last updated: #{album.last_updated.strftime format})"
+
+    # The commit timestamp can also be set in an implicit transaction. Note that the following two statements will
+    # create two separate (implicit) transactions, and the commit timestamps of the two records will now be slightly
+    # different.
+    singer.update last_updated: :commit_timestamp
+    album.update last_updated: :commit_timestamp
+    singer.reload
+    album.reload
+    puts ""
+    puts "Singer and album updated:"
+    puts "#{singer.first_name} #{singer.last_name} (Last updated: #{singer.last_updated.strftime format})"
+    puts "   #{album.title} (Last updated: #{album.last_updated.strftime format})"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run