activerecord-spanner-adapter 0.3.0 → 1.0.0

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

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

@@ -0,0 +1,26 @@
+# 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
+        # Create a `last_updated` column that supports server side commit timestamps.
+        t.datetime :last_updated, allow_commit_timestamp: true
+      end
+
+      create_table :albums do |t|
+        t.string :title
+        t.numeric :marketing_budget
+        t.references :singer, index: false, foreign_key: true
+        # Create a `last_updated` column that supports server side commit timestamps.
+        t.datetime :last_updated, allow_commit_timestamp: true
+      end
+    end
+  end
+end

data/examples/snippets/commit-timestamp/db/schema.rb

@@ -0,0 +1,29 @@
+# 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.decimal "marketing_budget"
+    t.integer "singer_id", limit: 8
+    t.time "last_updated"
+  end
+
+  create_table "singers", force: :cascade do |t|
+    t.string "first_name"
+    t.string "last_name"
+    t.time "last_updated"
+  end
+
+  add_foreign_key "albums", "singers"
+end

data/examples/snippets/commit-timestamp/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/commit-timestamp/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/commit-timestamp/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/config/environment.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.
+
+require "active_record"
+require "bundler"
+
+Dir["../../lib/*.rb"].each { |file| require file }
+
+Bundler.require
+
+ActiveRecord::Base.establish_connection(
+  adapter: "spanner",
+  emulator_host: "localhost:9010",
+  project: "test-project",
+  instance: "test-instance",
+  database: "testdb"
+)
+ActiveRecord::Base.logger = nil

data/examples/snippets/create-records/README.md

@@ -0,0 +1,12 @@
+# Sample - Create Records
+
+This sample shows how to create and save entities using ActiveRecord.
+
+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/create-records/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 create one or more records in Spanner using ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[create-records]" }
+end

data/examples/snippets/create-records/application.rb

@@ -0,0 +1,42 @@
+# 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
+    # Creating a single record without an explicit transaction will automatically save it to the database.
+    # It is not recommended to call Entity.create repeatedly to insert multiple records, as each call will
+    # use a separate Spanner transaction. Instead multiple records should be created by passing an array of
+    # entities to the Entity.create method.
+    singer = Singer.create first_name: "Dave", last_name: "Allison"
+    puts ""
+    puts "Created singer #{singer.first_name} #{singer.last_name} with id #{singer.id}"
+    puts ""
+
+    # 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. This is the recommended way to create
+    # a batch of entities.
+    singers = Singer.create [
+      { first_name: "Alice", last_name: "Wendelson" },
+      { first_name: "Nick", last_name: "Rainbow" },
+      { first_name: "Elena", last_name: "Quick" }
+    ]
+    puts "Created a batch of #{singers.length} singers:"
+    singers.each do |s|
+      puts "  Created singer #{s.first_name} #{s.last_name} with id #{s.id}"
+    end
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/create-records/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/create-records/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/create-records/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/create-records/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/create-records/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/create-records/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/date-data-type/README.md

@@ -0,0 +1,19 @@
+# Sample - Date Data Type
+
+This example shows how to use the `DATE` data type with the Spanner ActiveRecord adapter. A `DATE` is a
+timezone-independent date. It does not designate a specific point in time, such as UTC midnight of the date.
+If you create a timezone-specific date/time object in Ruby and assign it to a `DATE` attribute, all time and timezone
+information will be lost after saving and reloading the object.
+
+Use the `TIMESTAMP` data type for attributes that represent a specific point in time.
+
+## 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/date-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 the DATE data type in ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[date-data-type]" }
+end

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

@@ -0,0 +1,35 @@
+# 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"
+
+class Application
+  def self.run
+    # Get all singers order by birthdate
+    puts ""
+    puts "Listing all singers order by birth date:"
+    Singer.all.order(:birth_date).each do |singer|
+      puts "#{"#{singer.first_name} #{singer.last_name}".ljust 30}#{singer.birth_date}"
+    end
+
+    # Update the birth date of a random singer using the current system time. Any time and timezone information will be
+    # lost after saving the record as a DATE only contains the year, month and day-of-month information.
+    singer = Singer.all.sample
+    singer.update birth_date: Time.now
+    singer.reload
+    puts ""
+    puts "Updated birth date to current system time:"
+    puts "#{"#{singer.first_name} #{singer.last_name}".ljust 30}#{singer.birth_date}"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

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

@@ -0,0 +1,20 @@
+# 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
+        # A date in Cloud Spanner represents a timezone independent date. It does not designate a specific point in
+        # time, such as for example midnight UTC of the specified date.
+        # See https://cloud.google.com/spanner/docs/data-definition-language#data_types for more information.
+        t.date   :birth_date
+      end
+    end
+  end
+end