Merge #260

260: Add support for named args to the Hrana protocol r=honzasp a=honzasp



Co-authored-by: Jan Špaček <[email protected]>

Author: bors[bot]

docs/HRANA_SPEC.md

@@ -281,16 +281,32 @@ The server responds with the result of the statement.
 ```
 type Stmt = {
     "sql": string,
-    "args": Array<Value>,
+    "args"?: Array<Value>,
+    "named_args"?: Array<NamedArg>,
     "want_rows": boolean,
 }
+
+type NamedArg = {
+    "name": string,
+    "value": Value,
+}
 ```
 
-A statement contains the SQL text in `sql` and an array of arguments in
-`args`. The arguments are bound to positional parameters in the SQL statement
-(such as `$NNN` in Postgres or `?NNN` in SQLite). There is currently no way to
-bind named parameters by name (such as `:XXX` in SQLite), the protocol might be
-extended with this feature in the future.
+A statement contains the SQL text in `sql` and arguments.
+
+The arguments in `args` are bound to positional parameters in the SQL statement
+(such as `$NNN` in Postgres or `?NNN` in SQLite). The arguments in `named_args`
+are bound to named arguments, such as `:AAAA`, `@AAAA` and `$AAAA` in SQLite.
+
+For SQLite, the names of arguments include the prefix sign (`:`, `@` or `$`). If
+the name of the argument does not start with this prefix, the server will try to
+guess the correct prefix. If an argument is specified both as a positional
+argument and as a named argument, the named argument should take precedence.
+
+It is an error if the request specifies an argument that is not expected by the
+SQL statement, or if the request does not specify and argument that is expected
+by the SQL statement. Some servers may not support specifying both positional
+and named arguments.
 
 The `want_rows` field specifies whether the client is interested in the rows
 produced by the SQL statement. If it is set to `false`, the server should always

sqld/src/hrana/proto.rs

@@ -65,10 +65,19 @@ pub struct ExecuteResp {
 #[derive(Deserialize, Debug)]
 pub struct Stmt {
     pub sql: String,
+    #[serde(default)]
     pub args: Vec<Value>,
+    #[serde(default)]
+    pub named_args: Vec<NamedArg>,
     pub want_rows: bool,
 }
 
+#[derive(Deserialize, Debug)]
+pub struct NamedArg {
+    pub name: String,
+    pub value: Value,
+}
+
 #[derive(Serialize, Debug)]
 pub struct StmtResult {
     pub cols: Vec<Col>,

sqld/src/hrana/session.rs

@@ -63,7 +63,10 @@ pub enum ResponseError {
     #[error("SQL string contains more than one statement")]
     SqlManyStmts,
     #[error("Arguments do not match SQL parameters: {source}")]
-    InvalidArgs { source: anyhow::Error },
+    ArgsInvalid { source: anyhow::Error },
+    #[error("Specifying both positional and named arguments is not supported")]
+    ArgsBothPositionalAndNamed,
+
     #[error("Transaction timed out")]
     TransactionTimeout,
     #[error("Server cannot handle additional transactions")]
@@ -206,12 +209,24 @@ fn proto_stmt_to_query(proto_stmt: proto::Stmt) -> Result<Query> {
         bail!(ResponseError::SqlManyStmts)
     }
 
-    let params = proto_stmt
-        .args
-        .into_iter()
-        .map(proto_value_to_value)
-        .collect();
-    let params = Params::Positional(params);
+    let params = if proto_stmt.named_args.is_empty() {
+        let values = proto_stmt
+            .args
+            .into_iter()
+            .map(proto_value_to_value)
+            .collect();
+        Params::Positional(values)
+    } else if proto_stmt.args.is_empty() {
+        let values = proto_stmt
+            .named_args
+            .into_iter()
+            .map(|arg| (arg.name, proto_value_to_value(arg.value)))
+            .collect();
+        Params::Named(values)
+    } else {
+        bail!(ResponseError::ArgsBothPositionalAndNamed)
+    };
+
     Ok(Query { stmt, params })
 }
 
@@ -258,7 +273,7 @@ fn proto_value_from_value(value: Value) -> proto::Value {
 
 fn proto_response_error_from_error(error: Error) -> Result<ResponseError, Error> {
     Ok(match error {
-        Error::LibSqlInvalidQueryParams(source) => ResponseError::InvalidArgs { source },
+        Error::LibSqlInvalidQueryParams(source) => ResponseError::ArgsInvalid { source },
         Error::LibSqlTxTimeout(_) => ResponseError::TransactionTimeout,
         Error::LibSqlTxBusy => ResponseError::TransactionBusy,
         Error::RusqliteError(rusqlite_error) => match rusqlite_error {