From 3bdf98e66b768b616228164b302e8bcae66e34a9 Mon Sep 17 00:00:00 2001 From: Andrey Listopadov Date: Thu, 19 Mar 2026 19:30:23 +0300 Subject: [PATCH 1/3] add databricks lakebase postgress documentation --- .../run-aidbox-on-managed-postgresql.md | 54 ++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md b/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md index 575b2b658..436f6665d 100644 --- a/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md +++ b/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md @@ -1,5 +1,5 @@ --- -description: Run Aidbox on managed PostgreSQL services like AWS Aurora, Azure Database, and GCP Cloud SQL. Setup guide for extensions and user configuration. +description: Run Aidbox on managed PostgreSQL services like AWS Aurora, Azure Database, GCP Cloud SQL, and Databricks Lakebase. Setup guide for extensions and user configuration. --- # Run Aidbox on managed PostgreSQL @@ -39,6 +39,58 @@ Follow [Azure Documentation](https://learn.microsoft.com/en-us/azure/postgresql/ CREATE USER aidbox WITH CREATEDB ENCRYPTED PASSWORD 'aidboxpass'; ``` +### Databricks Lakebase + +#### Prerequisites + +* A Databricks workspace with [Lakebase Postgres](https://docs.databricks.com/aws/en/oltp/) enabled +* A [service principal](https://docs.databricks.com/aws/en/admin/users-groups/service-principals) with a generated OAuth secret, [added to the workspace](https://docs.databricks.com/aws/en/admin/users-groups/service-principals#add-a-service-principal-to-a-workspace) +* Follow [Databricks documentation](https://docs.databricks.com/aws/en/oltp/instances/pg-roles?language=PostgreSQL) to create a PostgreSQL role for the service principal. + +#### Configure Aidbox + +Lakebase uses OAuth token-based authentication. Aidbox supports both **Provisioned** and **Autoscaling** deployment modes. + +{% tabs %} +{% tab title="Provisioned" %} +```shell +BOX_DB_HOST=.database.cloud.databricks.com +BOX_DB_PORT=5432 +BOX_DB_DATABASE=databricks_postgres +BOX_DB_USER= +BOX_DB_PASSWORD=placeholder + +BOX_DB_AUTH_METHOD=databricks-provisioned +BOX_DB_DATABRICKS_HOST=https://your-workspace.cloud.databricks.com +BOX_DB_DATABRICKS_PROVISIONED_INSTANCE_NAME= +BOX_DB_DATABRICKS_CLIENT_ID= +BOX_DB_DATABRICKS_CLIENT_SECRET= +``` +{% endtab %} +{% tab title="Autoscaling" %} +```shell +BOX_DB_HOST=.database.cloud.databricks.com +BOX_DB_PORT=5432 +BOX_DB_DATABASE=databricks_postgres +BOX_DB_USER= +BOX_DB_PASSWORD=placeholder + +BOX_DB_AUTH_METHOD=databricks-autoscale +BOX_DB_DATABRICKS_HOST=https://your-workspace.cloud.databricks.com +BOX_DB_DATABRICKS_AUTOSCALE_ENDPOINT=projects//branches//endpoints/ +BOX_DB_DATABRICKS_CLIENT_ID= +BOX_DB_DATABRICKS_CLIENT_SECRET= +``` +{% endtab %} +{% endtabs %} + +{% hint style="info" %} +`BOX_DB_USER` and `BOX_DB_DATABRICKS_CLIENT_ID` are both the service principal's application ID. +`BOX_DB_PASSWORD` is a placeholder — the credentials provider overrides it. +`BOX_DB_DATABRICKS_HOST` is the workspace URL (from your browser), not the database hostname. +The same auth settings are available for read-only replica with the `BOX_DB_RO_REPLICA_*` prefix. +{% endhint %} + ### Disable installation of PostgreSQL extensions on Aidbox startup If your PostgreSQL user used by Aidbox does not have sufficient privileges to install extensions, you can disable the installation of extensions on startup of Aidbox by setting the environment variable `AIDBOX_INSTALL_PG_EXTENSIONS` to `false`. From 91f2a517aaeffef7db613facaaec2ba73a8794f7 Mon Sep 17 00:00:00 2001 From: Andrey Listopadov Date: Fri, 20 Mar 2026 12:17:47 +0300 Subject: [PATCH 2/3] address review comments --- .../run-aidbox-on-managed-postgresql.md | 9 +- docs/reference/all-settings.md | 160 ++++++++++++++++++ 2 files changed, 167 insertions(+), 2 deletions(-) diff --git a/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md b/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md index 436f6665d..d356fea38 100644 --- a/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md +++ b/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md @@ -45,12 +45,15 @@ CREATE USER aidbox WITH CREATEDB ENCRYPTED PASSWORD 'aidboxpass'; * A Databricks workspace with [Lakebase Postgres](https://docs.databricks.com/aws/en/oltp/) enabled * A [service principal](https://docs.databricks.com/aws/en/admin/users-groups/service-principals) with a generated OAuth secret, [added to the workspace](https://docs.databricks.com/aws/en/admin/users-groups/service-principals#add-a-service-principal-to-a-workspace) -* Follow [Databricks documentation](https://docs.databricks.com/aws/en/oltp/instances/pg-roles?language=PostgreSQL) to create a PostgreSQL role for the service principal. +* Follow [Databricks documentation](https://docs.databricks.com/aws/en/oltp/instances/pg-roles?language=PostgreSQL) to create a PostgreSQL role for the service principal +* The database must already exist before starting Aidbox — Aidbox will not create it automatically when using Databricks authentication #### Configure Aidbox Lakebase uses OAuth token-based authentication. Aidbox supports both **Provisioned** and **Autoscaling** deployment modes. +Aidbox fetches short-lived tokens (1 hour expiry) from Databricks and caches them for 45 minutes (configurable via `BOX_DB_CREDENTIAL_REFRESH_INTERVAL`). When the cache expires, a fresh token is fetched on the next connection. HikariCP `max-lifetime` is set to match the cache TTL so existing connections rotate before tokens expire. SSL is enforced automatically. + {% tabs %} {% tab title="Provisioned" %} ```shell @@ -88,7 +91,9 @@ BOX_DB_DATABRICKS_CLIENT_SECRET= `BOX_DB_USER` and `BOX_DB_DATABRICKS_CLIENT_ID` are both the service principal's application ID. `BOX_DB_PASSWORD` is a placeholder — the credentials provider overrides it. `BOX_DB_DATABRICKS_HOST` is the workspace URL (from your browser), not the database hostname. -The same auth settings are available for read-only replica with the `BOX_DB_RO_REPLICA_*` prefix. +`BOX_DB_DATABRICKS_SCOPE` defaults to `all-apis`. Do not change unless you know your workspace requires a different scope. +`BOX_DB_CREDENTIAL_REFRESH_INTERVAL` controls the token cache TTL in milliseconds (default: `2700000`, i.e. 45 minutes). Should be less than the Databricks token expiry (60 minutes). +The same auth settings are available for read-only replica with the `BOX_DB_RO_REPLICA_*` prefix (e.g. `BOX_DB_RO_REPLICA_AUTH_METHOD`, `BOX_DB_RO_REPLICA_DATABRICKS_HOST`, etc.). {% endhint %} ### Disable installation of PostgreSQL extensions on Aidbox startup diff --git a/docs/reference/all-settings.md b/docs/reference/all-settings.md index 930b4f252..c46210587 100644 --- a/docs/reference/all-settings.md +++ b/docs/reference/all-settings.md @@ -1716,6 +1716,86 @@ If enabled, the health status of the database will be reflected in the overall h
Details
IDdb.propagate-db-health-status-to-box
TypeBool
Default valuefalse
Environment variableBOX_PROPAGATE_DB_HEALTH_STATUS_TO_BOX
Available from2509
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadtrue — setting can be changed at runtime
+#### Database authentication method + +```yaml +BOX_DB_AUTH_METHOD: "password" +``` + +Authentication method for the database connection. `password` — static password. `databricks-provisioned` — Databricks Lakebase Provisioned OAuth token (BYOT). `databricks-autoscale` — Databricks Lakebase Autoscaling OAuth token. + +
Details
IDdb.auth-method
TypeString (enum: password, databricks-provisioned, databricks-autoscale)
Default valuepassword
Environment variableBOX_DB_AUTH_METHOD
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ +#### Databricks workspace host + +```yaml +BOX_DB_DATABRICKS_HOST: "https://your-workspace.cloud.databricks.com" +``` + +Databricks workspace URL. Required when `auth-method` is `databricks-provisioned` or `databricks-autoscale`. + +
Details
IDdb.databricks-host
TypeString
Default value(no default)
Environment variableBOX_DB_DATABRICKS_HOST
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ +#### Databricks Provisioned instance name + +```yaml +BOX_DB_DATABRICKS_PROVISIONED_INSTANCE_NAME: "" +``` + +Name of the Databricks Lakebase Provisioned instance. Required when `auth-method` is `databricks-provisioned`. + +
Details
IDdb.databricks-provisioned-instance-name
TypeString
Default value(no default)
Environment variableBOX_DB_DATABRICKS_PROVISIONED_INSTANCE_NAME
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ +#### Databricks client ID + +```yaml +BOX_DB_DATABRICKS_CLIENT_ID: "" +``` + +Databricks service principal client ID. Required when `auth-method` is `databricks-provisioned` or `databricks-autoscale`. + +
Details
IDdb.databricks-client-id
TypeString
Default value(no default)
Environment variableBOX_DB_DATABRICKS_CLIENT_ID
Available from2603
Sensitivetrue — value will be masked in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ +#### Databricks client secret + +```yaml +BOX_DB_DATABRICKS_CLIENT_SECRET: "" +``` + +Databricks service principal client secret. Required when `auth-method` is `databricks-provisioned` or `databricks-autoscale`. + +
Details
IDdb.databricks-client-secret
TypeString
Default value(no default)
Environment variableBOX_DB_DATABRICKS_CLIENT_SECRET
Available from2603
Sensitivetrue — value will be masked in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ +#### Databricks OAuth scope + +```yaml +BOX_DB_DATABRICKS_SCOPE: "all-apis" +``` + +OAuth scope for the Databricks token request. + +
Details
IDdb.databricks-scope
TypeString
Default valueall-apis
Environment variableBOX_DB_DATABRICKS_SCOPE
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ +#### Databricks Autoscaling endpoint + +```yaml +BOX_DB_DATABRICKS_AUTOSCALE_ENDPOINT: "projects//branches//endpoints/" +``` + +Lakebase Autoscaling endpoint path. Required when `auth-method` is `databricks-autoscale`. + +
Details
IDdb.databricks-autoscale-endpoint
TypeString
Default value(no default)
Environment variableBOX_DB_DATABRICKS_AUTOSCALE_ENDPOINT
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ +#### Credential refresh interval + +```yaml +BOX_DB_CREDENTIAL_REFRESH_INTERVAL: 2700000 +``` + +Token cache TTL in milliseconds. Controls how often Aidbox fetches a fresh database credential token. Also sets HikariCP `max-lifetime` so existing connections rotate before tokens expire. Default is 45 minutes (2700000 ms), which is less than the Databricks token expiry of 60 minutes. + +
Details
IDdb.credential-refresh-interval
TypeInt (milliseconds)
Default value2700000
Environment variableBOX_DB_CREDENTIAL_REFRESH_INTERVAL
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart
+ ### Read-only replica Read-only database replica settings @@ -1878,6 +1958,86 @@ The pool connection initialization SQL statement.
Details
IDdb.ro-replica.pool.connection-init-sql
TypeString
Default valueselect 1
Environment variableBOX_DB_RO_REPLICA_POOL_CONNECTION_INIT_SQL
Available from2507
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+#### RO replica authentication method + +```yaml +BOX_DB_RO_REPLICA_AUTH_METHOD: "password" +``` + +Authentication method for the read-only replica connection. + +
Details
IDdb.ro-replica.auth-method
TypeString (enum: password, databricks-provisioned, databricks-autoscale)
Default valuepassword
Environment variableBOX_DB_RO_REPLICA_AUTH_METHOD
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+ +#### RO replica Databricks workspace host + +```yaml +BOX_DB_RO_REPLICA_DATABRICKS_HOST: "https://your-workspace.cloud.databricks.com" +``` + +Databricks workspace URL for the read-only replica. + +
Details
IDdb.ro-replica.databricks-host
TypeString
Default value(no default)
Environment variableBOX_DB_RO_REPLICA_DATABRICKS_HOST
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+ +#### RO replica Databricks Provisioned instance name + +```yaml +BOX_DB_RO_REPLICA_DATABRICKS_PROVISIONED_INSTANCE_NAME: "" +``` + +Lakebase Provisioned instance name for the read-only replica. + +
Details
IDdb.ro-replica.databricks-provisioned-instance-name
TypeString
Default value(no default)
Environment variableBOX_DB_RO_REPLICA_DATABRICKS_PROVISIONED_INSTANCE_NAME
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+ +#### RO replica Databricks client ID + +```yaml +BOX_DB_RO_REPLICA_DATABRICKS_CLIENT_ID: "" +``` + +Databricks service principal client ID for the read-only replica. + +
Details
IDdb.ro-replica.databricks-client-id
TypeString
Default value(no default)
Environment variableBOX_DB_RO_REPLICA_DATABRICKS_CLIENT_ID
Available from2603
Sensitivetrue — value will be masked in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+ +#### RO replica Databricks client secret + +```yaml +BOX_DB_RO_REPLICA_DATABRICKS_CLIENT_SECRET: "" +``` + +Databricks service principal client secret for the read-only replica. + +
Details
IDdb.ro-replica.databricks-client-secret
TypeString
Default value(no default)
Environment variableBOX_DB_RO_REPLICA_DATABRICKS_CLIENT_SECRET
Available from2603
Sensitivetrue — value will be masked in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+ +#### RO replica Databricks OAuth scope + +```yaml +BOX_DB_RO_REPLICA_DATABRICKS_SCOPE: "all-apis" +``` + +OAuth scope for the read-only replica token request. + +
Details
IDdb.ro-replica.databricks-scope
TypeString
Default valueall-apis
Environment variableBOX_DB_RO_REPLICA_DATABRICKS_SCOPE
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+ +#### RO replica Databricks Autoscaling endpoint + +```yaml +BOX_DB_RO_REPLICA_DATABRICKS_AUTOSCALE_ENDPOINT: "projects//branches//endpoints/" +``` + +Lakebase Autoscaling endpoint for the read-only replica. + +
Details
IDdb.ro-replica.databricks-autoscale-endpoint
TypeString
Default value(no default)
Environment variableBOX_DB_RO_REPLICA_DATABRICKS_AUTOSCALE_ENDPOINT
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+ +#### RO replica credential refresh interval + +```yaml +BOX_DB_RO_REPLICA_CREDENTIAL_REFRESH_INTERVAL: 2700000 +``` + +Token cache TTL in milliseconds for the read-only replica. + +
Details
IDdb.ro-replica.credential-refresh-interval
TypeInt (milliseconds)
Default value2700000
Environment variableBOX_DB_RO_REPLICA_CREDENTIAL_REFRESH_INTERVAL
Available from2603
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart
+ ## Web Server Web Server settings From f727d6e18e5dfb2139674c447a89a230a8fdc466 Mon Sep 17 00:00:00 2001 From: Andrey Listopadov Date: Fri, 20 Mar 2026 18:49:33 +0300 Subject: [PATCH 3/3] fix --- .../deploy-aidbox/run-aidbox-on-managed-postgresql.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md b/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md index d356fea38..4bcfdf00e 100644 --- a/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md +++ b/docs/deployment-and-maintenance/deploy-aidbox/run-aidbox-on-managed-postgresql.md @@ -50,7 +50,7 @@ CREATE USER aidbox WITH CREATEDB ENCRYPTED PASSWORD 'aidboxpass'; #### Configure Aidbox -Lakebase uses OAuth token-based authentication. Aidbox supports both **Provisioned** and **Autoscaling** deployment modes. +Lakebase uses OAuth token-based authentication. Aidbox supports both Lakebase deployment modes: [Provisioned](https://docs.databricks.com/aws/en/oltp/instances/) (fixed-capacity instances) and [Autoscaling](https://docs.databricks.com/aws/en/oltp/projects/about) (scale-to-zero projects). Aidbox fetches short-lived tokens (1 hour expiry) from Databricks and caches them for 45 minutes (configurable via `BOX_DB_CREDENTIAL_REFRESH_INTERVAL`). When the cache expires, a fresh token is fetched on the next connection. HikariCP `max-lifetime` is set to match the cache TTL so existing connections rotate before tokens expire. SSL is enforced automatically. @@ -68,6 +68,7 @@ BOX_DB_DATABRICKS_HOST=https://your-workspace.cloud.databricks.com BOX_DB_DATABRICKS_PROVISIONED_INSTANCE_NAME= BOX_DB_DATABRICKS_CLIENT_ID= BOX_DB_DATABRICKS_CLIENT_SECRET= +BOX_DB_DATABRICKS_SCOPE=all-apis ``` {% endtab %} {% tab title="Autoscaling" %} @@ -83,6 +84,7 @@ BOX_DB_DATABRICKS_HOST=https://your-workspace.cloud.databricks.com BOX_DB_DATABRICKS_AUTOSCALE_ENDPOINT=projects//branches//endpoints/ BOX_DB_DATABRICKS_CLIENT_ID= BOX_DB_DATABRICKS_CLIENT_SECRET= +BOX_DB_DATABRICKS_SCOPE=all-apis ``` {% endtab %} {% endtabs %}