feat(proxy): support OPE index type

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **OPE (Order-Preserving Encryption) index**: New `ope` index type alongside the existing `ore` for range and `ORDER BY` queries on encrypted columns. Drop-in alternative to `ore` — pick one per column. See the [encrypted indexes documentation](docs/how-to/index.md) for configuration.
+
 ## [2.2.0-alpha.1] - 2026-03-25
 
 ### Changed

docs/how-to/index.md

@@ -201,7 +201,7 @@ This statement adds a `unique` index for the `email` column in the `users` table
 
 `unique` indexes are used to find records with columns with unique values, like with the `=` operator.
 
-There are two other types of encrypted indexes you can use on `text` data:
+There are other types of encrypted indexes you can use on `text` data:
 
 ```sql
 SELECT eql_v2.add_search_config(
@@ -217,10 +217,20 @@ SELECT eql_v2.add_search_config(
   'ore',
   'text'
 );
+
+SELECT eql_v2.add_search_config(
+  'users',
+  'email',
+  'ope',
+  'text'
+);
 ```
 
 The first SQL statement adds a `match` index, which is used for partial matches with `LIKE`.
-The second SQL statement adds an `ore` index, which is used for ordering with `ORDER BY`.
+The second SQL statement adds an `ore` index, which is used for ordering with `ORDER BY` and range comparisons (`<`, `<=`, `>`, `>=`).
+The third SQL statement adds an `ope` index, which supports the same range and ordering operators as `ore`.
+
+`ore` and `ope` are alternatives for range and ordering queries — add one or the other to a column, not both. `ore` is the recommended default. `ope` produces ciphertexts that sort under PostgreSQL's native byte ordering, which makes ordering and range scans cheaper, but as an order-preserving scheme it reveals more about the relative order of stored values than `ore` does. Choose based on your performance and threat-model requirements; see the [EQL `INDEX` documentation](https://github.com/cipherstash/encrypt-query-language/blob/main/docs/reference/INDEX.md) for the full tradeoffs.
 
 
 > ![IMPORTANT]

docs/reference/searchable-json.md

@@ -127,7 +127,7 @@ Encrypted literals cannot be passed as arguments to SQL functions. Encrypted col
 
 Examples:
 - `AVG()` cannot be used on encrypted numeric values ❌
-- `MIN()` and `MAX()` can be used on encrypted values with ORE index ✅
+- `MIN()` and `MAX()` can be used on encrypted values with an `ore` or `ope` index ✅
 - `LOWER()` cannot be used on encrypted text (operates only on plaintext) ❌
 
 ⚠️ **CAST Operations**: CAST operations cannot work on encrypted data because casting would require decryption within the database, which is impossible. EQL's `ste_vec` configuration enables direct comparison and ordering operations on encrypted values without requiring CAST.

docs/sql/schema-example.sql

@@ -23,6 +23,8 @@ SELECT eql_v2.add_search_config(
   'text'
 );
 
+-- 'ore' supports ordering and range comparisons. 'ope' is a drop-in
+-- alternative with the same operator support — choose one per column.
 SELECT eql_v2.add_search_config(
   'users',
   'encrypted_email',

packages/cipherstash-proxy-integration/src/common.rs

@@ -88,6 +88,18 @@ pub async fn clear_with_client(client: &Client) {
     client.simple_query(sql).await.unwrap();
 }
 
+/// Truncate a single table by name. Useful for tests that own a dedicated
+/// fixture table (e.g. the per-test ORE/OPE tables) and don't need to wipe
+/// the shared `encrypted`/`plaintext` tables.
+pub async fn clear_table_with_client(client: &Client, table: &str) {
+    let sql = format!("TRUNCATE {}", table);
+    client.simple_query(&sql).await.unwrap();
+}
+
+pub async fn clear_table(table: &str) {
+    clear_table_with_client(&connect_with_tls(PROXY).await, table).await;
+}
+
 pub async fn reset_schema() {
     let port = std::env::var("CS_DATABASE__PORT")
         .map(|s| s.parse().unwrap())

packages/cipherstash-proxy-integration/src/lib.rs

@@ -12,6 +12,8 @@ mod map_concat;
 mod map_literals;
 mod map_match_index;
 mod map_nulls;
+mod map_ope_index_order;
+mod map_ope_index_where;
 mod map_ore_index_order;
 mod map_ore_index_where;
 mod map_params;

packages/cipherstash-proxy-integration/src/map_ope_index_order.rs

@@ -0,0 +1,146 @@
+#[cfg(test)]
+mod tests {
+    use crate::common::{
+        clear_table, connect_with_tls, interleaved_indices, random_id, trace, PROXY,
+    };
+    use std::fmt::Debug;
+    use tokio_postgres::types::{FromSql, ToSql};
+
+    #[tokio::test]
+    async fn map_ope_order_text_asc() {
+        run_order_test(
+            "encrypted_ope_order_text_asc",
+            "encrypted_text",
+            text_values(),
+            false,
+        )
+        .await;
+    }
+
+    #[tokio::test]
+    async fn map_ope_order_text_desc() {
+        run_order_test(
+            "encrypted_ope_order_text_desc",
+            "encrypted_text",
+            text_values(),
+            true,
+        )
+        .await;
+    }
+
+    #[tokio::test]
+    async fn map_ope_order_int4_asc() {
+        run_order_test(
+            "encrypted_ope_order_int4_asc",
+            "encrypted_int4",
+            vec![-100i32, -1, 0, 1, 42, 1000, i32::MAX],
+            false,
+        )
+        .await;
+    }
+
+    #[tokio::test]
+    async fn map_ope_order_int4_desc() {
+        run_order_test(
+            "encrypted_ope_order_int4_desc",
+            "encrypted_int4",
+            vec![-100i32, -1, 0, 1, 42, 1000, i32::MAX],
+            true,
+        )
+        .await;
+    }
+
+    fn text_values() -> Vec<String> {
+        ["aardvark", "aplomb", "chimera", "chrysalis", "zephyr"]
+            .iter()
+            .map(|s| s.to_string())
+            .collect()
+    }
+
+    /// Inserts `values` (given in ascending order) in interleaved order, then
+    /// verifies `ORDER BY {col_name}` returns them sorted in the requested
+    /// direction.
+    async fn run_order_test<T>(table: &str, col_name: &str, values: Vec<T>, descending: bool)
+    where
+        for<'a> T: PartialEq + ToSql + Sync + FromSql<'a> + Debug,
+    {
+        trace();
+        clear_table(table).await;
+        let client = connect_with_tls(PROXY).await;
+
+        let insert = format!("INSERT INTO {table} (id, {col_name}) VALUES ($1, $2)");
+        for idx in interleaved_indices(values.len()) {
+            client
+                .query(&insert, &[&random_id(), &values[idx]])
+                .await
+                .unwrap();
+        }
+
+        let dir = if descending { "DESC" } else { "ASC" };
+        let select = format!("SELECT {col_name} FROM {table} ORDER BY {col_name} {dir}");
+        let rows = client.query(&select, &[]).await.unwrap();
+
+        let actual: Vec<T> = rows.iter().map(|r| r.get(0)).collect();
+        let expected: Vec<T> = if descending {
+            values.into_iter().rev().collect()
+        } else {
+            values
+        };
+        assert_eq!(actual, expected);
+    }
+
+    #[tokio::test]
+    async fn map_ope_order_nulls_last_by_default() {
+        trace();
+        let table = "encrypted_ope_order_nulls_last";
+        clear_table(table).await;
+        let client = connect_with_tls(PROXY).await;
+
+        let null_insert = format!("INSERT INTO {table} (id) VALUES ($1)");
+        client.query(&null_insert, &[&random_id()]).await.unwrap();
+
+        let insert = format!("INSERT INTO {table} (id, encrypted_text) VALUES ($1, $2), ($3, $4)");
+        client
+            .query(&insert, &[&random_id(), &"a", &random_id(), &"b"])
+            .await
+            .unwrap();
+
+        let select = format!("SELECT encrypted_text FROM {table} ORDER BY encrypted_text");
+        let rows = client.query(&select, &[]).await.unwrap();
+
+        let actual: Vec<Option<String>> = rows.iter().map(|r| r.get(0)).collect();
+        assert_eq!(
+            actual,
+            vec![Some("a".into()), Some("b".into()), None],
+            "NULLs should sort last by default"
+        );
+    }
+
+    #[tokio::test]
+    async fn map_ope_order_nulls_first() {
+        trace();
+        let table = "encrypted_ope_order_nulls_first";
+        clear_table(table).await;
+        let client = connect_with_tls(PROXY).await;
+
+        let insert = format!("INSERT INTO {table} (id, encrypted_text) VALUES ($1, $2), ($3, $4)");
+        client
+            .query(&insert, &[&random_id(), &"a", &random_id(), &"b"])
+            .await
+            .unwrap();
+
+        let null_insert = format!("INSERT INTO {table} (id) VALUES ($1)");
+        client.query(&null_insert, &[&random_id()]).await.unwrap();
+
+        let select =
+            format!("SELECT encrypted_text FROM {table} ORDER BY encrypted_text NULLS FIRST");
+        let rows = client.query(&select, &[]).await.unwrap();
+
+        let actual: Vec<Option<String>> = rows.iter().map(|r| r.get(0)).collect();
+        assert_eq!(
+            actual,
+            vec![None, Some("a".into()), Some("b".into())],
+            "NULLS FIRST should explicitly sort NULLs first"
+        );
+    }
+}