Instance

Handles connection data and serves as the gateway for performing queries.

Instances can be managed globally via awSQL.

---

Methods

---

connect()

Promise → () → String

Establishes a connection to the database.

Possible Errors

Throws an error if the connection fails.

Returns

→ String - Connection confirmation in the format: "Connected to host with user user"

---

destroy()

→ () → true

Destroys the connection and releases resources.

Returns

→ true - Always returns true unless an error occurs.

---

queryRaw()

async → (queryString = String, values? = Array<any>) → any

Executes a raw SQL query.

Security Tip

Use ? placeholders and pass values seperately to prevent SQL injection.

Parameters

Parameter	Type	Description
queryString	String	SQL query to execute.
values	Array<any>	Values for placeholders (?), in left-to-right order.

Returns

→ any - Query Result

---

getDatabases()

async → (excludeSchema? = Boolean) → Array<String>

Retrieves a list of databases accessible to the user.

Parameters

Parameter	Type	Description
excludeSchema option	Boolean	Excludes information_schema if true

Returns

→ Array<String> - List of database names.

Example

const databases = await instance.getDatabases();
console.log(databases); // ['awSQL_dev','information_schema']

Excluding default database 'information_schema'

const databasesWithoutSchema = await instance.getDatabases(true);
console.log(databasesWithoutSchema); // ['awSQL_dev']

---

selectDatabase()

→ (name = String) → this

Sets a default database for future queries.

Parameters

Parameter	Type	Description
name	String	The database to select

Returns

→ this

---

getTables()

→ (database? = String) → Array<String>

Retrieves a list of tables in the selected database.

Possible Errors

Requires options.multipleStatements set to true at instance creation.

Returns

→ Array<String>

Example Usage

const tables = await instance.getTables("awSQL_dev");
console.log(tables);

Result

[
  'Categories',
  'Customers',
  'Employees',
  'OrderDetails',
  'Orders',
  'Products',
  'Shippers',
  'Suppliers'
]

---

Query Builders

These methods return specialized query objects that allow for structured queries:

Method	Description	Returns
.select(from, ...columns?)	Prepare a SELECT query.	Select
.insert(into)	Prepare an INSERT query.	Insert
.delete(from)	Prepare a DELETE query.	Delete
.update(table)	Prepare an UPDATE query.	Update

---

Database & Table Management

Method	Description	Returns
.dropDatabase(database)	Deletes an entire database (requires admin privileges).	OkPacket
.dropTable(table)	Deletes a table (default database must be set).	OkPacket
.createDatabase(name)	Creates a new database (fails if it already exists).	OkPacket
.createTable(name)	Prepares a new table creation query.	CreateTable
.alterTable(name)	Prepares a table modification query.	AlterTable

Potential Errors

• Creating a database requires admin privileges.
• Dropping a table reqeuires a default database to be selected.

---

Structure Management

Method	Description	Returns
.createStructure()	Creates a structure object.	Structure
.getStructure(table, database?)	Retrieves the structure of a table.	Structure
.checkStructure(table, desiredStructure, database?)	Compares a table's structure with the expected one.	{ errors: [], passed: [] } ✅ If errors.length === 0, the structure is correct.

---

Utility Methods

Method	Description	Returns
.total(table)	Counts total rows in a table. (Requires a default database).	Number
.isConnected()	Checks if the instance is connected.	Boolean

---