Merge pull request #185 from cipherstash/error-message-for-mappingerrorstatementcouldnotbemapped

Add details of StatementCouldNotBeMapped in errors.md

Author: tobyhede

docs/errors.md

@@ -12,6 +12,7 @@
   - [Invalid parameter](#mapping-invalid-parameter)
   - [Invalid SQL statement](#mapping-invalid-sql-statement)
   - [Unsupported parameter type](#mapping-unsupported-parameter-type)
+  - [Statement could not be type checked](#mapping-statement-could-not-be-type-checked)
   - [Internal Error](#mapping-internal-error)
 
 - Encrypt Errors:
@@ -167,13 +168,59 @@ Check the supported types for encrypted columns.
 
 
 
+<!-- ---------------------------------------------------------------------------------------------------- -->
+
+
+## Statement could not be type checked <a id='mapping-statement-could-not-be-type-checked'></a>
+
+An error occurred when attempting to type check the SQL statement.
+
+### Error message
+
+```
+Statement could not be type checked: '{type-check-erro-message}'
+```
+
+### Notes
+
+CipherStash Proxy checks SQL statements against the database schema to transparently encrypt and decrypt data.
+
+The behaviour of Proxy depends on the `mapping_errors_enabled` configuration.
+
+When `mapping_errors_enabled` is `false` (the default), then type check errors are logged, and the statement is passed through to the database.
+
+When `mapping_errors_enabled` is `true`, then type check errors are raised, and statement execution halts.
+
+In our experience, most production systems have a relatively small number of columns that require protection.
+As SQL is large and complex, instead of blocking statements with type check errors that are false negatives, the default behaviour of Proxy is to allow the statement.
+
+However, this does mean it is possible that a statement that references encrypted columns cannot be type-checked, and it will be passed through to the database.
+When a statement is passed through to the database, the database's column constraints (provided by EQL) will catch the statement, and return a PostgreSQL error.
+
+Example constraint error:
+```sql
+ERROR:  Encrypted column missing version (v) field: 34234
+CONTEXT:  PL/pgSQL function _cs_encrypted_check_v(jsonb) line 6 at RAISE
+SQL function "cs_check_encrypted_v1" statement 1
+```
+
+### How to Fix
+
+In most cases, this error will occur if the statement contains invalid or unsupported syntax.
+
+Check if you are running the latest version of CipherStash Proxy, and update to the latest version if not.
+
+If the error persists, please contact CipherStash [support](https://cipherstash.com/support).
+
+
+
 <!-- ---------------------------------------------------------------------------------------------------- -->
 
 
 ## Internal Mapper error <a id='mapping-internal-error'></a>
 
-An internal error occurred when attempting to rewrite the SQL statement.
-This could be due to an internal invariant failure or because of a specific fragment of unsupported SQL syntax.
+An internal error occurred when attempting to type check or transform a SQL statement.
+This could be due to an internal invariant failure, or because of a specific fragment of unsupported SQL syntax.
 
 ### Error message
 
@@ -183,7 +230,7 @@ Statement encountered an internal error. This may be a bug in the statement mapp
 
 ### How to Fix
 
-If you are running an older version of CipherStash Proxy, please update to the latest version.
+Check if you are running the latest version of CipherStash Proxy, and update to the latest version if not.
 
 If the error persists, please contact CipherStash [support](https://cipherstash.com/support).
 

packages/cipherstash-proxy/src/error.rs

@@ -80,8 +80,8 @@ pub enum MappingError {
     #[error("Encryption of PostgreSQL {name} (OID {oid}) types is not currently supported. For help visit {}#mapping-unsupported-parameter-type", ERROR_DOC_BASE_URL)]
     UnsupportedParameterType { name: String, oid: u32 },
 
-    #[error("Statement could not be type checked: {}. For help visit {}#mapping-statement-could-not-be-mapped", _0, ERROR_DOC_BASE_URL)]
-    StatementCouldNotBeMapped(String),
+    #[error("Statement could not be type checked: {}. For help visit {}#mapping-statement-could-not-be-type-checked", _0, ERROR_DOC_BASE_URL)]
+    StatementCouldNotBeTypeChecked(String),
 
     #[error("Statement could not be transformed: {0}")]
     StatementCouldNotBeTransformed(String),

packages/cipherstash-proxy/src/postgresql/frontend.rs

@@ -755,7 +755,7 @@ where
                     error = err.to_string(),
                 );
                 counter!(STATEMENTS_UNMAPPABLE_TOTAL).increment(1);
-                Err(MappingError::StatementCouldNotBeMapped(err.to_string()).into())
+                Err(MappingError::StatementCouldNotBeTypeChecked(err.to_string()).into())
             }
         }
     }

packages/eql-mapper/src/eql_mapper.rs

@@ -127,9 +127,6 @@ pub enum EqlMapperError {
     #[error("Internal error: {}", _0)]
     InternalError(String),
 
-    #[error("Unsupported value variant: {}", _0)]
-    UnsupportedValueVariant(String),
-
     /// A lexical scope error
     #[error(transparent)]
     Scope(#[from] ScopeError),