Configuring AIDB ================ To use AIDB, add it to ``shared_preload_libraries`` , create the extensions in the database, manage user access, and verify the installation. This page also covers proxy settings and the AIDB configuration parameters (GUCs) you can tune afterward. Configure shared_preload_libraries ---------------------------------- 1. In the ``postgresql.conf`` file, add ``aidb`` to the ``shared_preload_libraries`` parameter: .. code:: ini 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. .. :: 1. Restart 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. 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: .. code:: sql CREATE EXTENSION pgfs; For more information, see :ref:`PGFS documentation ` . Manage user access with the aidb_users role ------------------------------------------- When you create the AIDB extension, Postgres automatically creates a role named ``aidb_users`` . Grant a user membership in this role to give it access to AIDB’s SQL functions. This role isn’t removed if you later drop the extension. ``aidb_users`` is designed to simplify access management for AIDB features: - **Purpose:** Granting a user the ``aidb_users`` role gives it access to all AIDB functions, so it can use the extension’s capabilities. - **Security:** The ``aidb_users`` role **doesn’t** grant access to AIDB’s internal tables, so only the extension’s public API is exposed to users who hold it. - **Background workers:** When background workers are used, they execute as the user who defined them, or as a role specified by the user, provided that user has access to that role. To let a user use AIDB functions, grant them the ``aidb_users`` role: .. code:: sql GRANT aidb_users TO your_user; For example, create a role named ``alice`` with no privileges or role membership to start with: .. code:: sql CREATE ROLE alice LOGIN PASSWORD change_me; -- replace with a real password Then add ``alice`` to the ``aidb_users`` role: .. code:: sql GRANT aidb_users TO alice; ``alice`` now inherits whatever privileges ``aidb_users`` has, for example ``EXECUTE`` on routines in the ``aidb`` schema. Membership in ``aidb_users`` doesn’t grant access to your own data. Give ``alice`` (not ``aidb_users`` ) the privileges it needs on the tables AIDB will read or write. This example grants access to three arbitrary tables that would ordinarily be source tables used in a pipeline: .. code:: sql GRANT SELECT, INSERT, UPDATE, DELETE ON public.documents, public.email_text, public.chats TO alice; If ``alice`` also needs to create objects in the ``public`` schema: .. code:: sql GRANT CREATE ON SCHEMA public TO alice; !!!note Using AIDB through Pipeline Designer If you access AIDB through Hybrid Manager’s Pipeline Designer, pipeline operations run under a separate role, ``visual_pipeline_user`` , which must also be granted membership in ``aidb_users`` . See `VPU and permissions `_ for that setup. 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//main/environment`` : .. code:: bash echo "HTTP_PROXY = http:///" | sudo tee -a /etc/postgresql/16/main/environment echo "HTTPS_PROXY = http:///" | 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 ```` 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 AIDB has limited air-gapped support. The built-in CPU model runtimes (Candle and llama.cpp) run fully offline once their model files are available locally, but any pipeline step or agent tool that calls out to a remote model provider still needs outbound network access to that provider. 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`` . Most parameters below are ``USERSET`` — any role can change them for its own session; parameters with a different context are called out individually. Threading limits ^^^^^^^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Default,Range,Description :widths: 12,8,10,8,16 :align: left :class: longtable `aidb.max_threads`,integer,`0`,0–1024,Maximum number of CPU threads used for local model inference (Candle and llama.cpp). `0` uses the default: half of the available CPUs. `SUSET`. `aidb.max_io_threads`,integer,`0`,0–1024,"Maximum number of threads for AIDB's async I/O runtimes (remote model HTTP calls, and volume/object-store I/O). `0` falls back to the `TOKIO_WORKER_THREADS` environment variable, or Tokio's own default (one per CPU) if that isn't set either. `SUSET`." Both apply live: a session-local ``SET`` takes effect immediately in that backend only. Setting either with ``ALTER SYSTEM`` or in ``postgresql.conf`` takes effect after ``pg_reload_conf()`` (or ``SIGHUP`` ), and propagates to all backends and background workers — no restart required. aidb.max_threads ^^^^^^^^^^^^^^^^ .. code:: sql SET aidb.max_threads = 4; aidb.max_io_threads ^^^^^^^^^^^^^^^^^^^ .. code:: sql SET aidb.max_io_threads = 4; See :ref:`Threading limits ` for what these two parameters control, how they interact, and when to lower them. Model download ^^^^^^^^^^^^^^ The following parameters control how AIDB downloads local model files from HuggingFace (see :ref:`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 (for example, download start/complete, byte-progress heartbeats, and 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` 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; llama.cpp native logs ^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Default,Range,Description :widths: 12,8,10,8,16 :align: left :class: longtable `aidb.enable_llamacpp_logs`,boolean,`false`,—,"Controls whether llama.cpp's own diagnostic output (GGUF metadata, tensor shapes, and backend/model initialization) is written to the server log. `SUSET`. Read once at extension initialization — see below." aidb.enable_llamacpp_logs ^^^^^^^^^^^^^^^^^^^^^^^^^ Off by default: llama.cpp’s native logging is verbose — hundreds of lines per model load — so it’s suppressed unless you need it. This is separate from ``aidb.download_log_level`` above, which controls AIDB’s own download-progress messages; the two are independent. Unlike the other parameters on this page, ``aidb.enable_llamacpp_logs`` is ``SUSET`` (a superuser, or a role granted ``SET`` on the parameter, can change it) and is read once when the extension initializes. Setting it with ``SET`` , ``ALTER SYSTEM`` , or editing ``postgresql.conf`` and reloading (``pg_reload_conf()`` ) doesn’t take effect until Postgres is restarted: .. code:: ini aidb.enable_llamacpp_logs = true .. code:: bash sudo systemctl restart postgresql@16-main Applies only to ``llamacpp_generate`` and ``llamacpp_embeddings`` models — it has no effect on Candle-based models (``bert_local`` , ``clip_local`` , ``t5_local`` , ``llama_instruct_local`` ). See :ref:`Local models — Troubleshooting ` for when to use this. 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. `SUSET`." `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. `SUSET`. 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` (doesn't 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. Doesn't match hostnames. `2001:db8::/32`,IPv6 CIDR range. Whitespace around entries is ignored. CIDR entries are checked only against IP literals — hostnames aren’t 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 ` . 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 ` for how AIDB and PGFS work together. .. :: ### Credential environment variables ``aidb.create_model(credentials_env => ...)`` and ``aidb.import_mcp_tools(headers_env => ...)`` read a Postgres backend process environment variable, named by the caller, instead of storing a credential in the database. The following parameter restricts which variable names may be referenced this way: .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable `aidb.env_var_allowed_prefix`,string,`AIDB_`,Required prefix for environment variable names read via `credentials_env`/`headers_env`. Set to an empty string to disable the restriction. Only a superuser may change it. `SUSET`. Combined with a caller-controlled provider or MCP server URL, an unrestricted variable name would let a malicious configuration read out unrelated secrets that happen to live in the Postgres process’s environment — this parameter closes that off by default while staying overridable per deployment. See :ref:`Credentials from environment variables ` for ``credentials_env`` , and :ref:`MCP tools ` for ``headers_env`` . 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 __OUTPUT__ List of installed extensions Name | Version | Schema | Description - ----------------------+---------+------------+------------------------------------------------------------ aidb | 7.6.0 | aidb | aidb: makes it easy to build AI applications with postgres pgfs | 3.3.0 | pgfs | pgfs: enables access to filesystem-like storage locations vector | 0.8.0 | public | vector data type and ivfflat and hnsw access methods