From 7b08726d3a086227046dc8a66b3e90b42f22dcda Mon Sep 17 00:00:00 2001
From: Julien Goux <hi@jgoux.dev>
Date: Thu, 1 Oct 2026 13:13:19 +0200
Subject: [PATCH] docs(cli): document OrioleDB initialization and
 db.orioledb_version (#50908)

Document `supabase init --use-orioledb` in the CLI reference. Add
`db.orioledb_version` to the CLI config reference, and mark
`experimental.orioledb_version` as deprecated.

This complements the general OrioleDB beta guide update in #50813.

Companion CLI PR: https://github.com/supabase/cli/pull/6828, released in
[v2.119.0](https://github.com/supabase/cli/releases/tag/v2.119.0).


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Documented the `supabase init --use-orioledb` option, which sets the
OrioleDB image version in `supabase/config.toml`.
* Added configuration guidance for `db.orioledb_version`, including its
PostgreSQL version requirements.
* Marked `experimental.orioledb_version` as deprecated and directed
users to `db.orioledb_version`. The CLI continues to read the
experimental setting and warns when it is set.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
---
 apps/docs/spec/cli_v1_commands.yaml |  6 ++++++
 apps/docs/spec/cli_v1_config.yaml   | 13 +++++++++++--
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/apps/docs/spec/cli_v1_commands.yaml b/apps/docs/spec/cli_v1_commands.yaml
index ce3a23aa4ee..0af1323dc4a 100644
--- a/apps/docs/spec/cli_v1_commands.yaml
+++ b/apps/docs/spec/cli_v1_commands.yaml
@@ -2359,6 +2359,8 @@ commands:
       > You may override the directory path by specifying the `SUPABASE_WORKDIR` environment variable or `--workdir` flag.
 
       In addition to `config.toml`, the `supabase` directory may also contain other Supabase objects, such as `migrations`, `functions`, `tests`, etc.
+
+      To use OrioleDB as the Postgres storage engine, run `supabase init --use-orioledb`. The command writes the OrioleDB version to `db.orioledb_version` in `supabase/config.toml`.
     examples:
       - id: basic-usage
         name: Basic usage
@@ -2368,6 +2370,10 @@ commands:
         name: Initialize from an existing directory
         code: supabase init --workdir .
         response: Finished supabase init.
+      - id: with-orioledb
+        name: Initialize with OrioleDB
+        code: supabase init --use-orioledb
+        response: Finished supabase init.
     tags:
       - local-dev
     links: []
diff --git a/apps/docs/spec/cli_v1_config.yaml b/apps/docs/spec/cli_v1_config.yaml
index ab88a167a6c..5d6ff187e08 100644
--- a/apps/docs/spec/cli_v1_config.yaml
+++ b/apps/docs/spec/cli_v1_config.yaml
@@ -152,6 +152,16 @@ parameters:
       - name: 'PostgreSQL configuration'
         link: 'https://postgrest.org/en/stable/configuration.html'
 
+  - id: 'db.orioledb_version'
+    title: 'db.orioledb_version'
+    tags: ['database']
+    required: false
+    description: |
+      OrioleDB version of the Postgres image to use for the local database. Leave empty to use the default storage engine. Requires `db.major_version` 15 or 17. `supabase init --use-orioledb` sets this value.
+    links:
+      - name: 'OrioleDB'
+        link: 'https://supabase.com/docs/guides/database/orioledb'
+
   - id: 'db.pooler.enabled'
     title: 'db.pooler.enabled'
     tags: ['database']
@@ -1763,8 +1773,7 @@ parameters:
     tags: ['experimental']
     required: false
     description: |
-      Configures Postgres storage engine to use OrioleDB with S3 support.
-      Note: This is an experimental feature and may change in future releases.
+      Deprecated. Use `db.orioledb_version` instead. The CLI still reads this setting and prints a deprecation warning when it is set.
     links: []
 
   - id: 'experimental.s3_host'