mysql.unsafe.connection source code

1 /++
2 Connect to a MySQL/MariaDB server (unsafe version).
3 
4 This is the unsafe API for the Connection type. It publicly imports
5 `mysql.impl.connection`, and also provides the unsafe version of the API for
6 preparing statements. Note that unsafe prepared statements actually use safe
7 code underneath.
8 
9 Note that the common pieces of the connection are documented and currently
10 reside in `mysql.impl.connection`. Please see this module for documentation of
11 the connection object.
12 
13 This module also contains the soon-to-be-deprecated BackwardCompatPrepared type.
14 
15 $(SAFE_MIGRATION)
16 +/
17 module mysql.unsafe.connection;
18 
19 public import mysql.impl.connection;
20 import mysql.unsafe.prepared;
21 import mysql.unsafe.commands;
22 private import CS = mysql.safe.connection;
23 
24 /++
25 Convenience functions.
26 
27 Returns: an UnsafePrepared instance based on the result of the corresponding `mysql.safe.connection` function.
28 
29 See that module for more details on how these functions work.
30 +/
31 UnsafePrepared prepare(Connection conn, const(char[]) sql) @safe
32 {
33 	return CS.prepare(conn, sql).unsafe;
34 }
35 
36 /// ditto
37 UnsafePrepared prepareFunction(Connection conn, string name, int numArgs) @safe
38 {
39 	return CS.prepareFunction(conn, name, numArgs).unsafe;
40 }
41 
42 /// ditto
43 UnsafePrepared prepareProcedure(Connection conn, string name, int numArgs) @safe
44 {
45 	return CS.prepareProcedure(conn, name, numArgs).unsafe;
46 }
47 
48 /++
49 This function is provided ONLY as a temporary aid in upgrading to mysql-native v2.0.0.
50 
51 See `BackwardCompatPrepared` for more info.
52 +/
53 deprecated("This is provided ONLY as a temporary aid in upgrading to mysql-native v2.0.0. You should migrate from this to the Prepared-compatible exec/query overloads in 'mysql.commands'.")
54 BackwardCompatPrepared prepareBackwardCompat(Connection conn, const(char[]) sql)
55 {
56 	return prepareBackwardCompatImpl(conn, sql);
57 }
58 
59 /// Allow mysql-native tests to get around the deprecation message
60 package(mysql) BackwardCompatPrepared prepareBackwardCompatImpl(Connection conn, const(char[]) sql)
61 {
62 	return BackwardCompatPrepared(conn, prepare(conn, sql));
63 }
64 
65 /++
66 This is a wrapper over `mysql.unsafe.prepared.Prepared`, provided ONLY as a
67 temporary aid in upgrading to mysql-native v2.0.0 and its
68 new connection-independent model of prepared statements. See the
69 $(LINK2 https://github.com/mysql-d/mysql-native/blob/master/MIGRATING_TO_V2.md, migration guide)
70 for more info.
71 
72 In most cases, this layer shouldn't even be needed. But if you have many
73 lines of code making calls to exec/query the same prepared statement,
74 then this may be helpful.
75 
76 To use this temporary compatability layer, change instances of:
77 
78 ---
79 auto stmt = conn.prepare(...);
80 ---
81 
82 to this:
83 
84 ---
85 auto stmt = conn.prepareBackwardCompat(...);
86 ---
87 
88 And then your prepared statement should work as before.
89 
90 BUT DO NOT LEAVE IT LIKE THIS! Ultimately, you should update
91 your prepared statement code to the mysql-native v2.0.0 API, by changing
92 instances of:
93 
94 ---
95 stmt.exec()
96 stmt.query()
97 stmt.queryRow()
98 stmt.queryRowTuple(outputArgs...)
99 stmt.queryValue()
100 ---
101 
102 to this:
103 
104 ---
105 conn.exec(stmt)
106 conn.query(stmt)
107 conn.queryRow(stmt)
108 conn.queryRowTuple(stmt, outputArgs...)
109 conn.queryValue(stmt)
110 ---
111 
112 Both of the above syntaxes can be used with a `BackwardCompatPrepared`
113 (the `Connection` passed directly to `mysql.commands.exec`/`mysql.commands.query`
114 will override the one embedded associated with your `BackwardCompatPrepared`).
115 
116 Once all of your code is updated, you can change `prepareBackwardCompat`
117 back to `prepare` again, and your upgrade will be complete.
118 +/
119 struct BackwardCompatPrepared
120 {
121 	import std.variant;
122 	import mysql.unsafe.result;
123 	import std.typecons;
124 
125 	private Connection _conn;
126 	Prepared _prepared;
127 
128 	/// Access underlying `Prepared`
129 	@property Prepared prepared() @safe { return _prepared; }
130 
131 	alias _prepared this;
132 
133 	/++
134 	This function is provided ONLY as a temporary aid in upgrading to mysql-native v2.0.0.
135 
136 	See `BackwardCompatPrepared` for more info.
137 	+/
138 	deprecated("Change 'preparedStmt.exec()' to 'conn.exec(preparedStmt)'")
139 	ulong exec() @system
140 	{
141 		return .exec(_conn, _prepared);
142 	}
143 
144 	///ditto
145 	deprecated("Change 'preparedStmt.query()' to 'conn.query(preparedStmt)'")
146 	ResultRange query() @system
147 	{
148 		return .query(_conn, _prepared);
149 	}
150 
151 	///ditto
152 	deprecated("Change 'preparedStmt.queryRow()' to 'conn.queryRow(preparedStmt)'")
153 	Nullable!Row queryRow() @system
154 	{
155 		return .queryRow(_conn, _prepared);
156 	}
157 
158 	///ditto
159 	deprecated("Change 'preparedStmt.queryRowTuple(outArgs...)' to 'conn.queryRowTuple(preparedStmt, outArgs...)'")
160 	void queryRowTuple(T...)(ref T args) if(T.length == 0 || !is(T[0] : Connection))
161 	{
162 		return .queryRowTuple(_conn, _prepared, args);
163 	}
164 
165 	///ditto
166 	deprecated("Change 'preparedStmt.queryValue()' to 'conn.queryValue(preparedStmt)'")
167 	Nullable!Variant queryValue() @system
168 	{
169 		return .queryValue(_conn, _prepared);
170 	}
171 }
172