timescaledb 0.1.2 → 0.2.0

data/examples/ranking/.gitignore

@@ -0,0 +1,29 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+# Ignore uploaded files in development.
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/
+!/tmp/storage/.keep
+
+# Ignore master key for decrypting credentials and more.
+/config/master.key

data/examples/ranking/.ruby-version

@@ -0,0 +1 @@
+2.7.1

data/examples/ranking/Gemfile

@@ -0,0 +1,33 @@
+source "https://rubygems.org"
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+ruby "2.7.1"
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem "rails", "~> 7.0.2"
+
+gem "timescaledb", path: "../../"
+gem "pg", "~> 1.1"
+gem "puma", "~> 5.0"
+gem "tzinfo-data", platforms: %i[ mingw mswin x64_mingw jruby ]
+
+# Reduces boot times through caching; required in config/boot.rb
+gem "bootsnap", require: false
+
+# Use Active Storage variants [https://guides.rubyonrails.org/active_storage_overview.html#transforming-images]
+# gem "image_processing", "~> 1.2"
+
+# Use Rack CORS for handling Cross-Origin Resource Sharing (CORS), making cross-origin AJAX possible
+# gem "rack-cors"
+
+group :development, :test do
+  gem "pry-rails"
+end
+
+group :development do
+  # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
+  # gem "spring"
+end
+
+
+gem "scenic", "~> 1.5"

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==