diff --git a/README.md b/README.md index 26cbcac..6c55b10 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,8 @@ DBInterface.execute(stmt, ("alice", Date(2026, 1, 2))) DBInterface.executemany(stmt, (name=["bob", "carol"], joined=[Date(2026, 1, 3), Date(2026, 1, 4)])) DBInterface.close!(stmt) cursor = DBInterface.execute(conn, "SELECT * FROM users WHERE id = ?", (17,)) # one-shot prepare + execute +# named parameters bind from a NamedTuple or Dict by name +cursor = DBInterface.execute(conn, "SELECT * FROM users WHERE id = :id OR parent = :id", (id=17,)) DBInterface.lastrowid(DBInterface.execute(conn, "INSERT INTO users (name) VALUES ('dave')")) # transactions, streaming, bulk loading diff --git a/docs/src/index.md b/docs/src/index.md index 5349906..d288b18 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -34,8 +34,8 @@ There are two ways to run SQL: * `DBInterface.execute(conn, sql)` runs a statement over the text protocol. * `stmt = DBInterface.prepare(conn, sql); DBInterface.execute(stmt, params)` prepares a statement once and executes it any number of times with parameters bound to its `?` - markers over the binary protocol. `DBInterface.execute(conn, sql, params)` is the - one-shot form (prepare, execute, close). + or `:name` markers over the binary protocol. `DBInterface.execute(conn, sql, params)` is + the one-shot form (prepare, execute, close). Both return a `MySQL.Cursor`, a [Tables.jl](https://juliadata.github.io/Tables.jl/stable/) row source, so a result can be materialized as `DataFrame(cursor)`, `Tables.columntable(cursor)`, @@ -60,10 +60,9 @@ Parameters are bound by their Julia type: integers, floats, strings (`String`, `missing`/`nothing` for NULL. Pass a tuple, named tuple, vector, or `Tables.AbstractRow` for multiple parameters. -Values bind to `?` markers in iteration order; names do not change that order. Named SQL -markers such as `:name` are not supported. A bare scalar binds one parameter; use -`(bytes,)` to bind a byte vector as one binary value. `executemany` takes one collection -per parameter, as in the example below. +Values bind to `?` markers in iteration order; names do not change that order. A bare +scalar binds one parameter; use `(bytes,)` to bind a byte vector as one binary value. +`executemany` takes one collection per parameter, as in the example below. ```julia stmt = DBInterface.prepare(conn, "INSERT INTO users (name, joined) VALUES (?, ?)") @@ -72,6 +71,38 @@ DBInterface.executemany(stmt, (name=["bob", "carol"], joined=[Date(2026, 1, 3), DBInterface.close!(stmt) ``` +#### Named parameters + +Write `:name` in place of `?` to bind values by name. MySQL's prepared statements accept only +`?`, so MySQL.jl sends each `:name` to the server as `?` and looks up the values by name when +the statement executes. Pass a `NamedTuple`, or an `AbstractDict` keyed by `Symbol` or +`String`: + +```julia +stmt = DBInterface.prepare(conn, "UPDATE users SET name = :name WHERE id = :id OR parent = :id") +DBInterface.execute(stmt, (id=7, name="alice")) +DBInterface.execute(stmt, Dict("id" => 8, "name" => "bob")) +DBInterface.executemany(stmt, (name=["carol", "dan"], id=[9, 10])) # each row binds by name +DBInterface.close!(stmt) +DBInterface.execute(conn, "SELECT * FROM users WHERE id = :id", (id=7,)) +``` + + * A name starts with a letter or `_` and continues with letters, digits, and `_`. Names + are case-sensitive: `:userId` takes the value of `userId`, not `userid`. + * A name used more than once binds the same value each time. + * Keys that the statement does not use are ignored. A missing name raises + `MySQL.MySQLInterfaceError` before anything is sent to the server. + * A statement uses `?` markers or `:name` markers, not both. A tuple, vector, or bare + scalar binds one value per `:name` marker, in the order the markers appear. A row + (`Tables.AbstractRow`) raises an error, because its column order need not match the + markers; bind it by name with `NamedTuple(row)`. + * A `:name` inside a string literal, a quoted identifier, or a comment is not a parameter. + Executable comments (`/*! ... */`) are sent unchanged, and `:=` stays an assignment. + String literals end where the session's `NO_BACKSLASH_ESCAPES` mode says they do when the + statement is prepared. + * When the server does not read a `:name` as a parameter, as with a label in a MariaDB + stored procedure (`lbl:LOOP`), MySQL.jl prepares the SQL as written. + `DBInterface.transaction(conn) do ... end` wraps the block in `START TRANSACTION`/`COMMIT` (`ROLLBACK` on an exception). If a transaction is already active, including one started with SQL, the block uses a savepoint. Nested success leaves the outer transaction open; @@ -280,6 +311,7 @@ MySQL.ConnectOptions DBInterface.connect DBInterface.close! DBInterface.execute +DBInterface.executemany DBInterface.executemultiple DBInterface.prepare DBInterface.transaction diff --git a/src/MySQL.jl b/src/MySQL.jl index c422eaa..54e2822 100644 --- a/src/MySQL.jl +++ b/src/MySQL.jl @@ -37,6 +37,7 @@ include("reaper.jl") include("connect.jl") include("connection.jl") include("cursor.jl") +include("named_parameters.jl") include("statement.jl") include("load.jl") include("precompile.jl") diff --git a/src/Protocol/constants.jl b/src/Protocol/constants.jl index c704993..219955d 100644 --- a/src/Protocol/constants.jl +++ b/src/Protocol/constants.jl @@ -76,6 +76,7 @@ const MYSQL_OPTION_MULTI_STATEMENTS_OFF = 0x0001 # Server error codes the client must recognise. const ER_ACCESS_DENIED_ERROR = 1045 +const ER_PARSE_ERROR = 1064 const ER_NET_PACKET_TOO_LARGE = 1153 const ER_SP_DOES_NOT_EXIST = 1305 const ER_QUERY_INTERRUPTED = 1317 diff --git a/src/named_parameters.jl b/src/named_parameters.jl new file mode 100644 index 0000000..5d0cc07 --- /dev/null +++ b/src/named_parameters.jl @@ -0,0 +1,129 @@ +# Named parameters for prepared statements. The server's prepared statements take positional +# `?` markers only, so `DBInterface.prepare` rewrites each `:name` to `?` and keeps the names, +# and `DBInterface.execute` looks each value up by name in a NamedTuple or AbstractDict. + +""" + MySQL.NamedSQL + +The SQL of a statement with named parameters as the server prepares it: `sql` has each +`:name` replaced by `?`, and `names[i]` is the name of the `i`-th `?` (a reused name repeats). +""" +struct NamedSQL + sql::String + names::Vector{Symbol} +end + +is_name_start(b::UInt8) = return (UInt8('a') <= b <= UInt8('z')) | (UInt8('A') <= b <= UInt8('Z')) | (b == UInt8('_')) | (b >= 0x80) +is_name_char(b::UInt8) = return is_name_start(b) | (UInt8('0') <= b <= UInt8('9')) + +""" + MySQL.named_sql(sql, no_backslash_escapes) -> Union{Nothing, NamedSQL} + +Finds the `:name` parameters of `sql` the way the server's lexer reads the text, and returns +the rewritten SQL, or `nothing` when `sql` has none. A name starts with a letter, `_`, or a +non-ASCII character, and continues with those or digits; `:=` and `:1` are not parameters. +String literals (`'...'` and `"..."`, where a backslash escapes the next byte unless +`no_backslash_escapes`), backtick identifiers, and comments (`#`, `-- `, `/* */`) are skipped. +Executable comments (`/*! */`, `/*M! */`) are skipped too: the server runs or ignores them +depending on its version, so their text is never changed. +""" +function named_sql(sql::AbstractString, no_backslash_escapes::Bool) + # Positional SQL usually has no colon at all: one memchr. + findfirst(==(UInt8(':')), codeunits(sql)) === nothing && return nothing + str = String(sql) + bytes = codeunits(str) + span = next_name(bytes, 1, no_backslash_escapes) + span === nothing && return nothing + names = Symbol[] + out = UInt8[] + copied = 0 # bytes[1:copied] are already in `out` + while span !== nothing + colon, stop = span + push!(names, Symbol(SubString(str, colon + 1, prevind(str, stop + 1)))) + append!(out, view(bytes, (copied + 1):(colon - 1))) + push!(out, UInt8('?')) + copied = stop + span = next_name(bytes, stop + 1, no_backslash_escapes) + end + append!(out, view(bytes, (copied + 1):length(bytes))) + return NamedSQL(String(out), names) +end + +# `(colon, stop)`: the byte range of the next `:name` at or after `i`, or `nothing`. +function next_name(bytes::Base.CodeUnits{UInt8, String}, i::Int, no_backslash_escapes::Bool) + n = length(bytes) + while i <= n + b = bytes[i] + if b == UInt8('\'') || b == UInt8('"') + i = skip_quoted(bytes, i, !no_backslash_escapes) + elseif b == UInt8('`') + i = skip_quoted(bytes, i, false) + elseif b == UInt8('#') || (b == UInt8('-') && i < n && bytes[i + 1] == UInt8('-') && + (i + 2 > n || bytes[i + 2] <= 0x20 || bytes[i + 2] == 0x7f)) + newline = findnext(==(UInt8('\n')), bytes, i) + i = newline === nothing ? n + 1 : newline + 1 + elseif b == UInt8('/') && i < n && bytes[i + 1] == UInt8('*') + i += 2 + while i < n && !(bytes[i] == UInt8('*') && bytes[i + 1] == UInt8('/')) + i += 1 + end + i += 2 + elseif b == UInt8(':') && i < n && is_name_start(bytes[i + 1]) + stop = i + 1 + while stop < n && is_name_char(bytes[stop + 1]) + stop += 1 + end + return (i, stop) + else + i += 1 + end + end + return nothing +end + +# Index just past the quoted run that starts at `bytes[i]`. A doubled quote (`''`) ends one +# run and starts the next, which skips the same bytes. +function skip_quoted(bytes::Base.CodeUnits{UInt8, String}, i::Int, backslash_escapes::Bool) + q = bytes[i] + i += 1 + while i <= length(bytes) + b = bytes[i] + b == q && return i + 1 + i += (backslash_escapes && b == UInt8('\\')) ? 2 : 1 + end + return i +end + +# The values of a named statement's `?` markers, looked up by name in a NamedTuple or +# AbstractDict; the positional encoder iterates it like a tuple. +struct NamedValues{T} + names::Vector{Symbol} + params::T +end + +Base.length(v::NamedValues) = return length(v.names) +Base.getindex(v::NamedValues, i::Int) = return param_value(v.params, v.names[i]) +Base.iterate(v::NamedValues, i::Int=1) = return i > length(v.names) ? nothing : (v[i], i + 1) + +has_param(p::NamedTuple, name::Symbol) = return haskey(p, name) +param_value(p::NamedTuple, name::Symbol) = return getfield(p, name) +has_param(p::AbstractDict, name::Symbol) = return haskey(p, name) || haskey(p, String(name)) +param_value(p::AbstractDict, name::Symbol) = return haskey(p, name) ? p[name] : p[String(name)] + +function named_values(names::Vector{Symbol}, params::Union{NamedTuple, AbstractDict}) + for name in names + has_param(params, name) || missing_param(name) + end + return NamedValues(names, params) +end + +# A tuple or vector binds one value per marker in marker order, the way MariaDB binds its own +# `:name` markers under sql_mode=ORACLE. +named_values(names::Vector{Symbol}, params::Union{Tuple, AbstractVector}) = return params + +# A row has names but iterates in column order, which need not match the markers. +named_values(names::Vector{Symbol}, params) = throw(MySQLInterfaceError( + "a statement with named parameters takes a NamedTuple or AbstractDict (bound by name) or a tuple or vector (bound in marker order), not a $(typeof(params))", +)) + +@noinline missing_param(name::Symbol) = throw(MySQLInterfaceError("no value for named parameter :$name")) diff --git a/src/statement.jl b/src/statement.jl index f8cbd4e..588ced7 100644 --- a/src/statement.jl +++ b/src/statement.jl @@ -14,12 +14,14 @@ end A prepared statement on the native backend, from `DBInterface.prepare(conn, sql)`. Execute it with `DBInterface.execute(stmt, params)`; close it with `DBInterface.close!(stmt)` (the -COM_STMT_CLOSE is deferred to the next command, never sent from a finalizer). +COM_STMT_CLOSE is deferred to the next command, never sent from a finalizer). `stmt.sql` is +the SQL as written, `:name` parameters included. """ mutable struct Statement <: DBInterface.Statement conn::Connection statement_id::UInt32 sql::String + named::Union{Nothing, NamedSQL} # `nothing`: no `:name` parameters, `sql` is prepared as written generation::Int nparams::Int params::Vector{P.ColumnDef} @@ -67,19 +69,31 @@ end """ DBInterface.prepare(conn::MySQL.Connection, sql) -> Statement -Prepares `sql` on the server and returns a `Statement`. +Prepares `sql` on the server and returns a `Statement`. Parameters are positional `?` markers +or named `:name` markers; one statement cannot mix the two. The server takes only `?`, so each +`:name` is sent as `?` and execution binds its value by name. A `:name` inside a string +literal, a quoted identifier, or a comment (executable `/*! */` comments included) is left +alone. When the server does not read every `:name` as a parameter, as with a MariaDB +stored-program label such as `lbl:LOOP`, the SQL is prepared as written and binds positionally. """ function DBInterface.prepare(conn::Connection, sql::AbstractString) lock(conn.lock) do s = begin_command!(conn) - P.stmt_prepare!(s, sql) - ok = P.read_prepare_response!(s) + named = named_sql(sql, (s.status & P.SERVER_STATUS_NO_BACKSLASH_ESCAPES) != 0) + ok = if named === nothing + P.stmt_prepare!(s, sql) + P.read_prepare_response!(s) + else + ok, named = prepare_named!(s, sql, named) + ok + end names, types, lookup, coltypes = statement_schema(conn, ok) generation = @atomic conn.generation stmt = Statement( conn, ok.statement_id, String(sql), + named, generation, P.num_params(ok), ok.params, @@ -101,13 +115,40 @@ function DBInterface.prepare(conn::Connection, sql::AbstractString) end end -# Re-prepares `stmt.sql` on the current (READY) session and refreshes its id/generation and -# cached metadata. A 1615 retry closes the superseded id on the same session. A reconnect -# leaves the old-generation id alone because it belongs to the dead session. +# Prepares the `?` rewrite. If the server does not read every `:name` as a parameter (the +# rewrite does not parse, or it counts other parameters), the SQL is prepared as written: +# MariaDB prepares stored-program labels (`lbl:LOOP`) and Oracle-mode `:NEW.col`, which have no +# `?` form. If that fails too, the rewrite's problem is reported. +function prepare_named!(s::P.Session, sql::AbstractString, named::NamedSQL) + P.stmt_prepare!(s, named.sql) + problem = try + ok = P.read_prepare_response!(s) + P.num_params(ok) == length(named.names) && return ok, named + P.stmt_close!(s, ok.statement_id) + MySQLInterfaceError("the server found $(P.num_params(ok)) parameters but the statement names $(length(named.names)); a statement cannot mix `?` and `:name` parameters") + catch err + (err isa P.StmtError && err.errno == P.ER_PARSE_ERROR) || rethrow() + err + end + P.stmt_prepare!(s, sql) + ok = try + P.read_prepare_response!(s) + catch err + err isa P.StmtError || rethrow() + throw(problem) + end + return ok, nothing +end + +# Re-prepares the statement (its `?` rewrite when it has `:name` parameters) on the current +# (READY) session and refreshes its id/generation and cached metadata. A 1615 retry closes the +# superseded id on the same session. A reconnect leaves the old-generation id alone because it +# belongs to the dead session. function reprepare!(conn::Connection, s::P.Session, stmt::Statement; close_previous::Bool=false, replay_long_data::Bool=true) old_id = stmt.statement_id old_generation = stmt.generation - P.stmt_prepare!(s, stmt.sql) + named = stmt.named + P.stmt_prepare!(s, named === nothing ? stmt.sql : named.sql) ok = P.read_prepare_response!(s) generation = @atomic conn.generation if close_previous && old_generation == generation && old_id != ok.statement_id @@ -282,16 +323,28 @@ normalize_params(p::Union{Number, AbstractString, Missing, Nothing, Dates.TimeTy """ DBInterface.execute(stmt::MySQL.Statement, params=(); mysql_store_result=true) -> BinaryCursor -Executes the prepared statement with `params` bound as the `?` markers and returns a -binary-protocol cursor. A tuple, named tuple, vector, or `Tables.AbstractRow` supplies values -in iteration order; names do not select SQL parameters. A bare scalar binds one parameter. -Wrap a binary byte vector as `(bytes,)` to bind it as one value. Named SQL markers such as -`:name` are not supported. `mysql_store_result=false` streams rows (the connection is busy until -the cursor is exhausted or closed). +Executes the prepared statement with `params` bound to its parameters and returns a +binary-protocol cursor. For `?` markers, a tuple, named tuple, vector, or `Tables.AbstractRow` +supplies values in iteration order; names do not select SQL parameters. A bare scalar binds one +parameter. Wrap a binary byte vector as `(bytes,)` to bind it as one value. For `:name` markers, +pass a `NamedTuple` or an `AbstractDict` keyed by `Symbol` or `String`: each marker takes the +value of its name (case-sensitive), a reused name binds the same value, and keys the SQL does +not name are ignored. A missing name raises an error before anything is sent. A tuple, vector, +or bare scalar binds one value per `:name` marker in marker order; a `Tables.AbstractRow` raises +an error (convert it with `NamedTuple(row)` to bind by name). `mysql_store_result=false` +streams rows (the connection is busy until the cursor is exhausted or closed). """ function DBInterface.execute(stmt::Statement, params=(); mysql_store_result::Bool=true) - conn = stmt.conn params = normalize_params(params) + named = stmt.named + # Two calls, not one variable: a Union of both value types would box the parameters. + named === nothing && return execute_values(stmt, params, mysql_store_result) + return execute_values(stmt, named_values(named.names, params), mysql_store_result) +end + +# Executes with `params` in `?` marker order. +function execute_values(stmt::Statement, params, mysql_store_result::Bool) + conn = stmt.conn lock(conn.lock) do stmt.closed && closed_statement() check_paramcount(stmt, params) @@ -351,6 +404,29 @@ function DBInterface.executemultiple(stmt::Statement, params=(); mysql_store_res return Cursors(stmt.conn, stmt.sql, first.opts, first) end +""" + DBInterface.executemany(stmt::MySQL.Statement, params::NamedTuple) + +Executes `stmt` once per row of a batch that holds one equal-length collection per parameter, +inside one transaction. For `:name` markers each row binds by name; for `?` markers each row +binds in field order, as in DBInterface's generic method. +""" +function DBInterface.executemany(stmt::Statement, params::NamedTuple) + # DBInterface hands each row to `execute` positionally, which a `:name` statement rejects. + (stmt.named === nothing || isempty(params)) && + return invoke(DBInterface.executemany, Tuple{DBInterface.Statement, Any}, stmt, params) + n = length(first(params)) + all(c -> length(c) == n, params) || + throw(DBInterface.ParameterError("parameter collections provided to `DBInterface.executemany` must have equal lengths")) + n == 0 && return nothing + DBInterface.transaction(stmt.conn) do + for i in 1:n + DBInterface.close!(DBInterface.execute(stmt, map(c -> c[i], params))) + end + end + return nothing +end + """ DBInterface.close!(stmt::MySQL.Statement) diff --git a/test/mysql_trim_workload.jl b/test/mysql_trim_workload.jl index 340ef5b..e5b0b5b 100644 --- a/test/mysql_trim_workload.jl +++ b/test/mysql_trim_workload.jl @@ -198,6 +198,7 @@ function serve_connection!(conn)::Nothing end elseif cmd == P.COM_STMT_PREPARE sql = String(payload[2:end]) + occursin(":id", sql) && error("a named parameter reached the server: $sql") if occursin("INSERT", sql) send_prepare_ok(conn, INSERT_STMT_ID, Vector{UInt8}[coldef("?"), coldef("?")], Vector{UInt8}[]) else @@ -280,6 +281,19 @@ function run_workload(port::Int, value::Int)::Int end check(oids == Int32[17, 18], "one-shot execute") + # named parameters: `:id` is prepared as `?` and bound by name + nids = Int32[] + nstmt = DBInterface.prepare(conn, "SELECT id, name FROM people WHERE id = :id") + for row in DBInterface.execute(nstmt, (id=17,))::MySQL.BinaryCursor{true} + push!(nids, Tables.getcolumn(row, Int32, 1, :id)) + end + for row in DBInterface.execute(nstmt, Dict(:id => 17))::MySQL.BinaryCursor{true} + push!(nids, Tables.getcolumn(row, Int32, 1, :id)) + end + check(nids == Int32[17, 18, 17, 18], "named parameters") + DBInterface.executemany(nstmt, (id=[17, 18],)) + DBInterface.close!(nstmt) + # simple commands and escaping check(MySQL.ping(conn), "ping") check(MySQL.escape(conn, "a'b") == "a\\'b", "escape") diff --git a/test/protocol/named_parameters_tests.jl b/test/protocol/named_parameters_tests.jl new file mode 100644 index 0000000..b3fbf1e --- /dev/null +++ b/test/protocol/named_parameters_tests.jl @@ -0,0 +1,206 @@ +# Named `:name` parameters (#207) against the fake peer: the client rewrites each `:name` to `?` +# outside literals and comments, and binds values by name. Uses the binary-protocol helpers +# from binary_tests.jl; the live-server checks are in test/user_workflow.jl. + +rewrite(sql; no_backslash_escapes=false) = (r = N.named_sql(sql, no_backslash_escapes); r === nothing ? nothing : (r.sql, r.names)) + +@testset "named parameters: rewrite rules" begin + unchanged = [ + "SELECT id FROM t WHERE id = ?", + "SELECT @x := ?, @y:=1", + "SELECT ':a', \":b\", `:c`", + "SELECT TIME '10:30:00'", + "SELECT 1 # :a\n", + "SELECT 1 -- :a", + "SELECT 1 /* :a */", + "SELECT /*+ BKA(:a) */ 1", + "SELECT 1 /*! , :a */", + "SELECT 1 /*!80000 , :a */", + "SELECT 1 /*M! , :a */", + "SELECT :1", + "SELECT 1:", + "SELECT 'it''s :a'", + "SELECT 'it\\'s :a'", + "SELECT `a``:b`", + "SELECT 'unterminated :a", + "SELECT 1 /* unterminated :a", + ] + for sql in unchanged + @test rewrite(sql) === nothing + end + rewritten = [ + "SELECT :a" => ("SELECT ?", [:a]), + "INSERT INTO t VALUES (:id, :name)" => ("INSERT INTO t VALUES (?, ?)", [:id, :name]), + "SELECT * FROM t WHERE a = :x OR b = :x" => ("SELECT * FROM t WHERE a = ? OR b = ?", [:x, :x]), + "WHERE a=:userId AND b=:userid" => ("WHERE a=? AND b=?", [:userId, :userid]), + "SELECT :_a1, :α" => ("SELECT ?, ?", [:_a1, :α]), + "SET @v:=:val" => ("SET @v:=?", [:val]), + "SELECT ':a', :b, \":c\", `:d`, :e" => ("SELECT ':a', ?, \":c\", `:d`, ?", [:b, :e]), + "SELECT 'it''s', :a, 'x\\'y'" => ("SELECT 'it''s', ?, 'x\\'y'", [:a]), + "SELECT 1--:a" => ("SELECT 1--?", [:a]), # `--` without a space is two minus signs + "SELECT 1 --\t:a\n, :b" => ("SELECT 1 --\t:a\n, ?", [:b]), + "SELECT :a #:b\n, :c" => ("SELECT ? #:b\n, ?", [:a, :c]), + "SELECT :a/*:b*/:c" => ("SELECT ?/*:b*/?", [:a, :c]), + "SELECT /*!STRAIGHT_JOIN*/ a FROM t WHERE id = :id" => ("SELECT /*!STRAIGHT_JOIN*/ a FROM t WHERE id = ?", [:id]), + "SELECT :a, 'x\\" => ("SELECT ?, 'x\\", [:a]), # unterminated literal ending in a backslash + ] + for (sql, expected) in rewritten + @test rewrite(sql) == expected + end + @test rewrite(SubString("xSELECT :a", 2)) == ("SELECT ?", [:a]) + # Under NO_BACKSLASH_ESCAPES a backslash is an ordinary character, so 'a\' ends the literal. + @test rewrite("SELECT 'a\\', :b, 'c'"; no_backslash_escapes=true) == ("SELECT 'a\\', ?, 'c'", [:b]) + @test rewrite("SELECT \"a\\\", :b, \"c\""; no_backslash_escapes=true) == ("SELECT \"a\\\", ?, \"c\"", [:b]) + @test rewrite("SELECT 'a\\', :b, 'c'") === nothing +end + +# The COM_STMT_EXECUTE parameter block after the 9-byte header. +param_block(payload) = payload[10:end] + +@testset "named parameters: prepare and execute bind by name" begin + sent = String[] + payloads = Vector{UInt8}[] + with_native(c -> begin + push!(sent, expect_prepare(c)); send_prepare_ok(c, 1, 21, paramdefs(3), P.ColumnDef[]) + for _ in 1:4 + push!(payloads, expect_execute(c)); send_ok(c, 1; affected=1) + end + @test expect_stmt_close(c) == 21 + expect_query(c); send_ok(c, 1) + end) do conn + stmt = DBInterface.prepare(conn, "INSERT INTO t (a, b, c) VALUES (:id, :name, :id)") + @test stmt.sql == "INSERT INTO t (a, b, c) VALUES (:id, :name, :id)" + @test stmt.nparams == 3 + @test DBInterface.execute(stmt, (name="x", id=Int32(7), unused=1.5)).rows_affected == 1 + @test DBInterface.execute(stmt, Dict(:id => Int32(8), :name => "y")).rows_affected == 1 + @test DBInterface.execute(stmt, Dict("id" => Int32(9), "name" => "z")).rows_affected == 1 + @test DBInterface.execute(stmt, (Int32(10), "w", Int32(11))).rows_affected == 1 # one value per marker + # Rejected before anything is sent: the peer sees COM_STMT_CLOSE next. + err = try; DBInterface.execute(stmt, (id=Int32(1),)); nothing; catch e; e; end + @test err isa MySQL.MySQLInterfaceError && occursin(":name", err.msg) + @test_throws MySQL.MySQLInterfaceError DBInterface.execute(stmt, (id=Int32(1), Name="case matters")) + @test_throws MySQL.MySQLInterfaceError DBInterface.execute(stmt, Tables.Row((id=Int32(1), name="x"))) + @test_throws MySQL.MySQLInterfaceError DBInterface.execute(stmt, (Int32(1), "x")) + @test_throws MySQL.MySQLInterfaceError DBInterface.execute(stmt) + DBInterface.close!(stmt) + @test DBInterface.execute(conn, "SELECT 1").rows_affected == 0 + end + @test sent == ["INSERT INTO t (a, b, c) VALUES (?, ?, ?)"] + expected = [(Int32(7), "x", Int32(7)), (Int32(8), "y", Int32(8)), (Int32(9), "z", Int32(9)), (Int32(10), "w", Int32(11))] + for (i, (payload, values)) in enumerate(zip(payloads, expected)) + @test param_block(payload) == N.encode_param_block(values, N.param_signature(values), i == 1) + end +end + +@testset "named parameters: SQL without names is sent as written" begin + sent = String[] + payloads = Vector{UInt8}[] + with_native(c -> begin + push!(sent, expect_prepare(c)); send_prepare_ok(c, 1, 22, paramdefs(2), P.ColumnDef[]) + push!(payloads, expect_execute(c)); send_ok(c, 1) + @test expect_stmt_close(c) == 22 + expect_query(c); send_ok(c, 1) + end) do conn + sql = "UPDATE t SET at = '10:30:00', v = @x := ? WHERE n = ? /* :a */" + stmt = DBInterface.prepare(conn, sql) + DBInterface.execute(stmt, (b=Int32(2), a="first")) # a NamedTuple still binds in field order + DBInterface.close!(stmt) + DBInterface.execute(conn, "SELECT 1") + end + @test sent == ["UPDATE t SET at = '10:30:00', v = @x := ? WHERE n = ? /* :a */"] + @test param_block(only(payloads)) == N.encode_param_block((Int32(2), "first"), N.param_signature((Int32(2), "first")), true) +end + +@testset "named parameters: the session's NO_BACKSLASH_ESCAPES mode decides literal ends" begin + sent = String[] + with_native(c -> begin + expect_query(c); send_ok(c, 1; status=P.SERVER_STATUS_AUTOCOMMIT | P.SERVER_STATUS_NO_BACKSLASH_ESCAPES) + push!(sent, expect_prepare(c)); send_prepare_ok(c, 1, 23, paramdefs(1), P.ColumnDef[]) + expect_query(c); send_ok(c, 1) + end) do conn + DBInterface.execute(conn, "SET sql_mode = 'NO_BACKSLASH_ESCAPES'") + stmt = DBInterface.prepare(conn, "SELECT 'C:\\', :v") + @test stmt.nparams == 1 + DBInterface.execute(conn, "SELECT 1") + end + @test sent == ["SELECT 'C:\\', ?"] +end + +@testset "named parameters: ER_NEED_REPREPARE re-prepares the rewritten SQL" begin + cols = [coldef("x"; type=P.MYSQL_TYPE_LONG, flags=NOT_NULL)] + with_native(c -> begin + @test expect_prepare(c) == "SELECT x FROM t WHERE x = ?" + send_prepare_ok(c, 1, 24, paramdefs(1), cols) + expect_execute(c); send_err(c, 1, P.ER_NEED_REPREPARE, "Prepared statement needs re-preparing") + @test expect_prepare(c) == "SELECT x FROM t WHERE x = ?" + send_prepare_ok(c, 1, 25, paramdefs(1), cols) + @test expect_stmt_close(c) == 24 + expect_execute(c); send_resultset(c, 1, cols, [binary_row(Int32(5))]) + end) do conn + stmt = DBInterface.prepare(conn, "SELECT x FROM t WHERE x = :x") + @test Tables.columntable(DBInterface.execute(stmt, (x=Int32(5),))).x == Int32[5] + DBInterface.close!(stmt) + end +end + +@testset "named parameters: the server decides when a :word is not a parameter" begin + sent = String[] + with_native(c -> begin + # MariaDB prepares stored-program DDL; a label's `?` rewrite does not parse + push!(sent, expect_prepare(c)); send_err(c, 1, P.ER_PARSE_ERROR, "near '? LEAVE'") + push!(sent, expect_prepare(c)); send_prepare_ok(c, 1, 26, P.ColumnDef[], P.ColumnDef[]) + expect_execute(c); send_ok(c, 1) + # `?` mixed with `:name`: the server counts both; the SQL as written does not parse + push!(sent, expect_prepare(c)); send_prepare_ok(c, 1, 27, paramdefs(2), P.ColumnDef[]) + @test expect_stmt_close(c) == 27 + push!(sent, expect_prepare(c)); send_err(c, 1, P.ER_PARSE_ERROR, "near ':a'") + # a typo: both attempts fail, and the rewrite's error is the one reported + push!(sent, expect_prepare(c)); send_err(c, 1, P.ER_PARSE_ERROR, "near 'ORDR BY a'") + push!(sent, expect_prepare(c)); send_err(c, 1, P.ER_PARSE_ERROR, "near ':a ORDR BY a'") + # other errors are not retried + push!(sent, expect_prepare(c)); send_err(c, 1, 1146, "Table 'x' doesn't exist") + expect_query(c); send_ok(c, 1) + end) do conn + label = "CREATE PROCEDURE p() BEGIN lbl:LOOP LEAVE lbl; END LOOP; END" + stmt = DBInterface.prepare(conn, label) + @test stmt.nparams == 0 + @test DBInterface.execute(stmt).rows_affected == 0 + err = try; DBInterface.prepare(conn, "SELECT :a, ?"); nothing; catch e; e; end + @test err isa MySQL.MySQLInterfaceError && occursin("cannot mix", err.msg) + err = try; DBInterface.prepare(conn, "SELECT * FROM t WHERE a = :a ORDR BY a"); nothing; catch e; e; end + @test err isa MySQL.StmtError && err.errno == P.ER_PARSE_ERROR && err.msg == "near 'ORDR BY a'" + err = try; DBInterface.prepare(conn, "SELECT :a FROM x"); nothing; catch e; e; end + @test err isa MySQL.StmtError && err.errno == 1146 + @test DBInterface.execute(conn, "SELECT 1").rows_affected == 0 + end + @test sent == [ + "CREATE PROCEDURE p() BEGIN lbl? LEAVE lbl; END LOOP; END", + "CREATE PROCEDURE p() BEGIN lbl:LOOP LEAVE lbl; END LOOP; END", + "SELECT ?, ?", + "SELECT :a, ?", + "SELECT * FROM t WHERE a = ? ORDR BY a", + "SELECT * FROM t WHERE a = :a ORDR BY a", + "SELECT ? FROM x", + ] +end + +@testset "named parameters: executemany binds each NamedTuple row by name" begin + seen = String[] + payloads = Vector{UInt8}[] + with_native(c -> begin + expect_prepare(c); send_prepare_ok(c, 1, 28, paramdefs(2), P.ColumnDef[]) + push!(seen, expect_query(c)); send_ok(c, 1) # START TRANSACTION + for _ in 1:2 + push!(payloads, expect_execute(c)); send_ok(c, 1; affected=1) + end + push!(seen, expect_query(c)); send_ok(c, 1) # COMMIT + end) do conn + stmt = DBInterface.prepare(conn, "INSERT INTO t (a, b) VALUES (:a, :b)") + DBInterface.executemany(stmt, (b=["x", "y"], a=Int32[1, 2])) + @test_throws DBInterface.ParameterError DBInterface.executemany(stmt, (a=Int32[1, 2], b=["x"])) + DBInterface.close!(stmt) + end + @test seen == ["START TRANSACTION", "COMMIT"] + @test param_block(payloads[1]) == N.encode_param_block((Int32(1), "x"), N.param_signature((Int32(1), "x")), true) + @test param_block(payloads[2]) == N.encode_param_block((Int32(2), "y"), N.param_signature((Int32(2), "y")), false) +end diff --git a/test/protocol/runtests.jl b/test/protocol/runtests.jl index 5a8e3ed..26738ba 100644 --- a/test/protocol/runtests.jl +++ b/test/protocol/runtests.jl @@ -29,6 +29,7 @@ empty!(P.COVERAGE) include("binary_tests.jl") include("transaction_tests.jl") include("sharedvalues_tests.jl") + include("named_parameters_tests.jl") include("fuzz_tests.jl") include("perf_tests.jl") include("coverage_tests.jl") diff --git a/test/user_workflow.jl b/test/user_workflow.jl index f124da9..112af38 100644 --- a/test/user_workflow.jl +++ b/test/user_workflow.jl @@ -96,5 +96,57 @@ function run_user_workflow(conn) @test length(results) == 3 # CALL has a final status result. @test MySQL.ping(conn) DBInterface.execute(conn, "DROP PROCEDURE workflow_results") + run_named_parameter_workflow(conn) + end +end + +# #207: `:name` parameters are rewritten to `?` client-side and bound by name. +function run_named_parameter_workflow(conn) + @testset "named parameters (#207)" begin + DBInterface.execute(conn, "DROP TABLE IF EXISTS named_params") + DBInterface.execute(conn, "CREATE TABLE named_params (id INT PRIMARY KEY, name VARCHAR(32), note VARCHAR(32))") + stmt = DBInterface.prepare(conn, "INSERT INTO named_params (id, name, note) VALUES (:id, :name, ':note')") + try + DBInterface.execute(stmt, (name="one", id=1)) + DBInterface.execute(stmt, Dict(:id => 2, :name => "two")) + DBInterface.execute(stmt, Dict("id" => 3, "name" => "three")) + DBInterface.execute(stmt, (id=4, name="four", unused=true)) + @test_throws MySQL.MySQLInterfaceError DBInterface.execute(stmt, (id=5,)) + @test_throws MySQL.MySQLInterfaceError DBInterface.execute(stmt, Tables.Row((id=5, name="five"))) + DBInterface.execute(stmt, (5, "five")) # positional values bind in marker order + DBInterface.executemany(stmt, (name=["six", "seven"], id=[6, 7])) + DBInterface.executemany(stmt, Dict(:id => [8], :name => ["eight"])) + finally + DBInterface.close!(stmt) + end + rows = Tables.columntable(DBInterface.execute(conn, "SELECT id, name, note FROM named_params ORDER BY id")) + @test rows.id == 1:8 + @test rows.name == ["one", "two", "three", "four", "five", "six", "seven", "eight"] + @test all(==(":note"), rows.note) + + # a reused name binds every use; names are case-sensitive + sql = "SELECT id FROM named_params WHERE id = :Id OR id = :Id + :step ORDER BY id" + @test Tables.columntable(DBInterface.execute(conn, sql, (Id=2, step=1))).id == [2, 3] + @test_throws MySQL.MySQLInterfaceError DBInterface.execute(conn, sql, (id=2, step=1)) + @test_throws MySQL.MySQLInterfaceError DBInterface.prepare(conn, "SELECT :a, ?") + + # the literal ends where the session's sql_mode says it does + DBInterface.execute(conn, "SET @named_saved_mode = @@sql_mode") + DBInterface.execute(conn, "SET SESSION sql_mode = CONCAT(@@sql_mode, ',NO_BACKSLASH_ESCAPES')") + try + @test Tuple(first(DBInterface.execute(conn, "SELECT 'C:\\' AS path, :v AS v", (v=7,)))) == ("C:\\", 7) + finally + DBInterface.execute(conn, "SET SESSION sql_mode = @named_saved_mode") + end + + if MySQL.server_kind(conn) == :mariadb + # MariaDB prepares stored-program DDL: `lbl:LOOP` is a label, not a parameter + DBInterface.execute(conn, "DROP PROCEDURE IF EXISTS named_label") + stmt = DBInterface.prepare(conn, "CREATE PROCEDURE named_label() BEGIN lbl:LOOP LEAVE lbl; END LOOP lbl; END") + DBInterface.execute(stmt) + DBInterface.close!(stmt) + @test DBInterface.execute(conn, "CALL named_label()").rows_affected == 0 + DBInterface.execute(conn, "DROP PROCEDURE named_label") + end end end