Encrypt Query Language (EQL)

Encrypt Query Language (EQL) is a set of abstractions for transmitting, storing, and interacting with encrypted data and indexes in PostgreSQL.

Tip

New to EQL? EQL is the basis for searchable encryption functionality when using Protect.js and/or CipherStash Proxy.

Store encrypted data alongside your existing data:

• Encrypted data is stored using a jsonb column type
• Query encrypted data with specialized SQL functions (equality, range, full-text, etc.)
• Index encrypted columns to enable searchable encryption

Table of Contents

• Installation
  • dbdev
• Getting started
  • Enable encrypted columns
• Encrypt configuration
• CipherStash integrations using EQL
• Developing

---

Installation

The simplest way to get up and running with EQL is to execute the install SQL file directly in your PostgreSQL database.

1. Download the latest EQL install script:

   curl -sLo cipherstash-encrypt.sql https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt.sql

2. Run this command to install the custom types and functions:

   psql -f cipherstash-encrypt.sql

dbdev

Warning

The version released on dbdev may not be in sync with the version released on GitHub until we automate the publishing process.

You can find the EQL extension on dbdev's extension catalog with instructions on how to install it.

Getting started

Once the custom types and functions are installed in your PostgreSQL database, you can start using EQL in your queries.

Enable encrypted columns

Define encrypted columns using the eql_v2_encrypted type, which stores encrypted data as jsonb with additional constraints to ensure data integrity.

Example:

CREATE TABLE users (
    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    encrypted_email eql_v2_encrypted
);

Encrypt configuration

In order to enable searchable encryption, you will need to configure your CipherStash integration appropriately.

• If you are using CipherStash Proxy, see this guide.
• If you are using Protect.js, use the Protect.js schema.

CipherStash integrations using EQL

These frameworks use EQL to enable searchable encryption functionality in PostgreSQL.

Framework	Repo
Protect.js	Protect.js
Protect.php	Protect.php
CipherStash Proxy	CipherStash Proxy

Versioning

You can find the version of EQL installed in your database by running the following query:

SELECT eql_v2.version();

Upgrading

To upgrade to the latest version of EQL, you can simply run the install script again.

1. Download the latest EQL install script:

   curl -sLo cipherstash-encrypt.sql https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt.sql

2. Run this command to install the custom types and functions:

   psql -f cipherstash-encrypt.sql

Note

The install script will not remove any existing configurations, so you can safely run it multiple times.

Using dbdev?

Follow the instructions in the dbdev documentation to upgrade the extension to your desired version.

Developing

See the development guide.