Use Orloi with AI agents

Orloi stores operational history in your Postgres database. An AI agent can use that history to answer questions, investigate unusual activity, or prepare updates, but it should never receive the connection that installs or operates Orloi.

This guide separates four database identities. They solve different problems and must not be treated as interchangeable.

Access level	Purpose	What it can access
Installation/schema owner	Creates the orloi schema and owns its objects	Schema creation, upgrades, and all Orloi objects
Orloi runtime	The connection configured in Orloi	Reads and writes needed to capture and process data; must also be able to complete schema upgrades when Orloi runs them
Whole-Orloi reader	Human, BI tool, or agent that may read every captured base in orloi	SELECT on all current and future Orloi tables
Single-base analytical reader	Agent limited to one base or sync_id	Only an API, dedicated database, or carefully designed restricted views/RLS boundary exposes that base

Installation and runtime are not agent roles

The role that first connects Orloi creates the orloi schema and the installed tables. PostgreSQL makes that active role the owner of those objects. Orloi also checks and upgrades its schema on the configured database connection, so an upgrade can require ownership-level DDL privileges.

Use the installation/schema-owner connection for setup and schema upgrades only. Do not give it to an agent, MCP server, notebook, or BI tool.

The simplest supported setup uses that same owner connection at runtime. A separate runtime connection is only safe when it can still complete the required Orloi schema upgrade path—for example, through the actual object-owning role under a controlled deployment process. Ordinary INSERT, UPDATE, and SELECT grants do not permit ALTER TABLE or other owner-only upgrades. Test this arrangement on every upgrade; do not assume a narrower role is sufficient.

Orloi does not need permission to modify your application schemas. Its managed objects belong in orloi; see Set up Orloi for the required installation and runtime capabilities.

Whole-Orloi read-only access

Use a dedicated login role for an agent that is allowed to read all bases captured in the orloi schema. Run the following as a database administrator or the role that can create roles and manage the Orloi schema. Replace the example password and the actual role that creates Orloi objects.

create role orloi_agent_reader
  login
  nosuperuser
  nocreatedb
  nocreaterole
  noinherit
  noreplication
  nobypassrls
  password 'replace-with-a-long-random-password';

grant usage on schema orloi to orloi_agent_reader;
grant select on all tables in schema orloi to orloi_agent_reader;

-- Replace orloi_schema_owner with the active role that creates future
-- Orloi tables. Run this as that role or as one of its members.
alter default privileges for role orloi_schema_owner in schema orloi
  grant select on tables to orloi_agent_reader;

SELECT on tables is sufficient for ordinary analysis; do not grant sequence privileges, schema CREATE, table writes, ownership, BYPASSRLS, superuser, or role-management privileges to this role.

Why FOR ROLE matters

ALTER DEFAULT PRIVILEGES applies only to objects created later by its target role. Without FOR ROLE, PostgreSQL changes the defaults of the role running the command, which is often the database administrator rather than the Orloi schema owner. Defaults are also not inherited through role membership, and they do not change existing tables.

If more than one identity can create Orloi tables, repeat the ALTER DEFAULT PRIVILEGES FOR ROLE ... statement for each actual creator. If the runtime process uses SET ROLE, target the role active when it creates the object. See PostgreSQL's ALTER DEFAULT PRIVILEGES reference and role membership rules.

The grants on all existing tables and the default grants for future tables are both required. Re-run the existing-table grant after adding a reader if tables were created before the default rule was configured.

One base is not a prompt boundary

Every Orloi table can contain data for multiple bases. sync_id is a useful query filter, but a prompt such as “only analyze syn_123” does not restrict SQL. A role that has SELECT on orloi tables can remove that predicate and read another base. The same is true of client-side filters and an MCP tool that forwards arbitrary SQL.

For single-base access, use one of these real enforcement boundaries instead:

• A dedicated database or isolated storage destination for that base. This is the clearest database boundary.
• A small internal API or MCP server that authenticates the caller and only executes parameterized, allowlisted queries with the assigned sync_id enforced server-side. Give the agent the API credential, not direct table access.
• Restricted, separately owned views that hard-code the allowed sync_id (or otherwise enforce a fixed base mapping). Grant the reader USAGE on the access schema and SELECT only on those views; do not grant it access to orloi base tables. Review every view, including joins and derived objects, so it cannot leak rows from another base.
• Row-level security (RLS) designed and tested by a PostgreSQL administrator for every relevant table and role. The reader must not own the tables or have BYPASSRLS; policies must derive the allowed base from a trusted identity, not a client-controlled setting or prompt.

Do not implement single-base isolation with a custom session setting that the agent can set itself. Do not rely on a view if the same role can also read the underlying tables. If you cannot maintain one of these boundaries, provide a bounded export or give the agent whole-Orloi read-only access only after deciding that all captured bases are in scope.

Verify the role and grants

Run these checks from an administrator connection after granting access. They intentionally inspect the configured role rather than trusting the SQL above.

-- Confirm the login role has no elevated attributes.
select rolname, rolcanlogin, rolsuper, rolcreaterole, rolcreatedb,
       rolreplication, rolbypassrls, rolinherit
from pg_roles
where rolname = 'orloi_agent_reader';

-- Confirm it can resolve the schema and read each current table.
select
  has_schema_privilege('orloi_agent_reader', 'orloi', 'USAGE') as schema_usage,
  table_name,
  has_table_privilege(
    'orloi_agent_reader',
    format('%I.%I', table_schema, table_name),
    'SELECT'
  ) as can_select
from information_schema.tables
where table_schema = 'orloi'
  and table_type in ('BASE TABLE', 'VIEW')
order by table_name;

-- Inspect future-object rules. The target role must be the object creator.
select
  defaclrole::regrole as object_creator,
  coalesce(defaclnamespace::regnamespace::text, '(all schemas)') as schema_name,
  defaclobjtype as object_type,
  defaclacl as access_privileges
from pg_default_acl
where defaclnamespace = 'orloi'::regnamespace
order by object_creator, object_type;

Test that future tables receive the grant in a disposable fixture database or transaction, executed as the actual object-creating role:

begin;
create table orloi._agent_reader_privilege_probe (id bigint primary key);
select has_table_privilege(
  'orloi_agent_reader',
  'orloi._agent_reader_privilege_probe',
  'SELECT'
) as reader_can_select_future_table;
rollback;

Finally, connect using the agent connection string and confirm both a read and a denied write. The write probe is inside a transaction and must fail with permission denied; if it succeeds, immediately roll back and correct the grants.

select current_user, session_user;
select count(*) from orloi.schema_meta;

begin;
update orloi.schema_meta
set updated_at = updated_at
where false;
rollback;

For restricted views or RLS, add a test using the agent credential that attempts to read a known row from a different sync_id. The query must return no row or fail. A successful “allowed base” query alone does not prove isolation.

Connect agents safely

Use the reader credential only in a secret manager, environment variable, or MCP/server configuration. Never paste the installation or runtime connection string into a prompt.

export ORLOI_DATABASE_URL="postgresql://orloi_agent_reader:password@db.example.com:5432/app_database?sslmode=require"

For hosted agents whose secret handling is unclear, use an internal API, a configured MCP connector, a bounded export, or a temporary revocable reader credential. Keep action-taking workflows separate from Orloi analysis.

Analysis behavior

The Orloi agent instructions provide safe query practices: discover the installed schema, set timeouts, use bounded windows, begin with derived data, and avoid raw payload dumps. They are behavior guidance, not an authorization boundary.

Agents can investigate activity, metrics, alerts, reports, and process patterns. Start with compacted events, metrics, reports, alerts, and signals. Use raw events only when provenance is necessary, and summarize or redact sensitive values in the answer.

Security checklist

• The agent never receives the installation/schema-owner or runtime credential.
• Whole-Orloi agents use a dedicated reader with only schema USAGE and table SELECT.
• Existing and future-object grants were verified for the actual object creator.
• A single-base agent has an API, isolated database, audited restricted views, or tested RLS—not only a sync_id prompt filter.
• The agent connection is kept in configured secrets, not conversation text or source control.
• Any write or action workflow has a separate, explicitly approved path.