From 925c3c072682f79864bc857aed6d9376c29c675f Mon Sep 17 00:00:00 2001
From: leaf corcoran <leafot@gmail.com>
Date: Tue, 8 Oct 2024 14:04:13 -0700
Subject: [PATCH] update database docs for index_name override on create_index

---
 docs/database.md | 50 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 40 insertions(+), 10 deletions(-)

diff --git a/docs/database.md b/docs/database.md
index 29d5c5f8..7a0e066a 100644
--- a/docs/database.md
+++ b/docs/database.md
@@ -922,14 +922,35 @@ DROP TABLE IF EXISTS "users";
 table, the rest of the arguments are the ordered columns that make up the
 index. Optionally the last argument can be a Lua table of options.
 
-There are two options `unique: BOOL`, `where: clause_string`.
+$options_table{
+  {
+    name = "unique",
+    description = [[
+      A boolean value indicating whether the index should be unique.
+    ]]
+  }, {
+    name = "where",
+    description = [[
+      A clause string that specifies conditions for the index. This string will be used literally in the query and is used to create partial indexes.
+    ]],
+    example = dual_code{[[
+      create_index("example_table", "example_column", { where = "some_column is not null" })
+    ]]}
+  }, {
+    name = "index_name",
+    description = [[
+      A string value that overrides the default generated index name.
+    ]]
+  }
+}
 
 `create_index` will also check if the index exists before attempting to create
 it. If the index exists then nothing will happen.
 
 Here are some example indexes:
 
-```lua
+$dual_code{
+lua=[[
 local create_index = schema.create_index
 
 create_index("users", "created_at")
@@ -937,9 +958,8 @@ create_index("users", "username", { unique = true })
 
 create_index("posts", "category", "title")
 create_index("uploads", "name", { where = "not deleted" })
-```
-
-```moon
+]],
+moon=[[
 import create_index from schema
 
 create_index "users", "created_at"
@@ -947,17 +967,27 @@ create_index "users", "username", unique: true
 
 create_index "posts", "category", "title"
 create_index "uploads", "name", where: "not deleted"
-```
+]]}
 
 This will generate the following SQL:
 
 ```sql
-CREATE INDEX ON "users" (created_at);
-CREATE UNIQUE INDEX ON "users" (username);
-CREATE INDEX ON "posts" (category, title);
-CREATE INDEX ON "uploads" (name) WHERE not deleted;
+CREATE INDEX "users_created_at_idx" ON "users" (created_at);
+CREATE UNIQUE INDEX "users_username_idx" ON "users" (username);
+CREATE INDEX "posts_category_title_idx" ON "posts" (category, title);
+CREATE INDEX "uploads_name_idx" ON "uploads" (name) WHERE not deleted;
 ```
 
+The index name is generated by concatenating the table name and the column
+names, separated by underscores, followed by the suffix "_idx". For example, an
+index on the "users" table with columns "username" and "email" would have a
+default index name of "users_username_email_idx". Special characters in column
+names are replaced with underscores to ensure the index name is valid.
+
+To override the default index name, you can use the `index_name` option when
+creating an index.
+
+
 #### `drop_index(table_name, col1, col2...)`
 
 Drops an index from a table. It calculates the name of the index from the table