Configuring AIDB#

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

Configure shared_preload_libraries#

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

shared_preload_libraries = aidb

!!! 노트: shared_preload_libraries 에 이미 다른 확장자가 나열되어 있는 경우 쉼표로 구분하여 aidb 를 추가하십시오. 순서는 중요하지 않습니다. .. ::

Postgres 다시 시작하십시오.

Create the extensions#

Create the AIDB extension in your database:

CREATE EXTENSION aidb CASCADE;

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

!!!Note 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:

SELECT aidb.bdr_setup();

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.

!!!Note Air-gapped environments aren’t currently supported.

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).

Parameter	Type	Default	Range	Description
aidb.download_log_level	string	notice	—	Controls the output channel for routine download progress messages (download start/complete, byte-progress heartbeats, adapter load lines). Valid values: notice, log, off. See below.
aidb.download_max_attempts	integer	30	1–500	Maximum total download attempts per file (initial request plus retries) before AIDB aborts. See Local model downloads for the retry behavior.

aidb.download_log_level#

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

Value	Behavior
notice	Send messages to the client at NOTICE level. Useful for interactive sessions in psql.
log	Send messages to the server log only (subject to log_min_messages). Use this for batch jobs and tests where the client output needs to be stable across cold and warm caches.
off	Suppress routine progress messages entirely.

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.

Parameter	Type	Default	Description
aidb.egress_allowlist	string	unset	Comma-separated list of hosts and/or CIDR ranges that AIDB is allowed to reach. When set, any outbound request to a destination not on the list is rejected before the connection is made.
edb.egress_allowlist	string	unset	Shared fallback allowlist used by all EDB extensions when the per-extension aidb.egress_allowlist is not set. Useful when AIDB and other EDB extensions (such as PGFS) share the same network policy.

Entry format#

Each comma-separated entry is one of:

Form	Matches
host.example.com	Exact hostname match (case-insensitive).
.example.com	Any subdomain of example.com (does not match example.com itself).
203.0.113.10	Exact IPv4 or IPv6 literal in the destination URL.
203.0.113.0/24	IPv4 CIDR range; matches IP literals in that range. Does not match hostnames.
2001:db8::/32	IPv6 CIDR range.

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.

!!!Note PGFS implements the same allowlist mechanism under pgfs.egress_allowlist , applied to traffic from PGFS to cloud object-store endpoints (S3, Google Cloud Storage, Azure Blob). edb.egress_allowlist is the shared fallback for both extensions: set it to apply one list to AIDB and PGFS together, or use the per-extension parameters when each needs a different policy. See PGFS — Network egress .

If your AIDB pipelines read from external storage, both allowlists are relevant: AIDB’s controls model-provider and HuggingFace traffic, and PGFS’s controls the connection to your object store. See Configuring external storage for how AIDB and PGFS work together.

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

aidb=# \dx
__OUTPUT__
                                     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

Configuring AIDB

Contents