This document connects a customer database (PostgreSQL) to Knowledge Base so an agent can understand your table structure, write SQL against it, and query the database directly to answer questions. The work proceeds in this order.1.
Create a dedicated read-only account on the customer DB
2.
Decide the network path and TLS mode
3.
Connect a Database source in Knowledge Base
4.
Test the connection and check the first sync
5.
Refine table descriptions and relationships
6.
Attach the source to an agent and verify with a question
Knowledge Base does not copy the full row data of your tables. It stores the table and column definitions plus descriptions, with one exception: a small sample of values is read so the AI can write descriptions.
1. Before you start#
(1) People you need#
You need a database administrator (DBA) who can create an account and grant privileges on the customer DB, and a network administrator who can open a firewall if the DB is not reachable from outside its network. You also need a user with permission to add and edit sources in Knowledge Base.| Item | Description | Screen label |
|---|
| Host | Domain or IP of the DB server. Example: db.example.com or 10.0.0.5 | Host |
| Port | 1–65535. Default is 5432 | Port |
| Database | One database to connect (63 characters or fewer) | Database |
| Account | Read-only account name (63 characters or fewer) | Account (read-only) |
| Password | Password of that account | Password |
| TLS | One of require / verify-full / disable | TLS |
| Schemas | Schemas to import, comma separated. Empty means everything the account can read | Schemas (optional) |
PostgreSQL is the only supported database. In the source catalog the name is Database and the description is "Connect tables from a database".
Connect a Database#
1. Create a dedicated read-only account#
Reusing an operations or application account will not connect. Create a new account dedicated to Knowledge Base.GRANT SELECT names only the tables you allow. Do not use ALL TABLES.
Extensions installed in the same schema (citext, postgis, hstore, and others) are covered by the REVOKE as well. Re-grant the extension functions you need, or install extensions in a separate schema.
REVOKE and ALTER DEFAULT PRIVILEGES must run as the function owner role or a superuser. Functions owned by someone else only produce a warning and are not revoked.
A SECURITY DEFINER function runs with the privileges of its owner. If the connector account has EXECUTE on such a function, tables you did not grant SELECT on can be read through the function. For any schema containing these functions, verify that EXECUTE has been revoked.
2. Check which accounts are rejected#
The connection is checked on every attempt, and any one of the following produces the error "Only read-only accounts can connect".Superuser, replication, or row-level security bypass privileges
Database creation or role creation privileges
Membership in pg_read_server_files, pg_write_server_files, pg_execute_server_program, or pg_signal_backend
INSERT / UPDATE / DELETE / TRUNCATE / TRIGGER on any table or view outside the system schemas
Ownership of a table or view, or the privileges of the owning role
CREATE on the current database
TEMP privileges and CREATE on the public schema in PostgreSQL 14 and earlier are not checked, because nearly every account has them by default.
3. Choose the network path and TLS mode#
The address is checked against the IP that actually resolves at connection time.Loopback, link-local (cloud metadata addresses), and multicast addresses cannot be connected under any setting.
Private network addresses (10.x, 172.16–31.x, 192.168.x and similar) are blocked by default. A STORM operator must add the host to the allowlist.
Public internet addresses connect only when TLS is set to verify-full.
| Option | Meaning | Where it can be used |
|---|
require (encrypted) — default | Encrypts the connection only; the server certificate is not verified | Private network addresses or allowlisted hosts |
verify-full (verify certificate) | Encrypts and verifies the server certificate and host name | Everywhere. The only option for public internet addresses |
disable (private network only) | No encryption | Private network addresses or allowlisted hosts |
Entering a private address directly produces the error "Internal (private network) addresses cannot be connected". In that case, ask a STORM operator to add the host to the allowlist (CONNECTOR_ENDPOINT_ALLOWLIST).
To identify the connection on the DB side, look for rows in pg_stat_activity where application_name is cybros-connector-postgres. The connection waits up to 10 seconds.4. Connect a Database source#
1.
On the Knowledge Base Sources screen, select Connect source.
2.
Select Database in the catalog.
4.
Enter the Host, Port, Database, Account (read-only), and Password you prepared earlier.
6.
If you need to narrow the scope, enter schemas in Schemas (optional), comma separated.
7.
Choose a Sync interval. When creating a source you can pick Every hour or Daily (midnight).
The form shows the notice "Only read-only accounts can connect". Connect a DB that holds only the tables people may see, with a read-only account.
The password is stored in a separate secret store, apart from the other settings.
Schema names start with a letter or _, may contain letters, digits, _, and $, and are 63 characters or fewer. Names are compared case-sensitively.
5. Test the connection and create the source#
Test connection checks the connection, the read-only status of the account, schema existence and privileges, and the table count limit in one pass.On success a Table relationships preview appears below the form. Nothing is stored yet, so select Create source to save it.If there are no readable tables, the form shows "No readable tables found". If tables exceed 50, columns exceed 500, or relationship lines exceed 100, the full diagram is skipped and selecting a table draws only its connected tables.Failure messages and what to check#
| Screen message | What to check |
|---|
| Internal (private network) addresses cannot be connected … | Ask an operator to allowlist the host |
| Public internet addresses must use TLS with verify-full … | Change the TLS mode to verify-full |
| The DB server does not support TLS (SSL) connections … | Enable SSL on the DB, or use disable on a private network |
| The DB server certificate could not be verified … | Check the CA certificate and host name |
| Incorrect user name or password | Recheck the account and password |
| Database not found … | Check the database name |
| Schema {name} not found / no access privilege | Check the schema name and USAGE privilege |
| Only read-only accounts can connect … | Check the account against the reject list in step 2 |
| Too many tables … | Specify schemas to narrow the scope |
| Connection timed out … | Check network latency and the firewall, then retry |
6. Refine table descriptions and relationships#
Saving a source starts the first sync automatically. Every sync re-reads the full table list and creates AI descriptions only for tables whose schema changed or that are seen for the first time. A consistency check also runs periodically, at 24-hour to 7-day intervals.The import covers regular tables, partitioned tables, views, and materialized views the account has SELECT on. It reads table and column names, types, nullability, DB comments, primary keys, unique keys, and foreign keys, and skips information_schema and schemas starting with pg_.On the Documents screen, items from a DB source appear as DB table, not as files. Opening one shows the table structure, each column's type, nullability, and description, primary and foreign keys, connected tables, and the data preview summary.Select Edit to change the table description and column descriptions directly. Descriptions and relationships the AI filled in feed SQL generation immediately, and the values you edit here take precedence. Clearing a column description falls back to the AI or database description. Saving starts a sync so the change reaches the search cards.Exceeding an input limit rejects the save instead of truncating it. The limits are 2,000 characters for a description, 64 relationships, and 16 columns per relationship.
Without write permission on the source, the screen shows "Write permission on the source is required to edit".
A single source imports up to 5,000 tables and views combined. Exceeding that raises an error rather than importing a subset, so specify schemas to narrow the scope.
7. Attach the source to an agent#
Creating a source does not make an agent use it. Attach it on the agent's Knowledge screen.1.
On the agent's Knowledge screen, select Document registration.
2.
Select Use team knowledge.
3.
Choose the DB source in the list, then choose the whole source or specific tables.
The data source type in the knowledge list is shown as Database.
Attaching the whole source makes every current table in it queryable; attaching specific tables limits queries to those tables. SQL that reads a table outside the scope is rejected.
Folder sync keeps additions, edits, moves, and deletions of documents inside the folder reflected automatically.
8. Verify with a question#
Ask the agent a question about table contents. The answer and logs show the SQL search step, the list of searched tables, the Executed SQL, and the result table. The citation lists the queried tables and columns used.The result table shows up to 50 rows and notes "Showing M of N rows". N is the number of rows actually fetched (up to 1,000) and M is the number displayed. When the result exceeds 1,000 rows, N may differ from the real total in the DB.
A partial result carries the note "This result is incomplete. Do not use it as a complete total."
Empty results, missing privileges, and timeouts are reported with distinct status messages.
DB queries run through the single read-only account registered on the source. DB privileges are not split per user of the agent, so if you need to show different scopes to different users, create a separate read-only account for each scope and split the agents as well. Splitting sources alone still shows the same data to everyone who uses the same agent.
Operations and limits#
1. Edit and disable a source#
Open a source from the list and select Edit to change the source name, host, port, database, account, password, TLS, schemas, and sync interval. If the password changed on the DB, select Change and enter only the new password. Leaving it empty keeps the stored password.The sync interval on the edit screen offers Manual (set the interval yourself, from 1 minute up to 23 hours 59 minutes), Every 10 minutes, Every hour, and Daily (midnight).
Narrowing the schema scope deletes the tables of removed schemas from the source, so they stop appearing in search and agent SQL queries. Adding them back collects them again.
Disabling a source stops scheduled syncs and immediately stops DB questions from agents that use it. Enabling it resumes both.
2. AI descriptions and sample values#
During sync the AI drafts table descriptions, column descriptions, and reference relationships. It does nothing when no LLM is configured.To make descriptions match real data, a small sample of values is read from the customer DB.Value lists for code and status columns (string or enum, 20 or fewer distinct values, each value 60 characters or shorter)
Up to 6 sample rows per table (text up to 80 characters)
500 sample rows to measure how well join paths connect
Values are masked ([masked]) before use. Anything recognisable as personal data by column name or value shape — email, phone number, national ID, card or account number, token — is masked, as are name columns in person tables. Active screening rules in the workspace apply as well, and if the rules cannot be read no customer values are sent at all. The DB connection is closed after the values are read, and the AI is called afterwards.Environments that must not send customer data to an AI or an index can turn this off. With it off, value lists and the data preview summary are both omitted.
3. SQL restrictions and limits#
Before execution the SQL is parsed with PostgreSQL grammar, then the execution plan is checked once more for cost and tables, and the statement runs in a read-only transaction. Each query opens a new connection and closes it when done, and cancelling a request also cancels the query on the DB side.Allowed: a single SELECT statement only.
Rejected: multiple statements, INSERT, UPDATE, DELETE, SELECT INTO, locking clauses such as FOR UPDATE, tables outside the source and agent scope, and queries against the system catalogs (pg_catalog, information_schema).
Functions come from an allowlist. Aggregate, window, string, full-text search, date and time, math, JSON, and array functions are allowed; server information (version, current_setting), file and external access (pg_read_file, dblink), and XML functions (query_to_xml) are rejected. A function name qualified with pg_catalog. is allowed; qualifying it with any other schema is rejected.
Functions that can build large values are limited further. repeat and format are unavailable, lpad and rpad lengths are capped at 1,000, and generate_series at 10,000 rows.
| Item | Default |
|---|
| Result rows | 1,000 rows (truncated with a notice) |
| Query execution time | 30 seconds |
| Lock wait | 1 second |
| Estimated plan cost | 10,000,000 |
| Single cell size | 8 KiB |
| Total result size | 4 MiB |
| SQL statement length | 64 KiB |
| Concurrent queries per source | 4 (per server instance); without a free slot the request waits 5 seconds and returns "busy" |
These are defaults and an operator can adjust them with environment variables. Two are fixed and cannot be changed: the lock wait (1 second) and the SQL statement length (64 KiB).Tell your DBA: the load STORM places on a customer DB is 4 concurrent queries times the number of server instances, and a single query is capped at 30 seconds.
Modified at 2026-11-20 07:36:50