timescaledb-rails 0.0.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff972c0e2773b5032e350089f1f7c75c6975aa619db5c7b8b99350c5f9250347
-  data.tar.gz: 2b799232bb7927e2c73dd35d2c54b90c23b1a86f424d282593512269988d06c4
+  metadata.gz: af4399bfd70056ed23cfb0994580a8c61fcd88722a72ce7839761b305c6d2029
+  data.tar.gz: dad61e01554eee6ee23fd780a6745196d7fb5b3703398c795bbe3e00dfbe028b
 SHA512:
-  metadata.gz: 1e0229939288334ef8a612f16fd5f721b24fcba54340093ab9fa65ae538effd2a864294c3f3b6cf9f08ebc3db95fffe26b7f355503639630f7db48a15a57b942
-  data.tar.gz: 04d6a4d2fd560a53ecbe45ed3a20fba0d901971b10b0a7af80b61ec9dc80c0ae2c2adf1715f4e484edaf15da3a7aaf213343e716368f5d278093e66fdb5d7ae5
+  metadata.gz: 1679b7421eca2f5b557b83a7b338f72444d073009f532b77d75e8e233c07828750d02afc96f4b2ee0a5c61ce6c750f03832742621df1187529cddcec3e46995f
+  data.tar.gz: 3628e056c77754629a65c2ef343c59702272bbec882b47f2e70564fbd1008080729e05017f923a0145d78e186bb272a5e13394605ccf96bcb39a34f520c3ad9a

data/README.md

@@ -1,2 +1,77 @@
-# timescaledb-rails
-Ruby on Rails helpers for TimescaleDB
+# TimescaleDB extension for Rails [![Actions Status](https://github.com/crunchloop/timescaledb-rails/workflows/CI/badge.svg?branch=main)](https://github.com/crunchloop/timescaledb-rails/actions?query=workflow%3ACI)
+
+`timescaledb-rails` extends ActiveRecord PostgreSQL adapter and provides features from [`TimescaleDB`](https://www.timescale.com). It provides support for hypertables and other features added by TimescaleDB PostgreSQL extension.
+
+
+## Installation
+
+Install `timescaledb-rails` from RubyGems:
+
+``` sh
+$ gem install timescaledb-rails
+```
+
+Or include it in your project's `Gemfile` with Bundler:
+
+``` ruby
+gem 'timescaledb-rails', '~> 0.1'
+```
+
+## Examples
+
+Create a hypertable from a PostgreSQL table by doing:
+
+```ruby
+class CreateEvent < ActiveRecord::Migration[7.0]
+  def change
+    create_table :events, id: false do |t|
+      t.string :name, null: false
+      t.time :occured_at, null: false
+
+      t.timestamps
+    end
+
+    create_hypertable :events, :created_at, chunk_time_interval: '2 days'
+  end
+end
+```
+
+Create a hypertable without a PostgreSQL table by doing:
+
+```ruby
+class CreatePayloadHypertable < ActiveRecord::Migration[7.0]
+  def change
+    create_hypertable :payloads, :created_at, chunk_time_interval: '5 days' do |t|
+      t.string :ip, null: false
+
+      t.timestamps
+    end
+  end
+end
+```
+
+Enable hypertable compression by doing:
+
+```ruby
+class AddEventCompression < ActiveRecord::Migration[7.0]
+  def change
+    add_hypertable_compression :events, 20.days, segment_by: :name, order_by: 'occured_at DESC'
+  end
+end
+```
+
+## Supported Ruby/Rails versions
+
+Supported Ruby/Rails versions are listed in [`.github/workflows/ci.yaml`](https://github.com/crunchloop/timescaledb-rails/blob/main/.github/workflows/ci.yaml)
+
+## License
+
+Released under the MIT License.  See the [LICENSE][] file for further details.
+
+[license]: LICENSE
+
+## About Crunchloop
+
+![crunchloop](https://crunchloop.io/logo-blue.png)
+
+`timescaledb-rails` is supported with :heart: by [Crunchloop](https://crunchloop.io). We strongly believe in giving back :rocket:. Let's work together [`Get in touch`](https://crunchloop.io/contact).

data/lib/timescaledb/rails/extensions/active_record/database_tasks.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    module ActiveRecord
+      # :nodoc:
+      module DatabaseTasks
+        # @override
+        def structure_dump_flags_for(adapter)
+          return (flags = super) if adapter != 'postgresql'
+
+          if flags.nil?
+            timescaledb_structure_dump_default_flags
+          elsif flags.is_a?(Array)
+            flags << timescaledb_structure_dump_default_flags
+          elsif flags.is_a?(String)
+            "#{flags} #{timescaledb_structure_dump_default_flags}"
+          else
+            flags
+          end
+        end
+
+        # Returns `pg_dump` flag to exclude `_timescaledb_internal` schema tables.
+        #
+        # @return [String]
+        def timescaledb_structure_dump_default_flags
+          '--exclude-schema=_timescaledb_internal'
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/extensions/active_record/postgresql_database_tasks.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'active_record/tasks/postgresql_database_tasks'
+require 'timescaledb/rails/orderby_compression'
+
+module Timescaledb
+  module Rails
+    module ActiveRecord
+      # :nodoc:
+      module PostgreSQLDatabaseTasks
+        # @override
+        def structure_dump(filename, extra_flags)
+          super
+
+          return unless timescale_enabled?
+
+          File.open(filename, 'a') do |file|
+            Timescaledb::Rails::Hypertable.all.each do |hypertable|
+              drop_ts_insert_trigger_statment(hypertable, file)
+              create_hypertable_statement(hypertable, file)
+              add_hypertable_compression_statement(hypertable, file)
+            end
+          end
+        end
+
+        def drop_ts_insert_trigger_statment(hypertable, file)
+          file << "---\n"
+          file << "--- Drop ts_insert_blocker previously created by pg_dump to avoid pg errors, create_hypertable will re-create it again.\n" # rubocop:disable Layout/LineLength
+          file << "---\n\n"
+          file << "DROP TRIGGER IF EXISTS ts_insert_blocker ON #{hypertable.hypertable_name};\n"
+        end
+
+        def create_hypertable_statement(hypertable, file)
+          options = hypertable_options(hypertable)
+
+          file << "SELECT create_hypertable('#{hypertable.hypertable_name}', '#{hypertable.time_column_name}', #{options});\n\n" # rubocop:disable Layout/LineLength
+        end
+
+        def add_hypertable_compression_statement(hypertable, file)
+          return unless hypertable.compression?
+
+          options = hypertable_compression_options(hypertable)
+
+          file << "ALTER TABLE #{hypertable.hypertable_name} SET (#{options});\n\n"
+          file << "SELECT add_compression_policy('#{hypertable.hypertable_name}', INTERVAL '#{hypertable.compression_policy_interval}');\n\n" # rubocop:disable Layout/LineLength
+        end
+
+        def hypertable_options(hypertable)
+          sql_statements = ["if_not_exists => 'TRUE'"]
+          sql_statements << "chunk_time_interval => INTERVAL '#{hypertable.chunk_time_interval.inspect}'"
+
+          sql_statements.compact.join(', ')
+        end
+
+        def hypertable_compression_options(hypertable)
+          segmentby_setting = hypertable.compression_settings.segmentby_setting.first
+          orderby_setting = hypertable.compression_settings.orderby_setting.first
+
+          sql_statements = ['timescaledb.compress']
+          sql_statements << "timescaledb.compress_segmentby = '#{segmentby_setting.attname}'" if segmentby_setting
+
+          if orderby_setting
+            orderby = Timescaledb::Rails::OrderbyCompression.new(orderby_setting.attname,
+                                                                 orderby_setting.orderby_asc).to_s
+
+            sql_statements << "timescaledb.compress_orderby = '#{orderby}'"
+          end
+
+          sql_statements.join(', ')
+        end
+
+        def timescale_enabled?
+          Timescaledb::Rails::Hypertable.table_exists?
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/extensions/active_record/schema_dumper.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'active_record/connection_adapters/postgresql_adapter'
+require 'timescaledb/rails/orderby_compression'
+
+module Timescaledb
+  module Rails
+    module ActiveRecord
+      # :nodoc:
+      module SchemaDumper
+        def table(table, stream)
+          super(table, stream)
+
+          return unless timescale_enabled?
+          return if (hypertable = Timescaledb::Rails::Hypertable.find_by(hypertable_name: table)).nil?
+
+          hypertable(hypertable, stream)
+          hypertable_compression(hypertable, stream)
+        end
+
+        private
+
+        def hypertable(hypertable, stream)
+          options = [hypertable.hypertable_name.inspect, hypertable.time_column_name.inspect]
+          options |= hypertable_options(hypertable)
+
+          stream.puts "  create_hypertable #{options.join(', ')}"
+          stream.puts
+        end
+
+        def hypertable_compression(hypertable, stream)
+          return unless hypertable.compression?
+
+          options = [hypertable.hypertable_name.inspect, hypertable.compression_policy_interval.inspect]
+          options |= hypertable_compression_options(hypertable)
+
+          stream.puts "  add_hypertable_compression #{options.join(', ')}"
+          stream.puts
+        end
+
+        def hypertable_options(hypertable)
+          options = {
+            chunk_time_interval: hypertable.chunk_time_interval
+          }
+
+          options.each_with_object([]) do |(key, value), memo|
+            memo << "#{key}: #{format_hypertable_option_value(value)}"
+            memo
+          end
+        end
+
+        def hypertable_compression_options(hypertable)
+          segmentby_setting = hypertable.compression_settings.segmentby_setting.first
+          orderby_setting = hypertable.compression_settings.orderby_setting.first
+
+          [].tap do |result|
+            result << "segment_by: #{segmentby_setting.attname.inspect}" if segmentby_setting
+
+            if orderby_setting
+              orderby = Timescaledb::Rails::OrderbyCompression.new(orderby_setting.attname,
+                                                                   orderby_setting.orderby_asc).to_s
+
+              result << "order_by: #{orderby.inspect}"
+            end
+          end
+        end
+
+        def format_hypertable_option_value(value)
+          case value
+          when String then value.inspect
+          when ActiveSupport::Duration then value.inspect.inspect
+          else
+            value
+          end
+        end
+
+        def timescale_enabled?
+          Timescaledb::Rails::Hypertable.table_exists?
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/extensions/active_record/schema_statements.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'active_record/connection_adapters/postgresql_adapter'
+
+module Timescaledb
+  module Rails
+    module ActiveRecord
+      # :nodoc:
+      module SchemaStatements
+        # Converts given standard PG table into a hypertable.
+        #
+        #   create_hypertable('readings', 'created_at', chunk_time_interval: '7 days')
+        #
+        def create_hypertable(table_name, time_column_name, **options, &block)
+          options = options.symbolize_keys
+          options_as_sql = hypertable_options_to_sql(options)
+
+          if block
+            primary_key = options[:primary_key]
+            force = options[:force]
+
+            create_table(table_name, id: false, primary_key: primary_key, force: force, **options, &block)
+          end
+
+          execute "SELECT create_hypertable('#{table_name}', '#{time_column_name}', #{options_as_sql})"
+        end
+
+        # Enables compression and sets compression options.
+        #
+        #   add_hypertable_compression('events', 7.days, segment_by: :created_at, order_by: :name)
+        #
+        def add_hypertable_compression(table_name, compress_after, segment_by: nil, order_by: nil)
+          compress_after = compress_after.inspect if compress_after.is_a?(ActiveSupport::Duration)
+
+          options = ['timescaledb.compress']
+          options << "timescaledb.compress_orderby = '#{order_by}'" unless order_by.nil?
+          options << "timescaledb.compress_segmentby = '#{segment_by}'" unless segment_by.nil?
+
+          execute "ALTER TABLE #{table_name} SET (#{options.join(', ')})"
+
+          execute "SELECT add_compression_policy('#{table_name}', INTERVAL '#{compress_after}')"
+        end
+
+        def hypertable_options_to_sql(options)
+          sql_statements = options.map do |option, value|
+            case option
+            when :chunk_time_interval then "chunk_time_interval => INTERVAL '#{value}'"
+            when :if_not_exists then  "if_not_exists => #{value ? 'TRUE' : 'FALSE'}"
+            end
+          end
+
+          sql_statements.compact.join(', ')
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/models/compression_setting.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    class CompressionSetting < ::ActiveRecord::Base
+      self.table_name = 'timescaledb_information.compression_settings'
+      self.primary_key = 'hypertable_name'
+
+      scope :segmentby_setting, -> { where.not(segmentby_column_index: nil).order(:segmentby_column_index) }
+      scope :orderby_setting, -> { where.not(orderby_column_index: nil).order(:orderby_column_index) }
+    end
+  end
+end

data/lib/timescaledb/rails/models/dimension.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    class Dimension < ::ActiveRecord::Base
+      TIME_TYPE = 'Time'
+
+      self.table_name = 'timescaledb_information.dimensions'
+
+      attribute :time_interval, :interval if ::Rails.version.to_i >= 7
+
+      scope :time, -> { where(dimension_type: TIME_TYPE) }
+    end
+  end
+end

data/lib/timescaledb/rails/models/hypertable.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    class Hypertable < ::ActiveRecord::Base
+      self.table_name = 'timescaledb_information.hypertables'
+      self.primary_key = 'hypertable_name'
+
+      has_many :compression_settings, foreign_key: 'hypertable_name',
+                                      class_name: 'Timescaledb::Rails::CompressionSetting'
+      has_many :dimensions, foreign_key: 'hypertable_name', class_name: 'Timescaledb::Rails::Dimension'
+      has_many :jobs, foreign_key: 'hypertable_name', class_name: 'Timescaledb::Rails::Job'
+
+      # @return [String]
+      def time_column_name
+        time_dimension.column_name
+      end
+
+      # @return [String]
+      def chunk_time_interval
+        time_dimension.time_interval
+      end
+
+      # @return [String]
+      def compression_policy_interval
+        ActiveSupport::Duration.parse(compression_job.config['compress_after']).inspect
+      rescue ActiveSupport::Duration::ISO8601Parser::ParsingError
+        compression_job.config['compress_after']
+      end
+
+      # @return [Boolean]
+      def compression?
+        compression_job.present?
+      end
+
+      private
+
+      # @return [Job]
+      def compression_job
+        @compression_job ||= jobs.policy_compression.first
+      end
+
+      # @return [Dimension]
+      def time_dimension
+        @time_dimension ||= dimensions.time.first
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/models/job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    class Job < ::ActiveRecord::Base
+      self.table_name = 'timescaledb_information.jobs'
+      self.primary_key = 'hypertable_name'
+
+      POLICY_COMPRESSION = 'policy_compression'
+
+      scope :policy_compression, -> { where(proc_name: POLICY_COMPRESSION) }
+    end
+  end
+end

data/lib/timescaledb/rails/models.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative './models/compression_setting'
+require_relative './models/dimension'
+require_relative './models/job'
+require_relative './models/hypertable'

data/lib/timescaledb/rails/orderby_compression.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    class OrderbyCompression
+      # @param [String] column_name.
+      # @param [Boolean] orderby_asc.
+      def initialize(column_name, orderby_asc)
+        @column_name = column_name
+        @orderby_asc = orderby_asc
+      end
+
+      # @return [String]
+      def to_s
+        [@column_name, (@orderby_asc ? 'ASC' : 'DESC')].join(' ')
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/railtie.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rails'
+
+require_relative 'extensions/active_record/database_tasks'
+require_relative 'extensions/active_record/postgresql_database_tasks'
+require_relative 'extensions/active_record/schema_dumper'
+require_relative 'extensions/active_record/schema_statements'
+
+module Timescaledb
+  module Rails
+    # :nodoc:
+    class Railtie < ::Rails::Railtie
+      initializer 'timescaledb-rails.require_timescale_models' do
+        ActiveSupport.on_load(:active_record) do
+          require 'timescaledb/rails/models'
+        end
+      end
+
+      initializer 'timescaledb-rails.add_timescale_support_to_active_record' do
+        ActiveSupport.on_load(:active_record) do
+          ::ActiveRecord::Tasks::DatabaseTasks.extend(
+            Timescaledb::Rails::ActiveRecord::DatabaseTasks
+          )
+
+          ::ActiveRecord::Tasks::PostgreSQLDatabaseTasks.prepend(
+            Timescaledb::Rails::ActiveRecord::PostgreSQLDatabaseTasks
+          )
+
+          ::ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.prepend(
+            Timescaledb::Rails::ActiveRecord::SchemaStatements
+          )
+
+          ::ActiveRecord::ConnectionAdapters::PostgreSQL::SchemaDumper.prepend(
+            Timescaledb::Rails::ActiveRecord::SchemaDumper
+          )
+        end
+      end
+    end
+  end
+end

data/lib/timescaledb/rails/version.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 module Timescaledb
+  # :nodoc:
   module Rails
-    VERSION = '0.0.1'
+    VERSION = '0.1.2'
   end
 end

data/lib/timescaledb/rails.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Timescaledb
+  # :nodoc:
+  module Rails
+  end
+end

data/lib/timescaledb-rails.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'timescaledb/rails/version'
+require_relative 'timescaledb/rails/railtie'
+
+require_relative 'timescaledb/rails'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timescaledb-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Iván Etchart
@@ -9,8 +9,106 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-10-27 00:00:00.000000000 Z
-dependencies: []
+date: 2022-11-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.39'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.39'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.17'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.15'
 description: 
 email: oss@crunchloop.io
 executables: []
@@ -19,11 +117,25 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- lib/timescaledb-rails.rb
+- lib/timescaledb/rails.rb
+- lib/timescaledb/rails/extensions/active_record/database_tasks.rb
+- lib/timescaledb/rails/extensions/active_record/postgresql_database_tasks.rb
+- lib/timescaledb/rails/extensions/active_record/schema_dumper.rb
+- lib/timescaledb/rails/extensions/active_record/schema_statements.rb
+- lib/timescaledb/rails/models.rb
+- lib/timescaledb/rails/models/compression_setting.rb
+- lib/timescaledb/rails/models/dimension.rb
+- lib/timescaledb/rails/models/hypertable.rb
+- lib/timescaledb/rails/models/job.rb
+- lib/timescaledb/rails/orderby_compression.rb
+- lib/timescaledb/rails/railtie.rb
 - lib/timescaledb/rails/version.rb
 homepage: http://github.com/crunchloop/timescaledb-rails
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -32,14 +144,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
+rubygems_version: 3.3.26
 signing_key: 
 specification_version: 4
 summary: TimescaleDB Rails integration