Airport/DuckDB Catalog Integration

Each DuckDB session maintains its own catalog, which can contain multiple databases. Each database forms the root of a hierarchy that includes schemas, tables, and functions. The diagram below shows the default hierarchy for a DuckDB session using an in-memory database: a single database containing one schema, which in turn can hold multiple tables and functions. The diagram is intended to help you understand the relationships between sessions, databases, schemas, tables, and functions.

The Airport extension allows databases to be attached to the current DuckDB session, similar to how PostgreSQL and SQLite databases can be attached to a DuckDB session.

Note

As of DuckDB version 1.2.0, attached databases are not persisted in an on-disk DuckDB database. This means they need to be reattached for each session.

An Airport server-provided database can be attached using an ATTACH statement:

Example:

ATTACH 'database_name' (
  TYPE AIRPORT,
  LOCATION 'grpc://localhost:12345/'
);

Airport retrieves information about an attached database or schema only when an object within it is first referenced. This allows the ATTACH command to run quickly.

Attaching an Airport Database

To attach an database provided by Airport execute a SQL ATTACH statement with the necessary information that provides the name of the database to attach and the URL of the Arrow Flight server.

ATTACH 'airport_database_name' (
  TYPE AIRPORT,
  LOCATION 'grpc://localhost:12345/'
);

Tip

Arrow Flight servers can provide multiple databases at the same location or URL. It is important to match the target database name expected by the server. The database can be renamed in DuckDB by using an alias.

Attach Arguments:

Argument	Type	Description
type	`VARCHAR`	This must always be the value `AIRPORT`.
location	`VARCHAR`	This is the location of the Flight server. Typically this will be of the form `grpc://$HOST:PORT` or `grpc+tls://$HOST:$PORT`
secret	`VARCHAR`	This is the name of the DuckDB secret to use to supply the value for the `auth_token`.
auth_token	`VARCHAR`	A bearer value token to present to the server, the header is formatted like `Authorization: Bearer <auth_token>`

Once a database has been attached the tables will be visable in either SHOW ALL TABLES or SELECT * from duckdb_tables().

To make the tables accessible without using full qualification in the queries you may want to update the search path to include the newly attached database as show in the following example:

SET search_path = 'example,airport_database_name';
SELECT * FROM tbl1;
SELECT * FROM tbl2;

This example would find tbl1 or tbl2 if they are defined in either the example database or the airport_database_name database.

Arrow Flight Server Implementation Notes

For information about how to register an Arrow Flight as an object in the DuckDB catalog refer to Server Catalog Integration.