Guide

DuckDB on Layerbase

Hosted DuckDB is served over the PostgreSQL wire protocol, so you connect with psql or any Postgres driver, not the duckdb CLI. This page explains why the connection string is a Postgres URL, what SQL and introspection work, how to get data in, and how to export a regular .duckdb file.

Why the connection string is Postgres

DuckDB has no native network wire protocol. To make a hosted DuckDB reachable over TCP and TLS, Layerbase Cloud runs it behind a PostgreSQL-compatible proxy (duckgres) on port 5432. You connect with the same tools you would use for Postgres: psql, a Postgres driver in your language, Prisma or Drizzle, or a BI tool. Reaching for the duckdb CLI or a duckdb client library will not work, because there is nothing speaking the DuckDB protocol on the wire.

Copy the Postgres-style URL from Quick Connect in the dashboard. TLS is required: append ?sslmode=require, and some clients also need sslnegotiation=direct.

psql "postgresql://layerbase:PASSWORD@your-host.cloud.layerbase.dev:5432/duck1?sslmode=require&sslnegotiation=direct"

Authentication is the username and password embedded in that URL, the same as any Postgres connection. See connecting to DuckDB for per-client snippets.

What works

Once connected, you write DuckDB SQL as normal. Standard SQL, information_schema, and most pg_catalog introspection work, so a client or BI tool can browse your tables and columns. The database is a real DuckDB file underneath, so DuckDB functions and types behave the way they do locally.

Internal tables you may see

The proxy materializes its Postgres-compatibility shims as real tables in your schema, including some information_schema copies and __duckgres-prefixed bookkeeping tables (for example __duckgres_column_metadata). The in-dashboard query console filters these out, so its Tables sidebar shows only your own tables. A raw client listing (psql \dt or a SELECT against information_schema.tables) will still show them alongside yours. They are safe to ignore.

Importing data

The hosted DuckDB has no access to your local filesystem, so you cannot ATTACH or read a file straight off your machine over the wire. Use one of these instead.

Upload a file in the query console. The Import button (and drag-and-drop onto the editor) turns a CSV, TSV, JSON, NDJSON, or Parquet file into a table. The upload ceiling is 100 MB per file.

Query a remote file in place. If your data is at a URL, DuckDB can read it directly without importing.

-- Turn a hosted file into a view, no upload needed
CREATE OR REPLACE VIEW sales AS
SELECT * FROM read_parquet('https://example.com/sales.parquet');

-- Or CSV / JSON
SELECT * FROM read_csv_auto('https://example.com/data.csv');

Standard INSERT statements from any Postgres client work too. To restore a whole existing DuckDB database, upload its .duckdb file through the console import.

Exporting

Export your database from the dashboard and you get back a regular .duckdb file. It is a standard DuckDB database: open it with local DuckDB, the duckdb CLI, or the desktop app. Nothing about the hosted format is proprietary.

Plan and local use

DuckDB is a Standard engine included on the Free tier. A Free database hibernates after an hour of inactivity (six hours on paid plans) and wakes on the next connection, usually in one to two seconds. You can also run DuckDB locally with SpinDB or Layerbase Desktop; the database files are portable across local, desktop, and cloud.