tablature 0.1.1 → 1.0.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaec79244b29bb6514402673f8cb56f281c9cf25fb73c9a4dab413520e96b652
-  data.tar.gz: 54cfe803f7387135d1334dba6b4b16a0c7d1946adb6c88e092889fe881203511
+  metadata.gz: a72b6d120e1af25bf4b044347d02c552898ede4de5082a01f8b4ec3e24f4f6b0
+  data.tar.gz: e011684eadd4c9f39b83db417c6ef282f5291ed947c23651e8e5c70fcb76aa53
 SHA512:
-  metadata.gz: f30ffd3c9b8b14b08447b222a2bc5202042ef37f2c530beda33ed651c47ea7095f536bec494eef5767c44ba7a9b9751578bd9e3ff497e53203ac9bba477fc8a2
-  data.tar.gz: 2553bb52f8fecfa642cf2b8c1f3908bcabf01c3a9c6e5902076e7d447e6cf64c8bd13069902d95cc7e4478daff7a08b1d899128b74722687ad5a0dcf6e0962a0
+  metadata.gz: 9b49e89742a179e6f50ccf28789bdb66999f5edb56a4cdcf57c273abc055b5bdc9bb6cbbb754639831613d0b90c034d9ee16c07ea6f56e14ca276a819081296f
+  data.tar.gz: 540d21c49ac1f7e74da0abb9c697cfbc94c72452408acfb891edaf377a5b199bda57ae670dfd051cf266e8c4da86ea51e699a5e4bc25b6e3f0cfc9ade27f378c

data/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: master
+  pull_request:
+    branches: "*"
+
+jobs:
+  build:
+    name: Ruby ${{ matrix.ruby }}, Rails ${{ matrix.rails }}, Postgres ${{ matrix.postgres }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["2.5", "2.7"]
+        rails: ["5.2", "6.0", "master"]
+        postgres: ["10.12", "11.7", "12.2"]
+        include:
+          - postgres: "10.12"
+            rspec_tag: --tag ~postgres_11
+          - rails: "master"
+            continue-on-error: true
+
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:${{ matrix.postgres }}-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+
+    env:
+      RAILS_VERSION: ${{ matrix.rails }}
+      POSTGRES_USER: "postgres"
+      POSTGRES_PASSWORD: "postgres"
+      CI: "true"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install dependent libraries
+        run: sudo apt-get install libpq-dev
+
+      - name: Install Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1.31.0
+        with:
+          ruby-version: ${{ matrix.ruby }}
+
+      - name: Generate lockfile
+        run: bundle lock
+
+      - name: Cache dependencies
+        uses: actions/cache@v1
+        with:
+          path: vendor/bundle
+          key: bundle-${{ hashFiles('Gemfile.lock') }}
+
+      - name: Set up Tablature
+        run: bin/setup
+
+      - name: Run tests
+        run: bundle exec rspec ${{ matrix.rspec_tag }}
+        continue-on-error: ${{ matrix.continue-on-error }}

data/.gitignore

@@ -9,3 +9,5 @@
 
 # rspec failure tracking
 .rspec_status
+
+Gemfile.lock

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 2.5
 
 Metrics/BlockLength:
   Exclude:

data/.yardopts

@@ -0,0 +1 @@
+-m markdown

data/Gemfile

@@ -1,3 +1,11 @@
+source 'https://rubygems.org'
 gemspec
 
 gem 'pry'
+gem 'rubocop'
+
+rails_version = ENV.fetch('RAILS_VERSION', '6.0')
+
+rails_constraint = rails_version == 'master' ? { github: 'rails/rails' } : "~> #{rails_version}.0"
+
+gem 'rails', rails_constraint

data/README.md

@@ -7,7 +7,7 @@ It ships with Postgres support and can easily supports other databases through a
 
 ##### Requirements
 
-Tablature requires Rails 5+ and Postgres 10+.
+Tablature requires Ruby 2.5+, Rails 5+ and Postgres 10+.
 
 ##### Installation
 
@@ -55,10 +55,107 @@ class CreateEvents < ActiveRecord::Migration[5.0]
     # Create partitions with the bounds of the partition.
     create_list_partition_of :events_by_list,
       name: 'events_list_y2018m12', values: (Date.parse('2018-12-01')..Date.parse('2018-12-31')).to_a
+
   end
 
   def down
-    drop_table :events
+    drop_table :events_by_range
+    drop_table :events_by_list
+  end
+end
+```
+
+### Having a partition back a model
+
+In your migration:
+```ruby
+# db/migrate/create_events.rb
+class CreateEvents < ActiveRecord::Migration
+  def change
+    # You can use blocks when the partition key are SQL expression instead of
+    # being only a field.
+    create_range_partition :events, partition_key: -> { '(timestamp::DATE)' } do |t|
+      t.string :event_type, null: false
+      t.integer :value, null: false
+      t.datetime :timestamp, null: false
+      t.timestamps
+    end
+
+    create_range_partition_of :events,
+      name: 'events_y2018m12', range_start: '2018-12-01', range_end: '2019-01-01'
+
+    create_range_partition_of :events,
+      name: 'events_y2019m01', range_start: '2019-01-01', range_end: '2019-02-01'
+  end
+end
+```
+
+In your model, calling one of `range_partition` or `list_partition` to inject
+methods:
+```ruby
+# app/models/event.rb
+class Event < ApplicationRecord
+  range_partition
+end
+```
+
+Finally, you can now list the partitions :
+```ruby
+>> Event.partitions
+# => ["events_y2018m12", "events_y2019m01"]
+```
+
+You can also create new partitions directly from the model :
+```ruby
+>> Event.create_range_partition(
+    name: 'events_y2019m02',
+    range_start: '2019-02-01'.to_date,
+    range_end: '2019-03-01'.to_date
+  )
+# => ...
+>> Event.partitions
+# => ["events_y2018m12", "events_y2019m01", "events_y2019m02"]
+```
+
+### Partitioning an existing table
+Start by renaming your table and create the partition table:
+```ruby
+class PartitionEvents < ActiveRecord::Migration
+  def change
+    # Get the bounds of the events.
+    min_month = Event.minimum(:timestamp).beginning_of_month.to_date
+    max_month = Event.maximum(:timestamp).beginning_of_month.to_date
+
+    # Create the partition bounds based on the existing data. In this example,
+    # we generate an array with the ranges.
+    months = min_month.upto(max_month).uniq(&:beginning_of_month)
+
+    # Rename the existing table.
+    rename_table :events, :old_events
+
+    # Create the partitioned table.
+    create_range_partition :events, partition_key: -> { '(timestamp::DATE)' } do |t|
+      t.string :event_type, null: false
+      t.integer :value, null: false
+      t.datetime :timestamp, null: false
+      t.timestamps
+    end
+
+    # Create the partitions based on the bounds generated before:
+    months.each do |month|
+      # Creates a name like "events_y2018m12"
+      partition_name = "events_y#{month.year}m#{month.month}"
+
+      create_range_partition_of :events,
+        name: partition_name, range_start: month, range_end: month.next_month
+    end
+
+    # Finally, add the rows from the old table to the new partitioned table.
+    # This might take some time depending on the size of your old table.
+    execute(<<~SQL)
+      INSERT INTO events
+      SELECT * FROM old_events
+    SQL
   end
 end
 ```

data/lib/tablature.rb

@@ -2,6 +2,7 @@ require 'tablature/adapters/postgres'
 require 'tablature/command_recorder'
 require 'tablature/configuration'
 require 'tablature/model'
+require 'tablature/partition'
 require 'tablature/partitioned_table'
 require 'tablature/railtie'
 require 'tablature/schema_dumper'
@@ -20,7 +21,7 @@ module Tablature
     ActiveRecord::ConnectionAdapters::AbstractAdapter.include Tablature::Statements
     ActiveRecord::Migration::CommandRecorder.include Tablature::CommandRecorder
     ActiveRecord::SchemaDumper.prepend Tablature::SchemaDumper
-    ActiveRecord::Base.prepend Tablature::Model
+    ActiveRecord::Base.include Tablature::Model
   end
 
   # The current database adapter used by Tablature.
@@ -29,4 +30,10 @@ module Tablature
   def self.database
     configuration.database
   end
+
+  class MissingPartition < StandardError
+    def initialize
+      super('Missing partition')
+    end
+  end
 end

data/lib/tablature/adapters/postgres.rb

@@ -4,6 +4,7 @@ require_relative 'postgres/connection'
 require_relative 'postgres/errors'
 require_relative 'postgres/handlers/list'
 require_relative 'postgres/handlers/range'
+require_relative 'postgres/indexes'
 require_relative 'postgres/partitioned_tables'
 
 module Tablature
@@ -47,7 +48,7 @@ module Tablature
       # @param [String, Symbol] table_name The name of the table to partition.
       # @param [Hash] options The options to create the partition. Keys besides +:partition_key+
       #   will be passed to +create_table+.
-      # @option options [String, Symbol] :partition_key The partition key.
+      # @option options [String, Symbol, #call] :partition_key The partition key.
       # @yield [td] A TableDefinition object. This allows creating the table columns the same way
       #   as Rails's +create_table+ does.
       #
@@ -68,14 +69,44 @@ module Tablature
       # @option options [String, Symbol] :values The values appearing in the partition.
       # @option options [String, Symbol] :name The name of the partition. If it is not given, this
       #   will be randomly generated.
+      # @option options [Boolean] :default Whether the partition is the default partition or not.
       #
       # @example
       #   # With a table :events partitioned using the list method on the partition key `date`:
       #   create_list_partition_of :events, name: "events_2018-W49", values: [
-      #     "2018-12-03", "2018-12-04", "2018-12-05", "2018-12-06", "2018-12-07", "2018-12-08", "2018-12-09"
+      #     "2018-12-03", "2018-12-04", "2018-12-05", "2018-12-06", "2018-12-07", "2018-12-08",
+      #     "2018-12-09"
       #   ]
       delegate :create_list_partition_of, to: :list_handler
 
+      # @!method attach_to_list_partition(parent_table_name, options)
+      # Attaches a partition to a parent by specifying the key values appearing in the partition.
+      #
+      # @param parent_table_name [String, Symbol] The name of the parent table.
+      # @param [Hash] options The options to attach the partition.
+      # @option options [String, Symbol] :name The name of the partition.
+      # @option options [String, Symbol] :values The values appearing in the partition.
+      #
+      # @example
+      #   # With a table :events partitioned using the list method on the partition key `date`:
+      #   attach_to_list_partition :events, name: "events_2018-W49", values: [
+      #     "2018-12-03", "2018-12-04", "2018-12-05", "2018-12-06", "2018-12-07", "2018-12-08",
+      #     "2018-12-09"
+      #   ]
+      delegate :attach_to_list_partition, to: :list_handler
+
+      # @!method detach_from_list_partition(parent_table_name, options)
+      # Detaches a partition from a parent.
+      #
+      # @param parent_table_name [String, Symbol] The name of the parent table.
+      # @param [Hash] options The options to create the partition.
+      # @option options [String, Symbol] :name The name of the partition.
+      #
+      # @example
+      #   # With a table :events partitioned using the list method on the partition key `date`:
+      #   detach_from_list_partition :events, name: "events_2018-W49"
+      delegate :detach_from_list_partition, to: :list_handler
+
       # @!method create_range_partition(table_name, options, &block)
       # Creates a partitioned table using the range partition method.
       #
@@ -84,7 +115,6 @@ module Tablature
       # @param [String, Symbol] table_name The name of the table to partition.
       # @param [Hash] options The options to create the partition. Keys besides +:partition_key+
       #   will be passed to +create_table+.
-      # @option options [String, Symbol] :partition_key The partition key.
       # @yield [td] A TableDefinition object. This allows creating the table columns the same way
       #   as Rails's +create_table+ does.
       #
@@ -103,12 +133,13 @@ module Tablature
       #
       # @param parent_table_name [String, Symbol] The name of the parent table.
       # @param [Hash] options The options to create the partition.
+      # @option options [String, Symbol] :name The name of the partition. If it is not given, this
+      #   will be randomly generated.
       # @option options [String, Symbol] :range_start The start of the range of values appearing in
       #   the partition.
       # @option options [String, Symbol] :range_end The end of the range of values appearing in
       #   the partition.
-      # @option options [String, Symbol] :name The name of the partition. If it is not given, this
-      #   will be randomly generated.
+      # @option options [Boolean] :default Whether the partition is the default partition or not.
       #
       # @example
       #   # With a table :events partitioned using the range method on the partition key `date`:
@@ -116,6 +147,35 @@ module Tablature
       #                                                               range_end: '2018-12-10'
       delegate :create_range_partition_of, to: :range_handler
 
+      # @!method attach_to_range_partition(parent_table_name, options)
+      # Attaches a partition to a parent by specifying the key values appearing in the partition.
+      #
+      # @param parent_table_name [String, Symbol] The name of the parent table.
+      # @param [Hash] options The options to create the partition.
+      # @option options [String, Symbol] :name The name of the partition.
+      # @option options [String, Symbol] :range_start The start of the range of values appearing in
+      #   the partition.
+      # @option options [String, Symbol] :range_end The end of the range of values appearing in
+      #   the partition.
+      # @option options [Boolean] :default Whether the partition is the default partition or not.
+      #
+      # @example
+      #   # With a table :events partitioned using the range method on the partition key `date`:
+      #   attach_to_range_partition :events, name: "events_2018-W49", range_start: '2018-12-03',
+      #                                                               range_end: '2018-12-10'
+      delegate :attach_to_range_partition, to: :range_handler
+
+      # @!method detach_from_range_partition(parent_table_name, options)
+      # Detaches a partition from a parent.
+      #
+      # @param parent_table_name [String, Symbol] The name of the parent table.
+      # @param [Hash] options The options to detach the partition.
+      # @option options [String, Symbol] :name The name of the partition.
+      #
+      # @example
+      #   detach_from_range_partition :events, name: "events_2018-W49"
+      delegate :detach_from_range_partition, to: :range_handler
+
       # Returns an array of partitioned tables in the database.
       #
       # This collection of tables is used by the [Tablature::SchemaDumper] to populate the schema.rb
@@ -126,6 +186,17 @@ module Tablature
         PartitionedTables.new(connection).all
       end
 
+      # Indexes on the Partitioned Table.
+      #
+      # @param name [String] The name of the partitioned table we want indexes from.
+      # @return [Array<ActiveRecord::ConnectionAdapters::IndexDefinition>]
+      def indexes_on(partitioned_table)
+        return [] if Gem::Version.new(Rails.version) >= Gem::Version.new('6.0.3')
+        return [] unless connection.supports_indexes_on_partitioned_tables?
+
+        Indexes.new(connection).on(partitioned_table)
+      end
+
       private
 
       attr_reader :connectable

data/lib/tablature/adapters/postgres/connection.rb

@@ -31,6 +31,20 @@ module Tablature
           postgresql_version >= 110_000
         end
 
+        # True if the connection supports default partitions.
+        #
+        # @return [Boolean]
+        def supports_default_partitions?
+          postgresql_version >= 110_000
+        end
+
+        # True if the connection supports indexes on partitioned tables.
+        #
+        # @return [Boolean]
+        def supports_indexes_on_partitioned_tables?
+          postgresql_version >= 110_000
+        end
+
         # An integer representing the version of Postgres we're connected to.
         #
         # +postgresql_version+ is public in Rails 5, but protected in earlier

data/lib/tablature/adapters/postgres/errors.rb

@@ -1,6 +1,23 @@
 module Tablature
   module Adapters
     class Postgres
+      # Raised when a setting a partition as default  on a database
+      # version that does not support default partitions.
+      #
+      # Default partitions are supported on Postgres 11 or newer.
+      class DefaultPartitionNotSupportedError < StandardError
+        def initialize
+          super('Default partitions require Postgres 11 or newer')
+        end
+      end
+
+      # Raised when trying to attach or detach a partition without supplying a name.
+      class MissingPartitionName < StandardError
+        def initialize
+          super('Missing partition name')
+        end
+      end
+
       # Raised when a list partition operation is attempted on a database
       # version that does not support list partitions.
       #
@@ -15,7 +32,7 @@ module Tablature
       # key.
       class MissingListPartitionValuesError < StandardError
         def initialize
-          super('Missing values for of list partition')
+          super('Missing values for list partition')
         end
       end
 
@@ -33,7 +50,7 @@ module Tablature
       # key.
       class MissingRangePartitionBoundsError < StandardError
         def initialize
-          super('Missing bounds for of range partition')
+          super('Missing bounds for range partition')
         end
       end
     end