timescaledb 0.1.4 → 0.2.1

data/examples/ranking/Gemfile.lock

@@ -0,0 +1,189 @@
+PATH
+  remote: ../..
+  specs:
+    timescaledb (0.1.5)
+      activerecord
+      activesupport
+      pg (~> 1.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (7.0.2)
+      actionpack (= 7.0.2)
+      activesupport (= 7.0.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (7.0.2)
+      actionpack (= 7.0.2)
+      activejob (= 7.0.2)
+      activerecord (= 7.0.2)
+      activestorage (= 7.0.2)
+      activesupport (= 7.0.2)
+      mail (>= 2.7.1)
+      net-imap
+      net-pop
+      net-smtp
+    actionmailer (7.0.2)
+      actionpack (= 7.0.2)
+      actionview (= 7.0.2)
+      activejob (= 7.0.2)
+      activesupport (= 7.0.2)
+      mail (~> 2.5, >= 2.5.4)
+      net-imap
+      net-pop
+      net-smtp
+      rails-dom-testing (~> 2.0)
+    actionpack (7.0.2)
+      actionview (= 7.0.2)
+      activesupport (= 7.0.2)
+      rack (~> 2.0, >= 2.2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (7.0.2)
+      actionpack (= 7.0.2)
+      activerecord (= 7.0.2)
+      activestorage (= 7.0.2)
+      activesupport (= 7.0.2)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (7.0.2)
+      activesupport (= 7.0.2)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (7.0.2)
+      activesupport (= 7.0.2)
+      globalid (>= 0.3.6)
+    activemodel (7.0.2)
+      activesupport (= 7.0.2)
+    activerecord (7.0.2)
+      activemodel (= 7.0.2)
+      activesupport (= 7.0.2)
+    activestorage (7.0.2)
+      actionpack (= 7.0.2)
+      activejob (= 7.0.2)
+      activerecord (= 7.0.2)
+      activesupport (= 7.0.2)
+      marcel (~> 1.0)
+      mini_mime (>= 1.1.0)
+    activesupport (7.0.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    bootsnap (1.10.3)
+      msgpack (~> 1.2)
+    builder (3.2.4)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.9)
+    crass (1.0.6)
+    digest (3.1.0)
+    erubi (1.10.0)
+    globalid (1.0.0)
+      activesupport (>= 5.0)
+    i18n (1.9.1)
+      concurrent-ruby (~> 1.0)
+    io-wait (0.2.1)
+    loofah (2.13.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (1.0.2)
+    method_source (1.0.0)
+    mini_mime (1.1.2)
+    mini_portile2 (2.7.1)
+    minitest (5.15.0)
+    msgpack (1.4.4)
+    net-imap (0.2.3)
+      digest
+      net-protocol
+      strscan
+    net-pop (0.1.1)
+      digest
+      net-protocol
+      timeout
+    net-protocol (0.1.2)
+      io-wait
+      timeout
+    net-smtp (0.3.1)
+      digest
+      net-protocol
+      timeout
+    nio4r (2.5.8)
+    nokogiri (1.13.1)
+      mini_portile2 (~> 2.7.0)
+      racc (~> 1.4)
+    pg (1.3.1)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-rails (0.3.9)
+      pry (>= 0.10.4)
+    puma (5.6.1)
+      nio4r (~> 2.0)
+    racc (1.6.0)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (7.0.2)
+      actioncable (= 7.0.2)
+      actionmailbox (= 7.0.2)
+      actionmailer (= 7.0.2)
+      actionpack (= 7.0.2)
+      actiontext (= 7.0.2)
+      actionview (= 7.0.2)
+      activejob (= 7.0.2)
+      activemodel (= 7.0.2)
+      activerecord (= 7.0.2)
+      activestorage (= 7.0.2)
+      activesupport (= 7.0.2)
+      bundler (>= 1.15.0)
+      railties (= 7.0.2)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.4.2)
+      loofah (~> 2.3)
+    railties (7.0.2)
+      actionpack (= 7.0.2)
+      activesupport (= 7.0.2)
+      method_source
+      rake (>= 12.2)
+      thor (~> 1.0)
+      zeitwerk (~> 2.5)
+    rake (13.0.6)
+    scenic (1.5.5)
+      activerecord (>= 4.0.0)
+      railties (>= 4.0.0)
+    strscan (3.0.1)
+    thor (1.2.1)
+    timeout (0.2.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    websocket-driver (0.7.5)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.5.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bootsnap
+  pg (~> 1.1)
+  pry-rails
+  puma (~> 5.0)
+  rails (~> 7.0.2)
+  scenic (~> 1.5)
+  timescaledb!
+  tzinfo-data
+
+RUBY VERSION
+   ruby 2.7.1p83
+
+BUNDLED WITH
+   2.1.4

data/examples/ranking/README.md

@@ -0,0 +1,166 @@
+# README
+
+This example application is a "Scoring" service that stores "games" and "plays" of the games in question.
+
+There are two tables:
+
+* `games` that holds a name and description
+* `plays` is a [hypertable][hypertable] that references a `game`, storing `score` and `total_time`.
+
+Interesting things to observe here:
+
+* The gem is required on [config/initializers/timescale.rb](./config/initializers/timescale.rb).
+* The [hypertable creation](db/migrate/20220209120910_create_plays.rb) is also with the `enable_extension` command time.
+* See how the [play model](app/models/play.rb) uses [acts_as_hypertable](../../lib/timescale/acts_as_hypertable.rb).
+
+## Walkthrough
+
+Use `bin/console` to preload the environment and follow the next steps.
+
+Let's start by creating a game and a single play.
+
+```ruby
+lol = Game.create(name: "LoL", description: "League of Legends")
+Play.create(game: lol,
+  score: (rand * 100).to_i,
+  total_time: (rand * 1000).to_i)
+```
+You can also insert a few hundreds/thousands/millions of records to test it properly.
+
+```ruby
+100.times do
+   Play.create(game: lol,
+   score: (rand * 100).to_i,
+   total_time: (rand * 1000).to_i)
+end
+```
+
+You can play with multiple games and millions of play records to make it an impressive playground if you want :wink:
+
+
+Then you can experiment with the [time_bucket][time_bucket] funciton.
+
+```ruby
+Play.group("time_bucket('1 min',created_at)").count
+# => {2022-02-09 12:34:00 UTC=>1, 2022-02-09 12:39:00 UTC=>10100}
+```
+
+> Hypertables in TimescaleDB are designed to be easy to manage and to behave predictably to users familiar with standard PostgreSQL tables. Along those lines, SQL commands to create, alter, or delete hypertables in TimescaleDB are identical to those in PostgreSQL. Even though hypertables are comprised of many interlinked chunks, commands made to the hypertable automatically propagate changes down to all of the chunks belonging to that hypertable.
+
+When the model contains the `acts_as_hypertable` macro, it's possible to navigate into the hypertable internals:
+
+```ruby
+ Play.hypertable
+ # => #<Timescaledb::Hypertable:0x00007faa97df7e30
+ # hypertable_schema: "public",
+ # hypertable_name: "plays",
+ # owner: "jonatasdp",
+ # num_dimensions: 1,
+ # num_chunks: 2,
+ # compression_enabled: true,
+ # is_distributed: false,
+ # replication_factor: nil,
+ # data_nodes: nil,
+ # tablespaces: nil>
+```
+
+Each hypertable has many chunks. Chunks are the subtables spread accross the time. You can check chunks metadata from the `hypertable` relation here:
+
+```ruby
+Play.hypertable.chunks.pluck(:chunk_name)
+# => ["_hyper_1_1_chunk", "_hyper_1_2_chunk"]
+```
+
+Chunks can also be compressed/decompressed and you can check the state using scopes:
+
+```ruby
+Play.hypertable.chunks.compressed.count # => 2
+```
+
+Get a resume from chunks status:
+
+```ruby
+Play.hypertable.chunks.resume
+# => {:total=>2, :compressed=>0, :uncompressed=>2}
+```
+
+To get a full stats from all hypertables, you can see `Timescaledb.stats`:
+
+```ruby
+Timescaledb.stats
+ # => {:hypertables=>
+ #  {:count=>1,
+ #   :uncompressed=>0,
+ #   :approximate_row_count=>{"plays"=>10100},
+ #   :chunks=>{:total=>2, :compressed=>0, :uncompressed=>2},
+ #   :size=>{:uncompressed=>"1.3 MB", :compressed=>"0 Bytes"}},
+ # :continuous_aggregates=>{:total=>0},
+ # :jobs_stats=>[{:success=>100, :runs=>100, :failures=>0}]}
+```
+Note that we haven't  used compression yet. So, we can force compression directly from the `chunk` relation:
+
+```ruby
+Play.hypertable.chunks.each(&:compress!)
+```
+
+Calling `stats` to check the compressed size:
+
+```ruby
+Timescaledb.stats
+ #  {:count=>1,  ...
+ #   :size=>
+ #    {:uncompressed=>"1.2 MB",
+ #     :compressed=>"180 KB"}},
+ # :continuous_aggregates=>{:total=>0},
+ # :jobs_stats=>
+ #  [{:success=>107,
+ #    :runs=>107,
+ #    :failures=>0}]}
+```
+
+> :warning: Note that the chunks are not very effective compressing here because of the example is incomplete and with a little amount of records.
+
+You can decompress as the system will make the compression in the background as it already have a policy.
+
+```ruby
+Play.hypertable.chunks.each(&:decompress!)
+```
+
+## Dump schema
+
+The lib also contains a [schema_dumper](../../lib/timescale/schema_dumper.rb) that allows you to dump the schema and reload with the same hypertable options.
+
+```bash
+rails db:schema:dump
+```
+
+Confirm that the hypertable is on [db/schema.rb](db/schema.rb) file:
+
+```
+ grep hypertable db/schema.rb
+  create_hypertable "plays", time_column: "created_at", chunk_time_interval: "1
+  minute", compress_segmentby: "game_id", compress_orderby: "created_at ASC",
+  compression_interval: "P7D"
+```
+
+And you can also reload the configuration manually in the test environment:
+
+```bash
+RAILS_ENV=test rails db:schema:load
+```
+
+## Scenic views
+
+If you use [scenic](https://github.com/scenic-views/scenic) views, it will
+automatically recognize and dump the views.
+
+Check the [view migration](db/migrate/20220209143347_create_score_per_hours.rb)
+and the correspondent view defined in the [sql file](db/views/score_per_hours_v01.sql).
+
+> Note that scenic is not fully compatible with timescaledb continous aggregates
+> and we created a [helper](../../lib/timescale/scenic/extension.rb) to make it
+> easy to use along with scenic.
+
+[hypertable]: https://docs.timescale.com/timescaledb/latest/how-to-guides/hypertables/
+[time_bucket]: https://docs.timescale.com/api/latest/hyperfunctions/time_bucket/
+

data/examples/ranking/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/examples/ranking/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::API
+end

data/examples/ranking/app/jobs/application_job.rb

@@ -0,0 +1,7 @@
+class ApplicationJob < ActiveJob::Base
+  # Automatically retry jobs that encountered a deadlock
+  # retry_on ActiveRecord::Deadlocked
+
+  # Most jobs are safe to ignore if the underlying records are no longer available
+  # discard_on ActiveJob::DeserializationError
+end

data/examples/ranking/app/models/application_record.rb

@@ -0,0 +1,3 @@
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+end

data/examples/ranking/app/models/game.rb

@@ -0,0 +1,2 @@
+class Game < ApplicationRecord
+end

data/examples/ranking/app/models/play.rb

@@ -0,0 +1,7 @@
+class Play < ApplicationRecord
+  belongs_to :game
+
+  self.primary_key = "created_at"
+
+  acts_as_hypertable
+end

data/examples/ranking/bin/bundle

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundle' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "rubygems"
+
+m = Module.new do
+  module_function
+
+  def invoked_as_script?
+    File.expand_path($0) == File.expand_path(__FILE__)
+  end
+
+  def env_var_version
+    ENV["BUNDLER_VERSION"]
+  end
+
+  def cli_arg_version
+    return unless invoked_as_script? # don't want to hijack other binstubs
+    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
+    bundler_version = nil
+    update_index = nil
+    ARGV.each_with_index do |a, i|
+      if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN
+        bundler_version = a
+      end
+      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
+      bundler_version = $1
+      update_index = i
+    end
+    bundler_version
+  end
+
+  def gemfile
+    gemfile = ENV["BUNDLE_GEMFILE"]
+    return gemfile if gemfile && !gemfile.empty?
+
+    File.expand_path("../../Gemfile", __FILE__)
+  end
+
+  def lockfile
+    lockfile =
+      case File.basename(gemfile)
+      when "gems.rb" then gemfile.sub(/\.rb$/, gemfile)
+      else "#{gemfile}.lock"
+      end
+    File.expand_path(lockfile)
+  end
+
+  def lockfile_version
+    return unless File.file?(lockfile)
+    lockfile_contents = File.read(lockfile)
+    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
+    Regexp.last_match(1)
+  end
+
+  def bundler_version
+    @bundler_version ||=
+      env_var_version || cli_arg_version ||
+        lockfile_version
+  end
+
+  def bundler_requirement
+    return "#{Gem::Requirement.default}.a" unless bundler_version
+
+    bundler_gem_version = Gem::Version.new(bundler_version)
+
+    requirement = bundler_gem_version.approximate_recommendation
+
+    return requirement unless Gem::Version.new(Gem::VERSION) < Gem::Version.new("2.7.0")
+
+    requirement += ".a" if bundler_gem_version.prerelease?
+
+    requirement
+  end
+
+  def load_bundler!
+    ENV["BUNDLE_GEMFILE"] ||= gemfile
+
+    activate_bundler
+  end
+
+  def activate_bundler
+    gem_error = activation_error_handling do
+      gem "bundler", bundler_requirement
+    end
+    return if gem_error.nil?
+    require_error = activation_error_handling do
+      require "bundler/version"
+    end
+    return if require_error.nil? && Gem::Requirement.new(bundler_requirement).satisfied_by?(Gem::Version.new(Bundler::VERSION))
+    warn "Activating bundler (#{bundler_requirement}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_requirement}'`"
+    exit 42
+  end
+
+  def activation_error_handling
+    yield
+    nil
+  rescue StandardError, LoadError => e
+    e
+  end
+end
+
+m.load_bundler!
+
+if m.invoked_as_script?
+  load Gem.bin_path("bundler", "bundle")
+end

data/examples/ranking/bin/rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+APP_PATH = File.expand_path("../config/application", __dir__)
+require_relative "../config/boot"
+require "rails/commands"

data/examples/ranking/bin/rake

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative "../config/boot"
+require "rake"
+Rake.application.run

data/examples/ranking/bin/setup

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+require "fileutils"
+
+# path to your application root.
+APP_ROOT = File.expand_path("..", __dir__)
+
+def system!(*args)
+  system(*args) || abort("\n== Command #{args} failed ==")
+end
+
+FileUtils.chdir APP_ROOT do
+  # This script is a way to set up or update your development environment automatically.
+  # This script is idempotent, so that you can run it at any time and get an expectable outcome.
+  # Add necessary setup steps to this file.
+
+  puts "== Installing dependencies =="
+  system! "gem install bundler --conservative"
+  system("bundle check") || system!("bundle install")
+
+  # puts "\n== Copying sample files =="
+  # unless File.exist?("config/database.yml")
+  #   FileUtils.cp "config/database.yml.sample", "config/database.yml"
+  # end
+
+  puts "\n== Preparing database =="
+  system! "bin/rails db:prepare"
+
+  puts "\n== Removing old logs and tempfiles =="
+  system! "bin/rails log:clear tmp:clear"
+
+  puts "\n== Restarting application server =="
+  system! "bin/rails restart"
+end

data/examples/ranking/config/application.rb

@@ -0,0 +1,39 @@
+require_relative "boot"
+
+require "rails"
+# Pick the frameworks you want:
+require "active_model/railtie"
+require "active_job/railtie"
+require "active_record/railtie"
+require "active_storage/engine"
+require "action_controller/railtie"
+# require "action_mailer/railtie"
+require "action_mailbox/engine"
+require "action_text/engine"
+require "action_view/railtie"
+# require "action_cable/engine"
+# require "rails/test_unit/railtie"
+
+# Require the gems listed in Gemfile, including any gems
+# you've limited to :test, :development, or :production.
+Bundler.require(*Rails.groups)
+
+module Ranking
+  class Application < Rails::Application
+    # Initialize configuration defaults for originally generated Rails version.
+    config.load_defaults 7.0
+
+    # Configuration for the application, engines, and railties goes here.
+    #
+    # These settings can be overridden in specific environments using the files
+    # in config/environments, which are processed later.
+    #
+    # config.time_zone = "Central Time (US & Canada)"
+    # config.eager_load_paths << Rails.root.join("extras")
+
+    # Only loads a smaller set of middleware suitable for API only apps.
+    # Middleware like session, flash, cookies can be added back manually.
+    # Skip views, helpers and assets when generating a new resource.
+    config.api_only = true
+  end
+end

data/examples/ranking/config/boot.rb

@@ -0,0 +1,4 @@
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "bundler/setup" # Set up gems listed in the Gemfile.
+require "bootsnap/setup" # Speed up boot time by caching expensive operations.

data/examples/ranking/config/credentials.yml.enc

@@ -0,0 +1 @@
+89mWxkKPY+RpiS3ysJ0FE9ljcVzmhiJVCYL9MVKwqPzkU/tUhehytnhibSz/ZNV/ef8WqOzYm5DfFfKXAXXixut/Aazw8725RxxLUDcikpy8ayr13WZgj91XlaPLCHPVyuNlxgVJFN8HPw++Xfe3pakKeJB0hhAlCgwCWIT7tx7Zf6g8KaIbdvJ+U9drEu3n4OgaQuw+wzRU1EaI80BbX1r9+Uufg6t7mWzMEh7n55HEBTinyNL/UZgQ0XvOQs+bQjjHVxRATXT2Mxt1zF3FZQZ6ECtOPKBKit9PDaS3RCkN2tk3ObvXlmSbz2vcIB/oW03M63TfjmfXjpG25N8tXqLl0MKoyOv/3UiBqeC7orNLTXZuWxpaQyCjpTqmza/rQyPkTRsUt+V1Rtw1gZfMbTK/JOdXr1feMhrl--91mPoTmwkbiDY9sK--49vaWMgJTV11y2bdEDMgug==

data/examples/ranking/config/database.yml

@@ -0,0 +1,86 @@
+# PostgreSQL. Versions 9.3 and up are supported.
+#
+# Install the pg driver:
+#   gem install pg
+# On macOS with Homebrew:
+#   gem install pg -- --with-pg-config=/usr/local/bin/pg_config
+# On macOS with MacPorts:
+#   gem install pg -- --with-pg-config=/opt/local/lib/postgresql84/bin/pg_config
+# On Windows:
+#   gem install pg
+#       Choose the win32 build.
+#       Install PostgreSQL and put its /bin directory on your path.
+#
+# Configure Using Gemfile
+# gem "pg"
+#
+default: &default
+  adapter: postgresql
+  encoding: unicode
+  # For details on connection pooling, see Rails configuration guide
+  # https://guides.rubyonrails.org/configuring.html#database-pooling
+  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+
+development:
+  <<: *default
+  database: ranking_development
+
+  # The specified database role being used to connect to postgres.
+  # To create additional roles in postgres see `$ createuser --help`.
+  # When left blank, postgres will use the default role. This is
+  # the same name as the operating system user running Rails.
+  #username: ranking
+
+  # The password associated with the postgres role (username).
+  #password:
+
+  # Connect on a TCP socket. Omitted by default since the client uses a
+  # domain socket that doesn't need configuration. Windows does not have
+  # domain sockets, so uncomment these lines.
+  #host: localhost
+
+  # The TCP port the server listens on. Defaults to 5432.
+  # If your server runs on a different port number, change accordingly.
+  #port: 5432
+
+  # Schema search path. The server defaults to $user,public
+  #schema_search_path: myapp,sharedapp,public
+
+  # Minimum log levels, in increasing order:
+  #   debug5, debug4, debug3, debug2, debug1,
+  #   log, notice, warning, error, fatal, and panic
+  # Defaults to warning.
+  #min_messages: notice
+
+# Warning: The database defined as "test" will be erased and
+# re-generated from your development database when you run "rake".
+# Do not set this db to the same as development or production.
+test:
+  <<: *default
+  database: ranking_test
+
+# As with config/credentials.yml, you never want to store sensitive information,
+# like your database password, in your source code. If your source code is
+# ever seen by anyone, they now have access to your database.
+#
+# Instead, provide the password or a full connection URL as an environment
+# variable when you boot the app. For example:
+#
+#   DATABASE_URL="postgres://myuser:mypass@localhost/somedatabase"
+#
+# If the connection URL is provided in the special DATABASE_URL environment
+# variable, Rails will automatically merge its configuration values on top of
+# the values provided in this file. Alternatively, you can specify a connection
+# URL environment variable explicitly:
+#
+#   production:
+#     url: <%= ENV["MY_APP_DATABASE_URL"] %>
+#
+# Read https://guides.rubyonrails.org/configuring.html#configuring-a-database
+# for a full overview on how database connection configuration can be specified.
+#
+production:
+  <<: *default
+  database: ranking_production
+  username: ranking
+  password: <%= ENV["RANKING_DATABASE_PASSWORD"] %>