Dedalus API PostgreSQL Extension

Note

The Dedalus API PostgreSQL Extension is currently experimental and we're excited for you to experiment with it!

This extension has not yet been exhaustively tested in production environments and may be missing some features you'd expect in a stable release. As we continue development, there may be breaking changes that require updates to your code.

We'd love your feedback! Please share any suggestions, bug reports, feature requests, or general thoughts by filing an issue.

The Dedalus API PostgreSQL Extension provides convenient access to the Dedalus REST API from PostgreSQL.

It is generated with Stainless.

The REST API documentation can be found on docs.dedaluslabs.ai.

Installation

Clone the repository:

git clone git@github.com:stainless-sdks/dedalus-sql.git
cd dedalus-sql

Install the extension:

make install

Load it into the relevant database:

CREATE EXTENSION IF NOT EXISTS plpython3u; -- Dependency
CREATE EXTENSION dedalus;

And install the Python SDK dependency:

# install from PyPI
pip install dedalus-sdk

See ./scripts/test how to use a Python virtual environment if you prefer that instead.

Use the troubleshooting section if you encounter issues during or after installation.

Requirements

This extension requires:

• PostgreSQL 14 or higher
• PL/Python
• Python 3.9 or higher
• The dedalus-sdk Python package

Usage

SELECT *
FROM dedalus_usage.retrieve();

Client configuration

Configure the client by setting configuration parameters at the database level:

ALTER DATABASE my_database SET dedalus.api_key = 'My API Key';

Note

ALTER DATABASE persistently alters the database, but doesn't take effect until the next session. To ephemerally modify the current session, use SET dedalus.api_key TO 'My API Key';.

See this table for the available configuration parameters:

Parameter	Required	Default value
dedalus.api_key	false	-
dedalus.x_api_key	false	-
dedalus.org_id	false	-
dedalus.base_url	false	'https://dcs.dedaluslabs.ai'

Requests and responses

To send a request to the Dedalus API, call the relevant SQL function with values corresponding to the parameter types and SELECT the columns you need from the returned rows.

Pagination

For Dedalus API endpoints that return a paginated lists of results, the extension automatically fetches more pages as needed.

For example, the following query will make the minimum number of requests necessary to satisfy the LIMIT:

SELECT *
FROM dedalus_machines.list()
LIMIT 200;

Important

Place your LIMIT as close to the paginated function call as possible. If the LIMIT is too far removed, then PostgreSQL may not push down the condition, causing all pages to be requested and buffered.

Caching

Sending requests to the Dedalus API for every SQL query can be slow. Combine materialized views with pg_cron for scheduled data pulls:

CREATE MATERIALIZED VIEW dedalus_machines_machine_list_items AS
SELECT *
FROM dedalus_machines.list();

-- Refresh the view every 4 hours.
SELECT cron.schedule(
  'refresh-dedalus-machines-machine-list-items',
  '0 */4 * * *',
  'REFRESH MATERIALIZED VIEW CONCURRENTLY dedalus_machines_machine_list_items'
);

Troubleshooting

Installation

If you encounter an error such as:

Operation not permitted

Then run with sudo. If necessary, ensure your terminal has full disk access.

If you encounter an error such as:

make: pg_config: Command not found

Then ensure you have pg_config installed and in your PATH. If necessary, tell make where to find it:

PG_CONFIG=/path/to/pg_config make install

To install the extension in a custom prefix on PostgreSQL 18 or later, pass the prefix argument:

make install prefix=/usr/local/extras

You must also ensure that the prefix is included in the following postgresql.conf parameters:

extension_control_path = '/usr/local/extras/postgresql/share:$system'
dynamic_library_path   = '/usr/local/extras/postgresql/lib:$libdir'

Loading

If you encounter an error such as:

ERROR: could not load library

Then ensure your Python installation is linked to the directory where PostgreSQL was looking for it. You can print out the directory of your Python installation with this command:

python3 -c "import sys; print(sys.prefix)"

Semantic versioning

This package generally follows SemVer conventions, though certain backwards-incompatible changes may be released as minor versions:

1. Changes to library internals which are technically public but not intended or documented for external use. (Please open a GitHub issue to let us know if you are relying on such internals.)
2. Changes that we do not expect to impact the vast majority of users in practice.

We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.

We are keen for your feedback; please open an issue with questions, bugs, or suggestions.