WebMacro

What you can do with one query

Define a macro in a Git repo, point load_macro_from_url at the raw URL, and use it like any built-in DuckDB function:

SELECT load_macro_from_url(
  'https://raw.githubusercontent.com/your-org/sql-macros/main/search_posts.sql'
);
-- 'Successfully loaded macro: search_posts'

SELECT *
FROM search_posts('qxip.bsky.social', text := 'quack');

The whole extension is one function. One URL is one macro. The interesting part isn’t the protocol — it’s that the URL becomes the unit of distribution: pull requests review the SQL, tags pin versions, and every machine in your team gets the same macro from the same place.

The single function

The whole API surface is one scalar function: load_macro_from_url(url VARCHAR) → VARCHAR — accepts a URL, returns the loaded macro’s name (or an error).

load_macro_from_url does exactly four things, in order:

1. GET the URL (HTTPS supported via OpenSSL; redirects followed; 10 s read timeout).
2. Verify the response body contains a CREATE MACRO variant — CREATE MACRO, CREATE OR REPLACE MACRO, CREATE TEMP MACRO, CREATE TEMPORARY MACRO, or the OR REPLACE TEMP / OR REPLACE TEMPORARY variants.
3. Reject the response if it contains a dangerous keyword (DELETE, DROP, TRUNCATE, ALTER, GRANT, REVOKE, CREATE USER, ALTER USER, DROP USER, DROP DATABASE, EXEC, EXECUTE, SHUTDOWN, RESTART, DETACH).
4. Execute the SQL on the current connection and return Successfully loaded macro: <name>.

The macro is then callable by name in the session, like any hand-typed CREATE MACRO. There’s no separate registry to query and no unload — drop the macro with DROP MACRO if you need it gone before session end.

Hosting the macro

WebMacro doesn’t care where the URL lives, only that an HTTP GET against it returns a body that parses as a DuckDB macro. Common patterns:

• Git raw URL (recommended): https://raw.githubusercontent.com/org/repo/<sha>/macros/foo.sql. Pinning to a commit SHA makes the macro deterministic forever.
• Gist raw URL: https://gist.githubusercontent.com/<user>/<id>/raw/foo.sql. Convenient for one-off sharing; harder to review than a Git PR.
• Internal artifact server / S3 + presigned URL: any HTTP(S) endpoint that returns the SQL body works. TLS is honored.
• Self-hosted “macro registry”: a tiny static site at macros.your-org.internal/ mapping path → SQL. The whole thing can be a directory of .sql files behind any static webserver.

Loading at session start

A typical bootstrap pattern: pull a known set of macros at the top of a notebook or script, fail loudly if any URL is unreachable.

INSTALL webmacro FROM community;
LOAD webmacro;

SELECT
  url,
  load_macro_from_url(url) AS status
FROM (VALUES
  ('https://raw.githubusercontent.com/your-org/sql-macros/main/search_posts.sql'),
  ('https://raw.githubusercontent.com/your-org/sql-macros/main/normalize_handle.sql'),
  ('https://raw.githubusercontent.com/your-org/sql-macros/main/active_users.sql')
) AS macros(url);

If any URL fails the fetch, validation, or dangerous-command checks, the query errors out — so a missing macro shows up immediately rather than as a “function not found” later.

Compared to alternatives

• Hand-rolled wrapper around http_client + query. Possible — http_client returns the URL body, then you EXECUTE it. WebMacro collapses that to one statement and adds the (best-effort) safety filter. For everything beyond loading macros — calling REST APIs, posting form data, handling JSON responses — reach for http_client directly.
• Copy-pasting CREATE MACRO into every notebook. The thing this extension exists to replace. Drift between notebooks is the failure mode.
• Baking macros into a startup .duckdbrc / init script. Works for a single machine, doesn’t scale to a team or to ephemeral workers. WebMacro lets the URL be the artifact instead.

Caveats

• No caching. Every call hits the network. If you load the same macro 100 times in a session, that’s 100 HTTP requests.
• No dependency graph. If macro A calls macro B, you must load B first. WebMacro doesn’t parse the SQL to discover dependencies.
• No version negotiation. The URL is the version. If you want immutability, pin to a commit SHA or a content-addressed URL.
• Status is experimental. The function surface is small and stable in shape, but pin a known-good extension version in production setups.

Install and load

INSTALL webmacro FROM community;
LOAD webmacro;

The extension registers a single function: load_macro_from_url. Everything below is a recipe around it.

Load a macro from a Git repo

The recommended pattern — host the SQL in a Git repo, load by raw URL:

SELECT load_macro_from_url(
  'https://raw.githubusercontent.com/your-org/sql-macros/main/search_posts.sql'
) AS res;
-- 'Successfully loaded macro: search_posts'

-- Now use it like any DuckDB macro
SELECT *
FROM search_posts('qxip.bsky.social', text := 'quack');

The body of the URL must contain a CREATE MACRO statement (scalar or table macro). See load_macro_from_url for the validation rules.

Pin to an immutable commit

Use a commit SHA in the URL so a branch rebase or upstream change can’t silently swap the macro out from under you:

SELECT load_macro_from_url(
  'https://raw.githubusercontent.com/your-org/sql-macros/'
  || 'a3f8d21c9e7b4f0e6d2a1b5c8e9f0a1b2c3d4e5f'
  || '/macros/search_posts.sql'
);

The commit SHA pins the SQL forever — the same URL today and a year from now returns the same bytes. This is the closest thing to a versioned macro release.

Load several macros at once

A common bootstrap pattern at the top of a notebook or script:

SELECT
  url,
  load_macro_from_url(url) AS status
FROM (VALUES
  ('https://raw.githubusercontent.com/your-org/sql-macros/main/search_posts.sql'),
  ('https://raw.githubusercontent.com/your-org/sql-macros/main/normalize_handle.sql'),
  ('https://raw.githubusercontent.com/your-org/sql-macros/main/active_users.sql')
) AS macros(url);

Any URL that fails the fetch, the macro-statement check, or the dangerous-command filter raises an error — the bootstrap halts, you find out at session start instead of at first use.

Load from a private host with auth

load_macro_from_url issues a plain unauthenticated GET. If your macro lives behind auth, the simplest pattern is a presigned URL — generate a short-lived signed URL upstream (S3, GCS, etc.) and load that:

SET VARIABLE macro_url = getenv('MACRO_PRESIGNED_URL');

SELECT load_macro_from_url(:macro_url);

For an internally-routable host where TLS or network ACLs are the access control (e.g. https://macros.your-org.internal/foo.sql), a plain URL is fine.

Use scalar and table macros

Either macro form loads the same way — the difference is how you call the result.

A scalar macro definition at https://example.com/macros/normalize_handle.sql:

CREATE OR REPLACE MACRO normalize_handle(h)
AS lower(trim(h, '@'));

A table macro at https://example.com/macros/active_users.sql:

CREATE OR REPLACE MACRO active_users(since_date) AS TABLE
SELECT user_id, last_seen
FROM users
WHERE last_seen >= since_date;

After loading both, scalar macros go in the SELECT list; table macros go in the FROM clause:

SELECT load_macro_from_url('https://example.com/macros/normalize_handle.sql');
SELECT load_macro_from_url('https://example.com/macros/active_users.sql');

SELECT normalize_handle('@Alice  ') AS handle,
       u.last_seen
FROM active_users(DATE '2026-01-01') u;

Replace a macro mid-session

CREATE OR REPLACE MACRO is the supported way to update a macro you’ve already loaded. If the URL’s body uses CREATE OR REPLACE MACRO, re-loading swaps the definition in place:

-- Edit the SQL upstream, then re-run:
SELECT load_macro_from_url(
  'https://raw.githubusercontent.com/your-org/sql-macros/main/search_posts.sql'
);
-- 'Successfully loaded macro: search_posts'  -- now the new definition

If the macro was created without OR REPLACE, you’ll need to DROP MACRO it first.

Pair with http_client for richer pipelines

WebMacro is a one-trick extension on purpose — it loads macros and nothing else. For HTTP request patterns it doesn’t cover (POST bodies, custom headers, reading non-macro JSON), pair with the http_client extension, which exposes general-purpose http_get / http_post for SQL-level HTTP.

-- Fetch a macro index from your registry, then load each entry
INSTALL http_client FROM community;
LOAD http_client;

WITH index AS (
  SELECT (http_get('https://macros.your-org.internal/index.json')->>'body')::JSON AS j
)
SELECT load_macro_from_url(unnest(j->'$.macros[*].url')::VARCHAR)
FROM index;

Drop a loaded macro

A loaded macro is just a regular DuckDB macro — drop it like any other:

DROP MACRO search_posts;

DROP MACRO IF EXISTS active_users;

See DROP MACRO for the upstream syntax.