Connect to PostgreSQL, Snowflake, BigQuery, and other databases via ADBC.

Overview

pynb uses ADBC (Apache Arrow Database Connectivity) to connect to external databases. ADBC transfers data in Arrow columnar format, which means results arrive as Arrow tables with no row-by-row serialization overhead. This is significantly faster than ODBC or DBAPI for analytical queries.

Supported Databases

Database	URI Scheme	ADBC Driver Package
PostgreSQL	postgresql://	adbc-driver-postgresql
Snowflake	snowflake://	adbc-driver-snowflake
BigQuery	bigquery://	adbc-driver-bigquery
SQLite	sqlite://	adbc-driver-sqlite
DuckDB (file)	duckdb://	Uses native DuckDB
FlightSQL	grpc://, grpc+tls://	adbc-driver-flightsql

Driver packages are installed automatically when you save a connection in Settings.

Connection URI Syntax

Specify a connection URI directly in the SQL cell header:

# %%sql postgresql://user:pass@localhost:5432/mydb
SELECT * FROM users

This connects to the database, runs the query, and stores the result as an Arrow file, just like a regular DuckDB SQL cell. The result can be named and referenced the same way:

# %%sql postgresql://localhost/mydb orders <<
SELECT * FROM orders WHERE status = 'active'

Connection Aliases

Rather than repeating a full URI in every cell, register an alias and reference it with @:

# %%sql @prod
SELECT * FROM users LIMIT 10

Aliases can be registered in two ways:

In the cell header (registers the alias for the session):

# %%sql postgresql://localhost/mydb --alias prod users <<
SELECT * FROM users

After this cell runs, subsequent cells can use @prod without the full URI.

In Settings (persists across sessions): Open Settings > SQL Connections to add, edit, and remove saved connections. Each saved connection has a name that becomes its alias.

Connection Management UI

Open Settings > SQL Connections to manage your database connections. For each connection you can configure:

• Name: The alias used in @name references
• Driver: Database type (PostgreSQL, Snowflake, BigQuery, etc.)
• Host, Port, Database: Connection parameters
• Username and Password: Credentials (stored locally)
• Default: Whether this connection is used when no @alias is specified
• Init SQL: SQL to run once when the connection is first used

Init SQL

Each connection can have an init SQL script that runs once on first use. This is useful for setting session parameters:

SET search_path TO my_schema;
SET statement_timeout = '30s';

Configure init SQL per connection in Settings > SQL Connections, or for the built-in DuckDB connection in Settings > DuckDB Init SQL.

Default Connection

Mark one connection as the default in Settings > SQL Connections. When a default is set, SQL cells without an explicit @alias or URI will use the default connection instead of the built-in DuckDB instance.

Cross-Database Queries

Results from external databases integrate seamlessly with the rest of the notebook. A common pattern is to pull data from a production database and then analyze it locally with DuckDB:

# %%sql @prod raw_orders <<
SELECT * FROM orders WHERE created_at > '2025-01-01'

# %%sql
SELECT date_trunc('month', created_at) as month,
       COUNT(*) as order_count
FROM raw_orders
GROUP BY 1
ORDER BY 1

The first cell fetches data from PostgreSQL via ADBC. The second cell queries that result with DuckDB, with no data leaving your machine.