.duckdb database file living in your object storage — not a running server. Every node of every query engine attaches the file directly and reads it, read-only, the moment a query touches it.
Before you start
- The
.duckdbfile, uploaded to object storage you control (S3, S3-compatible storage, Azure Blob, or a plain HTTPS host for a publicly readable object). - For S3 or Azure, a cloud credential integration (AWS or Azure) holding access to that bucket or container. A publicly readable HTTPS object needs no credential at all.
Register the integration
From Integrations, choose Register integration and select DuckDB.
There are no secrets on this record — the credential comes entirely from the referenced cloud credential integration, or from nothing at all for a public HTTPS object.
Capabilities available for this kind: driver (required), federation.
Test connection
Checks that the object exists and is readable (a HEAD request against the store), then attaches it and counts its tables. The result reports the table count together with the object’s size and a fingerprint used for freshness tracking (below). An unreachable or missing object, or a credential without read access, fails here with the store’s own message.In Explore
Once a query engine applies this integration, it appears as a catalog named after the integration’s display name (lowercased, non-alphanumeric characters collapsed to underscores; a name that collides with another catalog gets a short suffix; see How catalogs are named). Every table in the file appears with its real column names and types. Trino lists table names in lowercase, and a table whose name has capitals (Sales, PROBE_UPPER) is read by that lowercase name: SELECT * FROM <catalog>.main.sales.
Read-only, always
Writing through this catalog is impossible, not merely disallowed: DuckDB’s remote attach is read-only by definition, and the platform additionally opens the connection in a read-only mode. There’s no configuration that makes this kind writable. If you need a database you can write to and query as a catalog, that’s a separate feature from registering this kind directly — see workspace databases. Dippr creates a platform-managed catalog for each workspace database automatically; engines read it live, and its owner can write it with Trino SQL.The file is the only thing it reads
The engine’s DuckDB reaches exactly one object: the file this integration names. Once that file is attached, DuckDB’s access to anything else is switched off and locked. That covers local files, other URLs and buckets,COPY, and extension installs. Nothing a query sends can switch it back on.
This applies to every query that reaches DuckDB, including SQL stored inside your file. A view whose body calls read_parquet, read_csv, read_text or read_json fails when you query it. That holds for a local path, an https:// URL and an s3:// object. The error is file system operations are disabled by configuration.
Tables, and views over tables in the same file, work as before. If a view needs data from somewhere else, materialize it into a table in the file before you upload it. You can also register that other location as its own integration.
Freshness: what happens when you replace the file
Each query engine node attaches the object the first time a query touches this catalog on that node, and keeps that attachment until the node restarts. So replacing the underlying file does not move a running engine to the new version by itself:- A node already attached keeps answering from the file it first saw, and refuses any read that needs bytes the old attachment doesn’t have.
- A node that attaches for the first time after the replacement serves the new file.
Limitations
- Read-only, by construction — see above.
- Reads only its own file. A stored view that reads another file or URL fails. See The file is the only thing it reads.
- No SSH tunnel support: an object store is reached over the public internet by host name, not through a private network path, so there’s nothing to route through a bastion.
- What you can query through the engine is governed by your own roles and grants, not by this record.
- Column types follow the same mapping as a workspace database: dates and timestamps keep their types,
STRUCT,LISTandMAPcolumns become Trinorow,arrayandmap(or JSON text when they hold a type that cannot be carried exactly), and other types the connector does not map appear asvarchar. See How DuckDB column types appear in Trino.
Equivalent dip command
Register a DuckDB source (S3)
Register a DuckDB source (public HTTPS)
Troubleshooting
Related
Cloud credentials
Register AWS, Azure or Google Cloud credentials this kind can reference.
Query and share a database
Query and write a workspace database live as a catalog.