mysql

The internal:mysql plugin executes queries against a MySQL database using the mysql2 driver.

Registration

x-plenum-upstream:
  kind: "plugin"
  plugin: "internal:mysql"
  options:
    host: "${{ env.DB_HOST }}"
    port: "${{ env.DB_PORT }}"
    database: "${{ env.DB_NAME }}"
    user: "${{ env.DB_USER }}"
    password: "${{ env.DB_PASSWORD }}"
  permissions:
    env: ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"]
    net: ["${{ env.DB_HOST }}"]

Connection config

Options passed to the plugin at registration become the connection pool configuration:

Field	Type	Default	Description
`host`	`string`	`"localhost"`	Database host
`port`	`string \| number`	`3306`	Database port
`database`	`string`	— (required)	Database name
`user`	`string`	— (required)	Database user
`password`	`string`	— (required)	Database password
`ssl`	`any`	—	Enable SSL. When set, uses `rejectUnauthorized: false`
`max_connections`	`string \| number`	`10`	Maximum pool size (`connectionLimit`)

The plugin verifies connectivity at startup by running SELECT 1. If the connection fails, the gateway refuses to start.

Per-operation config

Pass query configuration via x-plenum-backend:

actions:
  - target: "$.paths['/users'].get"
    update:
      x-plenum-backend:
        query: "SELECT id, name, email FROM users"
  - target: "$.paths['/users/{id}'].get"
    update:
      x-plenum-backend:
        query: "SELECT id, name, email FROM users WHERE id = ?"
        params:
          - "${{path.id}}"

Field	Type	Default	Description
`query`	`string`	— (required)	SQL query with `?` positional parameters
`params`	`(string \| number)[]`	`[]`	Values for positional parameters. The gateway resolves `${{...}}` tokens at request time
`fields`	`Record<string, string>`	—	Map database column names to response field names
`returns`	`string`	—	JSON Pointer to extract from the result. `"/0"` returns the first row as an object instead of an array

Parameterised queries

Always put request-derived values in params, never inline in the query string. The gateway resolves ${{...}} tokens in params at request time and passes resolved values as native query parameters:

x-plenum-backend:
  query: "SELECT id, name FROM users WHERE role = ? AND active = ?"
  params:
    - "${{query.role}}"
    - "${{query.active}}"

MySQL uses ? placeholders. PostgreSQL uses $1, $2, … See the PostgreSQL plugin for positional syntax.

Field mapping

Rename columns in the response using fields:

x-plenum-backend:
  query: "SELECT user_id, full_name FROM users"
  fields:
    user_id: "id"
    full_name: "name"

Response becomes [{ "id": 1, "name": "Alice" }] instead of [{ "user_id": 1, "full_name": "Alice" }].

Returns pointer

Use returns: "/0" to unwrap the result array when the query returns a single row:

x-plenum-backend:
  query: "SELECT id, name FROM users WHERE id = ?"
  params:
    - "${{path.id}}"
  returns: "/0"

Without "/0", the response is [{ "id": 1, "name": "Alice" }]. With it: { "id": 1, "name": "Alice" }.

If the row is not found, the plugin returns 404.

Error responses

Status	Condition
`200`	Query succeeded
`404`	`returns: "/0"` used and no row found
`500`	Pool not initialised, query error, or missing config

The 500 response body includes the error message from the driver.