readyset 0.1.1

data/lib/readyset/utils/window_counter.rb

@@ -0,0 +1,58 @@
+module Readyset
+  module Utils
+    # Keeps track of events that occur over time to see if the number of logged events exceeds a
+    # preconfigured threshold in a preconfigured window of time. For example, if `window_size` is
+    # 10 and `time_period` is 1 minute, the number of events logged in the last minute must exceed
+    # 10 in order for `WindowCounter#threshold_crossed?` to return true.
+    class WindowCounter
+      def initialize(window_size: 10, time_period: 1.minute)
+        @lock = Mutex.new
+        @time_period = time_period
+        @times = []
+        @window_size = window_size
+      end
+
+      delegate :clear, to: :times
+
+      # Logs a new event
+      def log
+        lock.synchronize do
+          remove_times_out_of_threshold!
+          times << Time.zone.now
+        end
+
+        nil
+      end
+
+      # Returns the current number of events logged in the configured `time_period`
+      #
+      # @return [Integer]
+      def size
+        lock.synchronize do
+          remove_times_out_of_threshold!
+          times.size
+        end
+      end
+
+      # Returns true only if the number of events logged in the configured `time_period` has
+      # exceeded the configured `window_size`.
+      #
+      # @return [Boolean]
+      def threshold_crossed?
+        lock.synchronize do
+          remove_times_out_of_threshold!
+          times.size > window_size
+        end
+      end
+
+      private
+
+      attr_reader :lock, :time_period, :times, :window_size
+
+      def remove_times_out_of_threshold!
+        times.select! { |time| time >= time_period.ago }
+        nil
+      end
+    end
+  end
+end

data/lib/readyset/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Readyset
+  VERSION = '0.1.1'
+end

data/lib/readyset.rb

@@ -0,0 +1,168 @@
+# lib/readyset.rb
+
+require 'active_record/connection_adapters/readyset_adapter'
+require 'readyset/caches'
+require 'readyset/configuration'
+require 'readyset/controller_extension'
+require 'readyset/health/healthchecker'
+require 'readyset/model_extension'
+require 'readyset/explain'
+require 'readyset/query'
+require 'readyset/query/cached_query'
+require 'readyset/query/proxied_query'
+require 'readyset/railtie' if defined?(Rails::Railtie)
+require 'readyset/relation_extension'
+require 'readyset/utils/window_counter'
+
+# The Readyset module provides functionality to integrate ReadySet caching
+# with Ruby on Rails applications.
+# It offers methods to configure and manage ReadySet caches,
+# as well as to route database queries through ReadySet.
+module Readyset
+  # Sets the configuration for Readyset.
+  # @!attribute [w] configuration
+  attr_writer :configuration
+
+  # Retrieves the Readyset configuration, initializing it if it hasn't been set yet.
+  # @return [Readyset::Configuration] the current configuration for Readyset.
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  class << self
+    alias_method :config, :configuration
+  end
+
+  # Configures Readyset by providing a block with configuration details.
+  # @yieldparam [Readyset::Configuration] configuration the current configuration instance.
+  # @yieldreturn [void]
+  def self.configure
+    yield configuration
+  end
+
+  # Creates a new cache on ReadySet using the given ReadySet query ID or SQL query.
+  # @param id [String] the ReadySet query ID of the query from which a cache should be created.
+  # @param sql [String] the SQL string from which a cache should be created.
+  # @param name [String] the name for the cache being created.
+  # @param always [Boolean] whether the cache should always be used;
+  # queries to these caches will never fall back to the database if this is true.
+  # @return [void]
+  # @raise [ArgumentError] raised if exactly one of the `id` or `sql` arguments was not provided.
+  def self.create_cache!(id: nil, sql: nil, name: nil, always: false)
+    if (sql.nil? && id.nil?) || (!sql.nil? && !id.nil?)
+      raise ArgumentError, 'Exactly one of the `id` and `sql` parameters must be provided'
+    end
+
+    connection = Readyset.route { ActiveRecord::Base.connection }
+    from =
+      if sql
+        sql
+      else
+        connection.quote_column_name(id)
+      end
+
+    if always && name
+      quoted_name = connection.quote_column_name(name)
+      raw_query("CREATE CACHE ALWAYS #{quoted_name} FROM #{from}")
+    elsif always
+      raw_query("CREATE CACHE ALWAYS FROM #{from}")
+    elsif name
+      quoted_name = connection.quote_column_name(name)
+      raw_query("CREATE CACHE #{quoted_name} FROM #{from}")
+    else
+      raw_query("CREATE CACHE FROM #{from}")
+    end
+
+    nil
+  end
+
+  # Drops an existing cache on ReadySet using the given query name.
+  # @param name [String] the name of the cache that should be dropped.
+  # @return [void]
+  def self.drop_cache!(name)
+    connection = Readyset.route { ActiveRecord::Base.connection }
+    quoted_name = connection.quote_column_name(name)
+    raw_query("DROP CACHE #{quoted_name}")
+
+    nil
+  end
+
+  # Gets information about the given query from ReadySet, including whether it's supported to be
+  # cached, its current status, the rewritten query text, and the query ID.
+  #
+  # The information about the given query is retrieved by invoking `EXPLAIN CREATE CACHE FROM` on
+  # ReadySet.
+  #
+  # @param [String] a query about which information should be retrieved
+  # @return [Explain]
+  def self.explain(query)
+    Explain.call(query)
+  end
+
+  # Executes a raw SQL query against ReadySet. The query is sanitized prior to being executed.
+  # @note This method is not part of the public API.
+  # @param sql_array [Array<Object>] the SQL array to be executed against ReadySet.
+  # @return [PG::Result] the result of executing the SQL query.
+  def self.raw_query_sanitize(*sql_array) # :nodoc:
+    raw_query(ActiveRecord::Base.sanitize_sql_array(sql_array))
+  end
+
+  def self.raw_query(query) # :nodoc:
+    ActiveRecord::Base.connected_to(role: writing_role, shard: shard, prevent_writes: false) do
+      ActiveRecord::Base.connection.execute(query)
+    end
+  end
+
+  # Routes to ReadySet any queries that occur in the given block.
+  # @param prevent_writes [Boolean] if true, prevents writes from being executed on
+  # the connection to ReadySet.
+  # @yield a block whose queries should be routed to ReadySet.
+  # @return the value of the last line of the block.
+  def self.route(prevent_writes: true, &block)
+    if healthchecker.healthy?
+      begin
+        if prevent_writes
+          ActiveRecord::Base.connected_to(role: reading_role, shard: shard, prevent_writes: true,
+            &block)
+        else
+          ActiveRecord::Base.connected_to(role: writing_role, shard: shard, prevent_writes: false,
+            &block)
+        end
+      rescue => e
+        healthchecker.process_exception(e)
+        raise e
+      end
+    else
+      yield
+    end
+  end
+
+  private
+
+  # Delegates the shard method to the configuration.
+  class << self
+    private(*delegate(:shard, to: :configuration))
+  end
+
+  def self.healthchecker
+    @healthchecker ||= Readyset::Health::Healthchecker.new(
+      config.failover,
+      shard: shard,
+    )
+  end
+  private_class_method :healthchecker
+
+  # Returns the reading role for ActiveRecord connections.
+  # @return [Symbol] the reading role.
+  def self.reading_role
+    ActiveRecord.reading_role
+  end
+  private_class_method :reading_role
+
+  # Returns the writing role for ActiveRecord connections.
+  # @return [Symbol] the writing role.
+  def self.writing_role
+    ActiveRecord.writing_role
+  end
+  private_class_method :writing_role
+end

data/lib/tasks/readyset.rake

@@ -0,0 +1,162 @@
+require 'colorize'
+require 'erb'
+require 'progressbar'
+require 'terminal-table'
+
+namespace :readyset do
+  desc 'Creates a cache from the given query ID'
+  task :create_cache, [:id] => :environment do |_, args|
+    if args.key?(:id)
+      Readyset.create_cache!(id: args[:id])
+    else
+      Rails.logger.error 'A query ID must be passed to this task'
+    end
+  end
+
+  desc 'Creates a cache from the given query ID whose queries will never fall back to the ' \
+    'primary database'
+  task :create_cache_always, [:id] => :environment do |_, args|
+    if args.key?(:id)
+      Readyset.create_cache!(id: args[:id], always: true)
+    else
+      Rails.logger.error 'A query ID must be passed to this task'
+    end
+  end
+
+  desc 'Prints a list of all the queries that ReadySet has proxied'
+  task proxied_queries: :environment do
+    rows = Readyset::Query::ProxiedQuery.all.map do |q|
+      [q.id, q.text, q.supported, q.count]
+    end
+    table = Terminal::Table.new(headings: [:id, :text, :supported, :count], rows: rows)
+
+    Rails.logger.info table.to_s
+  end
+
+  namespace :proxied_queries do
+    desc 'Creates caches for all of the supported queries on ReadySet'
+    task cache_all_supported: :environment do
+      Readyset::Query::ProxiedQuery.cache_all_supported!
+    end
+
+    desc 'Clears the list of proxied queries on ReadySet'
+    task drop_all: :environment do
+      Readyset.raw_query('DROP ALL PROXIED QUERIES'.freeze)
+    end
+
+    desc 'Prints a list of all the queries that ReadySet has proxied that can be cached'
+    task supported: :environment do
+      rows = Readyset::Query::ProxiedQuery.all.
+        select { |query| query.supported == :yes }.
+        map { |q| [q.id, q.text, q.count] }
+      table = Terminal::Table.new(headings: [:id, :text, :count], rows: rows)
+
+      Rails.logger.info table.to_s
+    end
+  end
+
+  desc 'Prints a list of all the cached queries on ReadySet'
+  task caches: :environment do
+    rows = Readyset::Query::CachedQuery.all.map do |q|
+      [q.id, q.name, q.text, q.always, q.count]
+    end
+    table = Terminal::Table.new(headings: [:id, :name, :text, :always, :count], rows: rows)
+
+    Rails.logger.info table.to_s
+  end
+
+  namespace :caches do
+    desc 'Drops the cache with the given name'
+    task :drop, [:name] => :environment do |_, args|
+      if args.key?(:name)
+        Readyset.drop_cache!(args[:name])
+      else
+        Rails.logger.error 'A cache name must be passed to this task'
+      end
+    end
+
+    desc 'Drops all the caches on ReadySet'
+    task drop_all: :environment do
+      Readyset::Query::CachedQuery.drop_all!
+    end
+
+    desc 'Dumps the set of caches that currently exist on ReadySet to a file'
+    task dump: :environment do
+      template = File.read(File.join(File.dirname(__FILE__), '../templates/caches.rb.tt'))
+
+      queries = Readyset::Query::CachedQuery.all
+
+      f = File.new(Readyset.configuration.migration_path, 'w')
+      f.write(ERB.new(template, trim_mode: '-').result(binding))
+      f.close
+    end
+
+    desc 'Synchronizes the caches on ReadySet such that the caches on ReadySet match those ' \
+      'listed in db/readyset_caches.rb'
+    task migrate: :environment do
+      file = Readyset.configuration.migration_path
+
+      # We load the definition of the `Readyset::Caches` subclass in the context of a
+      # container object so we can be sure that we are never re-opening a previously-defined
+      # subclass of `Readyset::Caches`. When the container object is garbage collected, the
+      # definition of the `Readyset::Caches` subclass is garbage collected too
+      container = Object.new
+      container.instance_eval(File.read(file))
+      caches_in_migration_file = container.singleton_class::ReadysetCaches.caches.index_by(&:text)
+      caches_on_readyset = Readyset::Query::CachedQuery.all.index_by(&:text)
+
+      to_drop = caches_on_readyset.keys - caches_in_migration_file.keys
+      to_create = caches_in_migration_file.keys - caches_on_readyset.keys
+
+      if to_drop.size.positive? || to_create.size.positive?
+        dropping = 'Dropping'.red
+        creating = 'creating'.green
+        print "#{dropping} #{to_drop.size} caches and #{creating} #{to_create.size} caches. " \
+          'Continue? (y/n) '
+        $stdout.flush
+        y_or_n = STDIN.gets.strip
+
+        if y_or_n == 'y'
+          if to_drop.size.positive?
+            bar = ProgressBar.create(title: 'Dropping caches', total: to_drop.size)
+
+            to_drop.each do |text|
+              bar.increment
+              Readyset.drop_cache!(caches_on_readyset[text].name)
+            end
+          end
+
+          if to_create.size.positive?
+            bar = ProgressBar.create(title: 'Creating caches', total: to_create.size)
+
+            to_create.each do |text|
+              bar.increment
+              cache = caches_in_migration_file[text]
+              Readyset.create_cache!(sql: text, always: cache.always)
+            end
+          end
+        end
+      else
+        Rails.logger.info 'Nothing to do'
+      end
+    end
+  end
+
+  desc 'Prints status information about ReadySet'
+  task status: :environment do
+    rows = Readyset.raw_query('SHOW READYSET STATUS'.freeze).
+      map { |result| [result['name'], result['value']] }
+    table = Terminal::Table.new(rows: rows)
+
+    Rails.logger.info table.to_s
+  end
+
+  desc 'Prints information about the tables known to ReadySet'
+  task tables: :environment do
+    rows = Readyset.raw_query('SHOW READYSET TABLES'.freeze).
+      map { |result| [result['table'], result['status'], result['description']] }
+    table = Terminal::Table.new(headings: [:table, :status, :description], rows: rows)
+
+    Rails.logger.info table.to_s
+  end
+end

data/lib/templates/caches.rb.tt

@@ -0,0 +1,11 @@
+class ReadysetCaches < Readyset::Caches
+<% queries.each do |query| -%>
+  cache always: <%= query.always %> do
+    <<~SQL
+      <%= query.text.gsub("\n", "\n      ") %>
+    SQL
+  end
+
+<%- end -%>
+end
+

data/readyset.gemspec

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'lib/readyset/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'readyset'
+  spec.version = Readyset::VERSION
+  spec.authors = ['ReadySet Technology, Inc.']
+  spec.email = ['info@readyset.io']
+  spec.licenses = ['MIT']
+
+  spec.summary = 'A Rails adapter for ReadySet, a partially-stateful, incrementally-maintained ' \
+                 'SQL cache.'
+  spec.description = 'This gem provides a Rails adapter to the ReadySet SQL cache.'
+  spec.homepage = 'https://readyset.io'
+  spec.required_ruby_version = '>= 3.0'
+
+  # spec.metadata['allowed_push_host'] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/readysettech/readyset-rails'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w(bin/ test/ spec/ features/ .git .github))
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'actionpack', ['>= 6.1', '<= 7.1']
+  spec.add_dependency 'activerecord', ['>= 6.1', '<= 7.1']
+  spec.add_dependency 'activesupport', ['>= 6.1', '<= 7.1']
+  spec.add_dependency 'colorize', '~> 1.1'
+  spec.add_dependency 'concurrent-ruby', '~> 1.2'
+  spec.add_dependency 'progressbar', '~> 1.13'
+  spec.add_dependency 'rake', '~> 13.0'
+  spec.add_dependency 'terminal-table', '~> 3.0'
+
+  spec.add_development_dependency 'combustion', '~> 1.3'
+  spec.add_development_dependency 'factory_bot', '~> 6.4'
+  spec.add_development_dependency 'pg', '~> 1.5'
+  spec.add_development_dependency 'pry', '~> 0.14'
+  spec.add_development_dependency 'rspec', '~> 3.2'
+  spec.add_development_dependency 'rspec-rails', '~> 6.0'
+  spec.add_development_dependency 'rubocop-airbnb', '~> 6.0'
+  spec.add_development_dependency 'timecop', '~> 0.9'
+end

data/sig/readyset.rbs

@@ -0,0 +1,4 @@
+module Readyset
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end