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

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

.. code:: ini

      shared_preload_libraries = aidb

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

Create the extensions
---------------------

1. Create the AIDB extension in your database:

.. code:: sql

      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:

.. code:: sql

      SELECT aidb.bdr_setup();

.. ::
   1. S3 호환 객체 저장소 또는 로컬 파일 시스템 볼륨과 같은 외부 데이터 소스를 사용할 계획이라면 Postgres 파일 시스템(PGFS) 확장 프로그램도 설치하십시오.

.. code:: sql

      CREATE EXTENSION pgfs;

For more information, see :ref:`PGFS documentation </pg_extensions/pgfs/>`  .

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`` :

.. code:: bash

   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:

.. code:: bash

   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 :ref:`Local models <Local models>`  for applicable providers).

.. csv-table::
  :header: Parameter,Type,Default,Range,Description
  :widths: 12,8,10,8,16
  :align: left
  :class: longtable

  `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  :ref:`Local model downloads<Local model downloads>`  for the retry behavior.

aidb.download_log_level
^^^^^^^^^^^^^^^^^^^^^^^

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

.. csv-table::
  :header: Value,Behavior
  :widths: 20,25
  :align: left
  :class: longtable

  `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:

.. code:: sql

   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:

.. code:: sql

   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.

.. csv-table::
  :header: Parameter,Type,Default,Description
  :widths: 15,12,12,20
  :align: left
  :class: longtable

  `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:

.. csv-table::
  :header: Form,Matches
  :widths: 15,25
  :align: left
  :class: longtable

  `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:

.. code:: ini

   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 :ref:`PGFS — Network egress </pg_extensions/pgfs/configuring#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 :ref:`Configuring external storage <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