Skip to main content

# awSQL

This is the default exported module that holds all Instances and manages them.

It does not provide any functionality on top of managing instances globally.

## 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 instance to connect to a database.

Parameters

Parameter | Type | Description
--- | --- | ---
`hostname` | String | The hostname where the database is hosted
`username` | String | Username to connect with
`password` | String | Password
`options` optional | Object | Additional options
→ `options.charset` optional | String | The charset to use
→ `options.defaultDatabase` optional | String | The default database to select for queries
→ `options.multipleStatements` optional | Boolean | Whether to allow multiple statements in a single query. Defaults to `false`
→ `options.insecureAuth` optional | Boolean | Whether insecure authentication methods should be allowed. Defaults to `false`
→ `options.customIdentifier` optional | String | Sets a custom identifier for this instance. Instances can be fetched by getInstance() with this identifier. If not set, the identifier will be "`username`@`hostname`" by default.
→ `options.isDefault` optional | Boolean | Whether this instance is returned by default via getInstance() if the given identifier is empty or not retrievable

Possible errors

This might crash if either of these situations happen:

- `password` is empty
- `username` is empty
- An instance with the same `identifier` already exists

Returns

→ Instance

### getInstance()​

→ (`identifier`? = String) → Instance / undefined

Returns an already defined instance with the given `identifier`.

If a default instance was set it returns said instance if the `identifier` is empty.

Parameters

Parameter | Type | Description
--- | --- | ---
`identifier` optional | String | The instance name to retrieve. Note: If not set with `options.customIdentifier` upon creation instances will be identified by "`username`@`hostname`". If not given it returns the defined default instance.

Returns

- Instance - Instance was found
- undefined

### listInstances()​

→ () → Array<String>

Returns a list of defined instance identifiers

Returns

→ Array<String>

### deleteInstance()​

→ (`identifier` = String) → true

Deletes an instance and closes any open connection

Parameters

Parameter | Type | Description
--- | --- | ---
`identifier` optional | String | The instance to delete. Note: If not set with `options.customIdentifier` upon creation instances will be identified by "`username`@`hostname`".

Possible crash

This might crash if either of these situations happen:

- `identifier` is empty
  - To delete the default instance you must provide the `identifier` of the default instance.
- `identifier` is not of type String
- No instance with the given `identifier` was found

Returns

→ true

info

Always returns true, as it will throw if any error happens to be sure any deletion was intended and correctly called.