# STAGE

Config path: `/<database>/<schema>/stage/<name>.yaml`

Example for internal stage:

```yaml
file_format: test_csv_format
copy_options:
  on_error: ABORT_STATEMENT
  enforce_length: true
```

Example of external stage:

```yaml
url: "gcs://test-bucket"
storage_integration: test_storage_integration
file_format: test_avro_format
```

## Schema

* **url** (str) - bucket URL for external stage
* **storage\_integration** (ident) - name of [storage integration](https://docs.snowddl.com/guides/other-guides/integrations) for external stage
* **encryption** (dict)
  * *{key}* (ident) - name of encryption parameter
  * *{value}* (bool, float, int, str) - value of encryption parameter
* **directory** (dict)
  * *{key}* (ident) - name of directory parameter
  * *{value}* (bool, float, int, str) - value of directory parameter
* **file\_format** (ident) - [file format](https://docs.snowddl.com/basic/yaml-configs/file-format) for files in stage
* **copy\_options** (dict)
  * *{key}* (ident) - COPY option name
  * *{value}* (bool, float, int, list, str) - COPY option value
* **comment** (str)

## Usage notes

1. Stages with **url** and **storage\_integration** are EXTERNAL. Stages without these parameters are INTERNAL.
2. When INTERNAL stage is being dropped, all files will be lost. When EXTERNAL stage is being dropped, nothing happens. EXTERNAL stage is just a metadata pointing to location in bucket.
3. Business users should only access buckets through stages. Business users should never use `STORAGE INTEGRATION` objects directly for security reasons.
4. SnowDDL is able to maintain not only stages in general, but also [specific files in stages](https://docs.snowddl.com/basic/yaml-configs/stage-file).
5. **file\_format** can only be specified by name referencing to `FILE_FORMAT` object.

## Additional privileges

In order for `STAGE` objects to operate properly, the following additional grants should be added to OWNER role in [schema config](https://docs.snowddl.com/basic/yaml-configs/schema):

* `owner_integration_usage` - please specify names of STORAGE INTEGRATION objects used by external stages. Stages may work without explicit INTEGRATION USAGE grant to OWNER role, but it is not guaranteed for Snowflake keep it this way forever.

## Encryption updates

Encryption on existing EXTERNAL stages cannot be updated by SnowDDL. Snowflake does not provide meta-data, so it is not possible to compare config with existing object.

In order to update encryption information manually, you should use an additional CLI argument:

&#x20;`--refresh-stage-encryption`

If you want to remove an encryption from EXTERNAL stage, you should set encryption type to `NONE` explicitly. It is not enough to remove `encryption` section from config, since default encryption settings are different for each cloud provider and may change in future.

## Safe & unsafe operations

All operations on stages are considered as "safe", EXCEPT:

* Replace existing stage due to change of stage type (INTERNAL to EXTERNAL or vice versa) or due to change of INTERNAL stage encryption method.
* Drop existing stage, both INTERNAL and EXTERNAL.

"Unsafe" operations on stages lead to loss of data or meta-data. Also, it may affect other objects depending on stages, like [PIPES](https://docs.snowddl.com/basic/yaml-configs/pipe) or [EXTERNAL TABLES](https://docs.snowddl.com/basic/yaml-configs/external-table).

## Links

* [CREATE STAGE](https://docs.snowflake.com/en/sql-reference/sql/create-stage.html)
* [ALTER STAGE](https://docs.snowflake.com/en/sql-reference/sql/alter-stage.html)
* [SHOW STAGES](https://docs.snowflake.com/en/sql-reference/sql/show-stages.html)
* [DESC STAGE](https://docs.snowflake.com/en/sql-reference/sql/desc-stage.html)
* [Parser & JSON Schema (GitHub)](https://github.com/littleK0i/SnowDDL/blob/master/snowddl/parser/stage.py)