From 92c156e8ba5ce33eb8d1dd2026df1a1f16efb6c1 Mon Sep 17 00:00:00 2001
From: Gang Tao <gang@timeplus.io>
Date: Mon, 17 Aug 2026 15:49:30 -0700
Subject: [PATCH] =?UTF-8?q?docs(k8s):=20app-only=20=E2=80=94=20account=20f?=
 =?UTF-8?q?or=20the=20dedicated=20`tpk`=20database=20(#58/#59)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The k8s manifests (#56/#57) predate the change that moved all tpk streams
under a dedicated `tpk` database (#59). For app-only — which connects to an
externally-managed Timeplus Enterprise — the app now runs
`CREATE DATABASE IF NOT EXISTS tpk` on startup, so the pre-existing DB user
needs CREATE DATABASE (first run) plus read/write on that database. A
restricted user would otherwise fail at startup/ingest.

- app-only.yaml: header now states the app creates its own database on the
  existing server; add a `TIMEPLUS_DATABASE` env (default `tpk`) with the
  privilege note and the pre-create fallback for restricted users.
- deploy/k8s/README.md: add a "tpk database" note to the App-only section
  (CREATE DATABASE grant + pre-create SQL), and a TIMEPLUS_DATABASE row to the
  Configuration table. Notes that enterprise/allinone are unaffected (they
  provision a full-privilege tpk user).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XPzYZXxyTdj5G25KoujpHb
---
 deploy/k8s/README.md     | 17 +++++++++++++++++
 deploy/k8s/app-only.yaml | 13 ++++++++++++-
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/deploy/k8s/README.md b/deploy/k8s/README.md
index 5023fc5..8a9d8b2 100644
--- a/deploy/k8s/README.md
+++ b/deploy/k8s/README.md
@@ -99,6 +99,22 @@ Or, to remap the port, a headless Service + an `EndpointSlice` pointing at the
 DB's IP on its real port, exposed as `port: 8123`. The DB user in `TIMEPLUS_USER`
 must already exist on your timeplusd — `app-only.yaml` does not provision users.
 
+**The `tpk` database.** All tpk streams live under a dedicated database (`tpk`
+by default, `TIMEPLUS_DATABASE`), which the app creates on startup (`CREATE
+DATABASE IF NOT EXISTS`). Against a shared, externally-managed Timeplus this is
+the one extra grant to check: the `TIMEPLUS_USER` needs **CREATE DATABASE** (the
+first time) plus read/write on that database. If that user isn't allowed to
+create databases, pre-create it and grant access, then keep `TIMEPLUS_DATABASE`
+pointed at it:
+
+```sql
+CREATE DATABASE IF NOT EXISTS tpk;
+-- grant your tpk user read/write on tpk (per your Timeplus access model)
+```
+
+This only applies to app-only: `enterprise.yaml` and `allinone.yaml` provision a
+`tpk` user with full privileges, so database creation just works there.
+
 ## 3. Build the knowledge graph (ingest)
 
 The corpus is defined in the `repos.toml` baked into the image. Run ingest once
@@ -169,6 +185,7 @@ manifests, others stubbed as commented-out examples):
 | `TPK_AGENT_PROVIDER` / `TPK_AGENT_MODEL` | chat-agent backend + model |
 | `TPK_EXTRACTION_BACKEND` | `tpk ingest` semantic backend (`openai`\|`claude`\|`auto`) |
 | `TPK_DB_BACKEND` | `timeplusd` (Enterprise, mutable streams) or `proton` |
+| `TIMEPLUS_DATABASE` | database all tpk streams live under (default `tpk`; app-only: user needs CREATE DATABASE) |
 | `TPK_DB_WAIT_SECONDS` | how long the app waits for the DB on boot |
 
 ### Custom corpus (`repos.toml`) via ConfigMap
diff --git a/deploy/k8s/app-only.yaml b/deploy/k8s/app-only.yaml
index 3d109e8..d2440b0 100644
--- a/deploy/k8s/app-only.yaml
+++ b/deploy/k8s/app-only.yaml
@@ -1,7 +1,11 @@
 # App-only deployment: the tpk `app` (chat agent + web UI + ingest + MCP)
 # ALONE, connecting to a Timeplus Enterprise (timeplusd) that is ALREADY
 # running — deployed and managed separately (its own Helm chart / operator /
-# existing cluster). Nothing here provisions or runs a database.
+# existing cluster). This does not run a database *server*; but on startup the
+# app DOES create its own database (`tpk` by default) on that server and puts
+# all its streams there. So the DB user you point it at needs CREATE DATABASE
+# (first run only) plus read/write on that database. If the user is restricted,
+# pre-create the database and grant it, then set TIMEPLUS_DATABASE (see below).
 #
 # Use this when you already operate Timeplus Enterprise and just want to add the
 # knowledge agent against it. If you want tpk to bring up its own timeplusd too,
@@ -84,6 +88,13 @@ spec:
             # Enterprise timeplusd -> `timeplusd` backend (mutable streams).
             - name: TPK_DB_BACKEND
               value: "timeplusd"
+            # All tpk streams live under this database, which the app creates on
+            # startup (CREATE DATABASE IF NOT EXISTS) — so the DB user needs
+            # CREATE DATABASE the first time, plus read/write on it. If the user
+            # can't create databases, pre-create this one and grant access, or
+            # point at an existing database you control.
+            - name: TIMEPLUS_DATABASE
+              value: "tpk"
             # The DB is already up; a short connect-retry covers transient blips.
             - name: TPK_DB_WAIT_SECONDS
               value: "120"