Add Oxla SQL Reference documentation (Beta)

local-antora-playbook.yml

@@ -15,6 +15,9 @@ content:
   sources:
   - url: .
     branches: HEAD
+  - url: .
+    branches: HEAD
+    start_path: oxla
   - url: https://github.com/redpanda-data/docs
     branches: [v/*, shared, site-search,'!v-end-of-life/*']
   - url: https://github.com/redpanda-data/cloud-docs

oxla/antora.yml

@@ -0,0 +1,51 @@
+name: oxla
+title: Oxla SQL
+version: beta
+start_page: oxla:index.adoc
+nav:
+  - modules/oxla/nav.adoc
+  - modules/oxla-reference/nav.adoc
+  - modules/oxla-manage/nav.adoc
+  - modules/oxla-troubleshoot/nav.adoc
+asciidoc:
+  attributes:
+    page-header-data:
+      order: 5                           # Position in main nav (after Upgrade)
+      color: '#4F46E5'                   # Oxla brand color (indigo)
+      beta: true                         # Beta badge flag
+    page-component-name: oxla
+    page-component-title: 'Oxla SQL (Beta)'
+    # Oxla-specific attributes
+    oxla-version: 'beta-1.0'
+    page-beta: ''                        # Enables beta badge on all pages
+    # Home page data for Oxla landing page
+    page-home-intro: 'Oxla is a PostgreSQL-compatible analytical database that provides high-performance SQL query processing. This documentation covers Oxla SQL dialect, including statements, functions, data types, and system configuration.'
+    page-home-intro-learn-more: oxla-reference:overview.adoc
+    page-home-primary-row-title: 'SQL Reference'
+    page-home-primary-row:
+      - title: 'SQL Statements'
+        description: 'Complete reference for all SQL statements supported by Oxla.'
+        url: 'oxla-reference:sql-statements/overview.adoc'
+        link-text: 'View statements'
+      - title: 'SQL Functions'
+        description: 'Browse all built-in SQL functions and operators.'
+        url: 'oxla-reference:sql-functions/overview.adoc'
+        link-text: 'View functions'
+      - title: 'Data Types'
+        description: 'Explore supported SQL data types and their usage.'
+        url: 'oxla-reference:sql-data-types/overview.adoc'
+        link-text: 'View types'
+    page-home-secondary-row-title: 'Security & Management'
+    page-home-secondary-row:
+      - title: 'Access Control'
+        description: 'Configure roles, privileges, and permissions.'
+        url: 'oxla-manage:access-control.adoc'
+        link-text: 'Learn more'
+      - title: 'Roles'
+        description: 'Manage database roles and permissions.'
+        url: 'oxla-manage:roles.adoc'
+        link-text: 'Learn more'
+      - title: 'Troubleshooting'
+        description: 'Error handling and degraded state management.'
+        url: 'oxla-troubleshoot:error-handling.adoc'
+        link-text: 'Learn more'

oxla/modules/oxla-manage/nav.adoc

@@ -0,0 +1,7 @@
+.Security
+* xref:oxla-manage:access-control.adoc[Access Control]
+* xref:oxla-manage:roles.adoc[Roles]
+* xref:oxla-manage:ownership.adoc[Ownership]
+* xref:oxla-manage:privileges.adoc[Privileges]
+* xref:oxla-manage:operation-permission-rules.adoc[Permission Rules for Operations]
+* xref:oxla-manage:ssl-configuration.adoc[SSL Configuration]

oxla/modules/oxla-manage/pages/access-control.adoc

@@ -0,0 +1,67 @@
+= Access Control
+
+
+## Overview
+
+Oxla implements role-based access control (RBAC) features, including roles, privileges 
+and ownership. These features function similarly to those found in other leading database systems, 
+providing a familiar access control model for users and administrators.
+
+## Enabling Access Control
+
+Access control is enabled by default on new Oxla installations. You can disable access control through the configuration file if needed. 
+For detailed instructions on configuring access control, refer to the Oxla 
+Configuration File documentation.
+
+The access control (AC) behavior is as follows:
+
+* If the access control flag is explicitly set in the configuration file, that setting is always followed
+* If the flag is not explicitly set in the configuration:
+    * When Oxla Home is empty, AC will be **enabled** by default
+    * When Oxla Home is non-empty, AC will be **enabled** only if it was previously enabled
+
+[NOTE]
+====
+For backward compatibility, old Oxla versions did not have access control (AC). 
+If you use a new Oxla release with an Oxla Home created by these old versions, AC will be **disabled** by default. 
+However, if the Oxla Home comes from an older where AC was likely enabled, then AC will be **enabled** by default. 
+This behavior helps maintain security settings appropriate to the Oxla Home’s history.
+====
+
+
+## Default Superuser
+
+Oxla always includes a default superuser account named `oxla` with the initial password `oxla`.
+
+* During the first startup, you can set a custom password for the default superuser using the `access_control.initial_password` parameter in the configuration file
+* After setting the password, you can remove this parameter from the configuration
+* You can also change the password later using the xref:oxla-manage:roles.adoc#changing-password[ALTER ROLE] query
+
+[TIP]
+====
+For security reasons, it is highly recommended to change the default superuser password immediately after installation.
+====
+
+
+## System Catalogs Visibility
+
+Users can view rows in system catalog tables only if those rows correspond to objects or reside in schemas to which the user has access. 
+For example, in the `information_schema.tables` table, a user can see all tables for which they have any grants, 
+as well as all tables in schemas where they have the `USAGE` privilege.
+
+## Restrictions
+
+* Only superusers have the `SELECT` privilege on internal system tables
+* Privileges on internal system tables cannot be granted or revoked
+* Only superusers and database owners can create new schemas
+* Only superusers can create new roles
+* Every role is granted the `CONNECT` privilege to the default database at creation (this privilege can be revoked)
+* Every role is granted the `USAGE` privilege on the default `public` schema at creation (this privilege can be revoked)
+* Oxla does not support role membership, so **privilege inheritance** is not available
+
+[NOTE]
+====
+Once access control is enabled and Oxla Home is not empty, you cannot disable access control. 
+If you attempt to run Oxla with the access control flag in `OXLA_HOME` set to `OFF` after it was previously enabled, 
+Oxla will enter a xref:oxla-troubleshoot:degraded-state-handling.adoc[degraded state].
+====

oxla/modules/oxla-manage/pages/operation-permission-rules.adoc

@@ -0,0 +1,136 @@
+= Permission Rules for Operations
+
+
+## Overview
+
+In Oxla, superusers can perform almost any operation, while object owners have broad privileges over their own objects. 
+This document explains the logic behind operation permissions and the factors considered when determining whether a specific 
+operation is allowed.
+
+## Classification of operations
+
+All operations that an Oxla client can perform fall into one of the following categories:
+
+* **Unavailable regardless of permissions**: operations that are never allowed
+* **Superusers-only**: operations restricted to superusers
+* **Owner-only**: operations allowed only for the object's owner
+* **Privilege-based:**: operations allowed for users with a specific privilege (P1) on an object (O1)
+* **Conditional**: operations are allowed only when all conditions are met. Each condition must belong to either category 3 or category 4
+* **Available to all users**: operations that anyone can perform
+
+## Implicitly Allowed Operations
+
+For operations in categories 3 and 4, two key rules apply:
+
+1. **Superuser Inheritance**: if an operation is allowed for the owner of object O1, it is also allowed for all superusers, 
+regardless of ownership
+
+2. **Owner Inheritance**: if an operation requires privilege P1 on object O1, the owner of O1 can perform it, 
+even without having privilage (P1). Referring to rule 1, all superusers can also perform such operations
+
+These rules mean that privileges granted to a superuser are irrelevant while they retain superuser status. 
+If a user loses superuser status, their explicit privileges become relevant again, 
+including any changes made while they were a superuser.
+
+[NOTE]
+====
+Role attributes, privileges, and ownership are managed independently. 
+Modifying one does not affect the others. This separation, combined with the implicit rules, 
+makes the privilege system straightforward and adaptable
+====
+
+
+## Operation Categories: Examples
+
+For clarity, reviewing examples of operations from each category can be highly beneficial.
+
+### Unavailable Regardless of Permissions
+
+Some operations are always forbidden because they would violate built-in constraints. 
+For example, deleting the default `public` schema or dropping a role that still owns objects is not allowed:
+
+[source,sql]
+----
+DROP ROLE john;
+----
+
+Even superusers cannot drop a role if it owns objects:
+
+[source]
+----
+ERROR:  role "john" cannot be dropped because some objects depend on it:
+... here is the list of dependent objects ...
+----
+
+
+[NOTE]
+====
+You can drop a role only after removing all its dependencies.
+====
+
+
+### Superuser-Only Operations
+
+Certain operations require superuser privileges. For example, creating a new role:
+
+[source,sql]
+----
+CREATE ROLE username PASSWORD 'your_secure_password';
+----
+
+Only superusers can execute this command.
+
+### Owner-Only Operations
+
+Some operations are restricted to object owners, even if other users have all possible privileges on the object. 
+For example, only the owner of schema `s1` can drop it:
+
+[source,sql]
+----
+DROP SCHEMA s1;
+----
+
+This operation is not permitted for non-owners, regardless of their privileges.
+
+### Privilege-Based Operations
+
+Many operations require specific privileges. For example, creating a table in schema `s1` requires the CREATE privilege on that schema:
+
+[source,sql]
+----
+CREATE TABLE s1.t1(a integer);
+----
+
+
+### Conditional Operations
+
+Some operations require multiple privileges or ownerships such as privileges of category 3 or 4. 
+If the user is a superuser, all such conditions are considered met. 
+If not, each condition must be checked individually, and all must be satisfied (either explicitly or implicitly).
+
+For example, to execute:
+
+[source,sql]
+----
+SELECT * FROM s1.t1;
+----
+
+
+The user must have:
+1. `USAGE` privilege on schema `s1`
+2. `SELECT` privilege on table `s1.t1`
+
+If a user owns the schema `s1` but not the table `s1.t1` and lacks `SELECT` privilege on `s1.t1`, the operation is forbidden. 
+Similarly, the operation will be forbidden if owning the table `s1.t1` without `USAGE` privilege on schema `s1`.
+
+### Operations Available to All Users
+
+Some operations are always available, assuming the user is connected to Oxla database. For example:
+
+[source,sql]
+----
+SELECT sqrt(15);
+----
+
+
+This query succeeds for any connected user, even if their `CONNECT` privilege was revoked after connecting.

oxla/modules/oxla-manage/pages/ownership.adoc

@@ -0,0 +1,105 @@
+= Ownership
+
+
+## Overview
+
+In Oxla, ownership defines the relationship where objects such as databases, tables and 
+schemas belong to a specific role. Keep the following principles in mind regarding ownership:
+
+* Indexes do not have explicit owners; the owner of the table also owns its indexes
+* Ownership is required to `DROP` an object
+* For grants validation, the owner implicitly has all privileges on the resource: 
+    * For table: `SELECT`, `INSERT`, `UPDATE`, `DELETE` 
+    * For schema: `USAGE`, `CREATE` 
+
+This section explains how to check and change ownership and clarifies the differences between ownership and role privileges.
+
+## Checking Ownership
+
+To check ownerships in Oxla, a superuser can execute the following query:
+
+[source,sql]
+----
+SELECT * FROM oxla_internal.oxla_object_owner;
+----
+
+
+Example output:
+
+[source,text]
+----
+id | database | schema |   object_name   | object_type
+----+----------+--------+-----------------+-------------
+  5 | oxla     | public | data_types_demo | TABLE
+----
+
+
+Here's the breakdown of the above output:
+
+* `id`: role ID
+* `database`: database name
+* `schema`: schema name (empty if `object_type` is DATABASE)
+* `object_name`: object name (empty if `object_type` is SCHEMA or DATABASE)
+* `object_type`: type of the object
+
+## Changing Ownership
+
+To change ownership, use the following syntax:
+
+[source,sql]
+----
+ALTER [ TABLE | SCHEMA | DATABASE ] OBJECT_NAME OWNER TO ROLE_NAME;
+----
+
+
+where:
+
+* `OBJECT_NAME`: name of the object, whose ownership they want to change
+* `ROLE_NAME`: name of the role that will become the new owner of the specified object, or keyword CURRENT_ROLE/CURRENT_USER
+
+## Ownership vs Role Privileges
+
+Unlike PostgreSQL, Oxla treats ownership and grants as independent. While owners implicitly have all privileges on their resources, 
+these privileges:
+
+* Are not visible in `oxla_internal.oxla_role_ns_grants` or `oxla_internal.oxla_role_table_grants`
+* Cannot be revoked
+
+`GRANT` or `REVOKE` operations can still be performed on object owner - they will result in creating or removing entries 
+in `oxla_internal.oxla_role_..._grants` tables, which are independent of data stored in `oxla_internal.oxla_object_owner`. 
+These grants do not matter anything as long as the user is the owner of a given resource, 
+but they will take effect when the owner is changed.
+
+## Examples
+
+Here are a few examples that demonstrate the behaviours described above, assuming there is a `table1` and `user1` role with `USAGE` grant in public schema:
+
+* After the following operations `user1` will no longer be the owner of `table1`, but will have `SELECT` grant on that table.
+
+  [source,sql]
+----
+ALTER TABLE table1 OWNER TO user1;
+  GRANT SELECT ON table1 TO user1;
+  ALTER TABLE table1 OWNER TO oxla;
+----
+
+
+* After the following operations `user1` will still be able to `SELECT` from `table1` because of ownership, however `REVOKE` does not change anything.
+
+  [source,sql]
+----
+ALTER TABLE table1 OWNER TO user1;
+  REVOKE SELECT ON table1 FROM user1;
+----
+
+
+* After the following operations `user1` will not have access to `table1`, however the owner has been changed and grant has been revoked.
+
+  [source,sql]
+----
+ALTER TABLE table1 OWNER TO user1;
+  GRANT SELECT ON table1 TO user1;
+  REVOKE SELECT ON table1 FROM user1;
+  ALTER TABLE table1 OWNER TO oxla;
+----
+