This guide explains how to connect Supabase to CipherStash Tandem. Supabase is a PostgreSQL compatible database that can be connected to CipherStash Tandem just like any other PostgreSQL database.

The following steps assume a database schema with a table named users that contains an email column that you want to protect.

Step 0: Prepare Your Environment

Ensure you have Docker installed and running on your system. If you don't have Docker, you can download and install it from Docker's official website.

Step 1: Set Up CipherStash Tandem

1.1 Create a CipherStash account

  • If you don't already have a CipherStash account, create one at CipherStash.
  • Download the CipherStash CLI and log in to your account. For more information, refer to the official documentation of CipherStash CLI.

1.2 Configure a dataset

  • Create a dataset for your Supabase database. For more information, refer to the official documentation of CipherStash Datasets.

For this tutorial, we will use the following dataset based on the users table and protection of the email column:

2  - path: users
3    fields:
4      - name: email
5        in_place: false
6        cast_type: utf8-str
7        mode: encrypted
8        indexes:
9          - version: 1
10            kind: match
11            tokenizer:
12              kind: ngram
13              token_length: 3
14            token_filters:
15              - kind: downcase
16            k: 6
17            m: 2048
18            include_original: true
19          - version: 1
20            kind: ore
21          - version: 1
22            kind: unique

Use this dataset as a template for your own dataset and upload it to CipherStash using the commands from creating a dataset.

1.3 Configure CipherStash Tandem

Step 2: Retrieve Supabase Connection Details

2.1 Get Supabase Host Information

  • In your Supabase project, navigate to Project Settings > Database.
  • Scroll to the Connection info section and note down the following Connection parameters:
    • Host
    • Port
    • Database name
    • Username
    • Password

Step 3: Configure CipherStash Tandem to Connect to Supabase

3.1 Set Up Database Proxy

  • Using the Supabase Host details, configure CipherStash Tandem to act as a proxy to your Supabase database.
  • Ensure CipherStash Tandem is configured to use the correct host, port, and any necessary authentication credentials for your Supabase database.
  • Create a tandem.toml file with the following contents:
1passthrough = true

For the full list of configuration options, refer to the CipherStash Tandem Configuration documentation.

3.2 Start CipherStash Tandem

Use the following command to start CipherStash Tandem, replacing the placeholder values with your own:

1docker run -p 6432:6432 \
2  -v ./tandem.toml:/etc/tandem/tandem.toml \
3  -e CS_PASSTHROUGH=true \
4  -e CS_PORT=6432 \
5  -e CS_USERNAME=fill-me-in \
6  -e CS_PASSWORD=fill-me-in \
7  -e CS_DATABASE__HOST=fill-me-in \
8  -e CS_DATABASE__PORT=fill-me-in \
9  -e CS_DATABASE__NAME=fill-me-in \
10  -e CS_WORKSPACE_ID=fill-me-in \
11  -e CS_CLIENT_ID=fill-me-in \
12  -e CS_CLIENT_KEY=fill-me-in \
13  -e CS_CLIENT_ACCESS_KEY=fill-me-in \
14  cipherstash/tandem-pgcat

Note: The CS_PASSTHROUGH environment variable is set to true. Please refer to the refer to the CipherStash Encryption Migrations documentation for more information on how to configure CipherStash Tandem to encrypt your data.

Step 4: Connect to Your Database Through CipherStash Tandem

4.1 Update Application Connection String

  • In your application, replace the original Supabase connection string with the connection string for CipherStash Tandem.
  • Typically, this would involve changing the host in the connection string to point to the local or network address where CipherStash Tandem is running, and updating the port to 6432, while keeping the same credentials.

Step 5: Test Your Connection

5.1 Verify Connectivity

  • Test the connection from your application to ensure that it can successfully communicate with the Supabase database through CipherStash Tandem.


By following these steps, you should have successfully integrated Supabase with CipherStash Tandem.

To enable encryption for your Supabase database, you will need to configure CipherStash Tandem to encrypt the columns you want to protect. For more information, refer to the CipherStash Encryption Migrations documentation.

ZeroKMS: Zero trust key management