# Source: https://docs.hypermode.com/modus/sdk/go/mysql.md

# Source: https://docs.hypermode.com/modus/sdk/assemblyscript/mysql.md

# Source: https://docs.hypermode.com/modus/sdk/go/mysql.md

# Source: https://docs.hypermode.com/modus/sdk/assemblyscript/mysql.md

# Source: https://docs.hypermode.com/modus/sdk/go/mysql.md

# Source: https://docs.hypermode.com/modus/sdk/assemblyscript/mysql.md

# Source: https://docs.hypermode.com/modus/sdk/go/mysql.md

# Source: https://docs.hypermode.com/modus/sdk/assemblyscript/mysql.md

# MySQL APIs

> Execute queries against a MySQL database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="MySQL" />

The Modus MySQL APIs allow you to run queries against MySQL or any
MySQL-compatible database platform.

## Import

To begin, import the `mysql` namespace from the SDK:

```ts
import { mysql } from "@hypermode/modus-sdk-as"
```

## MySQL APIs

{/* vale Google.Headings = NO */}

The APIs in the `mysql` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### execute

Execute a SQL statement against a MySQL database, without any data returned. Use
this for insert, update, or delete operations, or for other SQL statements that
don't return data.

<Note>
  The `execute` function is for operations that don't return data. However, some
  insert/update/delete operations may still return data. In these cases, you can
  use the `queryScalar` or `query` functions instead.
</Note>

```ts
function execute(
  connection: string,
  statement: string,
  params?: Params,
): Response
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

#### query

Execute a SQL statement against a MySQL database, returning a set of rows. In
the results, each row converts to an object of type `T`, with fields matching
the column names.

```ts
function query<T>(
  connection: string,
  statement: string,
  params?: Params,
): QueryResponse<T>
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This can be any
  type, including a custom type defined in your project. It should match the shape
  of the row returned from the SQL query.

  <Tip>
    Define custom types in the app's source code. In AssemblyScript, create classes
    decorated with `@json`.

    All types, including classes, base classes, and field types must be JSON
    serializable. You can also use built-in types such as strings, numbers, arrays,
    and maps.

    If working with MySQL's `point` data type, you can use a [`Point`](#point) or
    [`Location`](#location) object to represent the data.
  </Tip>
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

#### queryScalar

Execute a SQL statement against a MySQL database, returning a single scalar
value. For example, the result could be a count, sum, or average, or it could be
an identifier.

```ts
function queryScalar<T>(
  connection: string,
  statement: string,
  params?: Params,
): ScalarResponse<T>
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This should
  generally be a scalar data type, such as a number or string. It should match
  the type of the data returned from the SQL query.
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

### Types

#### Location

Represents a location on Earth, having `longitude` and `latitude` coordinates.

Correctly serializes to and from MySQL's point type, in (longitude, latitude)
order.

<Info>
  This class is identical to the [Point](#point) class, but uses different field
  names.
</Info>

```ts
class Location {
 longitude: f64,
 latitude: f64,
}
```

<ResponseField name="longitude" type="f64" required>
  The longitude coordinate of the location, in degrees.
</ResponseField>

<ResponseField name="latitude" type="f64" required>
  The latitude coordinate of the location, in degrees.
</ResponseField>

#### Params

A container for parameters to include with a SQL operation.

To use this feature, create a new `Params` object and call the `push` method for
each parameter you want to include. Then pass the object to the `execute`,
`query`, or `queryScalar` function along with your SQL statement.

```ts
class Params {
  push<T>(value: T): void
  toJSON(): string
}
```

<ResponseField name="push(value)">
  Push a parameter value into the list included with the SQL operation. The
  sequence of calls to `push` determines the order of the parameters in the SQL
  statement. This corresponds to the order of the `?` placeholders or `$1`, `$2`,
  etc.

  <Expandable title="parameters">
    {/* markdownlint-disable MD046 */}

    <ResponseField name="value" required>
      The value of the parameter to include in the SQL operation.

      The value can be of any type that's JSON serializable, including strings,
      numbers, boolean values, arrays, maps, and custom objects decorated with
      `@json`, as long as the database supports it.

      <Tip>
        If working with MySQL's `Point` data type, you can either pass separate
        parameters for the coordinates and use a `point()` function in the SQL
        statement, or you can pass a [`Point`](#point) or [`Location`](#location)
        object as a single parameter.
      </Tip>
    </ResponseField>

    {/* markdownlint-restore MD046 */}
  </Expandable>
</ResponseField>

<ResponseField name="toJSON()" type="string">
  Serializes the parameters to a JSON string for inclusion in the SQL operation.
  The SDK functions call this automatically when you pass a `Params` object. You
  typically don't need to call it directly.
</ResponseField>

#### Point

Represents a point in 2D space, having `x` and `y` coordinates. Correctly
serializes to and from MySQL's point type, in (x, y) order.

<Info>
  This class is identical to the [Location](#location) class, but uses different
  field names.
</Info>

```ts
class Point {
 x: f64,
 y: f64,
}
```

<ResponseField name="x" type="f64" required>
  The x coordinate of the point.
</ResponseField>

<ResponseField name="y" type="f64" required>
  The y coordinate of the point.
</ResponseField>

#### QueryResponse

Represents the response from a [`query`](#query) operation.

```ts
class QueryResponse<T> {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
  rows: T[]
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

<ResponseField name="rows" type="T[]">
  An array of objects, each representing a row returned from the query. Each
  object has fields corresponding to the columns in the result set.
</ResponseField>

#### Response

Represents the response from an [`execute`](#execute) operation. Also serves as
the base class for `QueryResponse<T>` and `ScalarResponse<T>`.

```ts
class Response {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

#### ScalarResponse

Represents the response from a [`queryScalar`](#queryscalar) operation.

```ts
class ScalarResponse<T> {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
  value: T
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation, which is typically 1 for a
  scalar query.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

<ResponseField name="value" type="T">
  The scalar value returned from the query.
</ResponseField>