arfi 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ed9672d7951cb9d1aeb28fe390ee92fff1664b4bdfa56a52196c0595df272d2
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: 40e55ca1e1481bb0b4e2c0e52dba409acee9cab6dc52b175c8ea07c43a8ff480
+  data.tar.gz: 54cf735abda9f80045e1d5dd182993fdbe3b9a82f4b1280a5bd0f9ca96664551
 SHA512:
-  metadata.gz: d9f5254996cf000979cc431862f6aedccb6599c277dccc5fd03e1052163a1c0aa7ee42a12e89b1925c867ba458fb93087e972cfe8a330a9b3547bedd70227d6d
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: 47e45b99ccccac4149e6fe340b72ff1a418c245fb6f151890d473c2ef18c0ef7d435e0faf95483cafbeee64478db2d1265281dc1fff8a8b32f0a39a9df10caa4
+  data.tar.gz: 6c008777c326d7f15afab77e1a6473ce6a4f94525898e2392d55664ff5d6b4213d2ed5a06050fdfd44a9e8f183cb66278bd17e832b15f4b256591129a73c95eb

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,9 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+    - lib/arfi/extensions/active_record/connection_adapters/postgresql/database_statements.rb
+    - 'vendor/**/*'
+
+Gemspec/DevelopmentDependencies:
+  EnforcedStyle: gemspec

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-04-22
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 daniil.lyubimcev
+
+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,267 @@
+# ARFI
+
+![Build status](https://img.shields.io/github/actions/workflow/status/unurgunite/arfi/main.yml "Build status")
+[![Gem Version](https://badge.fury.io/rb/arfi.svg)](https://badge.fury.io/rb/arfi)
+
+![Alt](https://repobeats.axiom.co/api/embed/324b4f481b219890ef5a26e3c6fb73fff8929c93.svg "Repobeats analytics image")
+
+---
+
+> [!WARNING]
+> This project only supports PostgreSQL and MySQL databases. SQLite3 will be supported in the future as well as other
+> databases supported by Rails.
+
+> [!NOTE]
+> This project requires Ruby 3.1.0+, in future updated 2.6+ Ruby versions will be supported.
+
+---
+
+ARFI – *ActiveRecord Functional Indexes*
+
+The ARFI gem provides the ability to create and maintain custom SQL functions for ActiveRecord models without switching
+to `structure.sql` (an SQL-based schema). You can use your own SQL functions in any part of the project, from migrations
+and models to everything else. There is a working example in
+the [demo project](https://github.com/unurgunite/poc_arfi_72). All instructions are described
+in [README](https://github.com/unurgunite/poc_arfi_72/blob/master/README.md). ARFI supports all types of database
+architectures implemented in Rails, suitable for both working with single databases and for simultaneous work with
+multiple databases in the same environment.
+
+* [ARFI](#arfi)
+    * [Installation](#installation)
+    * [Usage](#usage)
+        * [Internal documentation](#internal-documentation)
+        * [CLI](#cli)
+        * [Project creation](#project-creation)
+        * [Index creation](#index-creation)
+        * [Index destroy](#index-destroy)
+        * [Additional help](#additional-help)
+    * [Demo](#demo)
+    * [Library features](#library-features)
+    * [Roadmap](#roadmap)
+    * [Commands](#commands)
+        * [Function creation](#function-creation)
+        * [Function destroy](#function-destroy)
+            * [Options](#options)
+                * [`--template` option](#--template-option)
+                * [`--adapter` option](#--adapter-option)
+    * [Limitations](#limitations)
+    * [Development](#development)
+        * [Build from source](#build-from-source)
+    * [Requirements](#requirements)
+    * [Contributing](#contributing)
+    * [Miscellaneous](#miscellaneous)
+    * [License](#license)
+    * [Code of Conduct](#code-of-conduct)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add arfi
+```
+
+## Usage
+
+### Internal documentation
+
+Internal documentation available at https://github.com/unurgunite/arfi_docs.
+
+### CLI
+
+ARFI uses Thor as a command line interface (CLI) instead of Rake, so it has a specific DSL.
+
+### Project creation
+
+Firstly, run `bundle exec arfi project create` to create a new project. This command will create `db/functions`
+directory. ARFI uses `db/functions` directory to store your SQL functions.
+
+### Function creation
+
+Run `bundle exec arfi f_idx create function_name` to create a new function. New SQL function will be created in
+`db/functions` directory under `function_name_v01.sql` name. Edit your function and run `bundle exec rails db:migrate`.
+You can also use custom template for functions using `--template` flag, this behaviour is described below.
+Type `bundle exec arfi f_idx help create` for additional info.
+
+### Function destroy
+
+If you want to destroy your function, run `bundle exec arfi f_idx destroy function_name [revision (default 1)]`. Please
+note that after deleting the function, it will still be available, but if you run "bundle exec rails db:migrate" again,
+an error will occur when using the function. Enter `bundle exec arfi f_idx help destroy` for more information.
+
+### Additional help
+
+Run `bundle exec arfi` for additional help.
+
+## Demo
+
+Demo available as separate project built with Rails 7.2 and PostgreSQL 14: https://github.com/unurgunite/poc_arfi_72.
+README is also available.
+
+## Library features
+
+1. ARFI supports about all types of database initialization. It respects your database schema format and database
+   configuration.
+
+   | Task             | Completed                                                    |
+   |------------------|--------------------------------------------------------------|
+   | db:migrate       | :white_check_mark:                                           |
+   | db:setup         | :white_check_mark:                                           |
+   | db:prepare       | :white_check_mark:                                           |
+   | db:schema:load   | :white_check_mark:                                           |
+   | db:reset         | :white_check_mark:                                           |
+   | db:setup:db_name | In progress (see [limitations][1]) :arrows_counterclockwise: |
+
+2. Database support. ARFI supports PostgreSQL and MySQL databases and projects with multiple databases at the same time.
+
+   | DB adapter | Tested                                |
+   |------------|---------------------------------------|
+   | PostgreSQL | :white_check_mark:                    |
+   | MySQL      | :white_check_mark:                    |
+   | SQLite3    | In progress :arrows_counterclockwise: |
+
+3. Rails support
+
+   | Rails version | Tested                                |
+   |---------------|---------------------------------------|
+   | 8             | :white_check_mark:                    |
+   | 7             | :white_check_mark:                    |
+   | 6             | In progress :arrows_counterclockwise: |
+
+## Roadmap
+
+1. ~~Custom template for SQL functions using `--template` flag;~~
+2. ~~Multidb support (Rails 6+ feature);~~
+3. Add support for 4+ ActiveRecord;
+4. Add RSpec tests;
+5. ~~Add separate YARD doc page;~~
+6. ~~Update CI/CD;~~
+7. Add support for Ruby 2.6+.
+
+## Commands
+
+ARFI has a set of commands to work with SQL functions. Type `bundle exec arfi help` for additional help. As noted above,
+ARFI uses Thor as a command line interface.
+
+### Function creation
+
+ARFI supports creation of SQL functions. To create a new function, run `bundle exec arfi f_idx create function_name`.
+Also, there are some options:
+
+| Option name  | Description                                                                          | Possible values            | Default value                                                 |
+|--------------|--------------------------------------------------------------------------------------|----------------------------|---------------------------------------------------------------|
+| `--template` | use custom template                                                                  | path within you filesystem | nil (will be used default template for each type of adapters) |
+| `--adapter`  | adapter specific function creation due to syntax differences between different RDBMS | postgresql, mysql          | nil (function will be stored in generic `db/functions`)       |
+
+### Function destroy
+
+ARFI supports destroy of SQL functions. To destroy a function, run
+`bundle exec arfi f_idx destroy function_name [revision (1 by default)]`.
+
+| Option name  | Description                  | Possible values   | Default value                                              |
+|--------------|------------------------------|-------------------|------------------------------------------------------------|
+| `--revision` | Function revision to destroy | Integer           | 1                                                          |
+| `--adapter`  | adapter specific function    | postgresql, mysql | nil (function will be destroyed in generic `db/functions`) |
+
+#### Options
+
+##### `--template` option
+
+This option is used for creating an SQL function. In this case, the function will not be created with the default
+template, but with user defined. There are some rules for templates:
+
+1. The template must be written in a Ruby-compatible syntax: the function must be placed in a HEREDOC statement and must
+   use interpolation for variables. If you need to take a more comprehensive approach to the issue of function
+   generation, you can try using your own methods in the template file. No matter what you write there, the main rule is
+   that your main method should return a string with a function template, as described below.
+2. ARFI supports dynamic variables in templates, but only one at the moment. You need to specify `index_name`
+   variable as below. In feature updated ARFI will support more variables. Here are default templates in ARFI for
+   PostgreSQL and MySQL:
+
+   PostgreSQL:
+    ```ruby
+    <<~SQL
+      CREATE OR REPLACE FUNCTION #{index_name}() RETURNS TEXT[]
+      LANGUAGE SQL
+      IMMUTABLE AS
+      $$
+        -- Function body here
+      $$
+    SQL
+    ```
+   MySQL:
+    ```ruby
+    <<~SQL
+      CREATE FUNCTION #{index_name} ()
+      RETURNS return_type
+      BEGIN
+        -- Function body here
+      END;
+    SQL
+    ```
+3. By default ARFI uses PostgreSQL template.
+
+##### `--adapter` option
+
+This option is used both when destroying and when creating an SQL function. In this case, the function will not be
+created in the default directory `db/functions`, but in the child `db/functions/#{adapter}`. Supported adapters:
+`postgresql`and `mysql`, but there will be more in the future.
+
+## Limitations
+
+Currently, ARFI has a limitation for `db:setup:db_name` task due to the fact how Rails manage this rake task. More info
+here: [limitations][1]. This command will work, but it is not recommended to use it. Note that this limitation applies
+only to multi-db setup, default `db:setup` will work as expected.
+
+## Development
+
+### Build from source
+
+The manual installation includes installation via command line interface. it is practically no different from what
+happens during the automatic build of the project:
+
+```shell
+git clone https://github.com/unurgunite/arfi.git
+cd arfi
+bundle install
+gem build arfi.gemspec
+gem install arfi-0.5.0.gem
+```
+
+Also, you can run `bin/setup` to automatically install everything needed.
+
+## Requirements
+
+ARFI is built on top of the following gems:
+
+| Dependencies | Description                                                                                |
+|--------------|--------------------------------------------------------------------------------------------|
+| ActiveRecord | Used to patch `ActiveRecord::Base` module with new methods.                                |
+| Rails        | Used for fetching project settings (database connection settings, Rails environment, etc.) |
+| Thor         | For CLI development.                                                                       |
+| Rubocop      | For static code analysis.                                                                  |
+| Rake         | For patching built-in Rails Rake tasks.                                                    |
+| Steep        | For static type checking.                                                                  |
+| RBS          | For static type checking.                                                                  |
+| YARD         | For generating documentation.                                                              |
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/unurgunite/arfi. This project is intended to
+be a safe, welcoming space for collaboration, and contributors are expected to adhere to
+the [code of conduct](https://github.com/unurgunite/arfi/blob/master/CODE_OF_CONDUCT.md).
+
+## Miscellaneous
+
+ARFI is highly inspired by https://github.com/teoljungberg/fx project.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ARFI project's codebases, issue trackers, chat rooms and mailing lists is expected to follow
+the [code of conduct](https://github.com/unurgunite/arfi/blob/master/CODE_OF_CONDUCT.md).
+
+[1]: https://blog.saeloun.com/2021/10/27/rails-7-adds-database-specific-setup/#limitation

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/Steepfile

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# D = Steep::Diagnostic
+#
+target :lib do
+  signature 'sig'
+  # ignore_signature "sig/test"
+  # use "rbs_collection"
+  check 'lib' # Directory name
+  # check "path/to/source.rb"         # File name
+  # check "app/models/**/*.rb"        # Glob
+  # ignore "lib/templates/*.rb"
+  ignore 'lib/arfi/extensions/active_record/connection_adapters/postgresql/database_statements.rb'
+
+  # library "pathname"              # Standard libraries
+  # library "strong_json"           # Gems
+
+  # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end
+
+# target :test do
+#   unreferenced!                     # Skip type checking the `lib` code when types in `test` target is changed
+#   signature "sig/test"              # Put RBS files for tests under `sig/test`
+#   check "test"                      # Type check Ruby scripts under `test`
+#
+#   configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
+#
+#   # library "pathname"              # Standard libraries
+# end

data/exe/arfi

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'thor'
+require_relative '../lib/arfi/cli'
+
+Arfi::CLI.start(ARGV)

data/lib/arfi/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'arfi'
+
+path = File.expand_path(__dir__)
+Dir.glob("#{path}/tasks/**/*.rake").each { |f| import f }

data/lib/arfi/cli.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'commands/project'
+require_relative 'commands/f_idx'
+
+# steep:ignore:start
+module Arfi
+  # Top level CLI class
+  class CLI < Thor
+    desc 'project [COMMAND]', 'Project specific commands.'
+    subcommand 'project', Commands::Project
+
+    desc 'f_idx [COMMAND]', 'Command to handle functions.'
+    subcommand 'f_idx', Commands::FIdx
+
+    desc 'version', 'Print the version'
+    def version
+      $stdout.write(Arfi::VERSION, "\n")
+    end
+  end
+end
+# steep:ignore:end