CipherStash Documentation

Getting started with Ruby on Rails and CipherStash

This guide will step you through adding CipherStash to your Ruby on Rails application.

By the end of this guide, you will have:

  • Encrypted sensitive data inside your existing database
  • Queried that encrypted data

The steps you’ll go through are:

  1. Define which database columns should be encrypted
  2. Encrypt the sensitive data
  3. Query the newly encrypted data

Before you start

You’ll need to install some tools:

  1. The CipherStash CLI
  2. The CipherStash database driver

This tutorial takes you through adding CipherStash to an existing Rails application using PostgreSQL.

Start by cloning the repo and installing dependencies:

git clone
cd cipherstash-rails-demo-app
bundle install

Create the database, run migrations, and seed the database with dummy patient data:

rails db:setup

Install the CipherStash CLI

The CipherStash CLI is used to manage your encryption schema.

The encryption schema defines what encrypted indexes exist, and what queries you can perform on those indexes.

On macOS

Install via Homebrew:

brew install cipherstash/tap/stash

You will need to grant an exception in System Settings the first time you run the binary.

We will release a fix for this in Q2 2023.

On Linux

Download the binary for your platform:

  1. Make the binary executable:
    # on x86_64
    chmod +x $path_to/stash-x86_64-unknown-linux-gnu
    # on ARM64
    chmod +x $path_to/stash-aarch64-unknown-linux-gnu
  2. Rename the binary:
    # on x86_64
    mv stash-x86_64-unknown-linux-gnu stash
    # on ARM64
    mv stash-aarch64-unknown-linux-gnu stash
  3. Place the binary on your $PATH, so you can run it.

Sign up

You can start your signup from the CLI:

stash signup

Your browser will open to where you can sign up with either your GitHub account, or a standalone email.

CipherStash Signup Confirmation page

Install the CipherStash database driver

The CipherStash database driver transparently maps SQL statements to encrypted database columns.

We need to add it to your Rails app, and tell Rails to use it.

Supports Rails 6.x and 7.x.

Add the activerecord-cipherstash-pg-adapter to your Gemfile:

gem "activerecord-cipherstash-pg-adapter"

Remove (or comment out as below) the pg gem from your Gemfile.

# gem "pg", "~> 1.1"

Run bundle install.

And update the default adapter settings in the database.yml with postgres_cipherstash:

default: &default
  adapter: postgres_cipherstash