---
sidebar_position: 2
---

# Instance

Holds connection data and is the gateway to performing queries.

Instances can be managed via the default export [awSQL](./awsql)

## Methods

### connect()
`Promise` &rarr; () &rarr; __String__

Connects the instance.

:::warning Possible crash
Throws an error whenever the connection fails with an error
:::

**Returns**

&rarr; __String__ - A connection string in the following format: "Connected to `host` with user `user`"

***

### destroy()
&rarr; () &rarr; __true__

Destroys the connection

**Returns**

&rarr; __true__

***

### queryRaw()
`async` &rarr; (`queryString` = __String__, `values`? = __Array__\<__any__\>) &rarr; __any__

Performs a raw query with the given sql-string.

To prevent sql-injections use ? and push your values in order into the `values` array.

**Parameters**
| Parameter | Type | Description |
| -- | -- | -- |
| `queryString` | __String__ | The sql-query to perform |
| `values` | __Array__\<__any__\> | ? in the query string will be replaced by this values in order |

**Returns**

&rarr; __any__ - Whatever the query returns

***

### getDatabases()
`async` &rarr; (`excludeSchema`? = __Boolean__) &rarr; __Array__\<__String__\>

Returns a list of database names the user has access to

**Parameters**
| Parameter | Type | Description |
| -- | -- | -- |
| `excludeSchema` __option__ | __Boolean__ | Whether to exclude the default database 'information_schema' |

**Returns**

&rarr; __Array__\<__String__\>

***

### selectDatabase()
&rarr; (`name` = __String__) &rarr; `this`

Selects a default database for future queries

**Parameters**
| Parameter | Type | Description |
| -- | -- | -- |
| `name` | __String__ | The database to select |

**Returns**

&rarr; `this`

***

### getTables()
&rarr; (`database`? = __String__) &rarr; __Array__\<__String__\>

Returns a list of tables for the selected database

:::warning Possible crash
`options.multipleStatemens` must have been set to __true__ at creation of this instance for this to work. If not this will throw an error. 
:::

**Parameters**
| Parameter | Type | Description |
| -- | -- | -- |
| `database` __optional__ | __String__ | Database to get tables of. Can be empty as long as a default database was set with 'selectDatabase' |

**Returns**

&rarr; __Array__\<__String__\>

***

### select()
&rarr; (`from` = __String__, `...columns`? = __String__) &rarr; [Select](./select)

Prepares a new select query.

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `from` | __String__ | Name of the table to select from |
| `...columns` __optional__ | __String__ | Names of the columns to include in the query. Leave empty to select all (`*`) |

**Returns**

&rarr; [Select](./select)

***

### insert()
&rarr; (`into` = __String__) &rarr; [Insert](./insert)

Prepares a new query to insert data.

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `into` | __String__ | Name of the table to insert into |

**Returns**

&rarr; [Insert](./insert)

***

### delete()
&rarr; (`from` = __String__) &rarr; [Delete](./delete)

Prepares a new query to delete data.

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `from` | __String__ | Name of the table to delete from |

**Returns**

&rarr; [Delete](./delete)

***

### update()
&rarr; (`table` = __String__) &rarr; [Update](./update)

Prepares a new query to update data.

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `table` | __String__ | Name of the table to update data of |

**Returns**

&rarr; [Update](./update)

***

### dropDatabase()
`async` &rarr; (`database` = __String__) &rarr; __any__

Drops a whole database
- Requires admin privileges

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `database` | __String__ | The name of the database to drop |

**Returns**

&rarr; __any__ - Whatever the query result is

***

### dropTable()
`async` &rarr; (`table` = __String__) &rarr; __any__

Drops a whole table.

:::warning Possible crash
A default database must be set with [selectDatabase()](#selectdatabase)
:::

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `table` | __String__ | The name of the table to drop |

**Returns**

&rarr; __any__ - Whatever the query result is

***

### createDatabase()
`async` &rarr; (`name` = __String__) &rarr; __any__

Creates a new database.
- Requires admin privileges

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `name` | __String__ | The name of the database to create |

**Returns**

&rarr; __any__ - Whatever the query result is

***

### createTable()
&rarr; (`name` = __String__) &rarr; [CreateTable](./create-table)

Prepares to create a new table.

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `name` | __String__ | The name of the table to create |

**Returns**

&rarr; [CreateTable](./create-table)

***

### alterTable()
&rarr; (`name` = __String__) &rarr; [AlterTable](./alter-table)

Prepares to alter a table.

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `name` | __String__ | The name of the table to alter |

**Returns**

&rarr; [AlterTable](./alter-table)

***

### createStructure()
&rarr; () &rarr; [Structure](./structure)

Creates a new structure.

**Returns**

&rarr; [Structure](./structure)

***

### getStructure()
`async` &rarr; (`table` = __String__, `database`? = __String__) &rarr; [Structure](./structure)

Returns the structure object of a table.

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `table` | __String__ | The name of the table to get structure of |
| `database` __optional__ | __String__ | Name of the underlying database. Can be empty when a default database was set with [selectDatabase()](#selectdatabase) |

**Returns**

&rarr; [Structure](./structure)

***

### checkStructure()
`async` &rarr; (`table` = __String__, `desiredStructure` = [Structure](./structure), `database`? = __String__) &rarr; __Object__

Checks the structure of a table against a given structure.

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `table` | __String__ | The name of the table to check |
| `desiredStructure` | [Structure](./structure) | The structure to check against |
| `database` __optional__ | __String__ | Name of the underlying database. Can be empty when a default database was set with [selectDatabase()](#selectdatabase) |

**Returns**

&rarr; __Object__

```js
{
    errors: [<...String>],      // Holds error messages
    passed: [<...String>]       // Holds success messages
}
```

:::info
If `errors.length` is `0` the structure is correct
:::

***

### total()
`async` &rarr; (`table` = __String__) &rarr; __Number__

Returns the total amount of rows of a table.
- A default database must be set

**Parameters**

| Parameter | Type | Description |
| -- | -- | -- |
| `table` | __String__ | The name of the table to check. |

**Returns**

&rarr; __Number__

***

### isConnected()
&rarr; () &rarr; __Boolean__

Returns whether the connection has been established.

**Returns**

&rarr; __Boolean__