Skip to content

Commit e35d13a

Browse files
mcmcgrath13quinnj
mcmcgrath13
authored and
quinnj
committed
Update README.md (#114)
* Update README.md Add table of contents, reorganize slightly, add an example. * Fix anchor links * fix typo * fix example params
1 parent eca52e7 commit e35d13a

File tree

1 file changed

+124
-18
lines changed

1 file changed

+124
-18
lines changed

‎README.md

+124-18
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,16 @@
88
|[![][pkg-0.6-img]][pkg-0.6-url] | [![][travis-img]][travis-url] [![][codecov-img]][codecov-url] |
99

1010

11+
## Table of Contents
12+
13+
- [Installation](#installation)
14+
- [Project Status](#project-status)
15+
- [Contributing and Questions](#contributing-and-questions)
16+
- [Documentation](#documentation)
17+
- [Functions](#functions)
18+
- [Types](#types)
19+
- [Example](#example)
20+
1121
## Installation
1222

1323
The package is registered in `METADATA.jl` and so can be installed with `Pkg.add`.
@@ -45,58 +55,154 @@ Contributions are very welcome, as are feature requests and suggestions. Please
4555

4656
## Documentation
4757

58+
### Functions
59+
60+
#### MySQL.connect
61+
4862
```julia
4963
MySQL.connect(host::String, user::String, passwd::String; db::String = "", port = "3306", socket::String = MySQL.API.MYSQL_DEFAULT_SOCKET, opts = Dict())
5064
```
51-
Connect to a mysql database, returns a `MySQL.Connection` object to be passed to other API functions
65+
Connect to a mysql database. Returns a [`MySQL.Connection`](#mysqlconnection) object to be passed to other API functions.
5266

53-
```julia
54-
MySQL.disconnect(conn::MySQL.Connection)
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).
68+
69+
```
70+
MySQL.API.MYSQL_OPT_CONNECT_TIMEOUT
71+
MySQL.API.MYSQL_OPT_COMPRESS
72+
MySQL.API.MYSQL_OPT_NAMED_PIPE
73+
MySQL.API.MYSQL_INIT_COMMAND
74+
MySQL.API.MYSQL_READ_DEFAULT_FILE
75+
MySQL.API.MYSQL_READ_DEFAULT_GROUP
76+
MySQL.API.MYSQL_SET_CHARSET_DIR
77+
MySQL.API.MYSQL_SET_CHARSET_NAME
78+
MySQL.API.MYSQL_OPT_LOCAL_INFILE
79+
MySQL.API.MYSQL_OPT_PROTOCOL
80+
MySQL.API.MYSQL_SHARED_MEMORY_BASE_NAME
81+
MySQL.API.MYSQL_OPT_READ_TIMEOUT
82+
MySQL.API.MYSQL_OPT_WRITE_TIMEOUT
83+
MySQL.API.MYSQL_OPT_USE_RESULT
84+
MySQL.API.MYSQL_OPT_USE_REMOTE_CONNECTION
85+
MySQL.API.MYSQL_OPT_USE_EMBEDDED_CONNECTION
86+
MySQL.API.MYSQL_OPT_GUESS_CONNECTION
87+
MySQL.API.MYSQL_SET_CLIENT_IP
88+
MySQL.API.MYSQL_SECURE_AUTH
89+
MySQL.API.MYSQL_REPORT_DATA_TRUNCATION
90+
MySQL.API.MYSQL_OPT_RECONNECT
91+
MySQL.API.MYSQL_OPT_SSL_VERIFY_SERVER_CERT
92+
MySQL.API.MYSQL_PLUGIN_DIR
93+
MySQL.API.MYSQL_DEFAULT_AUTH
94+
MySQL.API.MYSQL_OPT_BIND
95+
MySQL.API.MYSQL_OPT_SSL_KEY
96+
MySQL.API.MYSQL_OPT_SSL_CERT
97+
MySQL.API.MYSQL_OPT_SSL_CA
98+
MySQL.API.MYSQL_OPT_SSL_CAPATH
99+
MySQL.API.MYSQL_OPT_SSL_CIPHER
100+
MySQL.API.MYSQL_OPT_SSL_CRL
101+
MySQL.API.MYSQL_OPT_SSL_CRLPATH
102+
MySQL.API.MYSQL_OPT_CONNECT_ATTR_RESET
103+
MySQL.API.MYSQL_OPT_CONNECT_ATTR_ADD
104+
MySQL.API.MYSQL_OPT_CONNECT_ATTR_DELETE
105+
MySQL.API.MYSQL_SERVER_PUBLIC_KEY
106+
MySQL.API.MYSQL_ENABLE_CLEARTEXT_PLUGIN
107+
MySQL.API.MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS
55108
```
56-
Disconnect a `MySQL.Connection` object from the remote database:
109+
110+
#### MySQL.disconnect
57111

58112
```julia
59-
MYSQL.insertid(conn::Connection)
113+
MySQL.disconnect(conn::MySQL.Connection)
60114
```
61-
Get the insert id of the most recently executed SQL statement:
115+
Disconnect a `MySQL.Connection` object from the remote database.
116+
117+
#### MySQL.escape
62118

63119
```julia
64120
MySQL.escape(conn::MySQL.Connection, str::String) -> String
65121
```
66122
Escape an SQL statement
67123

68-
```julia
69-
MySQL.execute!(conn, sql) => # of affected rows
70-
```
71-
Execute an SQL statement without returning results (useful for DDL statements, update, delete, etc.)
124+
#### MySQL.query
72125

73126
```julia
74-
MySQL.query(conn, sql, sink=Data.Table; append::Bool=false) => sink
127+
MySQL.query(conn::MySQL.Connection, sql::String, sink=Data.Table; append::Bool=false) => sink
75128
```
76-
Execute an SQL statement and return the results in `sink`, which can be any valid `Data.Sink` (interface from DataStreams.jl). By default, a NamedTuple of Vectors are returned.
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.
77130

78131
Passing `append=true` as a keyword argument will cause the resultset to be _appended_ to the sink instead of replacing.
79132

80133
To get the results as a `DataFrame`, you can just do `MySQL.query(conn, sql, DataFrame)`.
81134

82135
See list of DataStreams implementations [here](https://github.com/JuliaData/DataStreams.jl#list-of-known-implementations)
83136

137+
#### MySQL.execute!
138+
84139
```julia
85-
MySQL.Query(conn, sql, sink=Data.Table; append::Bool=false) => MySQL.Query
140+
MySQL.execute!(conn::MySQL.Connection, sql::String)
141+
MySQL.execute!(stmt::MySQL.Stmt, params)
86142
```
87-
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)`.
143+
Execute an SQL statement without returning results (useful for DDL statements, update, delete, etc.)
144+
145+
The SQL can either be passed as either a string or a prepared MySQL statement (see [MySQL.Stmt](#mysqlstmt)).
146+
147+
#### MySQL.insertid
88148

89149
```julia
90-
MySQL.Stmt(conn, sql) => MySQL.Stmt
150+
MYSQL.insertid(conn::Connection)
91151
```
92-
Prepare an SQL statement that may contain `?` parameter placeholders.
152+
Get the insert id of the most recently executed SQL statement.
153+
154+
### Types
155+
156+
#### MySQL.Connection
157+
158+
```julia
159+
MySQL.connect(host::String, user::String, passwd::String; db::String = "", port = "3306", socket::String = MySQL.API.MYSQL_DEFAULT_SOCKET, opts = Dict())
160+
```
161+
A connection to a MySQL database.
162+
163+
#### MySQL.Stmt
164+
165+
```julia
166+
MySQL.Stmt(conn::MySQL.Connection, sql::String) => MySQL.Stmt
167+
```
168+
A prepared SQL statement that may contain `?` parameter placeholders.
93169

94170
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.
95171

96172
Bulk statement execution can be accomplished by "streaming" a param source like:
97173

98174
```julia
99-
Data.stream!(source, stmt)
175+
Data.stream!(source::Data.Source, stmt::MySQL.Stmt)
176+
```
177+
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.
179+
180+
#### MySQL.Query
181+
182+
```julia
183+
MySQL.Query(conn, sql, sink=Data.Table; append::Bool=false) => MySQL.Query
184+
```
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)`.
186+
187+
### Example
188+
189+
Connect to a database, query a table, write to a table, then close the database connection.
190+
```julia
191+
using MySQL
192+
using DataFrames
193+
194+
conn = MySQL.connect("localhost", "root", "password", db = "test_db")
195+
196+
foo = MySQL.query(conn, """SELECT COUNT(*) FROM my_first_table;""", DataFrame)
197+
num_foo = foo[1,1]
198+
199+
my_stmt = MySQL.Stmt(conn, """INSERT INTO my_second_table ('foo_id','foo_name') VALUES (?,?);""")
200+
201+
for i = 1:num_foo
202+
MySQL.execute!(my_stmt, [i, "foo_$i"])
203+
end
204+
205+
MySQL.disconnect(conn)
206+
100207
```
101208

102-
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.

0 commit comments

Comments
 (0)