velocious 1.0.430 → 1.0.432

package/src/database/drivers/mysql/index.js

@@ -0,0 +1,473 @@
+// @ts-check
+
+import AlterTable from "./sql/alter-table.js"
+import Base from "../base.js"
+import CreateDatabase from "./sql/create-database.js"
+import CreateIndex from "./sql/create-index.js"
+import CreateTable from "./sql/create-table.js"
+import Delete from "./sql/delete.js"
+import {digg} from "diggerize"
+import DropDatabase from "./sql/drop-database.js"
+import DropTable from "./sql/drop-table.js"
+import Insert from "./sql/insert.js"
+import Options from "./options.js"
+import mysql from "mysql"
+import query from "./query.js"
+import QueryParser from "./query-parser.js"
+import Table from "./table.js"
+import StructureSql from "./structure-sql.js"
+import Upsert from "./sql/upsert.js"
+import Update from "./sql/update.js"
+
+/**
+ * Sentinel timeout (in seconds) used as the "block forever" value when a
+ * caller asks for an indefinite advisory lock acquire. MySQL historically
+ * accepted negative timeouts as "infinite", but MariaDB 10+ silently
+ * returns NULL from `GET_LOCK` when the timeout is negative, so the
+ * driver clamps to a comfortably large positive value (1 year ≫ any
+ * realistic critical section) instead.
+ */
+const MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS = 60 * 60 * 24 * 365
+
+export default class VelociousDatabaseDriversMysql extends Base{
+  /**
+   * Runs connect.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async connect() {
+    this.pool = mysql.createPool(Object.assign({connectionLimit: 1}, this.connectArgs()))
+    this.pool.on("error", this.onPoolError)
+  }
+
+  /**
+   * On pool error.
+   * @param {Error} error - Error from the connection attempt.
+   */
+  onPoolError = (error) => {
+    console.error("Velocious / MySQL driver / Pool error", error)
+  }
+
+  /**
+   * Runs close.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async close() {
+    await this.pool?.end()
+    this.pool = undefined
+  }
+
+  /**
+   * Runs set connection checkout name.
+   * @param {string | undefined} name - Human-readable name for this active checkout.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async setConnectionCheckoutName(name) {
+    await this.query(`SET @velocious_connection_checkout_name = ${name === undefined ? "NULL" : this.quote(name)}`, {logName: "Set Connection Checkout Name", processListComment: false})
+    await super.setConnectionCheckoutName(name)
+  }
+
+  /**
+   * Runs clear connection checkout name.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async clearConnectionCheckoutName() {
+    await this.query("SET @velocious_connection_checkout_name = NULL", {logName: "Clear Connection Checkout Name", processListComment: false})
+    await super.clearConnectionCheckoutName()
+  }
+
+  /**
+   * Runs connect args.
+   * @returns {Record<string, ?>} - The connect args.
+   */
+  connectArgs() {
+    const args = this.getArgs()
+    const forward = ["database", "host", "password"]
+
+    /**
+     * Connect args.
+      @type {Record<string, ?>} */
+    const connectArgs = {charset: "utf8mb4"}
+
+    for (const forwardValue of forward) {
+      if (forwardValue in args) connectArgs[forwardValue] = digg(args, forwardValue)
+    }
+
+    if ("username" in args) connectArgs["user"] = args["username"]
+    if ("charset" in args) connectArgs["charset"] = args["charset"]
+
+    return connectArgs
+  }
+
+  /**
+   * Runs alter table sqls.
+   * @param {import("../../table-data/index.js").default} tableData - Table data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async alterTableSQLs(tableData) {
+    const alterArgs = {tableData, driver: this}
+    const alterTable = new AlterTable(alterArgs)
+
+    return await alterTable.toSQLs()
+  }
+
+  /**
+   * Runs create database sql.
+   * @param {string} databaseName - Database name.
+   * @param {object} [args] - Options object.
+   * @param {boolean} [args.ifNotExists] - Whether if not exists.
+   * @returns {string[]} - SQL statements.
+   */
+  createDatabaseSql(databaseName, args) {
+    const createArgs = Object.assign({databaseName, driver: this}, args)
+    const createDatabase = new CreateDatabase(createArgs)
+
+    return createDatabase.toSql()
+  }
+
+  /**
+   * Runs drop database sql.
+   * @param {string} databaseName - Database name.
+   * @param {object} [args] - Options object.
+   * @param {boolean} [args.ifExists] - Whether if exists.
+   * @returns {string[]} - SQL statements.
+   */
+  dropDatabaseSql(databaseName, args) {
+    const dropArgs = Object.assign({databaseName, driver: this}, args)
+    const dropDatabase = new DropDatabase(dropArgs)
+
+    return dropDatabase.toSql()
+  }
+
+  /**
+   * Runs create index sqls.
+   * @param {import("../base.js").CreateIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async createIndexSQLs(indexData) {
+    const createArgs = Object.assign({driver: this}, indexData)
+    const createIndex = new CreateIndex(createArgs)
+
+    return await createIndex.toSQLs()
+  }
+
+  /**
+   * Runs create table sql.
+   * @param {import("../../table-data/index.js").default} tableData - Table data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async createTableSql(tableData) {
+    const createArgs = {tableData, driver: this}
+    const createTable = new CreateTable(createArgs)
+
+    return createTable.toSql()
+  }
+
+  /**
+   * Runs current database.
+   * @returns {Promise<string>} - Resolves with the current database.
+   */
+  async currentDatabase() {
+    const rows = await this.query("SELECT DATABASE() AS db_name")
+
+    return digg(rows, 0, "db_name")
+  }
+
+  /**
+   * Runs disable foreign keys.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async disableForeignKeys() {
+    await this.query("SET FOREIGN_KEY_CHECKS = 0")
+  }
+
+  /**
+   * Runs enable foreign keys.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async enableForeignKeys() {
+    await this.query("SET FOREIGN_KEY_CHECKS = 1")
+  }
+
+  /**
+   * Runs drop table sqls.
+   * @param {string} tableName - Table name.
+   * @param {import("../base.js").DropTableSqlArgsType} [args] - Options object.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async dropTableSQLs(tableName, args = {}) {
+    const dropArgs = Object.assign({tableName, driver: this}, args)
+    const dropTable = new DropTable(dropArgs)
+
+    return await dropTable.toSQLs()
+  }
+
+  /**
+   * Runs get type.
+   * @returns {string} - The type.
+   */
+  getType() { return "mysql" }
+
+  /**
+   * Runs primary key type.
+   * @returns {string} - The primary key type.
+   */
+  primaryKeyType() { return "bigint" }
+
+  /**
+   * Runs retryable database error.
+   * @param {Error} error - Error instance.
+   * @returns {import("../base.js").RetryableDatabaseErrorResult} - Retry info.
+   */
+  retryableDatabaseError(error) {
+    const errorCode = /**
+                       * Narrows the runtime value to the documented type.
+                        @type {?} */ (error).code
+    const message = error.message || ""
+    const shouldRetry = (
+      errorCode == "ECONNREFUSED" ||
+      message.includes("ECONNREFUSED") ||
+      message.includes("connect ECONNREFUSED") ||
+      message.includes("PROTOCOL_CONNECTION_LOST") ||
+      message.includes("Connection lost")
+    )
+
+    return {
+      retry: shouldRetry,
+      reconnect: shouldRetry,
+      waitMs: 50
+    }
+  }
+
+  /**
+   * Runs query actual.
+   * @param {string} sql - SQL string.
+   * @returns {Promise<import("../base.js").QueryResultType>} - Resolves with the query actual.
+   */
+  async _queryActual(sql) {
+    if (!this.pool) await this.connect()
+    if (!this.pool) throw new Error("MySQL pool failed to initialize")
+
+    try {
+      return await query(this.pool, sql)
+    } catch (error) {
+      // Re-throw to un-corrupt stacktrace
+      if (error instanceof Error) {
+        throw new Error(`Query failed: ${error.message}`, {cause: error})
+      } else {
+        throw new Error(`Query failed: ${error}`, {cause: error})
+      }
+    }
+  }
+
+  /**
+   * Runs query to sql.
+   * @param {import("../../query/index.js").default} query - Query instance.
+   * @returns {string} - SQL string.
+   */
+  queryToSql(query) { return new QueryParser({query}).toSql() }
+
+  /**
+   * Runs should set auto increment when primary key.
+   * @returns {boolean} - Whether set auto increment when primary key.
+   */
+  shouldSetAutoIncrementWhenPrimaryKey() { return true }
+  supportsDefaultPrimaryKeyUUID() { return false }
+
+  /**
+   * Runs escape.
+   * @param {?} value - Value to use.
+   * @returns {?} - The escape.
+   */
+  escape(value) {
+    const escapedValueWithQuotes = this.pool
+      ? this.pool.escape(this._convertValue(value))
+      : mysql.escape(this._convertValue(value))
+
+    return escapedValueWithQuotes.slice(1, escapedValueWithQuotes.length - 1)
+  }
+
+  /**
+   * Runs quote.
+   * @param {string} value - Value to use.
+   * @returns {string} - The quote.
+   */
+  quote(value) {
+    if (this.pool) {
+      return this.pool.escape(this._convertValue(value))
+    }
+
+    return mysql.escape(this._convertValue(value))
+  }
+
+  /**
+   * Runs delete sql.
+   * @param {import("../base.js").DeleteSqlArgsType} args - Options object.
+   * @returns {string} - SQL string.
+   */
+  deleteSql({tableName, conditions}) {
+    const deleteInstruction = new Delete({conditions, driver: this, tableName})
+
+    return deleteInstruction.toSql()
+  }
+
+  /**
+   * Runs insert sql.
+   * @abstract
+   * @param {import("../base.js").InsertSqlArgsType} args - Options object.
+   * @returns {string} - SQL string.
+   */
+  insertSql(args) {
+    const insertArgs = Object.assign({driver: this}, args)
+    const insert = new Insert(insertArgs)
+
+    return insert.toSql()
+  }
+
+  /**
+   * Runs get tables.
+   * @returns {Promise<Array<import("../base-table.js").default>>} - Resolves with the tables.
+   */
+  async getTables() {
+    return await this._cachedSchemaMetadata("tables", async () => {
+      const result = await this.query("SHOW FULL TABLES")
+      const tables = []
+
+      for (const row of result) {
+        const table = new Table(this, /**
+                                       * Narrows the runtime value to the documented type.
+                                        @type {Record<string, string>} */ (row))
+
+        tables.push(table)
+      }
+
+      return tables
+    })
+  }
+
+  /**
+   * Runs structure sql.
+   * @returns {Promise<string | null>} - Resolves with SQL string.
+   */
+  async structureSql() {
+    return await this._cachedSchemaMetadata("structureSql", async () => await new StructureSql({driver: this}).toSql())
+  }
+
+  /**
+   * Runs last insert id.
+   * @returns {Promise<number>} - Resolves with the last insert id.
+   */
+  async lastInsertID() {
+    const result = await this.query("SELECT LAST_INSERT_ID() AS last_insert_id")
+
+    return digg(result, 0, "last_insert_id")
+  }
+
+  /**
+   * Runs options.
+   * @returns {Options} - The options options.
+   */
+  options() {
+    if (!this._options) this._options = new Options({driver: this})
+
+    return this._options
+  }
+
+  /**
+   * Runs start transaction action.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async _startTransactionAction() {
+    await this.query("START TRANSACTION")
+  }
+
+  /**
+   * Runs update sql.
+   * @param {import("../base.js").UpdateSqlArgsType} args - Options object.
+   * @returns {string} - SQL string.
+   */
+  updateSql({conditions, data, tableName}) {
+    const update = new Update({conditions, data, driver: this, tableName})
+
+    return update.toSql()
+  }
+
+  /**
+   * Runs upsert sql.
+   * @param {import("../base.js").UpsertSqlArgsType} args - Options object.
+   * @returns {string} - SQL string.
+   */
+  upsertSql(args) {
+    const upsert = new Upsert({...args, driver: this})
+
+    return upsert.toSql()
+  }
+
+  /**
+   * Blocks until a MySQL/MariaDB user-level lock is acquired on this
+   * connection. Implemented via `GET_LOCK(name, timeout)`, where the
+   * timeout is in seconds.
+   *
+   * MySQL historically documented a negative timeout as "infinite",
+   * but MariaDB 10+ silently rejects negative timeouts and returns
+   * `NULL` from `GET_LOCK`. To make the helper portable across MySQL
+   * and MariaDB the "indefinite" case is encoded as a large positive
+   * timeout (one year), which is comfortably longer than any
+   * realistic critical section and works on every supported version.
+   * @param {string} name - Lock name.
+   * @param {{timeoutMs?: number | null}} [args] - Optional timeout in milliseconds; `null`, `undefined`, or negative blocks for `MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS`.
+   * @returns {Promise<boolean>} - True if acquired, false if the timeout elapsed.
+   */
+  async acquireAdvisoryLock(name, {timeoutMs} = {}) {
+    const timeoutSeconds = typeof timeoutMs === "number" && timeoutMs >= 0
+      ? Math.ceil(timeoutMs / 1000)
+      : MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS
+    const rows = await this.query(`SELECT GET_LOCK(${this.quote(name)}, ${timeoutSeconds}) AS velocious_advisory_lock_result`)
+    const result = rows?.[0]?.velocious_advisory_lock_result
+
+    if (result === null || result === undefined) {
+      throw new Error(`GET_LOCK returned NULL for advisory lock ${JSON.stringify(name)} (typically an out-of-memory or thread-killed condition)`)
+    }
+
+    return Number(result) === 1
+  }
+
+  /**
+   * Runs try acquire advisory lock.
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>} - True if the lock was acquired, false if it was already held.
+   */
+  async tryAcquireAdvisoryLock(name) {
+    const rows = await this.query(`SELECT GET_LOCK(${this.quote(name)}, 0) AS velocious_advisory_lock_result`)
+    const result = rows?.[0]?.velocious_advisory_lock_result
+
+    if (result === null || result === undefined) {
+      throw new Error(`GET_LOCK returned NULL for advisory lock ${JSON.stringify(name)} (typically an out-of-memory or thread-killed condition)`)
+    }
+
+    return Number(result) === 1
+  }
+
+  /**
+   * Runs release advisory lock.
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>} - True if the lock was held by this session and has now been released.
+   */
+  async releaseAdvisoryLock(name) {
+    const rows = await this.query(`SELECT RELEASE_LOCK(${this.quote(name)}) AS velocious_advisory_lock_result`)
+    const result = rows?.[0]?.velocious_advisory_lock_result
+
+    return Number(result) === 1
+  }
+
+  /**
+   * Runs is advisory lock held.
+   * @param {string} name - Lock name.
+   * @returns {Promise<boolean>} - True if any session currently holds the lock.
+   */
+  async isAdvisoryLockHeld(name) {
+    const rows = await this.query(`SELECT IS_USED_LOCK(${this.quote(name)}) AS velocious_advisory_lock_holder`)
+    const holder = rows?.[0]?.velocious_advisory_lock_holder
+
+    return holder !== null && holder !== undefined
+  }
+}

package/src/database/drivers/mysql/options.js

@@ -0,0 +1,34 @@
+// @ts-check
+
+import QueryParserOptions from "../../query-parser/options.js"
+
+export default class VelociousDatabaseDriversMysqlOptions extends QueryParserOptions {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../base.js").default} args.driver - Database driver instance.
+   */
+  constructor({driver}) {
+    const options = {
+      driver,
+      columnQuote: "`",
+      indexQuote: "`",
+      stringQuote: "'",
+      tableQuote: "`"
+    }
+
+    super(options)
+  }
+
+  /**
+   * Runs quote.
+   * @param {?} string - String.
+   * @returns {number | string} - The quote.
+   */
+  quote(string) {
+    if (!this.driver) throw new Error("Driver not set")
+
+    return this.driver.quote(string)
+  }
+}
+

package/src/database/drivers/mysql/query-parser.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import BaseQueryParser from "../../query-parser/base-query-parser.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlQueryParser extends BaseQueryParser {
+}

package/src/database/drivers/mysql/query.js

@@ -0,0 +1,37 @@
+/**
+ * Runs query.
+ * @param {import("mysql").Pool} pool - Pool.
+ * @param {string} sql - SQL string.
+ * @returns {Promise<Record<string, ?>[]>} - Resolves with string value.
+ */
+export default async function query(pool, sql) {
+  return new Promise((resolve, reject) => {
+    pool.query(sql, (error, results, fields) => {
+      if (error) {
+        reject(new Error(`Query failed because of ${error}: ${sql}`))
+      } else {
+        const rows = []
+        const resultRows = Array.isArray(results) ? results : []
+        const resultFields = Array.isArray(fields) ? fields : []
+
+        for (const rowData of resultRows) {
+          /**
+           * Result.
+            @type {Record<string, ?>} */
+          const result = {}
+
+          for (const fieldData of resultFields) {
+            const field = fieldData.name
+            const value = rowData[field]
+
+            result[field] = value
+          }
+
+          rows.push(result)
+        }
+
+        resolve(rows)
+      }
+    })
+  })
+}

package/src/database/drivers/mysql/sql/alter-table.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import AlterTableBase from "../../../query/alter-table-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlAlterTable extends AlterTableBase {
+}

package/src/database/drivers/mysql/sql/create-database.js

@@ -0,0 +1,39 @@
+// @ts-check
+
+import CreateDatabaseBase from "../../../query/create-database-base.js"
+
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9_]+$/
+
+/**
+ * Runs validate charset or collation.
+ * @param {string} field - Field name (for error messages).
+ * @param {string} value - Identifier value.
+ * @returns {string} - Same value, validated.
+ */
+function validateCharsetOrCollation(field, value) {
+  if (!IDENTIFIER_PATTERN.test(value)) {
+    throw new Error(`Invalid ${field} value: ${JSON.stringify(value)} — expected [A-Za-z0-9_]+`)
+  }
+
+  return value
+}
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlCreateDatabase extends CreateDatabaseBase {
+  /**
+   * Runs to sql.
+   * @returns {string[]} - SQL statements.
+   */
+  toSql() {
+    const options = this.getOptions()
+    let sql = "CREATE DATABASE"
+
+    if (this.ifNotExists) sql += " IF NOT EXISTS"
+
+    sql += ` ${options.quoteDatabaseName(this.databaseName)}`
+
+    if (this.databaseCharset) sql += ` CHARACTER SET ${validateCharsetOrCollation("databaseCharset", this.databaseCharset)}`
+    if (this.databaseCollation) sql += ` COLLATE ${validateCharsetOrCollation("databaseCollation", this.databaseCollation)}`
+
+    return [sql]
+  }
+}

package/src/database/drivers/mysql/sql/create-index.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import CreateIndexBase from "../../../query/create-index-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlCreateIndex extends CreateIndexBase {
+}

package/src/database/drivers/mysql/sql/create-table.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import CreateTableBase from "../../../query/create-table-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlCreateTable extends CreateTableBase {
+}

package/src/database/drivers/mysql/sql/delete.js

@@ -0,0 +1,21 @@
+// @ts-check
+
+import DeleteBase from "../../../query/delete-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlDelete extends DeleteBase {
+  toSql() {
+    let sql = `DELETE FROM ${this.getOptions().quoteTableName(this.tableName)} WHERE `
+    let count = 0
+
+    for (let columnName in this.conditions) {
+      if (count > 0) sql += " AND "
+
+      sql += this.getOptions().quoteColumnName(columnName)
+      sql += " = "
+      sql += this.getOptions().quote(this.conditions[columnName])
+      count++
+    }
+
+    return sql
+  }
+}

package/src/database/drivers/mysql/sql/drop-database.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import DropDatabaseBase from "../../../query/drop-database-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlDropDatabase extends DropDatabaseBase {
+}

package/src/database/drivers/mysql/sql/drop-table.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import DropTableBase from "../../../query/drop-table-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlDropTable extends DropTableBase {
+}

package/src/database/drivers/mysql/sql/insert.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import InsertBase from "../../../query/insert-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlInsert extends InsertBase {
+}

package/src/database/drivers/mysql/sql/update.js

@@ -0,0 +1,33 @@
+// @ts-check
+
+import UpdateBase from "../../../query/update-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlUpdate extends UpdateBase {
+  toSql() {
+    let sql = `UPDATE ${this.getOptions().quoteTableName(this.tableName)} SET `
+    let count = 0
+
+    for (let columnName in this.data) {
+      if (count > 0) sql += ", "
+
+      sql += this.getOptions().quoteColumnName(columnName)
+      sql += " = "
+      sql += this.formatValue(this.data[columnName])
+      count++
+    }
+
+    sql += " WHERE "
+    count = 0
+
+    for (let columnName in this.conditions) {
+      if (count > 0) sql += " AND "
+
+      sql += this.getOptions().quoteColumnName(columnName)
+      sql += " = "
+      sql += this.formatValue(this.conditions[columnName])
+      count++
+    }
+
+    return sql
+  }
+}