activerecord-spanner-adapter 0.3.0 → 1.0.0

data/benchmarks/db/migrate/01_create_tables.rb

@@ -0,0 +1,25 @@
+# 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, null: false, limit: 200
+        t.string :full_name, null: false, limit: 300, as: "COALESCE(first_name || ' ', '') || last_name", stored: true
+        t.date :birth_date
+        t.binary :picture
+      end
+
+      create_table :albums do |t|
+        t.string :title
+        t.date :release_date
+        t.references :singer, index: false
+      end
+    end
+  end
+end

data/benchmarks/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.date "release_date"
+    t.integer "singer_id", limit: 8
+  end
+
+  create_table "singers", 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.date "birth_date"
+    t.binary "picture"
+  end
+
+end

data/benchmarks/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/benchmarks/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/bin/console

@@ -1,14 +1,13 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "activerecord/spanner/adapter"
+require "activerecord-spanner-adapter"
+
+require "active_record"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)
+require "pry"
+require "pry-byebug" # For easy debugging
+Pry.start

data/examples/rails/README.md

@@ -0,0 +1,262 @@
+## activerecord-spanner-adapter for Rails tutorial
+
+This example shows how to use activerecord-spanner-adapter for Cloud Spanner as a backend database for [Rails's tutorials](https://guides.rubyonrails.org/getting_started.html).
+
+### Create a Spanner instance
+This step will create a Cloud Spanner instance. Cloud Spanner is a billable component of the Google Cloud. For information on the cost of using Cloud Spanner, see [Pricing](https://cloud.google.com/spanner/pricing).
+
+__Note__: If you want to try the tutorial without Cloud Spanner cost, you can use the emulator. Read the [doc](https://cloud.google.com/spanner/docs/emulator) for more details.
+
+1. Set the project environment variable:
+    ```shell
+    export PROJECT_ID=[your-cloud-project-id]
+    ```
+1. Set the default project:
+    ```shell
+    gcloud config set project $PROJECT_ID
+    ```
+1. If you haven't enabled the Cloud Spanner service, enable it:
+    ```shell
+    gcloud services enable spanner.googleapis.com
+    ```
+1. Create an instance. This tutorial will use a one-node instance in `regional-us-central1`.
+You can choose a region close to you:
+    ```shell
+    gcloud spanner instances create test-instance --config=regional-us-central1 \
+      --description="Rails Demo Instance" --nodes=1
+    ```
+1. Verify the instance has been created:
+    ```shell
+    gcloud spanner instances list
+    ```
+    You should see output like the following:
+    ```
+    NAME           DISPLAY_NAME         CONFIG                NODE_COUNT  STATE
+    test-instance  Rails Demo Instance  regional-us-central1  1           READY
+    ```
+1. Set the default instance:
+    ```shell
+    gcloud config set spanner/instance test-instance
+    ```
+
+Read the [Cloud Spanner setup guide](https://cloud.google.com/spanner/docs/getting-started/set-up) for more details.
+
+### Create a Rails project
+
+If you don't have Ruby and Rails installed, please follow the steps in the following links to install them:
+
+- [Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/)
+- [Installing Rails](https://guides.rubyonrails.org/getting_started.html#creating-a-new-rails-project-installing-rails)
+
+If you are not familiar with Active Record, you can read more about it on [Ruby on Rails Guides](https://guides.rubyonrails.org/)
+
+1. Verify the Ruby and Rails versions:
+    ```shell
+    ruby --version
+    rails --version
+    ```
+    The versions should be Ruby 2.6 or higher and Rails 6.0 or higher.
+1. Create a new Rails project:
+
+    ```shell
+    rails new blog
+    ```
+1. The `blog` directory will have a number of generated files and folders that make up the structure of a Rails application. You can list them:
+    ```shell
+    cd blog
+    ls -l
+    ```
+1. Starting up the web server and make sure the sample application works:
+    ```shell
+    bin/rails server
+    ```
+    After the server starts, open your browser and navigate to [http://localhost:3000](http://localhost:3000). You should see the default Rails page with the sentence: __Yay! You're on Rails!__
+
+### Create a service account
+
+1. Create a service account:
+    ```shell
+    gcloud iam service-accounts create activerecord-spanner
+    ```
+1. Grant an IAM role to access Cloud Spanner:
+    ```shell
+    gcloud projects add-iam-policy-binding ${PROJECT_ID} \
+    --member="serviceAccount:activerecord-spanner@${PROJECT_ID}.iam.gserviceaccount.com" \
+    --role="roles/spanner.databaseAdmin"
+    ```
+    Here the role `roles/spanner.databaseAdmin` is granted to the service account. If you want to restrict the permissions further, you can choose to create a custom role with proper permissions.
+1. Create a key file and download it:
+    ```shell
+    gcloud iam service-accounts keys create activerecord-spanner-key.json \
+    --iam-account=activerecord-spanner@${PROJECT_ID}.iam.gserviceaccount.com
+    ```
+    This tutorial uses the key file to access Cloud Spanner. If you are using services such as Compute Engine, Cloud Run, or Cloud Functions, you can associate the service account to the instance and avoid using the key file.
+1. From the previous step, a key file should be created and downloaded. You can run the following command to view its content:
+    ```shell
+    cat activerecord-spanner-key.json
+    ```
+
+### 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'
+    ```
+1. Install gems:
+
+    ```shell
+    bundle install
+    ```
+
+### Update database.yml to use Cloud Spanner.
+After the Cloud Spanner instance is running, you'll need a few variables:
+* Cloud project id
+* Cloud Spanner instance id, such as `test-instance`
+* Database name, such as `blog_dev`
+* Credential: Credential key file path or export `GOOGLE_CLOUD_KEYFILE`environment variable.
+
+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: test-instance
+  credentials: activerecord-spanner-key.json
+
+development:
+  <<: *default
+  database: blog_dev
+
+test:
+  <<: *default
+  database: blog_test
+
+production:
+  <<: *default
+  database: blog
+```
+
+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'
+    ```
+### 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
+    ```
+1. Apply the migration:
+    ```shell
+    ./bin/rails db:migrate
+    ```
+    The command takes a while to complete. When it's done, you will have an output like the following:
+    ```
+    $ ./bin/rails db:migrate
+    == 20210803025742 CreateArticles: migrating ===================================
+    -- create_table(:articles)
+      -> 23.5728s
+    == 20210803025742 CreateArticles: migrated (23.5729s) =========================
+    ```
+
+### Use the CLI to interact with the database
+1. Run the following command to start `irb`:
+    ```shell
+    bin/rails console
+    ```
+1. At the prompt, initialize a new `Article` object:
+    ```ruby
+    article = Article.new(title: "Hello Rails", body: "I am on Rails!")
+    ```
+1. Run the following command to save the object to the database:
+    ```ruby
+    article.save
+    ```
+1. Review the object and you can see the field `id`, `created_at`, and `updated_at` have been set:
+    ```ruby
+    article
+    ```
+    Sample output:
+    ```
+    => #<Article id: 4170057092403543076, title: "Hello Rails", body: "I am on Rails!", created_at: "2021-08-03 03:06:26.096275000 +0000", updated_at: "2021-08-03 03:06:26.096275000 +0000">
+    ```
+1. You can find `Article.find(id)` or `Article.all` to fetch data from the database. For example:
+    ```ruby
+    irb(main):007:0> Article.find(4170057092403543076)
+    Article Load (49.2ms)  SELECT `articles`.* FROM `articles` WHERE `articles`.`id` = @p1 LIMIT @p2
+    => #<Article id: 4170057092403543076, title: "Hello Rails", body: "I am on Rails!", created_at: "2021-08-03 03:06:26.096275000 +0000", updated_at: "2021-08-03 03:06:26.096275000 +0000">
+
+    irb(main):008:0> Article.all
+    Article Load (73.9ms)  SELECT `articles`.* FROM `articles` /* loading for inspect */ LIMIT @p1
+    => #<ActiveRecord::Relation [#<Article id: 4170057092403543076, title: "Hello Rails", body: "I am on Rails!", created_at: "2021-08-03 03:06:26.096275000 +0000", updated_at: "2021-08-03 03:06:26.096275000 +0000">]>
+    ```
+
+### Update the app to show a list of records
+1. Use the controller generator to create a controller:
+    ```shell
+    bin/rails generate controller Articles index
+    ```
+1. Open the file `app/controllers/articles_controller.rb`, and change the `index` action to fetch all articles from the database:
+    ```ruby
+    class ArticlesController < ApplicationController
+      def index
+        @articles = Article.all
+      end
+    end
+    ```
+1. Open `app/views/articles/index.html.erb`, and update the file as the following:
+    ```html
+    <h1>Articles</h1>
+    <ul>
+      <% @articles.each do |article| %>
+        <li>
+          <%= article.title %>
+        </li>
+      <% end %>
+    </ul>
+    ```
+1. Run your server again
+    ```shell
+    ./bin/rails s
+    ```
+1. In your browser, navigate to the URL [http://localhost:3000/articles/index](http://localhost:3000/articles/index). And you will see the `Hello Rails` record you entered previously.
+1. [Optional] you can follow the rest of the steps in the [Getting Started with Rails](https://guides.rubyonrails.org/getting_started.html) guide.
+
+### Clean up
+
+To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, you can delete the resources you created. You can either 
+delete the entire project or delete individual resources.
+
+Deleting a project has the following effects:
+
+* Everything in the project is deleted. If you used an existing project for this tutorial, when you delete it, you also delete any other work you've done in the
+  project.
+* Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs
+  that use the project ID, delete selected resources inside the project instead of deleting the whole project.
+
+If you plan to explore multiple tutorials, reusing projects can help you to avoid exceeding project quota limits.
+
+#### Delete the project
+
+The easiest way to eliminate billing is to delete the project you created for the tutorial. 
+
+1.  In the Cloud Console, go to the [**Manage resources** page](https://console.cloud.google.com/iam-admin/projects).  
+1.  In the project list, select the project that you want to delete and then click **Delete**.
+1.  In the dialog, type the project ID and then click **Shut down** to delete the project.
+
+#### Delete the resources
+
+If you don't want to delete the project, you can delete the provisioned resources:
+
+    gcloud iam service-accounts delete \
+    activerecord-spanner@${PROJECT_ID}.iam.gserviceaccount.com
+
+    gcloud spanner instances delete test-instance

data/examples/snippets/README.md

@@ -0,0 +1,29 @@
+# Sample snippets
+
+This directory contains a number of simple standalone samples that show how to use ActiveRecord with Cloud Spanner.
+
+### Running from this directory
+The samples can be executed using the following command in this directory:
+
+```bash
+bundle exec rake run\[<sample_name>\]
+```
+
+Example:
+
+```bash
+bundle exec rake run\[quickstart\]
+```
+
+The available samples can be listed using the command
+
+```bash
+bundle exec rake list
+```
+
+### Running from sample directory
+You can also run a sample by calling the following command __in the directory of the sample__:
+
+```bash
+bundle exec rake run
+```

data/examples/snippets/Rakefile

@@ -0,0 +1,57 @@
+# 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 "docker"
+
+desc "Lists all available samples."
+task :list do
+  samples = Dir.entries(".").select do |entry|
+    File.directory?(File.join(".", entry)) \
+     && !%w[. ..].include?(entry) \
+     && File.exist?(File.join(".", entry, "application.rb"))
+  end
+  puts "Available samples: "
+  samples.sort.each { |dir| puts "  #{dir}" }
+  puts ""
+  puts "Run a sample with the command `bundle exec rake run\\[<sample-name>\\]`"
+end
+
+desc "Runs a simple ActiveRecord tutorial on a Spanner emulator."
+task :run, [:sample] do |_t, args|
+  sample = args[:sample]
+  unless sample
+    puts "Missing argument :sample. Running quickstart sample"
+    puts ""
+    sample = "quickstart"
+  end
+
+  puts "Downloading Spanner emulator image..."
+  Docker::Image.create "fromImage" => "gcr.io/cloud-spanner-emulator/emulator:latest"
+  puts "Creating Spanner emulator container..."
+  container = Docker::Container.create(
+    "Image" => "gcr.io/cloud-spanner-emulator/emulator:latest",
+    "ExposedPorts" => { "9010/tcp" => {} },
+    "HostConfig" => {
+      "PortBindings" => {
+        "9010/tcp" => [{ "HostPort" => "9010" }]
+      }
+    }
+  )
+
+  begin
+    puts "Starting Spanner emulator..."
+    container.start!
+    Dir.chdir sample do
+      sh "ruby ../bin/create_emulator_instance.rb"
+      sh "rake db:migrate"
+      sh "rake db:seed"
+      sh "ruby application.rb"
+    end
+  ensure
+    container.stop!
+  end
+end

data/examples/snippets/array-data-type/README.md

@@ -0,0 +1,45 @@
+# Sample - Array Data Type
+
+This example shows how to use the `ARRAY` data type with the Spanner ActiveRecord adapter. The sample uses a single
+table that has one column for each possible `ARRAY` data type:
+
+```sql
+CREATE TABLE entity_with_array_types (
+    id INT64 NOT NULL,
+    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>,
+) PRIMARY KEY (id);
+```
+
+This schema is created in ActiveRecord as follows:
+
+```ruby
+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
+```
+
+## 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/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!