tablature 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a380696b917f7e478ea8823e9f9cd5fd0d1d77fbdfc540653d07fe7fc757922
-  data.tar.gz: 7bb88dc5ecc00fcba4c2fcb59a081bd89d183512bb9813287357e8bb54b4bdae
+  metadata.gz: 78e1704fd9d861cc494afaea95d8b823cd9067ff7100215fee67a80fd3a6ed8c
+  data.tar.gz: d4cbb87e57da6eca06be82239cd9f2ed57e0ddfedc64313f7d065b72b63d12e4
 SHA512:
-  metadata.gz: c18d7668835780d2df9b692b53ae81f2fb81eb16d26c2f2a4bf45cfb77f519e9b5c7f9cbd591c6a246f29d321f3c77187fa52a471af796b50a3b1142cd8fb5bc
-  data.tar.gz: 3f4aa6a40d39775bf14a714bc025f4d0d50d5395ba8e4c3e10c6616401b00ab160f1d1cf29108fec628eb6ffff4f9a5ea91082e6282c95eba4d8e9a7679f9b77
+  metadata.gz: ccaf49c24f56fd9dedc98c852fb7c0e79b90b80cb56822257c8ae3068d23afc5b0e116b3f3f09491c2f0f0a17d2d474ace5038e3907747b3a8fce193eb7c36b7
+  data.tar.gz: af0ac14e53c058c9c69700e9f8ce8e8195935ec4fa2719212243fec0ed6a93827f10807dfccc65c83dff0145241b389dc3db3a5b28a5938242bf2bd377e58345

data/.circleci/config.yml

@@ -0,0 +1,81 @@
+# TODO: Simplify this
+version: 2
+jobs:
+  postgres_10:
+    working_directory: ~/tablature-rb
+    docker:
+      - image: circleci/ruby:2.4
+        environment:
+          DATABASE_URL: "postgres://postgres@localhost:5432/dummy_test"
+      - image: circleci/postgres:10-alpine
+        environment:
+          POSTGRES_USER: postgres
+          POSTGRES_DB: dummy_test
+          POSTGRES_PASSWORD: ""
+    steps:
+      - checkout
+
+      - type: cache-restore
+        name: Restore bundle cache
+        key: tablature-{{ checksum "tablature.gemspec" }}-{{ checksum "Gemfile" }}
+
+      - run:
+          name: Install dependencies
+          command: bundle install --path vendor/bundle
+
+      - type: cache-save
+        name: Store bundle cache
+        key: tablature-{{ checksum "tablature.gemspec" }}-{{ checksum "Gemfile" }}
+        paths:
+          - vendor/bundle
+
+      - run:
+          name: Wait for Postgres
+          command: dockerize -wait tcp://localhost:5432 -timeout 1m
+
+      - run:
+          name: Run tests
+          command: bundle exec rspec --tag ~postgres_11
+
+  postgres_11:
+    working_directory: ~/tablature-rb
+    docker:
+      - image: circleci/ruby:2.4
+        environment:
+          DATABASE_URL: "postgres://postgres@localhost:5432/dummy_test"
+      - image: circleci/postgres:11-alpine
+        environment:
+          POSTGRES_USER: postgres
+          POSTGRES_DB: dummy_test
+          POSTGRES_PASSWORD: ""
+    steps:
+      - checkout
+
+      - type: cache-restore
+        name: Restore bundle cache
+        key: tablature-{{ checksum "tablature.gemspec" }}-{{ checksum "Gemfile" }}
+
+      - run:
+          name: Install dependencies
+          command: bundle install --path vendor/bundle
+
+      - type: cache-save
+        name: Store bundle cache
+        key: tablature-{{ checksum "tablature.gemspec" }}-{{ checksum "Gemfile" }}
+        paths:
+          - vendor/bundle
+
+      - run:
+          name: Wait for Postgres
+          command: dockerize -wait tcp://localhost:5432 -timeout 1m
+
+      - run:
+          name: Run tests
+          command: bundle exec rspec
+
+workflows:
+  version: 2
+  tablature:
+    jobs:
+      - postgres_10
+      - postgres_11

data/.rubocop.yml

@@ -1,3 +1,6 @@
+AllCops:
+  TargetRubyVersion: 2.3
+
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'

data/Gemfile

@@ -1 +1,3 @@
 gemspec
+
+gem 'pry'

data/Gemfile.lock

@@ -1,46 +1,48 @@
 PATH
   remote: .
   specs:
-    tablature (0.0.1)
+    tablature (0.1.0)
       activerecord (>= 5.0.0)
       railties (>= 5.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (5.2.1)
-      actionview (= 5.2.1)
-      activesupport (= 5.2.1)
+    actionpack (5.2.2)
+      actionview (= 5.2.2)
+      activesupport (= 5.2.2)
       rack (~> 2.0)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.2.1)
-      activesupport (= 5.2.1)
+    actionview (5.2.2)
+      activesupport (= 5.2.2)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activemodel (5.2.1)
-      activesupport (= 5.2.1)
-    activerecord (5.2.1)
-      activemodel (= 5.2.1)
-      activesupport (= 5.2.1)
+    activemodel (5.2.2)
+      activesupport (= 5.2.2)
+    activerecord (5.2.2)
+      activemodel (= 5.2.2)
+      activesupport (= 5.2.2)
       arel (>= 9.0)
-    activesupport (5.2.1)
+    activesupport (5.2.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
     arel (9.0.0)
     builder (3.2.3)
+    coderay (1.1.2)
     concurrent-ruby (1.1.3)
     crass (1.0.4)
+    database_cleaner (1.7.0)
     diff-lcs (1.3)
     erubi (1.7.1)
     i18n (1.1.1)
       concurrent-ruby (~> 1.0)
-    loofah (2.2.2)
+    loofah (2.2.3)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     method_source (0.9.0)
@@ -49,6 +51,9 @@ GEM
     nokogiri (1.8.5)
       mini_portile2 (~> 2.3.0)
     pg (0.21.0)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
     rack (2.0.6)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
@@ -57,9 +62,9 @@ GEM
       nokogiri (>= 1.6)
     rails-html-sanitizer (1.0.4)
       loofah (~> 2.2, >= 2.2.2)
-    railties (5.2.1)
-      actionpack (= 5.2.1)
-      activesupport (= 5.2.1)
+    railties (5.2.2)
+      actionpack (= 5.2.2)
+      activesupport (= 5.2.2)
       method_source
       rake (>= 0.8.7)
       thor (>= 0.19.0, < 2.0)
@@ -79,7 +84,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.1)
-    thor (0.20.0)
+    thor (0.20.3)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
@@ -89,7 +94,9 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.16)
+  database_cleaner
   pg (~> 0.19)
+  pry
   rake (~> 10.0)
   rspec (~> 3.0)
   rspec-instafail

data/README.md

@@ -1,11 +1,20 @@
 # Tablature
 
+Tablature is a library built on top of ActiveRecord to simplify management of partitioned tables in Rails applications.
+It ships with Postgres support and can easily supports other databases through adapters.
+
 ## Installation
 
+##### Requirements
+
+Tablature requires Rails 5+ and Postgres 10+.
+
+##### Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'tablature', github: 'aliou/tablature'
+gem 'tablature'
 ```
 
 And then execute:
@@ -18,15 +27,56 @@ Or install it yourself as:
 
 ## Usage
 
+### Partitioning a table
+
+```ruby
+class CreateEvents < ActiveRecord::Migration[5.0]
+  def up
+    # Create the events table as a partitioned table using range as partitioning method
+    # and `event_date` as partition key.
+    create_range_partition :events_by_range, partition_key: 'event_date' do |t|
+      t.string :event_type, null: false
+      t.integer :value, null: false
+      t.date :event_date, null: false
+    end
+
+    # Create partitions with the bounds of the partition.
+    create_range_partition_of :events_by_range,
+      name: 'events_range_y2018m12', range_start: '2018-12-01', range_end: '2019-01-01'
+
+    # Create the events table as a partitioned table using list as partitioning method
+    # and `event_date` as partition key.
+    create_list_partition :events_by_list, partition_key: 'event_date' do |t|
+      t.string :event_type, null: false
+      t.integer :value, null: false
+      t.date :event_date, null: false
+    end
+
+    # 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
+  end
+end
+```
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Acknowledgements
+Tablature's structure is heavily inspired by [Scenic](https://github.com/scenic-views/scenic) and [F(x)](http://github.com/teoljungberg/fx).
+Tablature's features are heavily inspired by [PgParty](https://github.com/rkrage/pg_party).
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/tablature.
+Bug reports and pull requests are welcome on GitHub at https://github.com/aliou/tablature.
 
 ## License
 

data/Rakefile

@@ -3,4 +3,9 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
+namespace :dummy do
+  require_relative 'spec/dummy/config/application'
+  Dummy::Application.load_tasks
+end
+
 task default: :spec

data/bin/console

@@ -3,12 +3,8 @@
 require 'bundler/setup'
 require 'tablature'
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
+# Require the dummy test app in the console.
+require File.expand_path('spec/dummy/config/environment')
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start(__FILE__)
+require 'pry'
+Pry.start

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

@@ -0,0 +1,56 @@
+module Tablature
+  module Adapters
+    class Postgres
+      # Decorates an ActiveRecord connection with methods that help determine
+      # the connections capabilities.
+      #
+      # Every attempt is made to use the versions of these methods defined by
+      # Rails where they are available and public before falling back to our own
+      # implementations for older Rails versions.
+      #
+      # @api private
+      class Connection < SimpleDelegator
+        # True if the connection supports range partitions.
+        #
+        # @return [Boolean]
+        def supports_range_partitions?
+          postgresql_version >= 100_000
+        end
+
+        # True if the connection supports list partitions.
+        #
+        # @return [Boolean]
+        def supports_list_partitions?
+          postgresql_version >= 100_000
+        end
+
+        # True if the connection supports hash partitions.
+        #
+        # @return [Boolean]
+        def supports_hash_partitions?
+          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
+        # versions.
+        #
+        # @return [Integer]
+        def postgresql_version
+          if undecorated_connection.respond_to?(:postgresql_version)
+            super
+          else
+            undecorated_connection.send(:postgresql_version)
+          end
+        end
+
+        private
+
+        def undecorated_connection
+          __getobj__
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+module Tablature
+  module Adapters
+    class Postgres
+      # Raised when a list partition operation is attempted on a database
+      # version that does not support list partitions.
+      #
+      # List partitions are supported on Postgres 10 or newer.
+      class ListPartitionsNotSupportedError < StandardError
+        def initialize
+          super('List partitions require Postgres 10 or newer')
+        end
+      end
+
+      # Raised when trying to create a list partition without specifying the values of the partition
+      # key.
+      class MissingListPartitionValuesError < StandardError
+        def initialize
+          super('Missing values for of list partition')
+        end
+      end
+
+      # Raised when a range partition operation is attempted on a database
+      # version that does not support range partitions.
+      #
+      # Range partitions are supported on Postgres 10 or newer.
+      class RangePartitionsNotSupportedError < StandardError
+        def initialize
+          super('Range partitions require Postgres 10 or newer')
+        end
+      end
+
+      # Raised when trying to create a range partition without specifying the range of the partition
+      # key.
+      class MissingRangePartitionBoundsError < StandardError
+        def initialize
+          super('Missing bounds for of range partition')
+        end
+      end
+    end
+  end
+end

data/lib/tablature/adapters/postgres/handlers/base.rb

@@ -0,0 +1,43 @@
+require 'tablature/adapters/postgres/quoting'
+require 'tablature/adapters/postgres/uuid'
+
+module Tablature
+  module Adapters
+    class Postgres
+      # @api private
+      module Handlers
+        # @api private
+        class Base
+          include Postgres::Quoting
+          include Postgres::UUID
+
+          protected
+
+          def create_partition(table_name, id_options, table_options, &block)
+            create_table(table_name, table_options) do |td|
+              # TODO: Handle the id things here (depending on the postgres version)
+              if id_options[:type] == :uuid
+                td.column(
+                  id_options[:column_name], id_options[:type], null: false, default: uuid_function
+                )
+              elsif id_options[:type]
+                td.column(id_options[:column_name], id_options[:type], null: false)
+              end
+
+              yield(td) if block.present?
+            end
+          end
+
+          def extract_primary_key!(options)
+            type = options.fetch(:id, :bigserial)
+            column_name = options.fetch(:primary_key, :id)
+
+            raise ArgumentError, 'composite primary key not supported' if column_name.is_a?(Array)
+
+            { type: type, column_name: column_name }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tablature/adapters/postgres/handlers/list.rb

@@ -0,0 +1,66 @@
+require_relative 'base'
+
+module Tablature
+  module Adapters
+    class Postgres
+      module Handlers
+        # @api private
+        class List < Base
+          def initialize(connection)
+            @connection = connection
+          end
+
+          def create_list_partition(table_name, options, &block)
+            raise_unless_list_partition_supported
+
+            # Postgres 10 does not handle indexes and therefore primary keys.
+            # Therefore we manually create an `id` column.
+            # TODO: Either make the library Postgres 11 only, or two code paths between Postgres 10
+            # and Postgres 11.
+            modified_options = options.except(:id, :primary_key, :partition_key)
+            id_options = extract_primary_key!(options.slice(:id, :primary_key))
+            partition_key = options.fetch(:partition_key)
+
+            modified_options[:id]      = false
+            modified_options[:options] = "PARTITION BY LIST (#{quote_partition_key(partition_key)})"
+
+            create_partition(table_name, id_options, modified_options, &block)
+          end
+
+          def create_list_partition_of(parent_table, options)
+            values = options.fetch(:values, [])
+            raise MissingListPartitionValuesError if values.blank?
+
+            name = options.fetch(:name, partition_name(parent_table, values))
+            # TODO: Call `create_table` here instead of running the query.
+            # TODO: Pass the options to `create_table` to allow further configuration of the table,
+            # e.g. sub-partitioning the table.
+            query = <<~SQL.strip
+              CREATE TABLE #{quote_table_name(name)} PARTITION OF #{quote_table_name(parent_table)}
+              FOR VALUES IN (#{quote_collection(values)})
+            SQL
+
+            execute(query)
+          end
+
+          private
+
+          attr_reader :connection
+
+          delegate :execute, :quote, :quote_column_name, :quote_table_name, :create_table,
+                   to: :connection
+
+          def raise_unless_list_partition_supported
+            raise ListPartitionsNotSupportedError unless connection.supports_list_partitions?
+          end
+
+          # TODO: Better ?
+          def partition_name(parent_table, values)
+            key = values.inspect
+            "#{parent_table}_#{Digest::MD5.hexdigest(key)[0..6]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tablature/adapters/postgres/handlers/range.rb

@@ -0,0 +1,68 @@
+require_relative 'base'
+
+module Tablature
+  module Adapters
+    class Postgres
+      module Handlers
+        # @api private
+        class Range < Base
+          def initialize(connection)
+            @connection = connection
+          end
+
+          def create_range_partition(table_name, options, &block)
+            raise_unless_range_partition_supported
+
+            # Postgres 10 does not handle indexes and therefore primary keys.
+            # Therefore we manually create an `id` column.
+            # TODO: Either make the library Postgres 11 only, or two code paths between Postgres 10
+            # and Postgres 11.
+            modified_options = options.except(:id, :primary_key, :partition_key)
+            id_options = extract_primary_key!(options.slice(:id, :primary_key))
+            partition_key = options.fetch(:partition_key)
+
+            modified_options[:id]      = false
+            modified_options[:options] =
+              "PARTITION BY RANGE (#{quote_partition_key(partition_key)})"
+
+            create_partition(table_name, id_options, modified_options, &block)
+          end
+
+          def create_range_partition_of(parent_table, options)
+            range_start = options.fetch(:range_start, nil)
+            range_end = options.fetch(:range_end, nil)
+
+            raise MissingRangePartitionBoundsError if range_start.nil? || range_end.nil?
+
+            name = options.fetch(:name, partition_name(parent_table, range_start, range_end))
+            # TODO: Call `create_table` here instead of running the query.
+            # TODO: Pass the options to `create_table` to allow further configuration of the table,
+            # e.g. sub-partitioning the table.
+            query = <<~SQL.strip
+              CREATE TABLE #{quote_table_name(name)} PARTITION OF #{quote_table_name(parent_table)}
+              FOR VALUES FROM (#{quote(range_start)}) TO (#{quote(range_end)});
+            SQL
+
+            execute(query)
+          end
+
+          private
+
+          attr_reader :connection
+
+          delegate :execute, :quote, :quote_column_name, :quote_table_name, :create_table,
+                   to: :connection
+
+          def raise_unless_range_partition_supported
+            raise RangePartitionsNotSupportedError unless connection.supports_range_partitions?
+          end
+
+          def partition_name(parent_table, range_start, range_end)
+            key = [range_start, range_end].join(', ')
+            "#{parent_table}_#{Digest::MD5.hexdigest(key)[0..6]}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+module Tablature
+  module Adapters
+    class Postgres
+      # Fetches the defined partitioned tables from the postgres connection.
+      # @api private
+      class PartitionedTables
+        def initialize(connection)
+          @connection = connection
+        end
+
+        # All of the partitioned table that this connection has defined.
+        #
+        # @return [Array<Tablature::PartitionedTable>]
+        def all
+          partitions.group_by { |row| row['table_name'] }.map(&method(:to_tablature_table))
+        end
+
+        private
+
+        attr_reader :connection
+
+        def partitions
+          connection.execute(<<-SQL)
+            SELECT
+              c.oid,
+              c.relname AS table_name,
+              p.partstrat AS type,
+              (i.inhrelid::REGCLASS)::TEXT AS partition_name
+            FROM pg_class c
+              INNER JOIN pg_partitioned_table p ON c.oid = p.partrelid
+              LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
+              FULL OUTER JOIN pg_catalog.pg_inherits i ON c.oid = i.inhparent
+            WHERE
+              p.partstrat IN ('l', 'r', 'h')
+              AND c.relname NOT IN (SELECT extname FROM pg_extension)
+              AND n.nspname = ANY (current_schemas(false))
+            ORDER BY c.oid
+          SQL
+        end
+
+        METHOD_MAP = {
+          'l' => :list,
+          'r' => :range,
+          'h' => :hash
+        }.freeze
+        private_constant :METHOD_MAP
+
+        def to_tablature_table(table_name, rows)
+          result = rows.first
+          partioning_method = METHOD_MAP.fetch(result['type'])
+          partitions = rows.map { |row| row['partition_name'] }.compact
+
+          Tablature::PartitionedTable.new(
+            name: table_name, partioning_method: partioning_method, partitions: partitions
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Tablature
+  module Adapters
+    class Postgres
+      # @api private
+      module Quoting
+        def quote_partition_key(key)
+          key.to_s.split('::').map(&method(:quote_column_name)).join('::')
+        end
+
+        def quote_collection(values)
+          Array.wrap(values).map(&method(:quote)).join(',')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Tablature
+  module Adapters
+    class Postgres
+      # @api private
+      module UUID
+        def uuid_function
+          try(:supports_pgcrypto_uuid?) ? 'gen_random_uuid()' : 'uuid_generate_v4()'
+        end
+      end
+    end
+  end
+end

data/lib/tablature/adapters/postgres.rb

@@ -1,3 +1,11 @@
+require 'active_support/core_ext/module/delegation'
+
+require_relative 'postgres/connection'
+require_relative 'postgres/errors'
+require_relative 'postgres/handlers/list'
+require_relative 'postgres/handlers/range'
+require_relative 'postgres/partitioned_tables'
+
 module Tablature
   # Tablature database adapters.
   #
@@ -7,7 +15,7 @@ module Tablature
   module Adapters
     # An adapter for managing Postgres views.
     #
-    # These methods are used interally by Tablature and are not intended for direct
+    # These methods are used internally by Tablature and are not intended for direct
     # use. Methods that alter database schema are intended to be called via
     # {Statements}.
     #
@@ -21,7 +29,7 @@ module Tablature
       # would explicitly set it.
       #
       # @param [#connection] connectable An object that returns the connection
-      #   for Tablature to use. Defaults to `ActiveRecord::Base`.
+      #   for Tablature to use. Defaults to +ActiveRecord::Base+.
       #
       # @example
       #  Tablature.configure do |config|
@@ -30,6 +38,109 @@ module Tablature
       def initialize(connectable = ActiveRecord::Base)
         @connectable = connectable
       end
+
+      # @!method create_list_partition(table_name, options, &block)
+      # Creates a partitioned table using the list partition method.
+      #
+      # This is called in a migration via {Statements#create_list_partition}.
+      #
+      # @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.
+      #
+      # @example
+      #   create_list_partition :events, partition_key: :id
+      #
+      # @example
+      #   create_list_partition :events, partition_key: :date do |t|
+      #     t.date :date, null: false
+      #   end
+      delegate :create_list_partition, to: :list_handler
+
+      # @!method create_list_partition_of(parent_table_name, options)
+      # Creates a partition of 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] :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.
+      #
+      # @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"
+      #   ]
+      delegate :create_list_partition_of, to: :list_handler
+
+      # @!method create_range_partition(table_name, options, &block)
+      # Creates a partitioned table using the range partition method.
+      #
+      # This is called in a migration via {Statements#create_range_partition}.
+      #
+      # @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.
+      #
+      # @example
+      #   create_range_partition :events, partition_key: :id
+      #
+      # @example
+      #   create_range_partition :events, partition_key: :date do |t|
+      #     t.date :date, null: false
+      #   end
+      delegate :create_range_partition, to: :range_handler
+
+      # @!method create_range_partition_of(parent_table_name, options)
+      # Creates a partition of a parent by specifying the bound of the 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] :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.
+      #
+      # @example
+      #   # With a table :events partitioned using the range method on the partition key `date`:
+      #   create_range_partition_of :events, name: "events_2018-W49", range_start: '2018-12-03',
+      #                                                               range_end: '2018-12-10'
+      delegate :create_range_partition_of, 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
+      # file.
+      #
+      # @return [Array<Tablature::PartitionedTable]
+      def partitioned_tables
+        PartitionedTables.new(connection).all
+      end
+
+      private
+
+      attr_reader :connectable
+
+      def connection
+        Connection.new(connectable.connection)
+      end
+
+      def list_handler
+        @list_handler ||= Handlers::List.new(connection)
+      end
+
+      def range_handler
+        @range_handler ||= Handlers::Range.new(connection)
+      end
     end
   end
 end

data/lib/tablature/command_recorder.rb

@@ -0,0 +1,4 @@
+module Tablature
+  module CommandRecorder
+  end
+end

data/lib/tablature/configuration.rb

@@ -26,11 +26,10 @@ module Tablature
   # Modify Tablature's current configuration
   #
   # @yieldparam [Tablature::Configuration] config current Tablature config
-  # ```
-  # Tablature.configure do |config|
-  #   config.database = Tablature::Adapters::Postgres.new
-  # end
-  # ```
+  # @example
+  #   Tablature.configure do |config|
+  #     config.database = Tablature::Adapters::Postgres.new
+  #   end
   def self.configure
     yield configuration
   end

data/lib/tablature/model.rb

@@ -0,0 +1,4 @@
+module Tablature
+  module Model
+  end
+end

data/lib/tablature/partitioned_table.rb

@@ -0,0 +1,33 @@
+module Tablature
+  # The in-memory representation of a partitioned table definition.
+  #
+  # **This object is used internally by adapters and the schema dumper and is
+  # not intended to be used by application code. It is documented here for
+  # use by adapter gems.**
+  #
+  # @api extension
+  class PartitionedTable
+    # The name of the partitioned table
+    # @return [String]
+    attr_reader :name
+
+    # The partitioning method of the table
+    # @return [Symbol]
+    attr_reader :partioning_method
+
+    # The partitions of the table.
+    # @return [Array]
+    attr_reader :partitions
+
+    # Returns a new instance of PartitionTable.
+    #
+    # @param name [String] The name of the view.
+    # @param partioning_method [:symbol] One of :range, :list or :hash
+    # @param partitions [Array] The partitions of the table.
+    def initialize(name:, partioning_method:, partitions: [])
+      @name = name
+      @partioning_method = partioning_method
+      @partitions = partitions
+    end
+  end
+end

data/lib/tablature/schema_dumper.rb

@@ -0,0 +1,22 @@
+module Tablature
+  # @api private
+  module SchemaDumper
+    def tables(stream)
+      # Add partitions to the list of ignored tables.
+      ActiveRecord::SchemaDumper.ignore_tables =
+        (ActiveRecord::SchemaDumper.ignore_tables || []) + partitions
+
+      super
+    end
+
+    private
+
+    def dumpable_partitioned_tables
+      Tablature.database.partitioned_tables
+    end
+
+    def partitions
+      dumpable_partitioned_tables.flat_map(&:partitions)
+    end
+  end
+end

data/lib/tablature/statements.rb

@@ -0,0 +1,57 @@
+module Tablature
+  # Methods that are made available in migrations.
+  module Statements
+    # Creates a partitioned table using the list partition method.
+    #
+    # @param name [String, Symbol] The name of the partition.
+    # @param options [Hash] The options to create the partition.
+    # @yield [td] A TableDefinition object. This allows creating the table columns the same way
+    #   as Rails's +create_table+ does.
+    # @see Tablature::Adapters::Postgres#create_list_partition
+    def create_list_partition(name, options, &block)
+      raise ArgumentError, 'partition_key must be defined' if options[:partition_key].nil?
+
+      Tablature.database.create_list_partition(name, options, &block)
+    end
+
+    # Creates a partition of 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.
+    #
+    # @see Tablature::Adapters::Postgres#create_list_partition_of
+    def create_list_partition_of(parent_table_name, options)
+      raise ArgumentError, 'values must be defined' if options[:values].nil?
+
+      Tablature.database.create_list_partition_of(parent_table_name, options)
+    end
+
+    # Creates a partitioned table using the range partition method.
+    #
+    # @param name [String, Symbol] The name of the partition.
+    # @param options [Hash] The options to create the partition.
+    # @yield [td] A TableDefinition object. This allows creating the table columns the same way
+    #   as Rails's +create_table+ does.
+    #
+    # @see Tablature::Adapters::Postgres#create_range_partition
+    def create_range_partition(name, options, &block)
+      raise ArgumentError, 'partition_key must be defined' if options[:partition_key].nil?
+
+      Tablature.database.create_range_partition(name, options, &block)
+    end
+
+    # Creates a partition of 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.
+    #
+    # @see Tablature::Adapters::Postgres#create_range_partition_of
+    def create_range_partition_of(parent_table, options)
+      if options[:range_start].nil? || options[:range_end].nil?
+        raise ArgumentError, 'range_start and range_end must be defined'
+      end
+
+      Tablature.database.create_range_partition_of(parent_table, options)
+    end
+  end
+end

data/lib/tablature/version.rb

@@ -1,3 +1,3 @@
 module Tablature
-  VERSION = '0.0.1'.freeze
+  VERSION = '0.1.0'.freeze
 end

data/lib/tablature.rb

@@ -1,16 +1,31 @@
 require 'tablature/adapters/postgres'
+require 'tablature/command_recorder'
 require 'tablature/configuration'
+require 'tablature/model'
+require 'tablature/partitioned_table'
 require 'tablature/railtie'
+require 'tablature/schema_dumper'
+require 'tablature/statements'
 require 'tablature/version'
 
 require 'active_record'
 
-# Tablature adds methods to `ActiveRecord::Migration` to create and manage database
-# views in Rails applications.
+# Tablature adds methods to `ActiveRecord::Migration` to create and manage partitioned
+# tables in Rails applications.
 module Tablature
+  # Hooks Tablature into Rails.
+  #
+  # Enables tablature migration methods.
   def self.load
+    ActiveRecord::ConnectionAdapters::AbstractAdapter.include Tablature::Statements
+    ActiveRecord::Migration::CommandRecorder.include Tablature::CommandRecorder
+    ActiveRecord::SchemaDumper.prepend Tablature::SchemaDumper
+    ActiveRecord::Base.prepend Tablature::Model
   end
 
+  # The current database adapter used by Tablature.
+  #
+  # This defaults to {Adapters::Postgres} by can be overriden via {Configuration}.
   def self.database
     configuration.database
   end

data/tablature.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = 'Rails + Postgres Partitions'
   spec.description   = 'Rails + Postgres Partitions'
-  spec.homepage      = "https://aliou.me"
+  spec.homepage      = 'https://aliou.me'
   spec.license       = 'MIT'
 
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
@@ -21,10 +21,11 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'database_cleaner'
+  spec.add_development_dependency 'pg', '~> 0.19'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rspec-instafail'
-  spec.add_development_dependency 'pg', '~> 0.19'
 
   spec.add_dependency 'activerecord', '>= 5.0.0'
   spec.add_dependency 'railties', '>= 5.0.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tablature
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Aliou Diallo
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-01 00:00:00.000000000 Z
+date: 2018-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -66,20 +94,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: pg
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.19'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.19'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -115,6 +129,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/config.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -128,8 +143,21 @@ files:
 - bin/setup
 - lib/tablature.rb
 - lib/tablature/adapters/postgres.rb
+- lib/tablature/adapters/postgres/connection.rb
+- lib/tablature/adapters/postgres/errors.rb
+- lib/tablature/adapters/postgres/handlers/base.rb
+- lib/tablature/adapters/postgres/handlers/list.rb
+- lib/tablature/adapters/postgres/handlers/range.rb
+- lib/tablature/adapters/postgres/partitioned_tables.rb
+- lib/tablature/adapters/postgres/quoting.rb
+- lib/tablature/adapters/postgres/uuid.rb
+- lib/tablature/command_recorder.rb
 - lib/tablature/configuration.rb
+- lib/tablature/model.rb
+- lib/tablature/partitioned_table.rb
 - lib/tablature/railtie.rb
+- lib/tablature/schema_dumper.rb
+- lib/tablature/statements.rb
 - lib/tablature/version.rb
 - tablature.gemspec
 homepage: https://aliou.me