[glasstiger]

Summary

Documents the changes from questdb/questdb-enterprise#1222 and its OSS tandem questdb/questdb#7631, shipped in QuestDB Enterprise 4.1.0:

• New active_permissions() and active_grants() ACL table functions.
• Enterprise administrative functions are rejected in materialized view and live view queries.
• A read-only replica's access-list refresh is bounded to 30 seconds and fails closed.

Access control functions page

New reference page, Access control functions (query/functions/access-control.md), added to the Functions sidebar. It covers all four Enterprise ACL table functions:

Function	Returns	Required permissions
active_grants() (new in 4.1.0)	Direct grants of every user, group, and service account	LIST USERS and USER DETAILS
active_permissions() (new in 4.1.0)	Effective permissions of every user, group, and service account	LIST USERS and USER DETAILS
all_permissions()	Every permission and the levels it can be granted at	None
permissions([entityName])	Effective permissions of the current user or a named entity	USER DETAILS for other entities

The page documents:

• Result columns and scope semantics. Database-level rows have a null table_name. Each combination of entity, permission, table, and column appears once. A permission appears on two scopes when its grant option is narrower than the permission. Grants on tables or columns that do not exist yet are included, which permissions() omits.
• What active_permissions() adds to active_grants(). It adds permissions inherited from groups, the implicit permission on the designated timestamp, and the permissions that DATABASE ADMIN includes.
• Required permissions. Both functions need LIST USERS and USER DETAILS, even to read your own rows. The page lists the Access denied errors a caller gets without them.
• Limitations. The built-in admin and external (SSO/OIDC) users are not listed, so you audit their mapped groups instead. Group memberships and ASSUME SERVICE ACCOUNT grants are not listed. With acl.enabled=false the functions return no rows. They cannot be used in materialized or live views, but regular views can call them.
• Verified examples with result tables, all built on one set of entities and grants:
  • direct grants compared with effective permissions;
  • who can read a table, including database-level and column grants;
  • which entities hold the grant option;
  • the levels each permission can be granted at;
  • one entity's permissions, with the origin column.

Materialized views and live views

Eight Enterprise administrative functions are rejected in materialized view and live view queries: active_grants(), active_permissions(), backup_instance_name(), backup_status(), backups(), permissions(), reload_tick_calendars(), and reload_tls(). They check the caller's permissions, and a background refresh has no session to check against. This PR documents:

• the restriction in the query constraints of concepts/materialized-views.md, concepts/live-views.md, query/sql/create-mat-view.md, and query/sql/create-live-view.md;
• the administrative function cannot be used in materialized view: <function> error and its live view counterpart, in the CREATE MATERIALIZED VIEW and CREATE LIVE VIEW error tables.

Access control on replicas

New Access control on replicas section in security/rbac.md:

• Access control is managed on the primary. A read-only replica rejects statements such as CREATE USER and GRANT.
• Before it authorizes a statement, the replica reloads its replicated access lists if new changes have arrived.
• A statement waits up to 30 seconds for another session's reload. If the lists are still stale after that, the statement fails with timed out waiting for the access lists to refresh [timeout=30000ms] rather than being authorized against outdated permissions.

Related changes

• Enterprise quick start: corrects the claim that all_permissions() lists applied permissions. It now shows an active_grants() query for checking grants.
• RBAC:
  • adds an audit snippet using active_permissions() and active_grants();
  • notes that they require both LIST USERS and USER DETAILS;
  • links the permissions reference to all_permissions() and says that it lists the available permissions and their grant levels.
• SHOW PERMISSIONS: links to permissions(), which returns the same rows as a table function. Also links to active_permissions(), which lists every entity at once.
• GRANT: points to active_grants() for grants on tables or columns that do not exist yet, since SHOW PERMISSIONS does not show them.
• Changelog: entries for the new page and for the view, replica, and quick start updates.

Dependencies

All merged and included in QuestDB Enterprise 4.1.0:

• questdb/questdb-enterprise#1222: ACL functions, view restriction, and replica refresh.
• questdb/questdb#7631: OSS side of the view restriction.
• questdb/sql-parser#37: Web Console autocomplete and syntax highlighting for active_permissions() and active_grants().

[github-actions]

🚀 Build success!

Latest successful preview: https://preview-566--questdb-documentation.netlify.app/docs/

Commit SHA: 9a5928e

📦 Build generates a preview & updates the link on each commit.