DuckDB GCS Extension
Maintainer(s):
northpolesec
Compatibility Matrix
This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.
| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
|---|---|---|---|---|---|
| Linux AMD64 | |||||
| Linux ARM64 | |||||
| macOS AMD64 | |||||
| macOS ARM64 | |||||
| Windows AMD64 | |||||
| Windows ARM64 | |||||
| WebAssembly |
Installing and Loading
INSTALL gcs FROM community;
LOAD gcs;
Example
-- Add auth credentials using Application Default Creds
D CREATE SECRET secret (TYPE gcp, PROVIDER credential_chain);
-- Read a file from GCS
D SELECT * FROM read_text('gcss://rah-public-gcs-testing/quack.txt');
┌─────────────────────────────────────────┬─────────┬───────┬──────────────────────────┐
│ filename │ content │ size │ last_modified │
│ varchar │ varchar │ int64 │ timestamp with time zone │
├─────────────────────────────────────────┼─────────┼───────┼──────────────────────────┤
│ gcss://rah-public-gcs-testing/quack.txt │ 🦆 │ 4 │ 2025-09-23 16:20:03-04 │
└─────────────────────────────────────────┴─────────┴───────┴──────────────────────────┘
Added Functions
This extension does not add any functions.
Overloaded Functions
This extension does not add any function overloads.
Added Types
This extension does not add any types.
Added Settings
| name | description | input_type | scope | aliases | typed_value |
|---|---|---|---|---|---|
| gcs_enable_grpc | Use gRPC for connection to Google Cloud Storage. Can improve performance, especially when being used from Google Cloud. Default is false. | BOOLEAN | GLOBAL | [] | false |
| gcs_enable_metadata_cache | Enable caching of object metadata (size, modification time) to reduce API calls. Set to false to disable caching for debugging or when files change frequently. | BOOLEAN | GLOBAL | [] | true |
| gcs_list_cache_ttl | Time-to-live in seconds for cached object listing results (used in glob operations). Default is 60 seconds. Increase for stable directories, decrease if objects are added/removed frequently. | INTEGER | GLOBAL | [] | 60 |
| gcs_max_list_cache_entries | Maximum number of list cache entries to prevent unbounded memory growth. Default is 1000. When limit is reached, least recently used entries are evicted. | UBIGINT | GLOBAL | [] | 1000 |
| gcs_max_metadata_cache_entries | Maximum number of metadata cache entries to prevent unbounded memory growth. Default is 10000. When limit is reached, least recently used entries are evicted. | UBIGINT | GLOBAL | [] | 10000 |
| gcs_metadata_cache_ttl | Time-to-live in seconds for cached object metadata. Default is 300 seconds (5 minutes). Increase for stable files, decrease if files change frequently. | INTEGER | GLOBAL | [] | 300 |
| gcs_transfer_concurrency | Number of concurrent worker threads to use when reading. Default is 5. | INTEGER | GLOBAL | [] | 5 |
| temp_directory | Set the directory to which temporary files are written. | VARCHAR | GLOBAL | [] | post.db.tmp |