activerecord-spanner-adapter 0.3.0 → 1.0.0

data/examples/snippets/stale-reads/db/seeds.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.
+
+require_relative "../../config/environment.rb"
+require_relative "../models/singer"
+require_relative "../models/album"
+
+first_names = ["Pete", "Alice", "John", "Ethel", "Trudy", "Naomi", "Wendy", "Ruben", "Thomas", "Elly"]
+last_names = ["Wendelson", "Allison", "Peterson", "Johnson", "Henderson", "Ericsson", "Aronson", "Tennet", "Courtou"]
+
+adjectives = ["daily", "happy", "blue", "generous", "cooked", "bad", "open"]
+nouns = ["windows", "potatoes", "bank", "street", "tree", "glass", "bottle"]
+
+5.times do
+  Singer.create first_name: first_names.sample, last_name: last_names.sample
+end
+
+20.times do
+  singer_id = Singer.all.sample.id
+  Album.create title: "#{adjectives.sample} #{nouns.sample}", singer_id: singer_id
+end

data/examples/snippets/stale-reads/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/stale-reads/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/timestamp-data-type/README.md

@@ -0,0 +1,17 @@
+# Sample - Timestamp Data Type
+
+This example shows how to use the `TIMESTAMP` data type with the Spanner ActiveRecord adapter. A `TIMESTAMP` represents
+a specific point in time. Cloud Spanner always stores the timestamp in UTC, and it is not possible to include a
+specific timezone in a timestamp value in Cloud Spanner. Instead, a separate column containing a timezone can be used
+if your application needs to store both a timestamp and a timezone. This sample shows how to do this.
+
+## 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/timestamp-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 TIMESTAMP data type in ActiveRecord."
+task :run do
+  Dir.chdir("..") { sh "bundle exec rake run[timestamp-data-type]" }
+end

data/examples/snippets/timestamp-data-type/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/meeting"
+
+class Application
+  def self.run
+    # Set the default local timezone.
+    Time.zone = "Europe/Lisbon"
+
+    # Create a meeting using the local timezone. The timezone information will not be stored in the `meeting_time`
+    # column in the database, which is why we also include a separate column where we can store the timezone name.
+    meeting_time = Time.zone.local 2021, 7, 1, 10, 30, 0
+    meeting = Meeting.create title: "Standup", meeting_time: meeting_time, meeting_timezone: Time.zone.name
+
+    # The meeting_time is saved in UTC in Cloud Spanner. Reloading it will therefore lose the timezone information in
+    # the meeting_time attribute. It is however stored in the separate meeting_timezone attribute, and that can be used
+    # to reconstruct the meeting_time in the timezone where the meeting was planned.
+    # The Meeting model class also contains two helper methods:
+    # 1. `local_meeting_time`: Returns the meeting_time in the local timezone.
+    # 2. `meeting_time_in_planned_zone`: Returns the meeting_time in the timezone where it is planned.
+    meeting.reload
+    puts ""
+    puts "#{'Meeting time in UTC:'.ljust 60} #{meeting.meeting_time}"
+    puts "#{'Meeting time in the timezone where it was planned:'.ljust 60} #{meeting.meeting_time_in_planned_zone}"
+
+    # Simulate that the application is now running in the timezone America/Los_Angeles.
+    Time.zone = "America/Los_Angeles"
+    puts "#{'Meeting time in the local timezone (America/Los_Angeles):'.ljust 60} #{meeting.local_meeting_time}"
+
+    puts ""
+    puts "Press any key to end the application"
+    STDIN.getch
+  end
+end
+
+Application.run

data/examples/snippets/timestamp-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/timestamp-data-type/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 :meetings do |t|
+        t.string :title
+        # A `TIMESTAMP` column in Cloud Spanner contains a date/time value that designates a specific point in time. The
+        # value is always stored in UTC. If you specify a date/time value in a different timezone, the value is
+        # converted to UTC when saving it to the database. You can use a separate column to store the timezone of the
+        # timestamp if that is vital for your application, and use that information when the timestamp is read back.
+        t.datetime :meeting_time
+        t.string   :meeting_timezone
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# 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 "meetings", force: :cascade do |t|
+    t.string "title"
+    t.time "meeting_time"
+    t.string "meeting_timezone"
+  end
+
+end

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

@@ -0,0 +1,6 @@
+# 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/timestamp-data-type/models/meeting.rb

@@ -0,0 +1,19 @@
+# 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 Meeting < ActiveRecord::Base
+  # Returns the meeting time in the local timezone.
+  def local_meeting_time
+    return unless meeting_time && Time.zone
+    meeting_time.in_time_zone Time.zone
+  end
+
+  # Returns the time of the meeting in the timezone where the meeting is planned.
+  def meeting_time_in_planned_zone
+    return unless meeting_time && meeting_timezone
+    meeting_time.in_time_zone meeting_timezone
+  end
+end

data/examples/solidus/README.md

@@ -0,0 +1,172 @@
+## activerecord-spanner-adapter on Solidus
+
+This example shows how to use activerecord-spanner-adapter for Cloud Spanner as a backend database for https://solidus.io.
+
+#### Table of contents
+- [Ensure you have a Cloud Spanner database already created](#ensure-you-have-a-Cloud-Spanner-database-already-created)
+- [Create a Rails application and install Solidus](#create-a-rails-application-and-install-solidus)
+- [Update database.yml](#update-database.yml)
+- [Create application database](#create-application-database)
+- [Apply the migrations](#apply-the-migrations)
+- [Go view the results on Cloud Spanner UI](#go-view-the-results-on-Cloud-Spanner-UI)
+- [Run the application](#run-the-application)
+- [References](#references)
+
+### Ensure you have a Cloud Spanner database already created
+If you haven't already, please follow the steps to install [Cloud Spanner](https://cloud.google.com/spanner/docs/getting-started/set-up),
+or visit this [codelab](https://opencensus.io/codelabs/spanner/#0)
+
+**You'll need to ensure that your Google Application Default Credentials are properly downloaded and saved in your environment.**
+
+### Create a Rails application and install Solidus
+
+Create a Rails application.
+```shell
+rails new e-store
+cd e-store
+```
+Add `solidus` and  `activerecord-spanner-adapter` gem to Gemfile.
+
+Gemfile
+```ruby
+gem 'solidus'
+gem 'activerecord-spanner-adapter', git: 'https://github.com/orijtech/activerecord-spanner-adapter.git'
+```
+
+```shell
+bundle install
+```
+
+### Use Cloud Spanner adapter in Gemfile
+Edit Gemfile file and add `activerecord-spanner-adapter` gem.
+
+```ruby
+gem 'activerecord-spanner-adapter', git: 'https://github.com/orijtech/activerecord-spanner-adapter.git'
+```
+
+Install gems.
+
+```shell
+bundle install
+```
+
+After installing gems, you'll have to run the generator to create necessary configuration files and migrations.
+
+```shell
+bin/rails g spree:install
+```
+
+### Update database.yml
+
+Update `db/database.yml` to use `activerecord-spanner-adapter`
+
+After we have a Cloud Spanner database created, we'll need a few variables:
+* Project id
+* Instance id
+* Database name
+* Credential: Credential keyfile path or Export `GOOGLE_CLOUD_KEYFILE`environment variable.
+
+Once in, please edit the file `config/database.yml` and make the section `DATABASES` into the following:
+
+```yml
+default: &default
+  adapter: "spanner"
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 10 } %>
+  project: PROJECT_ID
+  instance: SPANNER_INSTANCE_ID
+  credentials: SPANNER_PROJECT_KEYFILE
+
+development:
+  <<: *default
+  database: e-store-dev
+
+test:
+  <<: *default
+  database: e-store-test
+
+production:
+  <<: *default
+  database: e-store
+```
+
+and for example here is a filled in database where:
+
+* `PROJECT_ID`: spanner-appdev
+* `SPANNER_INSTANCE_ID`: instance
+* `SPANNER_PROJECT_KEYFILE`:  credentials key file path. i.e "/app/keyfile.json".
+
+###  Create application database
+
+Please run:
+```shell
+$ ./bin/rails db:create
+```
+
+```shell
+Created database e-store-dev
+```
+
+### Apply the migrations
+Please run:
+```shell
+$ ./bin/rails db:migrate
+```
+
+and that'll take a while running, it will look like the following
+
+<details>
+
+```shell
+$ ./bin/rails db:migrate
+== 20200410055855 CreateActiveStorageTables: migrating ========================
+-- create_table(:active_storage_blobs, {})
+   -> 0.0011s
+-- create_table(:active_storage_attachments, {})
+   -> 0.0010s
+== 20200410055855 CreateActiveStorageTables: migrated (0.0023s) ===============
+
+..... MANY MORE MIGRATION LOG LINES
+```
+</details>
+
+### Go view the results on Cloud Spanner UI
+
+To double check that the respective tables and migrations were performed, please go visit the page with your database on Cloud Spanner's UI. For example it should look like this
+
+![](/assets/solidus-db.png)
+
+### Run the application
+After those migrations run application server.
+
+```shell
+./bin/rails s
+```
+<details>
+
+```
+./bin/rails s
+Puma starting in single mode...
+* Version 4.3.3 (ruby 2.6.3-p62), codename: Mysterious Traveller
+* Min threads: 5, max threads: 5
+* Environment: development
+* Listening on tcp://127.0.0.1:3000
+* Listening on tcp://[::1]:3000
+Use Ctrl-C to stop
+Started GET "/" for ::1 at 2020-04-10 11:42:00 +0530
+   (563.0ms)  SELECT `schema_migrations`.`version` FROM `schema_migrations` ORDER BY `schema_migrations`.`version` ASC
+Processing by Spree::HomeController#index as HTML
+  Spree::Store Load (507.9ms)  SELECT `spree_stores`.* FROM `spree_stores` WHERE (`spree_stores`.`url` = 'localhost' OR `spree_stores`.`default` = TRUE) ORDER BY `spree_stores`.`default` ASC LIMIT 1
+  Rendering /Users/jiren/work/spanner_orm/solidus/frontend/app/views/spree/home/index.html.erb within spree/layouts/spree_application
+  Spree::Taxonomy Load (571.6ms)  SELECT `spree_taxonomies`.* FROM `spree_taxonomies` ORDER BY `spree_taxonomies`.`position` ASC
+```
+
+</details>
+
+### References
+
+Resource|URL
+---|---
+Solidus application|https://solidus.io/
+Solidus application source code|https://github.com/solidusio/solidus
+Cloud Spanner homepage|https://cloud.google.com/spanner/
+activerecord-spanner-adapter project's source code|https://github.com/orijtech/activerecord-spanner-adapter