> For the complete documentation index, see [llms.txt](https://upsolver.gitbook.io/content/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://upsolver.gitbook.io/content/how-to-guides-1/connectors/create-connections/amazon-s3.md).
# Amazon S3
Amazon S3 connections have a wide variety of uses in Upsolver. As with other connection types, they can be used to read your data and/or write transformed data to a specified location. However, unlike other types, Amazon S3 connections also serve as a storage location for the underlying files for your Upsolver-managed tables as well as the intermediate files used while running a job.
This means that even if you don't intend to write to an Amazon S3 bucket as a target location, you should still have an Amazon S3 connection that has write permissions to an Amazon S3 bucket.
{% hint style="success" %}
An Amazon S3 connection is created by default when you deploy Upsolver on your AWS account. See the guide to [Deploy Upsolver on AWS](/content/how-to-guides-1/setup/deploy-upsolver-on-aws.md) for more information.
{% endhint %}
## Create an Amazon S3 connection
#### Simple example
An Amazon S3 connection can be created very simply as follows:
```sql
CREATE S3 CONNECTION my_s3_connection;
```
The connection in this example is created based on the default credentials derived from Upsolver's integration with your AWS account.
#### Full example
The following example creates an Amazon S3 connection but explicitly configures the credentials by providing a specific role:
{% code overflow="wrap" %}
```sql
CREATE S3 CONNECTION s3_example
AWS_ROLE = 'arn:aws:iam::123456789012:role/upsolver-sqlake-role'
PATH_DISPLAY_FILTERS = ('s3://bucket1/', 's3://bucket2/folder-path/')
READ_ONLY = TRUE
ENCRYPTION_KMS_KEY = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
COMMENT = 'My new S3 connection';
```
{% endcode %}
To establish a connection with specific permissions, you can configure the `AWS_ROLE` and `EXTERNAL_ID` options as per the example above, or you can configure the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` options to provide the credentials to read from your bucket.\
When creating a new connection, Upsolver automatically tries to list the bucket and prefixes to allow users to discover their data. This validates that the permissions are defined correctly.
Additionally, you can limit the list of buckets displayed within your catalog by providing a list of paths to display using `PATH_DISPLAY_FILTER[S]`.
All connections have read and write permissions by default but you can easily create a connection with read-only access by setting `READ_ONLY` to `true`.
The options `ENCRYPTION_KMS_KEY` or `ENCRYPTION_CUSTOMER_MANAGED_KEY` can be used to configure your bucket's encryption.
Finally, by using the `COMMENT` option, you can add a description for your connection.
After creating the connection you can browse your Amazon S3 buckets and prefixes from the navigation tree.
## Alter an Amazon S3 connection
Many connection options are considered mutable, meaning that in some cases, you need only run a SQL command to alter an existing Amazon S3 connection, rather than create a new one.
For example, take the Amazon S3 connection we created previously based on default credentials:
```sql
CREATE S3 CONNECTION my_s3_connection;
```
If you only need to change the connection's permissions, you can run the following command:
```sql
ALTER S3 CONNECTION my_s3_connection
SET AWS_ROLE = 'arn:aws:iam::123456789012:role/new-upsolver-role';
```
Note that some options such as `READ_ONLY` cannot be altered once the connection has been created.
## Drop an Amazon S3 connection
If you no longer need a connection, you can easily drop it with the following SQL command:
```sql
DROP CONNECTION my_s3_connection;
```
However, if existing tables or jobs are dependent upon the connection, the connection cannot be deleted.
***
{% hint style="success" %}
**Learn More**
To discover which connection options are mutable, and to learn more about the options, please see the SQL command reference for [Amazon S3](/content/reference-1/sql-commands/connections/create-connection/amazon-s3.md).
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://upsolver.gitbook.io/content/how-to-guides-1/connectors/create-connections/amazon-s3.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
