Installation

Copy Markdown

1. PostgreSQL extension

The PostgreSQL extension pg_roaringbitmap must be installed on the machine where the PostgreSQL server is running. This extension is supported by a number of cloud vendors ➚. If your vendor doesn't support it, or if you run your own server, you can easily install it yourself.

Linux

SSH into the server.

Update software package lists, install build tools and the pgxn client ➚:

apt-get update --fix-missing
apt install build-essential make gcc
apt install pgxnclient

Install PostgreSQL server tools for your PostgreSQL version. For PostgreSQL 17:

apt install postgresql-server-dev-17

Install PostgreSQL extension pg_roaringbitmap

pgxn install pg_roaringbitmap

macOS

For local development, install the extension on your development machine.

To simplify the installation, install the pgxn client ➚:

brew install pgxnclient

Install PostgreSQL extension pg_roaringbitmap.

pgxn install pg_roaringbitmap

With multiple installed PostgreSQL versions

The default setting will install the extension against the instance whose pg_config is first found on the PATH. A different instance can be specified using the option --pg_config some-other-path, for example:

sudo pgxn install pg_roaringbitmap \
  --pg_config /Applications/Postgres.app/Contents/Versions/17/bin/pg_config

Or update PATH:

export PATH="/Applications/Postgres.app/Contents/Versions/17/bin:$PATH"
sudo pgxn install pg_roaringbitmap

The extension is automatically loaded into the database when Refine.create_facets_table/2 is executed.

Alternatively, create a migratio file to set everything up upfront:

defmodule MyApp.Repo.Migrations.CreateExtensionRoaringBitmap do

  use Ecto.Migration

  def change do
    execute(
      "CREATE EXTENSION IF NOT EXISTS roaringbitmap",
      "DROP EXTENSION roaringbitmap"
    )
  end

end

Optional check

If you want to verify directly that the extension is working as expected, follow these steps:

Inside a psql session:

CREATE EXTENSION IF NOT EXISTS roaringbitmap;

Test:

select roaringbitmap('{1,100,10}');

2. Mix dependency

Add refine to your list of dependencies in mix.exs:

def deps do
  [
    {:refine, "~> 0.1"}
  ]
end

3. Postgrex types

Add a lib/postgrex_types.ex file with the following content:

Postgrex.Types.define(MyApp.PostgrexTypes, [
  Refine.RoaringBitmap
])

Replace RoaringBitmap with RoaringBitmap64 when using 64-bit bitmaps.

4. Repo configuration

Add the Postgrex types to the repo configuration. For example:

config :my_app, MyApp.Repo,
  ...
  types: MyApp.PostgrexTypes

5. Global configuration (optional)

Set the default Ecto repo that Refine should be using in the application environment. For example in confix.exs:

config :refine, repo: MyApp.Repo