Allow passing value parameters to bind in SQLite.execute (#190)

* Allow passing value parameters to bind in SQLite.execute

Author: quinnj

docs/src/index.md

@@ -49,12 +49,13 @@ SQLite.load!
   > In the examples above, NNN is an integer value and AAA is an identifier. A parameter initially has a value of NULL. Prior to calling sqlite3_step() for the first time or immediately after sqlite3_reset(), the application can invoke one of the sqlite3_bind() interfaces to attach values to the parameters. Each call to sqlite3_bind() overrides prior bindings on the same parameter.
 
 
-* `SQLite.execute!(stmt::SQLite.Stmt)`
+* `SQLite.execute!(stmt::SQLite.Stmt; values=[])`
 
   `SQLite.execute!(db::SQLite.DB, sql::String)`
 
 
-  Used to execute a prepared `SQLite.Stmt`. The 2nd method is a convenience method to pass in an SQL statement as a string which gets prepared and executed in one call. This method does not check for or return any results, hence it is only useful for database manipulation methods (i.e. ALTER, CREATE, UPDATE, DROP). To return results, see `SQLite.query` below.
+  Used to execute a prepared `SQLite.Stmt`. The 2nd method is a convenience method to pass in an SQL statement as a string which gets prepared and executed in one call. This method does not check for or return any results, hence it is only useful for database manipulation methods (i.e. ALTER, CREATE, UPDATE, DROP). To return results, see `SQLite.query` below. With a prepared `stmt`, you can also pass a `values` iterable or `Dict` that will bind to 
+  parameters in the prepared query.
 
 
 * `SQLite.Query(db::SQLite.DB, sql::String, values=[])`

src/SQLite.jl

@@ -106,23 +106,25 @@ Additional methods exist for working individual SQL parameters:
 """
 function bind! end
 
+bind!(stmt::Stmt, ::Nothing) = nothing
+
 function bind!(stmt::Stmt, values::Tuple)
     nparams = sqlite3_bind_parameter_count(stmt.handle)
-    @assert nparams == length(values) "you must provide values for all placeholders"
+    @assert nparams == length(values) "you must provide values for all query placeholders"
     for i in 1:nparams
         @inbounds bind!(stmt, i, values[i])
     end
 end
 function bind!(stmt::Stmt, values::Vector)
     nparams = sqlite3_bind_parameter_count(stmt.handle)
-    @assert nparams == length(values) "you must provide values for all placeholders"
+    @assert nparams == length(values) "you must provide values for all query placeholders"
     for i in 1:nparams
         @inbounds bind!(stmt, i, values[i])
     end
 end
 function bind!(stmt::Stmt, values::Dict{Symbol, V}) where {V}
     nparams = sqlite3_bind_parameter_count(stmt.handle)
-    @assert nparams == length(values) "you must provide values for all placeholders"
+    @assert nparams == length(values) "you must provide values for all query placeholders"
     for i in 1:nparams
         name = unsafe_string(sqlite3_bind_parameter_name(stmt.handle, i))
         @assert !isempty(name) "nameless parameters should be passed as a Vector"
@@ -235,16 +237,16 @@ sqlitetype(::Type{Missing}) = "NULL"
 sqlitetype(x) = "BLOB"
 
 """
-`SQLite.execute!(stmt::SQLite.Stmt)` => `Cvoid`
-
-`SQLite.execute!(db::DB, sql::String)` => `Cvoid`
-
+  `SQLite.execute!(stmt::SQLite.Stmt; values=[])` => `nothing`
+  `SQLite.execute!(db::DB, sql::String)` => `nothing`
 
 Execute a prepared SQLite statement, not checking for or returning any results.
+Will bind `values` to any parameters in `stmt`.
 """
 function execute! end
 
-function execute!(stmt::Stmt)
+function execute!(stmt::Stmt; values=nothing)
+    bind!(stmt, values)
     r = sqlite3_step(stmt.handle)
     if r == SQLITE_DONE
         sqlite3_reset(stmt.handle)
@@ -256,8 +258,9 @@ function execute!(stmt::Stmt)
     return r
 end
 
-function execute!(db::DB, sql::AbstractString)
+function execute!(db::DB, sql::AbstractString; values=nothing)
     stmt = Stmt(db, sql)
+    bind!(stmt, values)
     r = execute!(stmt)
     finalize(stmt)
     return r

test/runtests.jl

@@ -99,24 +99,24 @@ r = SQLite.Query(db, "select * from $tablename") |> DataFrame
 @test all([typeof(i) for i in r[1]] .== Dates.Date)
 SQLite.drop!(db, "$tablename")
 
-SQLite.Query(db, "CREATE TABLE temp AS SELECT * FROM Album")
+SQLite.execute!(db, "CREATE TABLE temp AS SELECT * FROM Album")
 r = SQLite.Query(db, "SELECT * FROM temp LIMIT ?"; values=[3]) |> DataFrame
 @test size(r) == (3,3)
 r = SQLite.Query(db, "SELECT * FROM temp WHERE Title LIKE ?"; values=["%time%"]) |> DataFrame
 @test r[1] == [76, 111, 187]
-SQLite.Query(db, "INSERT INTO temp VALUES (?1, ?3, ?2)"; values=[0,0,"Test Album"])
+SQLite.execute!(db, "INSERT INTO temp VALUES (?1, ?3, ?2)"; values=[0,0,"Test Album"])
 r = SQLite.Query(db, "SELECT * FROM temp WHERE AlbumId = 0") |> DataFrame
 @test r[1][1] === 0
 @test r[2][1] == "Test Album"
 @test r[3][1] === 0
 SQLite.drop!(db, "temp")
 
-SQLite.Query(db, "CREATE TABLE temp AS SELECT * FROM Album")
+SQLite.execute!(db, "CREATE TABLE temp AS SELECT * FROM Album")
 r = SQLite.Query(db, "SELECT * FROM temp LIMIT :a"; values=Dict(:a => 3)) |> DataFrame
 @test size(r) == (3,3)
 r = SQLite.Query(db, "SELECT * FROM temp WHERE Title LIKE @word"; values=Dict(:word => "%time%")) |> DataFrame
 @test r[1] == [76, 111, 187]
-SQLite.Query(db, "INSERT INTO temp VALUES (@lid, :title, \$rid)"; values=Dict(:rid => 0, :lid => 0, :title => "Test Album"))
+SQLite.execute!(db, "INSERT INTO temp VALUES (@lid, :title, \$rid)"; values=Dict(:rid => 0, :lid => 0, :title => "Test Album"))
 r = SQLite.Query(db, "SELECT * FROM temp WHERE AlbumId = 0") |> DataFrame
 @test r[1][1] === 0
 @test r[2][1] == "Test Album"
@@ -185,10 +185,10 @@ r = SQLite.Query(db, "SELECT bigsum(TrackId) FROM PlaylistTrack") |> DataFrame
 s = SQLite.Query(db, "SELECT TrackId FROM PlaylistTrack") |> DataFrame
 # @test r[1][1] == big(sum(convert(Vector{Int},s[1])))
 
-SQLite.Query(db, "CREATE TABLE points (x INT, y INT, z INT)")
-SQLite.Query(db, "INSERT INTO points VALUES (?, ?, ?)"; values=[1, 2, 3])
-SQLite.Query(db, "INSERT INTO points VALUES (?, ?, ?)"; values=[4, 5, 6])
-SQLite.Query(db, "INSERT INTO points VALUES (?, ?, ?)"; values=[7, 8, 9])
+SQLite.execute!(db, "CREATE TABLE points (x INT, y INT, z INT)")
+SQLite.execute!(db, "INSERT INTO points VALUES (?, ?, ?)"; values=[1, 2, 3])
+SQLite.execute!(db, "INSERT INTO points VALUES (?, ?, ?)"; values=[4, 5, 6])
+SQLite.execute!(db, "INSERT INTO points VALUES (?, ?, ?)"; values=[7, 8, 9])
 
 sumpoint(p::Point3D, x, y, z) = p + Point3D(x, y, z)
 SQLite.register(db, Point3D(0, 0, 0), sumpoint)
@@ -197,7 +197,7 @@ r = SQLite.Query(db, "SELECT sumpoint(x, y, z) FROM points") |> DataFrame
 SQLite.drop!(db, "points")
 
 db2 = SQLite.DB()
-SQLite.Query(db2, "CREATE TABLE tab1 (r REAL, s INT)")
+SQLite.execute!(db2, "CREATE TABLE tab1 (r REAL, s INT)")
 
 @test_throws SQLite.SQLiteException SQLite.drop!(db2, "nonexistant")
 # should not throw anything
@@ -233,22 +233,22 @@ stmt = SQLite.Stmt(db, "INSERT INTO tbl (a) VALUES (@a);")
 SQLite.bind!(stmt, "@a", 1)
 
 binddb = SQLite.DB()
-SQLite.Query(binddb, "CREATE TABLE temp (n NULL, i6 INT, f REAL, s TEXT, a BLOB)")
-SQLite.Query(binddb, "INSERT INTO temp VALUES (?1, ?2, ?3, ?4, ?5)"; values=Any[missing, convert(Int64,6), 6.4, "some text", b"bytearray"])
+SQLite.execute!(binddb, "CREATE TABLE temp (n NULL, i6 INT, f REAL, s TEXT, a BLOB)")
+SQLite.execute!(binddb, "INSERT INTO temp VALUES (?1, ?2, ?3, ?4, ?5)"; values=Any[missing, convert(Int64,6), 6.4, "some text", b"bytearray"])
 r = SQLite.Query(binddb, "SELECT * FROM temp") |> DataFrame
 @test isa(r[1][1], Missing)
 @test isa(r[2][1], Int)
 @test isa(r[3][1], Float64)
 @test isa(r[4][1], AbstractString)
 @test isa(r[5][1], Base.CodeUnits)
-SQLite.Query(binddb, "CREATE TABLE blobtest (a BLOB, b BLOB)")
-SQLite.Query(binddb, "INSERT INTO blobtest VALUES (?1, ?2)"; values=Any[b"a", b"b"])
-SQLite.Query(binddb, "INSERT INTO blobtest VALUES (?1, ?2)"; values=Any[b"a", BigInt(2)])
+SQLite.execute!(binddb, "CREATE TABLE blobtest (a BLOB, b BLOB)")
+SQLite.execute!(binddb, "INSERT INTO blobtest VALUES (?1, ?2)"; values=Any[b"a", b"b"])
+SQLite.execute!(binddb, "INSERT INTO blobtest VALUES (?1, ?2)"; values=Any[b"a", BigInt(2)])
 
 p1 = Point(1, 2)
 p2 = Point(1.3, 2.4)
-SQLite.Query(binddb, "INSERT INTO blobtest VALUES (?1, ?2)"; values=Any[b"a", p1])
-SQLite.Query(binddb, "INSERT INTO blobtest VALUES (?1, ?2)"; values=Any[b"a", p2])
+SQLite.execute!(binddb, "INSERT INTO blobtest VALUES (?1, ?2)"; values=Any[b"a", p1])
+SQLite.execute!(binddb, "INSERT INTO blobtest VALUES (?1, ?2)"; values=Any[b"a", p2])
 r = SQLite.Query(binddb, "SELECT * FROM blobtest"; stricttypes=false) |> DataFrame
 for value in r[1]
     @test value == b"a"