Doc/test updates (#122)

* refactor: add project.toml, set up so tests can run from pkg>

* test: query -> query, materialize results into columntable

* docs: update docs to reflect tables.jl interface

* docs: remove append to sink reference

* docs: update query signature line

* docs: udpate MySQL.Query docstring signature

* Update Project.toml

Author: mcmcgrath13

.gitignore

@@ -37,3 +37,6 @@ deps/mysql-connector*
 deps/downloads/
 deps/manifests/
 deps/build.log
+
+# Manifest file
+Manifest.toml

Project.toml

@@ -0,0 +1,19 @@
+name = "MySQL"
+uuid = "39abe10b-433b-5dbd-92d4-e302a9df00cd"
+author = ["quinnj"]
+version = "0.7.0"
+
+[deps]
+BinaryProvider = "b99e7846-7c00-51b0-8f62-c81ae34c0232"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+DecFP = "55939f99-70c6-5e9b-8bb0-5071ed7d61fd"
+Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
+
+[compat]
+julia = ">=0.7"
+
+[extras]
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test"]

README.md

@@ -28,7 +28,7 @@ julia> Pkg.add("MySQL")
 
 ## Project Status
 
-The package is tested against the current Julia `0.6` release and nightly on Linux and OS X.
+The package is tested against the current Julia `1.0` release and nightly on Linux and OS X.
 
 ## Contributing and Questions
 
@@ -64,7 +64,7 @@ MySQL.connect(host::String, user::String, passwd::String; db::String="", port::I
 ```
 Connect to a mysql database. Returns a [`MySQL.Connection`](#mysqlconnection) object to be passed to other API functions.
 
-Options are passed via dictionary. The available keys are below and a descrition of the options can be found in the [MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/mysql-options.html).
+Options are passed via dictionary. The available keys are below and a description of the options can be found in the [MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/mysql-options.html).
 
 ```
 MySQL.API.MYSQL_OPT_CONNECT_TIMEOUT
@@ -121,18 +121,15 @@ MySQL.escape(conn::MySQL.Connection, str::String) -> String
 ```
 Escape an SQL statement
 
-#### MySQL.query
+#### MySQL.Query (previously MySQL.query)
 
 ```julia
-MySQL.query(conn::MySQL.Connection, sql::String, sink=Data.Table; append::Bool=false) => sink
+MySQL.Query(conn::MySQL.Connection, sql::String; append::Bool=false) => sink
 ```
-Execute an SQL statement and return the results in the `sink`, which can be any valid `Data.Sink` (interface from [DataStreams.jl](https://github.com/JuliaData/DataStreams.jl)). By default, a NamedTuple of Vectors is returned.
+Execute an SQL statement and return the results as a MySQL.Query object (see [MySQL.Query](#mysqlquery)).
 
-Passing `append=true` as a keyword argument will cause the resultset to be _appended_ to the sink instead of replacing.
-
-To get the results as a `DataFrame`, you can just do `MySQL.query(conn, sql, DataFrame)`.
-
-See list of DataStreams implementations [here](https://github.com/JuliaData/DataStreams.jl#list-of-known-implementations)
+The results can be materialized as a data sink that implements the Tables.jl interface.
+E.g. `MySQL.Query(conn, sql) |> DataFrame` or `MySQL.Query(conn, sql) |> columntable`
 
 #### MySQL.execute!
 
@@ -167,22 +164,21 @@ MySQL.Stmt(conn::MySQL.Connection, sql::String) => MySQL.Stmt
 ```
 A prepared SQL statement that may contain `?` parameter placeholders.
 
-A `MySQL.Stmt` may then be executed by calling `MySQL.execute!(stmt, params)` where `params` are the values to be bound to the `?` placeholders in the original SQL statement. Params must be provided for every `?` and will be matched in the same order they appeared in the original SQL statement.
-
-Bulk statement execution can be accomplished by "streaming" a param source like:
-
-```julia
-Data.stream!(source::Data.Source, stmt::MySQL.Stmt)
-```
+A `MySQL.Stmt` may then be executed by calling `MySQL.execute!(stmt, params)` where
+`params` is a vector with the values to be bound to the `?` placeholders in the
+original SQL statement. Params must be provided for every `?` and will be matched in the same order they
+appeared in the original SQL statement.
 
-where `source` is any valid `Data.Source` (from DataStreams.jl). As with `MySQL.execute!`, the `source` must provide enough params and will be matched in the same order.
+Alternately, a source implementing the Tables.jl interface can be streamed by executing
+`MySQL.execute!(itr, stmt)`. Each row must have a value for each param.
 
 #### MySQL.Query
 
 ```julia
-MySQL.Query(conn, sql, sink=Data.Table; append::Bool=false) => MySQL.Query
+MySQL.Query(conn, sql, sink=Data.Table, kwargs...) => MySQL.Query
 ```
-Execute an SQL statement and return a `MySQL.Query` object. Result rows can be iterated as NamedTuples via `Data.rows(query)` where `query` is the `MySQL.Query` object. Results can also be streamed to any valid `Data.Sink` via `Data.stream!(query, sink)`.
+
+Execute an SQL statement and return a `MySQL.Query` object. Result rows can be iterated.
 
 ### Example
 
@@ -193,7 +189,7 @@ using DataFrames
 
 conn = MySQL.connect("localhost", "root", "password", db = "test_db")
 
-foo = MySQL.query(conn, """SELECT COUNT(*) FROM my_first_table;""", DataFrame)
+foo = MySQL.query(conn, """SELECT COUNT(*) FROM my_first_table;""") |> DataFrame
 num_foo = foo[1,1]
 
 my_stmt = MySQL.Stmt(conn, """INSERT INTO my_second_table ('foo_id','foo_name') VALUES (?,?);""")
@@ -203,5 +199,4 @@ for i = 1:num_foo
 end
 
 MySQL.disconnect(conn)
-
 ```

src/MySQL.jl

@@ -93,13 +93,7 @@ end
 """
     MySQL.query(conn, sql, sink=Data.Table, args...; append::Bool=false) => sink
 
-execute an sql statement and return the results in `sink`, which can be any valid `Data.Sink` (interface from DataStreams.jl), and `args...` are any necessary arguments to the sink. By default, a NamedTuple of Vectors are returned.
-
-Passing `append=true` as a keyword argument will cause the resultset to be _appended_ to the sink instead of replacing.
-
-To get the results as a `DataFrame`, you can just do `MySQL.query(conn, sql, DataFrame)`.
-
-See list of DataStreams implementations [here](https://github.com/JuliaData/DataStreams.jl#list-of-known-implementations)
+Deprecated.  See MySQL.Query
 """
 function query end
 

src/prepared.jl

@@ -9,13 +9,13 @@ Base.showerror(io::IO, e::MySQLStatementError) = print(io, unsafe_string(API.mys
 
 Prepare an SQL statement that may contain `?` parameter placeholders.
 
-A `MySQL.Stmt` may then be executed by calling `MySQL.execute!(stmt, params)` where `params` are the values to be bound to the `?` placeholders in the original SQL statement. Params must be provided for every `?` and will be matched in the same order they appeared in the original SQL statement.
+A `MySQL.Stmt` may then be executed by calling `MySQL.execute!(stmt, params)` where
+`params` is a vector with the values to be bound to the `?` placeholders in the
+original SQL statement. Params must be provided for every `?` and will be matched in the same order they
+appeared in the original SQL statement.
 
-Bulk statement execution can be accomplished by "streaming" a param source like:
-
-    Data.stream!(source, stmt)
-
-where `source` is any valid `Data.Source` (from DataStreams.jl). As with `MySQL.execute!`, the `source` must provide enough params and will be matched in the same order.
+Alternately, a source implementing the Tables.jl interface can be streamed by executing
+`MySQL.execute!(itr, stmt)`. Each row must have a value for each param.
 """
 mutable struct Stmt
     ptr::Ptr{Cvoid}

src/types.jl

@@ -62,9 +62,13 @@ function julia_type(field_type, notnullable, isunsigned)
 end
 
 """
-    MySQL.Query(conn, sql, sink=Data.Table; append::Bool=false) => MySQL.Query
+    MySQL.Query(conn, sql, sink=Data.Table; kwargs...) => MySQL.Query
 
-execute an sql statement and return a `MySQL.Query` object. Result rows can be iterated as NamedTuples via `Data.rows(query)` where `query` is the `MySQL.Query` object. Results can also be streamed to any valid `Data.Sink` via `Data.stream!(query, sink)`.
+Execute an SQL statement and return a `MySQL.Query` object. Result rows can be
+iterated as NamedTuples via `Data.rows(query)` where `query` is the `MySQL.Query`
+object.
+
+To materialize the results as a `DataFrame`, use `MySQL.query(conn, sql) |> DataFrame`.
 """
 function Query(conn::Connection, sql::String; kwargs...)
     conn.ptr == C_NULL && throw(MySQLInterfaceError("Method called with null connection."))

test/runtests.jl

@@ -37,7 +37,7 @@ MySQL.execute!(conn, """INSERT INTO Employee (Name, Salary, JoinDate, LastLogin,
 # id = MySQL.insertid(conn)
 # println("Last insert id was $id")
 
-res = MySQL.query(conn, "select * from Employee")
+res = MySQL.Query(conn, "select * from Employee") |> columntable
 
 @test length(res) == 10
 @test length(res[1]) == 4
@@ -61,7 +61,7 @@ expected = (
 # insert null row
 MySQL.execute!(conn, "INSERT INTO Employee () VALUES ();")
 
-res = MySQL.query(conn, "select * from Employee")
+res = MySQL.Query(conn, "select * from Employee") |> columntable
 
 foreach(x->push!(x[2], x[1] == 1 ? Int32(5) : missing), enumerate(expected))
 @test isequal(res, expected)
@@ -76,14 +76,15 @@ end
 stmt = MySQL.Stmt(conn, "UPDATE Employee SET Salary = ? WHERE ID > ?;")
 affrows = MySQL.execute!(stmt, [25000, 2])
 
-res = MySQL.query(conn, "select Salary from Employee")
+res = MySQL.Query(conn, "select Salary from Employee") |> columntable
 @test all(res[1][3:end] .== 25000)
 
 affrows = MySQL.execute!(stmt, [missing, 2])
 
-res = MySQL.query(conn, "select Salary from Employee")
+res = MySQL.Query(conn, "select Salary from Employee") |> columntable
 @test all(res[1][3:end] .=== missing)
 
+# test prepared statements
 stmt = MySQL.Stmt(conn, "INSERT INTO Employee (Name, Salary, JoinDate, LastLogin, LunchTime, OfficeNo, empno) VALUES (?, ?, ?, ?, ?, ?, ?);")
 
 values = [(Name="John", Salary=10000.50, JoinDate=Date("2015-8-3"), LastLogin=DateTime("2015-9-5T12:31:30"), LunchTime=Dates.Time(12,00,00), OfficeNo=1, empno=1301),
@@ -93,7 +94,7 @@ values = [(Name="John", Salary=10000.50, JoinDate=Date("2015-8-3"), LastLogin=Da
 
 MySQL.execute!(values, stmt)
 
-res = MySQL.query(conn, "select * from Employee")
+res = MySQL.Query(conn, "select * from Employee") |> columntable
 @test length(res) == 10
 @test length(res[1]) == 9
 
@@ -104,7 +105,7 @@ MySQL.execute!(conn, """DROP DATABASE if exists mysqltest2;
     CREATE TABLE test (a varchar(20), b integer);
     INSERT INTO test (a,b) value ("test",123);""")
 
-res = MySQL.query(conn, """select * from test;""")
+res = MySQL.Query(conn, """select * from test;""") |> columntable
 
 @test res.a[1] == "test"
 @test res.b[1] == 123