mysql.safe.connection source code

1 /++
2 Connect to a MySQL/MariaDB server (safe version).
3 
4 This is the @safe API for the Connection type. It publicly imports `mysql.impl.connection`, and also provides the safe version of the API for preparing statements.
5 
6 Note that the common pieces of the connection are documented and currently
7 reside in `mysql.impl.connection`. Please see this module for documentation of
8 the connection object.
9 
10 $(SAFE_MIGRATION)
11 +/
12 module mysql.safe.connection;
13 
14 public import mysql.impl.connection;
15 import mysql.safe.prepared;
16 import mysql.safe.commands;
17 
18 
19 @safe:
20 
21 /++
22 Submit an SQL command to the server to be compiled into a prepared statement.
23 
24 This will automatically register the prepared statement on the provided connection.
25 The resulting `mysql.impl.prepared.SafePrepared` can then be used freely on ANY
26 `mysql.impl.connection.Connection`, as it will automatically be registered upon
27 its first use on other connections. Or, pass it to
28 `mysql.impl.connection.Connection.register` if you prefer eager registration.
29 
30 Internally, the result of a successful outcome will be a statement handle - an ID -
31 for the prepared statement, a count of the parameters required for
32 execution of the statement, and a count of the columns that will be present
33 in any result set that the command generates.
34 
35 The server will then proceed to send prepared statement headers,
36 including parameter descriptions, and result set field descriptions,
37 followed by an EOF packet.
38 
39 Throws: `mysql.exceptions.MYX` if the server has a problem.
40 
41 Params:
42 	conn = The connection to use.
43 	sql = The SQL statement to prepare.
44 +/
45 SafePrepared prepare(Connection conn, const(char[]) sql)
46 {
47 	auto info = conn.registerIfNeeded(sql);
48 	return SafePrepared(sql, info.headers, info.numParams);
49 }
50 
51 /++
52 Convenience function to create a prepared statement which calls a stored function.
53 
54 Be careful that your `numArgs` is correct. If it isn't, you may get a
55 `mysql.exceptions.MYX` with a very unclear error message.
56 
57 Throws: `mysql.exceptions.MYX` if the server has a problem.
58 
59 Params:
60 	conn = The connection to use.
61 	name = The name of the stored function.
62 	numArgs = The number of arguments the stored procedure takes.
63 +/
64 SafePrepared prepareFunction(Connection conn, string name, int numArgs)
65 {
66 	auto sql = "select " ~ name ~ preparedPlaceholderArgs(numArgs);
67 	return prepare(conn, sql);
68 }
69 
70 /++
71 Convenience function to create a prepared statement which calls a stored procedure.
72 
73 OUT parameters are currently not supported. It should generally be
74 possible with MySQL to present them as a result set.
75 
76 Be careful that your `numArgs` is correct. If it isn't, you may get a
77 `mysql.exceptions.MYX` with a very unclear error message.
78 
79 Throws: `mysql.exceptions.MYX` if the server has a problem.
80 
81 Params:
82 	conn = The connection to use.
83 	name = The name of the stored procedure.
84 	numArgs = The number of arguments the stored procedure takes.
85 
86 +/
87 SafePrepared prepareProcedure(Connection conn, string name, int numArgs)
88 {
89 	auto sql = "call " ~ name ~ preparedPlaceholderArgs(numArgs);
90 	return prepare(conn, sql);
91 }
92