Configuring AIDB v7

To use AIDB, add it to shared_preload_libraries, create the extensions in the database, and verify the installation.

Configure shared_preload_libraries

1. In the postgresql.conf file, add aidb to the shared_preload_libraries parameter:

   → WrapCopy

   shared_preload_libraries = 'aidb'

   Note

   If shared_preload_libraries already has other extensions listed, append aidb using a comma separator. The order doesn't matter.

2. Restart Postgres.

Create the extensions

1. Create the AIDB extension in your database:

   → WrapCopy

   CREATE EXTENSION aidb CASCADE;

   The CASCADE option automatically installs the required vector extension if it isn't already present.

   PGD users

   If you're running EDB Postgres Distributed (PGD), run the following after creating the extension to register AIDB catalog tables in the replication set:

   → WrapCopy

   SELECT aidb.bdr_setup();

2. If you plan to use external data sources such as S3-compatible object stores or local file system volumes, also install the Postgres File System (PGFS) extension:

   → WrapCopy

   CREATE EXTENSION pgfs;

   For more information, see PGFS documentation.

Proxy settings

If your environment routes outbound HTTP traffic through a proxy, set the HTTP_PROXY and HTTPS_PROXY environment variables in the Postgres environment file. On Ubuntu with community Postgres, this file is at /etc/postgresql/<version>/main/environment:

echo "HTTP_PROXY = 'http://<your-proxy-settings>/'" | sudo tee -a /etc/postgresql/16/main/environment
echo "HTTPS_PROXY = 'http://<your-proxy-settings>/'" | sudo tee -a /etc/postgresql/16/main/environment

Then restart Postgres for the changes to take effect:

sudo systemctl restart postgresql@16-main

Replace <your-proxy-settings> with your proxy address, and 16 with your Postgres version. Consult the documentation for your Postgres distribution for the exact location of the environment file.

Configuration parameters

AIDB exposes a set of Postgres configuration parameters (GUCs) in the aidb.* namespace. Set them in postgresql.conf, per-session with SET, or per-connection with -c. All parameters below are USERSET — any role can change them for its own session.

Model download

The following parameters control how AIDB downloads local model files from HuggingFace (see Local models for applicable providers).

aidb.download_log_level

Controls where routine download-progress messages are sent. Warnings and errors are unaffected.

Example:

SET aidb.download_log_level = 'log';

aidb.download_max_attempts

Caps the total number of download attempts per file. The downloader aborts early when consecutive attempts make zero progress, so this parameter is primarily a safety ceiling against excessive retry loops.

Lower it (for example, to 3 or 5) for fail-fast behavior in CI or scripted batch jobs. Raise it only for very large files on lossy links.

Example:

SET aidb.download_max_attempts = 5;

Network egress

The following parameter restricts outbound HTTP traffic from AIDB — both calls to model provider APIs and model file downloads from HuggingFace. When unset, no restriction is applied and AIDB can reach any host.

Entry format

Each comma-separated entry is one of:

Whitespace around entries is ignored. CIDR entries are checked only against IP literals — hostnames are not resolved for matching.

Resolution order

For each outbound request, AIDB checks aidb.egress_allowlist first. If it isn't set, AIDB falls back to edb.egress_allowlist. If neither is set, no check is applied. Redirects (for example, HuggingFace redirecting to a CDN host) are re-checked against the same allowlist; a redirect to a host not on the list is rejected.

Example

Allow only direct calls to OpenAI and HuggingFace plus its CDN:

aidb.egress_allowlist = 'api.openai.com, huggingface.co, .huggingface.co, cdn-lfs.huggingface.co'

When a request is rejected, AIDB raises an error that names the active parameter so the operator can adjust the list.

Validate the installation

Confirm that the extensions are installed by running \dx in psql and looking for aidb, vector, pgfs (if installed), in the output:

aidb=# \dx

                                     List of installed extensions
       Name            | Version |   Schema   |                        Description
-----------------------+---------+------------+------------------------------------------------------------
 aidb                  | 7.4.0   | aidb       | aidb: makes it easy to build AI applications with postgres
 pgfs                  | 1.0.6   | pgfs       | pgfs: enables access to filesystem-like storage locations
 vector                | 0.8.0   | public     | vector data type and ivfflat and hnsw access methods