Skip to content
BoilStream

Grant AWS storage access

operations
TL;DR

Grant the server access to the buckets and prefixes it uses for analytical data and recovery. Keep object-storage credentials on the server and prefer a scoped workload identity when available. Separate bucket-listing permissions from object operations, then verify the configured storage backend before relying on uploads or restoration.

ArchitectureSQL access and AWS storage permissions guard different boundaries
SQL access and AWS storage permissions guard different boundariesA SQL client is authorized by BoilStream catalog permissions. The server uses its own AWS role credentials for object access. S3 evaluates the applicable IAM and bucket policy rules; SQL grants do not authorize S3 operations.AWS access boundarySQL clientUser credentialsBoilStreamCatalog permissionsIAM / bucket policyAllowed actions and prefixS3 objectsServer role credentialsSQL authorizationObject operationPolicy evaluationSQL access and AWS storage permissions guard different boundariesA SQL client is authorized by BoilStream catalog permissions. The server uses its own AWS role credentials for object access. S3 evaluates the applicable IAM and bucket policy rules; SQL grants do not authorize S3 operations.AWS access boundarySQL clientUser credentialsBoilStreamCatalog permissionsIAM / bucketpolicyAllowed actions andprefixS3 objectsServer rolecredentialsSQL authorizationObject operationPolicy evaluation
The policy arrow is a logical authorization check, not a separate network call to IAM. Grant the server only the storage access it needs.

BoilStream needs access to the object storage used by your deployment. AWS deployments may also need IAM role provisioning and STS access. Managed DuckDB clients use BoilStream credentials; they do not receive your storage access keys.

Object-storage permissions

Section titled “Object-storage permissions”

Typical storage operations need:

Permission Purpose
s3:ListBucket Discover objects within the deployment’s prefixes
s3:GetObject Read stored data and recovery backups
s3:PutObject Write data and backups
s3:DeleteObject Remove expired or obsolete objects
s3:AbortMultipartUpload Clean up incomplete uploads

Scope permissions to the deployment’s bucket and all configured data and recovery prefixes. The example uses one shared prefix. If recovery uses a different prefix or bucket, include it too; access to the data prefix alone is insufficient for recovery.

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListDeploymentObjects",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR-BUCKET"
    },
    {
      "Sid": "ManageDeploymentObjects",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET/YOUR-PREFIX/*"
    }
  ]
}

The service also performs a bucket-level listing during storage validation. Keep object operations scoped to your deployment prefixes. Let BoilStream manage those objects; their internal names and layout are not an application interface.

AWS role provisioning

Section titled “AWS role provisioning”

For an AWS backend, initial DuckLake provisioning checks or creates an access role and checks that the service can assume it. The deployment identity needs the following permissions for that setup:

Permission Purpose
sts:GetCallerIdentity Determine the AWS account
iam:GetRole Check the configured access role
iam:CreateRole Create a missing role
iam:PutRolePolicy Configure its storage access
sts:AssumeRole Use the role for storage operations

Scope role-management permissions to the role resources used by your deployment and review its trust policy. These permissions are for the BoilStream deployment, not every SQL user. An existing storage role does not eliminate all setup permission checks.

S3-compatible storage

Section titled “S3-compatible storage”

For MinIO or another non-AWS S3-compatible endpoint, use the provider’s bucket credentials and addressing settings. AWS IAM role provisioning is skipped for a backend recognized as non-AWS, but valid storage credentials and object permissions are still required.

Merge an appropriate backend into the generated configuration. Do not reuse development credentials in production. See Configuration.

Troubleshooting

Section titled “Troubleshooting”
Error Check
Bucket or object access denied Bucket, prefix, deployment identity, bucket policy and encryption-key permissions
Failed to create IAM role Role-management permissions and the intended role resource
AssumeRole failed Permission to assume the role and its trust policy
Recovery cannot read backups Access to the recovery bucket/prefix and the original encryption material

Prefer workload identity or instance roles over long-lived access keys. Keep credentials out of source control and use your organization’s secret-management process.

See Cluster mode for recovery requirements and DuckLake integration for client access.