Skip to content

Commit a0e70de

Browse files
mcmcgrath13quinnj
authored andcommitted
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
1 parent 5e77dfa commit a0e70de

File tree

7 files changed

+59
-43
lines changed

7 files changed

+59
-43
lines changed

.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,6 @@ deps/mysql-connector*
3737
deps/downloads/
3838
deps/manifests/
3939
deps/build.log
40+
41+
# Manifest file
42+
Manifest.toml

Project.toml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name = "MySQL"
2+
uuid = "39abe10b-433b-5dbd-92d4-e302a9df00cd"
3+
author = ["quinnj"]
4+
version = "0.7.0"
5+
6+
[deps]
7+
BinaryProvider = "b99e7846-7c00-51b0-8f62-c81ae34c0232"
8+
Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
9+
DecFP = "55939f99-70c6-5e9b-8bb0-5071ed7d61fd"
10+
Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
11+
12+
[compat]
13+
julia = ">=0.7"
14+
15+
[extras]
16+
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
17+
18+
[targets]
19+
test = ["Test"]

README.md

+17-22
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ julia> Pkg.add("MySQL")
2828

2929
## Project Status
3030

31-
The package is tested against the current Julia `0.6` release and nightly on Linux and OS X.
31+
The package is tested against the current Julia `1.0` release and nightly on Linux and OS X.
3232

3333
## Contributing and Questions
3434

@@ -64,7 +64,7 @@ MySQL.connect(host::String, user::String, passwd::String; db::String="", port::I
6464
```
6565
Connect to a mysql database. Returns a [`MySQL.Connection`](#mysqlconnection) object to be passed to other API functions.
6666

67-
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).
67+
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).
6868

6969
```
7070
MySQL.API.MYSQL_OPT_CONNECT_TIMEOUT
@@ -121,18 +121,15 @@ MySQL.escape(conn::MySQL.Connection, str::String) -> String
121121
```
122122
Escape an SQL statement
123123

124-
#### MySQL.query
124+
#### MySQL.Query (previously MySQL.query)
125125

126126
```julia
127-
MySQL.query(conn::MySQL.Connection, sql::String, sink=Data.Table; append::Bool=false) => sink
127+
MySQL.Query(conn::MySQL.Connection, sql::String; append::Bool=false) => sink
128128
```
129-
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.
129+
Execute an SQL statement and return the results as a MySQL.Query object (see [MySQL.Query](#mysqlquery)).
130130

131-
Passing `append=true` as a keyword argument will cause the resultset to be _appended_ to the sink instead of replacing.
132-
133-
To get the results as a `DataFrame`, you can just do `MySQL.query(conn, sql, DataFrame)`.
134-
135-
See list of DataStreams implementations [here](https://github.com/JuliaData/DataStreams.jl#list-of-known-implementations)
131+
The results can be materialized as a data sink that implements the Tables.jl interface.
132+
E.g. `MySQL.Query(conn, sql) |> DataFrame` or `MySQL.Query(conn, sql) |> columntable`
136133

137134
#### MySQL.execute!
138135

@@ -167,22 +164,21 @@ MySQL.Stmt(conn::MySQL.Connection, sql::String) => MySQL.Stmt
167164
```
168165
A prepared SQL statement that may contain `?` parameter placeholders.
169166

170-
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.
171-
172-
Bulk statement execution can be accomplished by "streaming" a param source like:
173-
174-
```julia
175-
Data.stream!(source::Data.Source, stmt::MySQL.Stmt)
176-
```
167+
A `MySQL.Stmt` may then be executed by calling `MySQL.execute!(stmt, params)` where
168+
`params` is a vector with the values to be bound to the `?` placeholders in the
169+
original SQL statement. Params must be provided for every `?` and will be matched in the same order they
170+
appeared in the original SQL statement.
177171

178-
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.
172+
Alternately, a source implementing the Tables.jl interface can be streamed by executing
173+
`MySQL.execute!(itr, stmt)`. Each row must have a value for each param.
179174

180175
#### MySQL.Query
181176

182177
```julia
183-
MySQL.Query(conn, sql, sink=Data.Table; append::Bool=false) => MySQL.Query
178+
MySQL.Query(conn, sql, sink=Data.Table, kwargs...) => MySQL.Query
184179
```
185-
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)`.
180+
181+
Execute an SQL statement and return a `MySQL.Query` object. Result rows can be iterated.
186182

187183
### Example
188184

@@ -193,7 +189,7 @@ using DataFrames
193189

194190
conn = MySQL.connect("localhost", "root", "password", db = "test_db")
195191

196-
foo = MySQL.query(conn, """SELECT COUNT(*) FROM my_first_table;""", DataFrame)
192+
foo = MySQL.query(conn, """SELECT COUNT(*) FROM my_first_table;""") |> DataFrame
197193
num_foo = foo[1,1]
198194

199195
my_stmt = MySQL.Stmt(conn, """INSERT INTO my_second_table ('foo_id','foo_name') VALUES (?,?);""")
@@ -203,5 +199,4 @@ for i = 1:num_foo
203199
end
204200

205201
MySQL.disconnect(conn)
206-
207202
```

src/MySQL.jl

+1-7
Original file line numberDiff line numberDiff line change
@@ -93,13 +93,7 @@ end
9393
"""
9494
MySQL.query(conn, sql, sink=Data.Table, args...; append::Bool=false) => sink
9595
96-
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.
97-
98-
Passing `append=true` as a keyword argument will cause the resultset to be _appended_ to the sink instead of replacing.
99-
100-
To get the results as a `DataFrame`, you can just do `MySQL.query(conn, sql, DataFrame)`.
101-
102-
See list of DataStreams implementations [here](https://github.com/JuliaData/DataStreams.jl#list-of-known-implementations)
96+
Deprecated. See MySQL.Query
10397
"""
10498
function query end
10599

src/prepared.jl

+6-6
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,13 @@ Base.showerror(io::IO, e::MySQLStatementError) = print(io, unsafe_string(API.mys
99
1010
Prepare an SQL statement that may contain `?` parameter placeholders.
1111
12-
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.
12+
A `MySQL.Stmt` may then be executed by calling `MySQL.execute!(stmt, params)` where
13+
`params` is a vector with the values to be bound to the `?` placeholders in the
14+
original SQL statement. Params must be provided for every `?` and will be matched in the same order they
15+
appeared in the original SQL statement.
1316
14-
Bulk statement execution can be accomplished by "streaming" a param source like:
15-
16-
Data.stream!(source, stmt)
17-
18-
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.
17+
Alternately, a source implementing the Tables.jl interface can be streamed by executing
18+
`MySQL.execute!(itr, stmt)`. Each row must have a value for each param.
1919
"""
2020
mutable struct Stmt
2121
ptr::Ptr{Cvoid}

src/types.jl

+6-2
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,13 @@ function julia_type(field_type, notnullable, isunsigned)
6262
end
6363

6464
"""
65-
MySQL.Query(conn, sql, sink=Data.Table; append::Bool=false) => MySQL.Query
65+
MySQL.Query(conn, sql, sink=Data.Table; kwargs...) => MySQL.Query
6666
67-
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)`.
67+
Execute an SQL statement and return a `MySQL.Query` object. Result rows can be
68+
iterated as NamedTuples via `Data.rows(query)` where `query` is the `MySQL.Query`
69+
object.
70+
71+
To materialize the results as a `DataFrame`, use `MySQL.query(conn, sql) |> DataFrame`.
6872
"""
6973
function Query(conn::Connection, sql::String; kwargs...)
7074
conn.ptr == C_NULL && throw(MySQLInterfaceError("Method called with null connection."))

test/runtests.jl

+7-6
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ MySQL.execute!(conn, """INSERT INTO Employee (Name, Salary, JoinDate, LastLogin,
3737
# id = MySQL.insertid(conn)
3838
# println("Last insert id was $id")
3939

40-
res = MySQL.query(conn, "select * from Employee")
40+
res = MySQL.Query(conn, "select * from Employee") |> columntable
4141

4242
@test length(res) == 10
4343
@test length(res[1]) == 4
@@ -61,7 +61,7 @@ expected = (
6161
# insert null row
6262
MySQL.execute!(conn, "INSERT INTO Employee () VALUES ();")
6363

64-
res = MySQL.query(conn, "select * from Employee")
64+
res = MySQL.Query(conn, "select * from Employee") |> columntable
6565

6666
foreach(x->push!(x[2], x[1] == 1 ? Int32(5) : missing), enumerate(expected))
6767
@test isequal(res, expected)
@@ -76,14 +76,15 @@ end
7676
stmt = MySQL.Stmt(conn, "UPDATE Employee SET Salary = ? WHERE ID > ?;")
7777
affrows = MySQL.execute!(stmt, [25000, 2])
7878

79-
res = MySQL.query(conn, "select Salary from Employee")
79+
res = MySQL.Query(conn, "select Salary from Employee") |> columntable
8080
@test all(res[1][3:end] .== 25000)
8181

8282
affrows = MySQL.execute!(stmt, [missing, 2])
8383

84-
res = MySQL.query(conn, "select Salary from Employee")
84+
res = MySQL.Query(conn, "select Salary from Employee") |> columntable
8585
@test all(res[1][3:end] .=== missing)
8686

87+
# test prepared statements
8788
stmt = MySQL.Stmt(conn, "INSERT INTO Employee (Name, Salary, JoinDate, LastLogin, LunchTime, OfficeNo, empno) VALUES (?, ?, ?, ?, ?, ?, ?);")
8889

8990
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
9394

9495
MySQL.execute!(values, stmt)
9596

96-
res = MySQL.query(conn, "select * from Employee")
97+
res = MySQL.Query(conn, "select * from Employee") |> columntable
9798
@test length(res) == 10
9899
@test length(res[1]) == 9
99100

@@ -104,7 +105,7 @@ MySQL.execute!(conn, """DROP DATABASE if exists mysqltest2;
104105
CREATE TABLE test (a varchar(20), b integer);
105106
INSERT INTO test (a,b) value ("test",123);""")
106107

107-
res = MySQL.query(conn, """select * from test;""")
108+
res = MySQL.Query(conn, """select * from test;""") |> columntable
108109

109110
@test res.a[1] == "test"
110111
@test res.b[1] == 123

0 commit comments

Comments
 (0)