# ActiveRecordExtended for PostgreSQL Queries in Rails

> ActiveRecordExtended adds PostgreSQL-oriented query helpers to Active Record applications, including array, JSONB, HSTORE, network address, set operation, CTE, and window function interfaces. It suits PostgreSQL-backed Rails applications, but it adds a database-specific dependency and does not cover every feature shown in its README.

**GeorgeKaraszi/ActiveRecordExtended** — Adds additional postgres functionality to an ActiveRecord / Rails application

- Repository: https://github.com/GeorgeKaraszi/ActiveRecordExtended
- Stars: 1,464 · Forks: 50
- Language: Ruby
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/georgekaraszi-activerecordextended

## Why ActiveRecordExtended Exists in a Rails Application

ActiveRecordExtended addresses a gap between PostgreSQL's query capabilities and the database-neutral query surface exposed by Active Record, Arel, and Rails. Its README describes the library as the continuation of Dan McClain's original `postgres_ext` project. The fork arose because compatibility work for newer Active Record versions had become scattered across application-specific patches, while the original source was no longer receiving direct contributions.

The intended audience is therefore narrow but practical: Ruby developers using Rails or Active Record with PostgreSQL. It is most relevant when models contain PostgreSQL arrays, JSONB, HSTORE, or `inet` columns, or when a report needs PostgreSQL-specific constructs that are awkward to express through ordinary Active Record scopes. The gem does not replace Active Record. It extends the existing relation API with helper methods that map to PostgreSQL querying behavior.

That distinction matters. Applications that use only basic equality, ordering, association, and aggregation queries may gain little from adding this package. The project targets a specific case: an application already depends on PostgreSQL, but developers want readable Active Record access to operators and SQL forms not represented in the standard abstraction. The database-specific design is a feature for PostgreSQL projects and a portability cost for applications intended to run on several database engines.

## How ActiveRecordExtended Builds PostgreSQL Predicates

The gem adds methods to Active Record's `where` interface for predicates involving collection and structured column types. According to the README, `any` searches for rows whose PostgreSQL array contains a single matchable value. `all` applies PostgreSQL's `ALL` expression, so every array element must match the supplied value. Repeated matching values and an empty array also satisfy the comparison; nulls follow SQL three-valued logic. These are different semantics: an array containing additional values may match `any` but not `all`.

The `contains` helper maps to containment behavior for PostgreSQL array, JSONB, and HSTORE columns. For arrays, the supplied values must all be present. For JSONB and HSTORE, the README describes containment of the supplied key and value structure. `overlap` is closer to an intersection test: it matches an array containing any value from the supplied list. These helpers allow application code to state the intended collection operation without manually assembling each SQL expression.

Network-address predicates target PostgreSQL `inet` columns. The documented `inet_contains` method accepts a network value and uses the column's mask to find related records within the supplied range. The README also indexes variants for containment or equality, being contained within or equal, and containment or containment within. These operations depend on valid `inet` values and meaningful network masks. The README does not discuss behavior for malformed or unexpected address values.

The README also lists `Any_of`, `None_of`, `Either Join`, `Either Order`, CTEs, JSON construction, unions, and window functions. The full README contains sections and examples for these features, including CTEs, union variants and window functions. Review the relevant examples and generated SQL for the exact version and query shape you use.

## Installing the Gem and Running an Array Query

The README gives a direct Bundler installation. Add the gem under its published package name to the application's `Gemfile`:

```ruby
gem 'active_record_extended'
```

Then install the bundle from the application directory:

```bash
bundle
```

The README does not provide a separate generator, initializer, migration task, or configuration file. Its examples assume an existing Active Record model named `User` with a PostgreSQL array column named `tags`. The following first use creates three records and queries records whose tags include `1`:

```ruby
alice = User.create!(tags: [1])
bob   = User.create!(tags: [1, 2])
randy = User.create!(tags: [3])

User.where.any(tags: 1) #=> [alice, bob]
```

The expected result is the first two users because both arrays contain `1`. The README explicitly warns that this method accepts only a single comparison value. Passing a multiple-value array such as `[1, 2]` to `where.any` is documented as returning no records.

For a clearer contrast, use `all` when every array element should equal the compared value (the predicate also matches empty arrays):

```ruby
alice = User.create!(tags: [1])
bob   = User.create!(tags: [1, 2])
randy = User.create!(tags: [3])

User.where.all(tags: 1) #=> [alice]
```

Here only the first record matches. The `Model.where.<predicate>` style is the visible extension point, so the real setup check is whether the helper appears on the relation API and produces the intended PostgreSQL predicate in the target application.

## JSONB and HSTORE Containment Without Raw Predicates

The `contains` method also covers structured PostgreSQL columns. For JSONB or HSTORE data, the README passes a Ruby hash to `where.contains` and expects records containing the requested key and value. This is useful when exact equality would be too restrictive and the application actually wants containment semantics.

The documented example uses a `data` column:

```ruby
alice = User.create!(data: { nickname: "ARExtend" })
bob   = User.create!(data: { nickname: "ARExtended" })
randy = User.create!(data: { nickname: "ARExtended" })

User.where.contains(data: { nickname: "ARExtended" }) #=> [bob, randy]
```

The result includes both records whose `nickname` is exactly `"ARExtended"`. The README does not show a case where the stored JSONB or HSTORE value contains extra keys, so it does not establish how this gem treats partial nested structures. Developers should not infer that behavior from the array examples.

The same method name serves arrays and structured key-value columns, but the data types have different PostgreSQL containment rules. That makes schema review important before adoption. A query that behaves correctly for an integer array does not prove that the gem serializes nested hashes, scalar values, or HSTORE key types correctly. The README does not document those edge cases, casts, null handling, or type mapping.

## Rails, Ruby, and PostgreSQL Compatibility Boundaries

The documented minimum versions are Ruby 3.1.x, Rails 6.1.x, and PostgreSQL 12.x, although each minimum carries an end-of-life warning in the README. The listed upper compatibility is Ruby 3.4.x and Rails 8.0.x. PostgreSQL support is stated as version 11 through version 18, with a qualification that older versions probably work only to a certain point.

This version matrix creates an adoption decision for applications pinned to an older runtime. A Rails application below 6.1 or a Ruby release below 3.1 falls outside the stated minimums. PostgreSQL 11 is listed as supported, but it is also below the stated minimum and receives the README's end-of-life warning. That combination makes PostgreSQL 12 the clearest documented baseline, while version 11 is an exception supported by the broader compatibility statement.

The project is not archived. Its last push was on 2026-06-23, and release `3.5.0` was published on 2026-06-11. That is evidence of recent repository activity, but it does not remove upgrade work. Applications still on `3.3.0` or `3.4.0` need to review the release history and changelog rather than assuming compatibility or behavior is unchanged.

The repository includes `Gemfile`, `Gemfile.lock`, gemspec files, `spec/`, `Rakefile`, and `.github/` entries. Based on that layout, the project has both package metadata and a dedicated test suite. The README does not state an exact `bundle exec rspec` workflow, so it should not be presented as a documented command.

## Maintenance, Licensing, and the Cost of PostgreSQL Coupling

ActiveRecordExtended is distributed under the MIT license. That permits broad reuse, modification, and distribution subject to the license terms, although the license file should be reviewed for the project's own compliance and notice requirements. Adding the gem also adds a third-party dependency whose future releases can affect a Rails application's dependency resolution.

The upgrade cost depends on the application's existing Rails and Ruby versions. The README claims alignment with officially supported Ruby and Rails versions and lists a broad range, but private applications can still encounter conflicts through other gems. A team adopting the project should inspect `active_record_extended.gemspec`, `Gemfile.lock`, `CHANGELOG.md`, and `gemfiles/` for the exact dependency constraints before changing its dependency set.

PostgreSQL coupling is the larger architectural cost. An Active Record query that depends on arrays, JSONB, HSTORE, `inet`, or PostgreSQL-specific operators cannot be moved unchanged to a database-neutral backend. That is acceptable when PostgreSQL is a deliberate platform decision. It is a poor fit when the same models and query layer must support multiple database engines.

A real alternative is to keep using standard Active Record relations where possible and express exceptional PostgreSQL queries with explicit Arel or parameterized SQL. That approach adds less package surface but makes each uncommon query more visible at the SQL level. The original `postgres_ext` is another historical reference, but ActiveRecordExtended's stated purpose is to continue and improve that work. The choice is between a reusable set of PostgreSQL-specific Active Record helpers and local query code that carries the same database dependency without the gem.

## Limits of the Documented ActiveRecordExtended API

The strongest documented use case is a PostgreSQL array or structured column that does not fit ordinary equality queries. The examples make the distinction among `any`, `all`, `contains`, and `overlap` understandable, but they cover only simple, valid values. The README does not document null handling, empty collections, invalid casts, nested JSONB behavior, or SQL generation.

The full README includes examples for advanced features such as CTEs, union variants and window functions. Use those sections as a starting point, then verify generated SQL and edge cases against the installed gem, Rails and PostgreSQL versions.

The gem is also the wrong choice when portability is mandatory. Database-agnostic Active Record features should remain preferable if they satisfy the query. Another wrong-fit case is a small application needing one unusual expression, because introducing a maintained PostgreSQL extension may add more dependency and upgrade work than a local, parameterized query.

Its clearest fit is a PostgreSQL-backed Rails application with recurring collection predicates or advanced SQL report requirements. The first verification should be query-level: reproduce the needed predicate in the project specs, inspect its SQL under the target adapter, and confirm that PostgreSQL version, column types, Rails version, and Ruby version all fall within the documented compatibility choices.

## Conclusion

Rails teams that use PostgreSQL-specific data types and repeatedly build raw SQL through Active Record are the clearest candidates. Applications that need database portability should first compare this dependency with plain Active Record and Arel expressions. Before adoption, verify the generated predicates for the exact query shape, run the project specs against the intended Rails and PostgreSQL versions, and confirm that the gem's minimum-version policy matches the deployment environment.

## FAQ

### How do I install ActiveRecordExtended in a Rails application?

Add `gem 'active_record_extended'` to the application's `Gemfile` and run `bundle`, as shown in the README. The README does not require a separate installer or initializer.

### When should I use where.any instead of where.all for a PostgreSQL array?

Use `where.any` when at least one array element must match. Use `where.all` when every element must match: repeated matching elements and an empty array also satisfy PostgreSQL's `ALL` comparison. Nulls follow SQL three-valued logic.

### Does ActiveRecordExtended support more than PostgreSQL arrays?

Yes. The README documents containment queries for JSONB and HSTORE, PostgreSQL network-address predicates, and indexes for CTEs, unions, JSON construction, conditional methods, and window functions. Detailed examples for several of those features are not shown in the README.

## Sources

- [GeorgeKaraszi/ActiveRecordExtended on GitHub](https://github.com/GeorgeKaraszi/ActiveRecordExtended)
- [Issues](https://github.com/GeorgeKaraszi/ActiveRecordExtended/issues)
- [License: MIT](https://github.com/GeorgeKaraszi/ActiveRecordExtended/blob/main/LICENSE)
- [README](https://github.com/GeorgeKaraszi/ActiveRecordExtended/blob/main/README.md)
- [Releases](https://github.com/GeorgeKaraszi/ActiveRecordExtended/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/georgekaraszi-activerecordextended