# Installation

## 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 ➚](https://github.com/ChenHuajun/pg_roaringbitmap#cloud-vendor-support).
If your vendor doesn't support it, or if you run your own server, you can easily install it yourself.

<!-- tabs-open -->

### Linux

SSH into the server.

Update software package lists, install build tools and the [pgxn client ➚](https://github.com/pgxn/pgxnclient):

```bash
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:

```bash
apt install postgresql-server-dev-17
```

Install PostgreSQL extension `pg_roaringbitmap`

```bash
pgxn install pg_roaringbitmap
```

### macOS

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

To simplify the installation, install the [pgxn client ➚](https://github.com/pgxn/pgxnclient):

```bash
brew install pgxnclient
```

Install PostgreSQL extension `pg_roaringbitmap`.

```bash
pgxn install pg_roaringbitmap
```

> #### With multiple installed PostgreSQL versions {: .info}
>
> 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:
>
> ```bash
> sudo pgxn install pg_roaringbitmap \
>   --pg_config /Applications/Postgres.app/Contents/Versions/17/bin/pg_config
> ```
>
> Or update `PATH`:
>
> ```bash
> export PATH="/Applications/Postgres.app/Contents/Versions/17/bin:$PATH"
> sudo pgxn install pg_roaringbitmap
> ```

<!-- tabs-close -->

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:

```elixir
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 {: .info}
>
> If you want to verify directly that the extension is working as expected, follow these steps:
>
> Inside a psql session:
>
> ```sql
> CREATE EXTENSION IF NOT EXISTS roaringbitmap;
> ```
>
> Test:
>
> ```sql
> select roaringbitmap('{1,100,10}');
> ```

## 2. Mix dependency

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

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

## 3. Postgrex types

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

```elixir
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:

```elixir
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`:

```elixir
config :refine, repo: MyApp.Repo
```