ARFI

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. All instructions are described in README. 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
  • Installation
  • Usage
    • Internal documentation
    • CLI
    • Project creation
    • Index creation
    • Index destroy
    • Additional help
  • Demo
  • Library features
  • Roadmap
  • Commands
    • Function creation
    • Function destroy
      • Options
        • --template option
        • --adapter option
  • Limitations
  • Development
    • Build from source
  • Requirements
  • Contributing
  • Miscellaneous
  • License
  • Code of Conduct

Install the gem and add to the application's Gemfile by executing:

bundle add arfi

Internal documentation available at https://github.com/unurgunite/arfi_docs.

ARFI uses Thor as a command line interface (CLI) instead of Rake, so it has a specific DSL.

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.

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.

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.

Run bundle exec arfi for additional help.

Demo available as separate project built with Rails 7.2 and PostgreSQL 14: https://github.com/unurgunite/poc_arfi_72. README is also available.

1. ARFI supports about all types of database initialization. It respects your database schema format and database configuration.

   Task	Completed
   db:migrate	✅
   db:setup	✅
   db:prepare	✅
   db:schema:load	✅
   db:reset	✅
   db:setup:db_name	In progress (see limitations) 🔄

2. Database support. ARFI supports PostgreSQL and MySQL databases and projects with multiple databases at the same time.

   DB adapter	Tested
   PostgreSQL	✅
   MySQL	✅
   SQLite3	In progress 🔄

3. Rails support

   Rails version	Tested
   8	✅
   7	✅
   6	In progress 🔄

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+.

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.

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:

ARFI supports destroy of SQL functions. To destroy a function, run bundle exec arfi f_idx destroy function_name [revision (1 by default)].

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:

   <<~SQL
     CREATE OR REPLACE FUNCTION #{index_name}() RETURNS TEXT[]
     LANGUAGE SQL
     IMMUTABLE AS
     $$
       -- Function body here
     $$
   SQL

   MySQL:

   <<~SQL
     CREATE FUNCTION #{index_name} ()
     RETURNS return_type
     BEGIN
       -- Function body here
     END;
   SQL

3. By default ARFI uses PostgreSQL template.

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: postgresqland mysql, but there will be more in the future.

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. 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.

The manual installation includes installation via command line interface. it is practically no different from what happens during the automatic build of the project:

git clone https://github.com/unurgunite/arfi.git
cd arfi
bundle install
gem build arfi.gemspec
gem install arfi-0.5.1.gem

Also, you can run bin/setup to automatically install everything needed.

ARFI is built on top of the following gems:

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.

ARFI is highly inspired by https://github.com/teoljungberg/fx project.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the ARFI project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.