awSQL/docs/docusaurus/docs/classes/awsql.md

sidebar_position
1

awSQL

The default exported module that holds and manages all database instances globally.

It does not provide any additional functionality beyond managing instances.

---

Methods

---

createInstance()

→ (hostname = String, username = String, password = String, options? = {charset?: String, defaultDatabase?: String, multipleStatements?: Boolean, insecureAuth?: Boolean, customIdentifier?: String, isDefault?: Boolean}) → Instance

Creates a new database connection instance.

Parameters

Parameter	Type	Description
hostname	String	The database hostname.
username	String	The username for authentication.
password	String	The password for authentication.
options optional	Object	Additional settings for the instance.
→ options.charset optional	String	The character set to use.
→ options.defaultDatabase optional	String	Default database for queries.
→ options.multipleStatements optional	Boolean	Allow multiple SQL statements in a single query (default: false).
→ options.insecureAuth optional	Boolean	Enables insecure authentication methods (default: false).
→ options.customIdentifier optional	String	Custom instance identifier. Defaults to username@hostname.
→ options.isDefault optional	Boolean	Marks this instance as the default when no identifier is provided in getInstance().

:::warning Possible errors This method may crash if:

• password or username is empty.
• An instance with the same identifier already exists. :::

Returns

→ Instance

---

getInstance()

→ (identifier? = String) → Instance / undefined

Retrieves an existing database instance by its identifier.

If no identifier is provided and a default instance exists, it returns the default instance.

Parameters

Parameter	Type	Description
identifier optional	String	The name of the instance to retrieve. If no explicitly set with customIdentifier, instances are identified as username@hostname.

Returns

• Instance - if found.
• undefined - if no instance matches the identifier.

---

listInstances()

→ () → Array<String>

Returns a list of all defined instance identifiers.

Returns

→ Array<String> - A list of instance identifiers.

---

deleteInstance()

→ (identifier = String) → true

Deletes an existing instance and closes its database connection.

Parameters

Parameter	Type	Description
identifier optional	String	The identifier of the instance to delete. If customIdentifier was not set, use username@hostname.

:::warning Possible Error This method may crash if:

• identifier is empty.
  • To delete the default instance, provide its identifier.
• identifier is not a String.
• No instance with the given identifier exists. :::

Returns

→ true - Awayls returns true. Errors will cause an exception instead.

---