> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Reference and syntax for the ALTER ENGINE command.

# ALTER ENGINE

Modify the configuration of an existing Firebolt engine.

## ALTER ENGINE SET

Updates the configuration of the specified engine.

### Syntax

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE <engine_name> SET
    [AUTO_START = <true/false>]
    [AUTO_STOP = <minutes>]
    [AUTO_VACUUM = <on/off>]
    [AUTO_VACUUM_WAIT_ON_STOP = <true/false>]
    [DEFAULT_DATABASE = <database_name>]
    [MIN_CLUSTERS = <clusters>]
    [MAX_CLUSTERS = <clusters>]
    [NODES = <nodes>]
    [TYPE = <type>]
    [FAMILY = <family>]
    [RELEASE = (CHANNEL = <channel>)]
    [QUERY_CACHE_MEMORY_FRACTION = <fraction>]
    [VECTOR_INDEX_CACHE_MEMORY_FRACTION = <fraction>]
```

### Options

| Parameter                                         | Description                                                                                                                                                                                                                                                                                  |
| :------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<engine_name>`                                   | The name of the engine to be altered.                                                                                                                                                                                                                                                        |
| `AUTO_START = <true/false>`                       | When set to `TRUE`, sending a query to a stopped engine will automatically start the engine before processing the query.                                                                                                                                                                     |
| `AUTO_STOP = <minutes>`                           | Specifies the number of minutes after which an engine automatically stops. Setting `minutes` to `0` disables `AUTO_STOP`.                                                                                                                                                                    |
| `AUTO_VACUUM = <on/off>`                          | When `on`, the engine will automatically assess the health of tables’ data layout after processing a DML operation, and will run the `VACUUM` command when necessary to maintain the underlying table health.                                                                                |
| `AUTO_VACUUM_WAIT_ON_STOP = <true/false>`         | When `false`, stopping the engine (explicitly or via auto-stop) does not wait for auto-vacuum tasks to complete. Default: `true`.                                                                                                                                                            |
| `DEFAULT_DATABASE = <database_name>`              | Specifies the default database that an engine will attempt to use when processing queries that require a database. To remove the default database, set `DEFAULT_DATABASE=default`.                                                                                                           |
| `CLUSTERS = <clusters>` (deprecated)              | Specifies the number of clusters in an engine. Each cluster is a group of nodes, and all clusters within an engine are identical in terms of node type and number of nodes.                                                                                                                  |
| `MIN_CLUSTERS = <clusters>`                       | Specifies a minimum number of clusters in an engine. If `MIN_CLUSTERS` is different from `MAX_CLUSTERS`, the engine will automatically change the number of clusters depending on load. If not specified, `1` is used as default.                                                            |
| `MAX_CLUSTERS = <clusters>`                       | Specifies a maximum number of clusters in an engine. If `MIN_CLUSTERS` is different from `MAX_CLUSTERS`, the engine will automatically change the number of clusters depending on load. If not specified, `1` is used as default.                                                            |
| `NODES = <nodes>`                                 | Specifies the number of nodes in each cluster within an engine. You can specify any integer between `1` to `128`, inclusive.                                                                                                                                                                 |
| `TYPE =<type>`                                    | Specifies the node type for the engine. You can choose `S`, `M`, `L`, or `XL`.                                                                                                                                                                                                               |
| `FAMILY =<family>`                                | Defines the family of node used in the engine. Options include `STORAGE_OPTIMIZED` (alias `SO`) or `COMPUTE_OPTIMIZED` (alias `CO`).                                                                                                                                                         |
| `CHANNEL = <channel>`                             | Specifies the release channel to be used. Options are `DEFAULT` to use the default release process or `PREVIEW` to get upgrades earlier.                                                                                                                                                     |
| `QUERY_CACHE_MEMORY_FRACTION = <fraction>`        | Sets the fraction of the engines memory that can be used to cache query (sub)results. `VECTOR_INDEX_CACHE_MEMORY_FRACTION` + `QUERY_CACHE_MEMORY_FRACTION` can be at most 0.8.                                                                                                               |
| `VECTOR_INDEX_CACHE_MEMORY_FRACTION = <fraction>` | Sets the fraction of the engines memory that can be used to cache vector indexes. See [Vector Search Indexes](/performance-and-observability/storage-and-indexing/vector-search-index) for details. `VECTOR_INDEX_CACHE_MEMORY_FRACTION` + `QUERY_CACHE_MEMORY_FRACTION` can be at most 0.8. |

**Limitations:**

For small and medium instance types:

* Each engine is limited to a maximum of two clusters
* Each cluster can have up to ten nodes
* The total number of nodes across all clusters cannot exceed 15
* When scaling a running engine either vertically or horizontally, new queries will be directed to the new cluster. Queries running on the original clusters will continue until completion. The clusters will wait up to 24 hours for these queries to finish, after which any unfinished queries may be stopped.

For large and extra-large instance types:

* Each engine is limited to a maximum of one node and one cluster

If you would like to remove the following limitations, reach out to Firebolt support at [support@firebolt.io](mailto:support@firebolt.io) to do the following:

* Use more than ten nodes per cluster.
* Use more than 15 nodes across all clusters.
* Use more than one large or extra-large node per engine.

## Examples

### Scale out an engine

The following code example scales out, or increases the number of nodes, in an engine by setting the engine's `NODES` to `3`:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE my_engine SET NODES = 3;
```

### Scale up an engine

The following code example scales up an engine by increasing its capacity from small (`S`) to medium (`M`) by setting the engine's `TYPE` parameter to `M`:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE my_engine SET TYPE = "M";
```

### Change Family

The following code example changes engine's family type to compute-optimized by setting the engine's `FAMILY` parameter to `CO`:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE my_engine SET FAMILY = "CO";
```

### Scale up and out an engine

The following code example both scales up and scales out an engine by increasing node capacity and the number of nodes:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE my_engine SET TYPE = "L" NODES = 5;
```

### Enable concurrency auto-scaling

The following code example adjusts the maximum number of engine clusters to enable concurrency auto-scaling:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE my_engine SET MAX_CLUSTERS = 2;
```

### Configure the maximum size of the query cache

The following code example changes the maximum size of the [query cache](/performance-and-observability/runtime/understand-query-performance-subresult) to 30% of the engine's total available memory.

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE my_engine SET QUERY_CACHE_MEMORY_FRACTION = 0.3;
```

### Enroll into the preview release channel

The following code example enrolls an engine into the preview release channel. For more information, see [release settings](/managed-service/operate-engines/engines-release-settings).

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE myengine SET RELEASE=(CHANNEL=PREVIEW);
```

## ALTER ENGINE RENAME TO

Renames an engine.

### Syntax

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE <engine_name> RENAME TO <new_engine_name>
```

### Parameters

| Parameter           | Description                       |
| :------------------ | :-------------------------------- |
| `<engine_name>`     | The name of the engine to rename. |
| `<new_engine_name>` | The new name of the engine.       |

## ALTER ENGINE OWNER TO

Changes the owner of an engine. You can view the current owner in the `engine_owner` column of the `information_schema.engines` view.

For more information, see [ownership](/security/guides/ownership).

### Syntax

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
ALTER ENGINE [IF EXISTS] <engine_name> OWNER TO <user>
```

### Parameters

| Parameter       | Description                                                            |
| :-------------- | :--------------------------------------------------------------------- |
| `<engine_name>` | The name of the engine to change the owner of.                         |
| `<user>`        | The new owner of the engine. Can be either a user name or a role name. |