Merge pull request #22 from JuliaDatabases/jq/updates

Few updates

Author: quinnj

Project.toml

@@ -1,7 +1,7 @@
 name = "DBInterface"
 uuid = "a10d1c49-ce27-4219-8d33-6db1a4562965"
 authors = ["Jacob Quinn <quinn.jacobd@gmail.com>"]
-version = "1.0.1"
+version = "2.0.0"
 
 [compat]
 julia = "1"

README.md

@@ -11,7 +11,7 @@ conn = DBInterface.connect(T, args...; kw...) # create a connection to a specifi
 
 stmt = DBInterface.prepare(conn, sql) # prepare a sql statement against the connection; returns a statement object
 
-results = DBInterface.execute!(stmt) # execute a prepared statement; returns an iterator of rows (property-accessible & indexable)
+results = DBInterface.execute(stmt) # execute a prepared statement; returns an iterator of rows (property-accessible & indexable)
 
 rowid = DBInterface.lastrowid(results) # get the last row id of an INSERT statement, as supported by the database
 
@@ -26,17 +26,19 @@ end
 df = DataFrame(results)
 CSV.write("results.csv", results)
 
-results = DBInterface.execute!(conn, sql) # convenience method if statement preparation/re-use isn't needed
+results = DBInterface.execute(conn, sql) # convenience method if statement preparation/re-use isn't needed
 
 stmt = DBInterface.prepare(conn, "INSERT INTO test_table VALUES(?, ?)") # prepare a statement with positional parameters
 
-DBInterface.execute!(stmt, 1, 3.14) # execute the prepared INSERT statement, passing 1 and 3.14 as positional parameters
+DBInterface.execute(stmt, [1, 3.14]) # execute the prepared INSERT statement, passing 1 and 3.14 as positional parameters
 
 stmt = DBInterface.prepare(conn, "INSERT INTO test_table VALUES(:col1, :col2)") # prepare a statement with named parameters
 
-DBInterface.execute!(stmt; col1=1, col2=3.14) # execute the prepared INSERT statement, with 1 and 3.14 as named parameters
+DBInterface.execute(stmt, (col1=1, col2=3.14)) # execute the prepared INSERT statement, with 1 and 3.14 as named parameters
 
-DBInterface.executemany!(stmt; col1=[1,2,3,4,5], col2=[3.14, 1.23, 2.34 3.45, 4.56]) # execute the prepared statement multiple times for each set of named parameters; each named parameter must be an indexable collection
+DBInterface.executemany(stmt, (col1=[1,2,3,4,5], col2=[3.14, 1.23, 2.34 3.45, 4.56])) # execute the prepared statement multiple times for each set of named parameters; each named parameter must be an indexable collection
+
+DBInterface.close!(stmt) # close the prepared statement
 ```
 
 ### For Database Package Developers
@@ -47,6 +49,6 @@ DBInterface.connect
 DBInterface.close!
 DBInterface.Statement
 DBInterface.prepare
-DBInterface.execute!
+DBInterface.execute
 DBInterface.lastrowid
 ```

src/DBInterface.jl

@@ -53,64 +53,76 @@ macro prepare(getDB, sql)
     key = gensym()
     return quote
         get!(DBInterface.PREPARED_STMTS, $(QuoteNode(key))) do
-            println("preparing stmt")
             DBInterface.prepare($(esc(getDB)), $sql)
         end
     end
 end
 
-"Any object that iterates \"rows\", which are objects that are property-accessible and indexable. See `DBInterface.execute!` for more details on fetching query results."
+"Any object that iterates \"rows\", which are objects that are property-accessible and indexable. See `DBInterface.execute` for more details on fetching query results."
 abstract type Cursor end
 
 """
-    DBInterface.execute!(conn::DBInterface.Connection, sql::AbstractString, args...; kw...) => DBInterface.Cursor
-    DBInterface.execute!(stmt::DBInterface.Statement, args...; kw...) => DBInterface.Cursor
+    DBInterface.execute(conn::DBInterface.Connection, sql::AbstractString, [params]) => DBInterface.Cursor
+    DBInterface.execute(stmt::DBInterface.Statement, [params]) => DBInterface.Cursor
 
-Database packages should overload `DBInterface.execute!` for a valid, prepared `DBInterface.Statement` subtype (the first method
-signature is defined in DBInterface.jl using `DBInterface.prepare`), which takes zero or more `args` or `kw` arguments that should
-be bound against the `stmt` (`args` as positional parameters, `kw` as named parameters, but not mixed) before executing the query
-against the database. `DBInterface.execute!` should return a valid `DBInterface.Cursor` object, which is any iterator of "rows",
+Database packages should overload `DBInterface.execute` for a valid, prepared `DBInterface.Statement` subtype (the first method
+signature is defined in DBInterface.jl using `DBInterface.prepare`), which takes an optional `params` argument, which should be
+an indexable collection (`Vector` or `Tuple`) for positional parameters, or a `NamedTuple` for named parameters.
+`DBInterface.execute` should return a valid `DBInterface.Cursor` object, which is any iterator of "rows",
 which themselves must be property-accessible (i.e. implement `propertynames` and `getproperty` for value access by name),
 and indexable (i.e. implement `length` and `getindex` for value access by index). These "result" objects do not need
 to subtype `DBInterface.Cursor` explicitly as long as they satisfy the interface. For DDL/DML SQL statements, which typically
 do not return results, an iterator is still expected to be returned that just iterates `nothing`, i.e. an "empty" iterator.
 """
-function execute! end
+function execute end
 
-execute!(stmt::Statement, args...; kw...) = throw(NotImplementedError("`DBInterface.execute!` not implemented for `$(typeof(stmt))`"))
+execute(stmt::Statement, params=()) = throw(NotImplementedError("`DBInterface.execute` not implemented for `$(typeof(stmt))`"))
 
-execute!(conn::Connection, sql::AbstractString, args...; kw...) = execute!(prepare(conn, sql), args...; kw...)
+execute(conn::Connection, sql::AbstractString, params=()) = execute(prepare(conn, sql), params)
+
+struct LazyIndex{T} <: AbstractVector{Any}
+    x::T
+    i::Int
+end
+
+Base.IndexStyle(::Type{<:LazyIndex}) = Base.IndexLinear()
+Base.IteratorSize(::Type{<:LazyIndex}) = Base.HasLength()
+Base.size(x::LazyIndex) = (length(x.x),)
+Base.getindex(x::LazyIndex, i::Int) = x.x[i][x.i]
 
 """
-    DBInterface.executemany!(conn::DBInterface.Connect, sql::AbstractString, args...; kw...) => Nothing
-    DBInterface.executemany!(stmt::DBInterface.Statement, args...; kw...) => Nothing
+    DBInterface.executemany(conn::DBInterface.Connect, sql::AbstractString, [params]) => Nothing
+    DBInterface.executemany(stmt::DBInterface.Statement, [params]) => Nothing
 
-Similar to 
+Similar in usage to `DBInterface.execute`, but allows passing multiple sets of parameters to be executed in sequence.
+`params`, like for `DBInterface.execute`, should be an indexable collection (`Vector` or `Tuple`) or `NamedTuple`, but instead
+of a single scalar value per parameter, an indexable collection should be passed for each parameter. By default, each set of
+parameters will be looped over and `DBInterface.execute` will be called for each. Note that no result sets or cursors are returned
+for any execution, so the usage is mainly intended for bulk INSERT statements.
 """
-function executemany!(stmt::Statement, args...; kw...)
-    if !isempty(args)
-        arg = args[1]
-        len = length(arg)
-        all(x -> length(x) == len, args) || throw(ParameterError("positional parameters provided to `DBInterface.executemany!` do not all have the same number of parameters"))
-        for i = 1:len
-            xargs = map(x -> x[i], args)
-            execute!(stmt, xargs...)
-        end
-    elseif !isempty(kw)
-        k = kw[1]
-        len = length(k)
-        all(x -> length(x) == len, kw) || throw(ParameterError("named parameters provided to `DBInterface.executemany!` do not all have the same number of parameters"))
+function executemany(stmt::Statement, params=())
+    if !isempty(params)
+        param = params[1]
+        len = length(param)
+        all(x -> length(x) == len, params) || throw(ParameterError("parameters provided to `DBInterface.executemany!` do not all have the same number of parameters"))
         for i = 1:len
-            xargs = collect(k=>v[i] for (k, v) in kw)
-            execute!(stmt; xargs...)
+            xargs = LazyIndex(params, i)
+            execute(stmt, xargs)
         end
     else
-        execute!(stmt)
+        execute(stmt)
     end
     return
 end
 
-executemany!(conn::Connection, sql::AbstractString, args...; kw...) = executemany!(prepare(conn, sql), args...; kw...)
+executemany(conn::Connection, sql::AbstractString, params=()) = executemany(prepare(conn, sql), params)
+
+"""
+    DBInterface.close!(stmt::DBInterface.Statement)
+
+Close a prepared statement so further queries cannot be executed.
+"""
+close!(stmt::Statement) = throw(NotImplementedError("`DBInterface.close!` not implemented for `$(typeof(stmt))`"))
 
 """
     DBInterface.lastrowid(x::Cursor) => Int