---
sidebar_position: 1
title: Amazon S3
description: Configure AWS S3 credentials to query files from private buckets using MotherDuck.
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import CloudExecutionCallout from "./_cloud-execution-callout.mdx";

## Configure S3 credentials

You can safely store your Amazon S3 credentials in MotherDuck for convenience by creating a `SECRET` object using the [CREATE SECRET](/sql-reference/motherduck-sql-reference/create-secret.md) command. Secrets are scoped to your user account and are not shared with other users in your organization.

### Create a SECRET object

<Tabs>
<TabItem value="sql" label="SQL">


```sql
-- to configure a secret manually:
CREATE SECRET IN MOTHERDUCK (
    TYPE S3,
    KEY_ID 'access_key',
    SECRET 'secret_key',
    REGION 'us-east-1',
    SCOPE 'my-bucket-path'
);
```

:::note
When creating a secret using the `CONFIG` (default) provider, be aware that the credential might be temporary. If so, a `SESSION_TOKEN` field also needs to be set for the secret to work correctly.
:::

```sql
-- to store a secret configured through `aws configure`:
CREATE SECRET aws_secret IN MOTHERDUCK (
      TYPE S3,
      PROVIDER credential_chain
  );
```

```sql
-- test the s3 credentials
SELECT count(*) FROM 's3://<bucket>/<file>';

-- browse objects in a bucket or prefix
FROM md_list_files('s3://<bucket>/');
```

</TabItem>
<TabItem value="python" label="Python">

```python
import duckdb

con = duckdb.connect('md:')
con.sql("CREATE SECRET IN MOTHERDUCK (TYPE S3, KEY_ID 'access_key', SECRET 'secret_key', REGION 'your_bucket_region')"); 

# testing that our s3 credentials work
con.sql("SELECT count(*) FROM 's3://<your_bucket>/<your_file>'").show()
# 42
```

</TabItem>
<TabItem value="ui" label="UI">

Click on your profile to access the `Settings` panel and click on `Secrets` menu.

![menu_1](./img/settings_access.png)
![menu_2](./img/settings_panel.png)

Then click on `Add secret` in the secrets section.

![menu_3](./img/settings_secrets_panel.png)

You will then be prompted to enter your Amazon S3 credentials.

![menu_3](./img/settings_secrets_pop_up.png)

</TabItem>
</Tabs>

You can update your secret by executing [CREATE OR REPLACE SECRET](/sql-reference/motherduck-sql-reference/create-secret.md) command to overwrite your secret.

### Delete a SECRET object

<Tabs>
<TabItem value="sql" label="SQL">

You can use the same method above, using the [DROP SECRET](/sql-reference/motherduck-sql-reference/delete-secret.md) command.

```sql
DROP SECRET <secret_name>;
```

</TabItem>

<TabItem value="ui" label="UI">

Click on your profile and access the `Settings` menu. Click on the bin icon to delete your current secrets.

![menu_4](./img/secrets_delete_4.png)

</TabItem>

</Tabs>

### Amazon S3 credentials as **temporary** secrets

MotherDuck supports DuckDB syntax for providing S3 credentials.

```sql
CREATE SECRET (
    TYPE S3,
    KEY_ID 's3_access_key',
    SECRET 's3_secret_key',
    REGION 'us-east-1'
);
```

:::note
Local/In-memory secrets are not persisted across sessions.
:::

<CloudExecutionCallout provider="S3" />

## Troubleshooting

For detailed troubleshooting steps, see our [AWS S3 Secrets Troubleshooting](/documentation/troubleshooting/aws-s3-secrets.md) guide.

## Browse buckets and files

To inspect storage from SQL before querying specific files:

```sql
FROM md_list_buckets_for_secret('__default_s3');

FROM md_list_files('s3://<bucket>/');
FROM md_list_files('s3://<bucket>/<prefix>/');
```

See [`MD_LIST_BUCKETS_FOR_SECRET()`](/sql-reference/motherduck-sql-reference/md-list-buckets-for-secret) and [`MD_LIST_FILES()`](/sql-reference/motherduck-sql-reference/md-list-files) for details.