---
sidebar_position: 1
---

# 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()
&rarr; (`hostname` = __String__, `username` = __String__, `password` = __String__, `options`? = \{`charset`?: __String__, `defaultDatabase`?: __String__, `multipleStatements`?: __Boolean__, `insecureAuth`?: __Boolean__, `customIdentifier`?: __String__, `isDefault`?: __Boolean__\}) &rarr; [Instance](./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 |
| &rarr; `options.charset` __optional__ | __String__ | The charset to use |
| &rarr; `options.defaultDatabase` __optional__ | __String__ | The default database to select for queries |
| &rarr; `options.multipleStatements` __optional__ | __Boolean__ | Whether to allow multiple statements in a single query. Defaults to `false` |
| &rarr; `options.insecureAuth` __optional__ | __Boolean__ | Whether insecure authentication methods should be allowed. Defaults to `false` |
| &rarr; `options.customIdentifier` __optional__ | __String__ | Sets a custom identifier for this instance. Instances can be fetched by [getInstance()](#getInstance) with this identifier. If not set, the identifier will be "`username`@`hostname`" by default. |
| &rarr; `options.isDefault` __optional__ | __Boolean__ | Whether this instance is returned by default via [getInstance()](#getInstance) if the given identifier is empty or not retrievable |

:::warning 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**

&rarr; [Instance](./instance)

***

### getInstance()
&rarr; (`identifier`? = __String__) &rarr; [Instance](./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`".<br/> If not given it returns the defined default instance. |

**Returns**

- [Instance](./instance) - Instance was found
- __undefined__

***

### listInstances()
&rarr; () &rarr; __Array__\<__String__\>

Returns a list of defined instance identifiers

**Returns**

&rarr; __Array__\<__String__\>

***

### deleteInstance()
&rarr; (`identifier` = __String__) &rarr; __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`". |

:::warning 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**

&rarr; __true__

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