pg_trunk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98c9050bc62e8f9a33f87ff77a836189fca018a968ff1fd487f1e5b613b1278f
+  data.tar.gz: 30bcc2a1d61cc3343a95e752d8307c20b1326b57969ac0479a3e4ef161026747
+SHA512:
+  metadata.gz: a4ba64e08cb9a12ce958e1a4a13a88370e4a20e8fe25cf9da19731c5e77ea8d952decabaebd89c6c0af545f34e955f274a768ad28282345e0365ef57f314d69b
+  data.tar.gz: 62289de65886d00d28a979149909839f237afdd9e1144f61710306f4da4258e9487da36e07ef21f46e90b86f63cd6b18a17db59317728eac56ce37524cdbc60a

data/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - "*"
+
+jobs:
+  build:
+    name: Ruby ${{ matrix.ruby }}, Rails ${{ matrix.rails }}, PostgreSQL ${{ matrix.postgres }}
+
+    strategy:
+      fail-fast: true
+      matrix:
+        ruby:
+          - "3.0"
+        rails:
+          - "7.0"
+        postgres:
+          - 10
+          - 11
+          - 12
+          - 13
+          - 14
+        include: # for backward-compatibility
+          - ruby: "2.7"
+            rails: "5.2"
+            postgres: 10
+          - ruby: "3.0"
+            rails: "6.1"
+            postgres: 10
+
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:${{ matrix.postgres }}
+        env:
+          POSTGRES_USER: postgres
+          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"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1.61.1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+
+      - name: Install dependent libraries
+        run: sudo apt-get install libpq-dev
+
+      - 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 PGTrunk
+        run: bin/setup
+
+      - name: Check code style
+        run: bundle exec rubocop
+        continue-on-error: false
+
+      - name: Run tests
+        run: bundle exec rake --trace
+        continue-on-error: false

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/gemfiles/*.gemfile.lock
+/Gemfile.lock
+/tmp/
+.rspec_status

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--require spec_helper
+--order random
+--warning

data/.rubocop.yml

@@ -0,0 +1,92 @@
+---
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.7
+
+Lint/AmbiguousBlockAssociation:
+  IgnoredMethods:
+    - change
+
+# Enable long'n'complex methods in operations
+# because we made those definitions using a DSL
+# which 'regularizes' a code, so we can afford that complexity.
+
+Metrics/BlockLength:
+  # these methods should wrap a lot of definitions by design
+  IgnoredMethods:
+    - class_methods
+    - configure
+    - context
+    - describe
+    - define
+  Exclude:
+    - lib/pg_trunk/operations/**/*.rb
+
+Metrics/AbcSize:
+  Exclude:
+    - lib/pg_trunk/operations/**/*.rb
+
+Metrics/ClassLength:
+  Exclude:
+    - spec/**/*_spec.rb
+    - lib/pg_trunk/operations/**/*.rb
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - lib/pg_trunk/operations/**/*.rb
+
+Metrics/MethodLength:
+  Exclude:
+    - lib/pg_trunk/operations/**/*.rb
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - lib/pg_trunk/operations/**/*.rb
+
+# Enable long modules in specs
+Metrics/ModuleLength:
+  Exclude:
+    - spec/**/*_spec.rb
+
+# Start class definitions from inline
+#   private def initialize(...)
+Style/AccessModifierDeclarations:
+  Enabled: false
+
+# Prefer the following style:
+#
+#   module Foo:Bar # directly accessible from Baz
+#     class Baz
+#       # ...
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# The convention is too opinionated
+Style/DocumentDynamicEvalDefinition:
+  Enabled: false
+
+# The convention is too opinionated
+Style/EmptyCaseCondition:
+  Enabled: false
+
+Style/EmptyMethod:
+  EnforcedStyle: compact
+
+Style/ModuleFunction:
+  EnforcedStyle: extend_self
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/WordArray:
+  Exclude:
+    - spec/features/**/*

data/.yardopts

@@ -0,0 +1,4 @@
+--hide-api private
+--exclude templates
+--markup markdown
+--markup-provider redcarpet

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+The noteworthy changes for each PGTrunk version are included here.
+The format is based on [Keep a Changelog] and this project adheres to [Semantic Versioning].
+For a complete changelog, see the [commits] for each version via the version links.
+
+## [0.1.0] (2022-01-14)
+
+This is a first public release (nepalez)
+
+Supported features:
+
+- tables
+- indexes (separated from tables)
+- check constraints (separated from tables)
+- foreign keys (including multi-column ones)
+- views
+- materialized views
+- functions
+- procedures
+- triggers
+- custom statistics
+- enumerable types
+- composite types
+- domains types
+
+[0.1.0]: https://github.com/nepalez/pg_trunk/releases/tag/v0.1.0
+
+[Keep a Changelog]: http://keepachangelog.com/
+[Semantic Versioning]: http://semver.org/
+[commits]: https://github.com/nepalez/pg_trunk/commits/master

data/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+1. Fork the repository.
+2. Run `bin/setup`, which will install dependencies and create the dummy
+   application database.
+3. Run `rake` to verify that the tests pass against the version of Rails you are
+   running locally, and that the code is styled properly.
+4. Make your change with new passing tests, following the existing style.
+5. Write a [good commit message], push your fork, and submit a pull request.
+6. CI will run the test suite on all configured versions of Ruby and Rails.
+   Address any failures.
+
+[good commit message]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+
+Others will give constructive feedback.  This is a time for discussion and
+improvements, and making the necessary changes will be required before we can
+merge the contribution.

data/Gemfile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in pg_trunk.gemspec
+gemspec
+
+gem "appraisal", "~> 2.3.0"
+gem "bundler", ">= 1.5"
+gem "database_cleaner"
+gem "pg"
+gem "pry"
+gem "pry-byebug"
+gem "rake"
+gem "redcarpet"
+gem "rspec", ">= 3.3"
+gem "rspec-its"
+gem "rubocop"
+gem "rubocop-rake"
+gem "rubocop-rspec"
+gem "test-prof"
+gem "yard"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Andrew Kozin (nepalez)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# PGTrunk
+
+Empower PostgreSQL migrations in Rails app
+
+<a href="https://evilmartians.com/">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+
+[![Gem Version][gem-badger]][gem]
+[![Build Status][build-badger]][build]
+
+PGTrunk adds methods to `ActiveRecord::Migration` to create and manage
+various PostgreSQL objects (like views, functions, triggers, statistics, types etc.)
+in Rails.
+
+This gem is greatly influenced by the [Scenic], [F(x)] and [ActiveRecord::PostgtresEnum] projects
+but takes some steps further.
+
+In addition to support of different objects, we are solving a problem of interdependency between them.
+For example, you can create a table, then a function using its type as an argument,
+then check constraint and index using the function:
+
+```ruby
+create_table "users" do |t|
+  t.text "first_name"
+  t.text "last_name"
+end
+
+# depends on the `users` table
+create_function "full_name(u users) text" do |f|
+  f.volatility :immutable
+  f.strict true
+  f.parallel :safe
+  f.body <<~SQL.strip
+    string_trim(
+      SELECT COALESCE(u.first_name, '') + '.' + COALESCE(u.second_name, ''),
+      '.'
+    )
+  SQL
+end
+
+# both objects below depend on the `users` and `full_name(users)`
+# so they couldn't be placed inside the `create_table` definition in the schema.
+
+create_index "users", "full_name(users.*)", unique: true
+
+# users.full_name is the PostgreSQL alternative syntax for the `full_name(users.*)`
+create_check_constraint "users", "length(users.full_name) > 0", name: "full_name_present"
+```
+
+Notice, that we had to separate definitions of indexes and check constraints from tables,
+because there can be other objects (like functions or types) squeezing between them.
+
+Another difference from aforementioned gems is that we explicitly register
+all objects created by migrations in the special table (`pg_trunk`).
+This let us distinct objects created by "regular" migration from temporary ones
+added manually and exclude the latter from the schema. We bind any object
+to a particular version of migration which added it. That's how only those
+objects that belong to the current branch are dumped into the `schema.rb`.
+
+As of today we support creation, modification and dropping the following objects:
+
+- tables
+- indexes
+- foreign keys (including multi-column ones)
+- check constraints
+- views
+- materialized views
+- functions
+- procedures
+- triggers
+- custom statistics
+- enumerable types
+- composite types
+- domains types
+
+For `tables` and `indexes` we reuse the ActiveRecord's native methods.
+For `check constraints` and `foreign keys` we support both the native definitions inside the table
+and standalone methods (like `create_foreign_key`) with additional features.
+The other methods are implemented from scratch.
+
+In the future other objects like aggregate functions, range types, operators, collations, and more
+will be supported.
+
+From now and on we support all versions of PostgreSQL since v10.
+
+The gem is targeted to support PostgreSQL-specific features, that's why we won't provide adapters to other databases like [Scenic] does.
+
+## Documentation
+
+The gem provides a lot of additional methods to create, rename, change a drop various objects.
+You can find the necessary details in the gem's [wiki].
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pg_trunk'
+```
+
+And then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install pg_trunk
+```
+
+Add the line somewhere in your ruby code:
+
+```ruby
+require "pg_trunk"
+```
+
+## 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.
+
+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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at `https://github.com/nepalez/pg_trunk`.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License].
+
+[build-badger]: https://github.com/nepalez/pg_trunk/workflows/CI/badge.svg
+[build]: https://github.com/nepalez/pg_trunk/actions?query=workflow%3ACI+branch%3Amaster
+[gem-badger]: https://img.shields.io/gem/v/pg_trunk.svg?style=flat
+[gem]: https://rubygems.org/gems/pg_trunk
+[MIT License]: https://opensource.org/licenses/MIT
+[Scenic]: https://github.com/scenic-views/scenic
+[F(x)]: https://github.com/teoljungberg/fx
+[ActiveRecord::PostgtresEnum]: https://github.com/bibendi/activerecord-postgres_enum
+[wiki]: https://github.com/nepalez/pg_trunk/wiki

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+namespace :dummy do
+  require_relative "spec/dummy/config/application"
+  Dummy::Application.load_tasks
+end
+
+task(:spec).clear
+desc "Run specs"
+RSpec::Core::RakeTask.new(:spec) { |task| task.verbose = false }
+
+desc "Run the specs on the dummy database"
+task default: %w[dummy:db:reset spec]

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "pg_trunk"
+require "pry"
+
+Pry.start

data/bin/rake

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||=
+  File.expand_path("../../Gemfile", Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+# noinspection RubyResolve
+load Gem.bin_path("rake", "rake")

data/bin/rspec

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||=
+  File.expand_path("../../Gemfile", Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+# noinspection RubyResolve
+load Gem.bin_path("rspec-core", "rspec")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/yard

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'yard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||=
+  File.expand_path("../../Gemfile", Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+# noinspection RubyResolve
+load Gem.bin_path("yard", "yard")

data/lib/pg_trunk/core/adapters/postgres.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PGTrunk
+  # @private
+  # PGTrunk database adapters.
+  #
+  # PGTrunk ships with a Postgres adapter only,
+  # with interface implemented as +PGTrunk::Adapters::Postgres+.
+  #
+  module Adapters
+    # Creates an instance of the PGTrunk Postgres adapter.
+    # This is the only supported adapter for PGTrunk.
+    #
+    # @param [#connection] connectable An object that returns the connection
+    #   for PGTrunk to use. Defaults to `ActiveRecord::Base`.
+    #
+    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.
+      #
+      # @private
+      class Connection < SimpleDelegator
+        def server_version
+          raw_connection.server_version.to_s
+        end
+
+        # Expose private method helpers
+
+        def check_constraint_name(table, expression)
+          __getobj__.send(
+            :check_constraint_name,
+            table,
+            expression: expression,
+          )
+        end
+
+        def strip_table_name(table)
+          __getobj__.send(:strip_table_name_prefix_and_suffix, table)
+        end
+      end
+
+      # Execute operation by its definition
+      # @param [Class < PgExtra::Operation] operation
+      def execute_operation(operation)
+        query = operation.to_sql(server_version)
+        connection.execute(query) if query
+      end
+
+      def dumper
+        # This instance is used to dump the table
+        # using its name extracted from the database.
+        # That's why we can skip prefix/suffix definitions
+        # in the parameters of the constructor.
+        @dumper ||= connection.create_schema_dumper({})
+      end
+
+      private
+
+      attr_reader :connectable
+
+      def connection
+        @connection ||= Connection.new(ActiveRecord::Base.connection)
+      end
+
+      def respond_to_missing?(symbol, *)
+        connection.respond_to?(symbol, true)
+      end
+
+      def method_missing(symbol, *args, **opts, &block)
+        super unless connection.respond_to?(symbol, true)
+
+        connection.send(symbol, *args, **opts, &block)
+      end
+    end
+  end
+end