From 8254a1458d33eeba9716c2a00f5870da01c67298 Mon Sep 17 00:00:00 2001
From: Trezy <tre@trezy.com>
Date: Tue, 10 Mar 2026 11:28:47 -0500
Subject: [PATCH] docs: fix bugs in examples in documentation

---
 docs/guides/index-hooks.md                 | 13 ++++++++-----
 docs/guides/scripting.md                   | 12 +++++++++---
 docs/reference/scripts/algolia-sync.md     |  2 ++
 docs/reference/scripts/meilisearch-sync.md |  2 ++
 4 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/docs/guides/index-hooks.md b/docs/guides/index-hooks.md
index f4239a5..c834172 100644
--- a/docs/guides/index-hooks.md
+++ b/docs/guides/index-hooks.md
@@ -24,14 +24,17 @@ end
 
 The function is called once per record event. The return value controls what happens next:
 
-| Return value | Effect                                           |
-| ------------ | ------------------------------------------------ |
-| `nil`        | The record is **not** indexed (skipped entirely) |
-| A table      | That table is stored as the record instead       |
-| *(no hook)*  | The original record is stored as-is              |
+| Return value | Effect                                                      |
+| ------------ | ----------------------------------------------------------- |
+| `nil`        | The record is **not** indexed (skipped entirely)            |
+| A table      | That table is stored as the record instead                  |
+| `true`       | The original record is stored as-is                         |
+| *(no hook)*  | The original record is stored as-is                         |
 
 On **delete** events, returning `nil` skips the delete (the record stays in the database).
 
+**Important:** If your hook has side effects (e.g. syncing to a search index) but you want normal indexing to proceed, return `record` or `true` — not nothing. A missing return statement returns `nil`, which **skips indexing**.
+
 If the hook errors after all retries, the system **fails open** — the original record is stored and the failed event is dead-lettered for later inspection.
 
 ## Context globals
diff --git a/docs/guides/scripting.md b/docs/guides/scripting.md
index e0f9633..dc02673 100644
--- a/docs/guides/scripting.md
+++ b/docs/guides/scripting.md
@@ -8,7 +8,7 @@ Without Lua scripts, HappyView's query endpoints return raw records and procedur
 - Compose multi-record operations
 - Build entirely custom behavior
 
-Scripts are attached to query and procedure lexicons and run in a sandboxed Lua VM with access to the [Record API](#record-api), a [read-only database API](#database-api), an [HTTP client API](#http-api), a [JSON API](#json-api), and a set of [context globals](#context-globals).
+Scripts are attached to query and procedure lexicons and run in a sandboxed Lua VM with access to the [Record API](#record-api), a [database API](#database-api), an [HTTP client API](#http-api), a [JSON API](#json-api), and a set of [context globals](#context-globals).
 
 For scripts that react to record changes from the network (rather than XRPC requests), see [Index Hooks](index-hooks.md).
 
@@ -166,7 +166,7 @@ After a successful save, `_uri` and `_cid` are updated on the record instance.
 
 ## Database API
 
-The `db` table provides read-only access to indexed records. Available in both queries and procedures.
+The `db` table provides access to the database. Available in both queries and procedures.
 
 ### db.query
 
@@ -236,9 +236,10 @@ local n = db.count("xyz.statusphere.status", "did:plc:abc")  -- filter by DID
 
 ### db.raw
 
-Run a raw SQL query against the database. Only `SELECT` statements are allowed.
+Run a raw SQL query against the database. Supports `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and `CREATE TABLE` statements.
 
 ```lua
+-- Read query
 local rows = db.raw(
   "SELECT uri, did, record FROM records WHERE collection = $1 AND did = $2 LIMIT $3",
   { "xyz.statusphere.status", "did:plc:abc", 10 }
@@ -247,6 +248,11 @@ local rows = db.raw(
 for _, row in ipairs(rows) do
   -- row.uri, row.did, row.record (JSONB is returned as a Lua table)
 end
+
+-- Write query (returns affected rows, if any)
+db.raw("CREATE TABLE IF NOT EXISTS my_table (id TEXT PRIMARY KEY, value TEXT NOT NULL)")
+db.raw("INSERT INTO my_table (id, value) VALUES ($1, $2) ON CONFLICT (id) DO UPDATE SET value = $2",
+  { "key1", "hello" })
 ```
 
 Parameters are passed as an array and bound to `$1`, `$2`, etc. Supported parameter types: strings, integers, numbers, booleans, and nil.
diff --git a/docs/reference/scripts/algolia-sync.md b/docs/reference/scripts/algolia-sync.md
index a0a39f6..80c9d99 100644
--- a/docs/reference/scripts/algolia-sync.md
+++ b/docs/reference/scripts/algolia-sync.md
@@ -27,6 +27,8 @@ function handle()
       })
     })
   end
+
+  return record
 end
 ```
 
diff --git a/docs/reference/scripts/meilisearch-sync.md b/docs/reference/scripts/meilisearch-sync.md
index 7ec9b97..908e3bd 100644
--- a/docs/reference/scripts/meilisearch-sync.md
+++ b/docs/reference/scripts/meilisearch-sync.md
@@ -28,6 +28,8 @@ function handle()
       }))
     })
   end
+
+  return record
 end
 ```
 
-- 
2.51.2