Skip to content

Commit 4cd817a

Browse files
mattjohnsonpintmattjohnsonpint
committed
Add MySQL docs
1 parent ec5adc2 commit 4cd817a

File tree

6 files changed

+673
-10
lines changed

6 files changed

+673
-10
lines changed

‎mint.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,7 @@
118118
"group": "Database APIs",
119119
"pages": [
120120
"modus/sdk/assemblyscript/dgraph",
121+
"modus/sdk/assemblyscript/mysql",
121122
"modus/sdk/assemblyscript/neo4j",
122123
"modus/sdk/assemblyscript/postgresql"
123124
]
@@ -147,6 +148,7 @@
147148
"group": "Database APIs",
148149
"pages": [
149150
"modus/sdk/go/dgraph",
151+
"modus/sdk/go/mysql",
150152
"modus/sdk/go/neo4j",
151153
"modus/sdk/go/postgresql"
152154
]

‎modus/sdk/assemblyscript/mysql.mdx‎

Lines changed: 383 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,383 @@
1+
---
2+
title: MySQL
3+
description: "Execute queries against a MySQL database"
4+
---
5+
6+
import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx"
7+
8+
<SdkHeader language="AssemblyScript" feature="MySQL" />
9+
10+
The Modus MySQL APIs allow you to run queries against MySQL or any
11+
MySQL-compatible database platform.
12+
13+
## Import
14+
15+
To begin, import the `mysql` namespace from the SDK:
16+
17+
```ts
18+
import { mysql } from "@hypermode/modus-sdk-as"
19+
```
20+
21+
## MySQL APIs
22+
23+
{/* <!-- vale Google.Headings = NO --> */}
24+
25+
The APIs in the `mysql` namespace are below, organized by category.
26+
27+
<SdkTip />
28+
29+
### Functions
30+
31+
#### execute
32+
33+
Execute a SQL statement against a MySQL database, without any data returned. Use
34+
this for insert, update, or delete operations, or for other SQL statements that
35+
don't return data.
36+
37+
<Note>
38+
The `execute` function is for operations that don't return data. However, some
39+
insert/update/delete operations may still return data. In these cases, you can
40+
use the `queryScalar` or `query` functions instead.
41+
</Note>
42+
43+
```ts
44+
function execute(
45+
connection: string,
46+
statement: string,
47+
params?: Params,
48+
): Response
49+
```
50+
51+
<ResponseField name="connection" type="string" required>
52+
Name of the connection, as [defined in the
53+
manifest](/modus/app-manifest#connections).
54+
</ResponseField>
55+
56+
<ResponseField name="statement" type="string" required>
57+
58+
SQL statement containing the query or mutation operation to execute.
59+
60+
<Warning>
61+
While it's possible to directly include parameter values into your SQL
62+
statement, it's highly recommended to pass a [`Params`](#params) object
63+
instead. This can help to protect against injection attacks and other security
64+
vulnerabilities.
65+
</Warning>
66+
67+
</ResponseField>
68+
69+
<ResponseField name="params" type="Params">
70+
71+
Optional parameters to include with the query.
72+
73+
See the details of the [`Params`](#params) object for more information.
74+
75+
</ResponseField>
76+
77+
#### query
78+
79+
Execute a SQL statement against a MySQL database, returning a set of rows. In
80+
the results, each row converts to an object of type `T`, with fields matching
81+
the column names.
82+
83+
```ts
84+
function query<T>(
85+
connection: string,
86+
statement: string,
87+
params?: Params,
88+
): QueryResponse<T>
89+
```
90+
91+
<ResponseField name="T" required>
92+
93+
Type of object to use for the data returned from the query. This can be any
94+
type, including a custom type defined in your project. It should match the shape
95+
of the row returned from the SQL query.
96+
97+
<Tip>
98+
99+
Define custom types in the app's source code. In AssemblyScript, create classes
100+
decorated with `@json`.
101+
102+
All types, including classes, base classes, and field types must be JSON
103+
serializable. You can also use built-in types such as strings, numbers, arrays,
104+
and maps.
105+
106+
If working with MySQL's `point` data type, you can use a [`Point`](#point) or
107+
[`Location`](#location) object to represent the data.
108+
109+
</Tip>
110+
111+
</ResponseField>
112+
113+
<ResponseField name="connection" type="string" required>
114+
Name of the connection, as [defined in the
115+
manifest](/modus/app-manifest#connections).
116+
</ResponseField>
117+
118+
<ResponseField name="statement" type="string" required>
119+
120+
SQL statement containing the query or mutation operation to execute.
121+
122+
<Warning>
123+
While it's possible to directly include parameter values into your SQL
124+
statement, it's highly recommended to pass a [`Params`](#params) object
125+
instead. This can help to protect against injection attacks and other security
126+
vulnerabilities.
127+
</Warning>
128+
129+
</ResponseField>
130+
131+
<ResponseField name="params" type="Params">
132+
133+
Optional parameters to include with the query.
134+
135+
See the details of the [`Params`](#params) object for more information.
136+
137+
</ResponseField>
138+
139+
#### queryScalar
140+
141+
Execute a SQL statement against a MySQL database, returning a single scalar
142+
value. For example, the result could be a count, sum, or average, or it could be
143+
an identifier.
144+
145+
```ts
146+
function queryScalar<T>(
147+
connection: string,
148+
statement: string,
149+
params?: Params,
150+
): ScalarResponse<T>
151+
```
152+
153+
<ResponseField name="T" required>
154+
Type of object to use for the data returned from the query. This should
155+
generally be a scalar data type, such as a number or string. It should match
156+
the type of the data returned from the SQL query.
157+
</ResponseField>
158+
159+
<ResponseField name="connection" type="string" required>
160+
Name of the connection, as [defined in the
161+
manifest](/modus/app-manifest#connections).
162+
</ResponseField>
163+
164+
<ResponseField name="statement" type="string" required>
165+
166+
SQL statement containing the query or mutation operation to execute.
167+
168+
<Warning>
169+
While it's possible to directly include parameter values into your SQL
170+
statement, it's highly recommended to pass a [`Params`](#params) object
171+
instead. This can help to protect against injection attacks and other security
172+
vulnerabilities.
173+
</Warning>
174+
175+
</ResponseField>
176+
177+
<ResponseField name="params" type="Params">
178+
179+
Optional parameters to include with the query.
180+
181+
See the details of the [`Params`](#params) object for more information.
182+
183+
</ResponseField>
184+
185+
### Types
186+
187+
#### Location
188+
189+
Represents a location on Earth, having `longitude` and `latitude` coordinates.
190+
191+
Correctly serializes to and from MySQL's point type, in (longitude, latitude)
192+
order.
193+
194+
<Info>
195+
This class is identical to the [Point](#point) class, but uses different field
196+
names.
197+
</Info>
198+
199+
```ts
200+
class Location {
201+
longitude: f64,
202+
latitude: f64,
203+
}
204+
```
205+
206+
<ResponseField name="longitude" type="f64" required>
207+
The longitude coordinate of the location, in degrees.
208+
</ResponseField>
209+
210+
<ResponseField name="latitude" type="f64" required>
211+
The latitude coordinate of the location, in degrees.
212+
</ResponseField>
213+
214+
#### Params
215+
216+
A container for parameters to include with a SQL operation.
217+
218+
To use this feature, create a new `Params` object and call the `push` method for
219+
each parameter you want to include. Then pass the object to the `execute`,
220+
`query`, or `queryScalar` function along with your SQL statement.
221+
222+
```ts
223+
class Params {
224+
push<T>(value: T): void
225+
toJSON(): string
226+
}
227+
```
228+
229+
<ResponseField name="push(value)">
230+
231+
Push a parameter value into the list included with the SQL operation. The
232+
sequence of calls to `push` determines the order of the parameters in the SQL
233+
statement. This corresponds to the order of the `?` placeholders or `$1`, `$2`,
234+
etc.
235+
236+
<Expandable title="parameters">
237+
{/* <!-- markdownlint-disable MD046 --> */}
238+
239+
<ResponseField name="value" required>
240+
241+
The value of the parameter to include in the SQL operation.
242+
243+
The value can be of any type that's JSON serializable, including strings,
244+
numbers, boolean values, arrays, maps, and custom objects decorated with
245+
`@json`, as long as the database supports it.
246+
247+
<Tip>
248+
If working with MySQL's `Point` data type, you can either pass separate
249+
parameters for the coordinates and use a `point()` function in the SQL
250+
statement, or you can pass a [`Point`](#point) or [`Location`](#location)
251+
object as a single parameter.
252+
</Tip>
253+
254+
</ResponseField>
255+
256+
{/* <!-- markdownlint-restore MD046 --> */}
257+
258+
</Expandable>
259+
260+
</ResponseField>
261+
262+
<ResponseField name="toJSON()" type="string">
263+
Serializes the parameters to a JSON string for inclusion in the SQL operation.
264+
The SDK functions call this automatically when you pass a `Params` object. You
265+
typically don't need to call it directly.
266+
</ResponseField>
267+
268+
#### Point
269+
270+
Represents a point in 2D space, having `x` and `y` coordinates. Correctly
271+
serializes to and from MySQL's point type, in (x, y) order.
272+
273+
<Info>
274+
This class is identical to the [Location](#location) class, but uses different
275+
field names.
276+
</Info>
277+
278+
```ts
279+
class Point {
280+
x: f64,
281+
y: f64,
282+
}
283+
```
284+
285+
<ResponseField name="x" type="f64" required>
286+
The x coordinate of the point.
287+
</ResponseField>
288+
289+
<ResponseField name="y" type="f64" required>
290+
The y coordinate of the point.
291+
</ResponseField>
292+
293+
#### QueryResponse
294+
295+
Represents the response from a [`query`](#query) operation.
296+
297+
```ts
298+
class QueryResponse<T> {
299+
error: string | null
300+
rowsAffected: u32
301+
lastInsertId: u64
302+
rows: T[]
303+
}
304+
```
305+
306+
<ResponseField name="error" type="string | null">
307+
An error message, if an error occurred during the operation. Otherwise, this
308+
field is `null`.
309+
</ResponseField>
310+
311+
<ResponseField name="rowsAffected" type="u32">
312+
The number of rows affected by the operation, which typically corresponds to
313+
the number of rows returned.
314+
</ResponseField>
315+
316+
<ResponseField name="lastInsertId" type="u64">
317+
When inserting a row, this field contains the ID of the last inserted row.
318+
This is useful for tables with auto-incrementing primary keys.
319+
</ResponseField>
320+
321+
<ResponseField name="rows" type="T[]">
322+
An array of objects, each representing a row returned from the query. Each
323+
object has fields corresponding to the columns in the result set.
324+
</ResponseField>
325+
326+
#### Response
327+
328+
Represents the response from an [`execute`](#execute) operation. Also serves as
329+
the base class for `QueryResponse<T>` and `ScalarResponse<T>`.
330+
331+
```ts
332+
class Response {
333+
error: string | null
334+
rowsAffected: u32
335+
lastInsertId: u64
336+
}
337+
```
338+
339+
<ResponseField name="error" type="string | null">
340+
An error message, if an error occurred during the operation. Otherwise, this
341+
field is `null`.
342+
</ResponseField>
343+
344+
<ResponseField name="rowsAffected" type="u32">
345+
The number of rows affected by the operation.
346+
</ResponseField>
347+
348+
<ResponseField name="lastInsertId" type="u64">
349+
When inserting a row, this field contains the ID of the last inserted row.
350+
This is useful for tables with auto-incrementing primary keys.
351+
</ResponseField>
352+
353+
#### ScalarResponse
354+
355+
Represents the response from a [`queryScalar`](#queryscalar) operation.
356+
357+
```ts
358+
class ScalarResponse<T> {
359+
error: string | null
360+
rowsAffected: u32
361+
lastInsertId: u64
362+
value: T
363+
}
364+
```
365+
366+
<ResponseField name="error" type="string | null">
367+
An error message, if an error occurred during the operation. Otherwise, this
368+
field is `null`.
369+
</ResponseField>
370+
371+
<ResponseField name="rowsAffected" type="u32">
372+
The number of rows affected by the operation, which is typically 1 for a
373+
scalar query.
374+
</ResponseField>
375+
376+
<ResponseField name="lastInsertId" type="u64">
377+
When inserting a row, this field contains the ID of the last inserted row.
378+
This is useful for tables with auto-incrementing primary keys.
379+
</ResponseField>
380+
381+
<ResponseField name="value" type="T">
382+
The scalar value returned from the query.
383+
</ResponseField>

0 commit comments

Comments
 (0)