From 7bcfab495db6a886b1212128a4363800b9d6e811 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@crate.io>
Date: Thu, 28 Sep 2023 20:52:46 +0200
Subject: [PATCH] Documentation: Add section about using `gen_random_text_uuid`
 as auto-PK

---
 docs/sqlalchemy.rst | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/sqlalchemy.rst b/docs/sqlalchemy.rst
index c31396ab..8c399a5c 100644
--- a/docs/sqlalchemy.rst
+++ b/docs/sqlalchemy.rst
@@ -300,6 +300,41 @@ would translate into the following declarative model:
     >>> log.id
     ...
 
+
+Auto-generated primary key
+..........................
+
+CrateDB 4.5.0 added the :ref:`gen_random_text_uuid() <crate-reference:scalar-gen_random_text_uuid>`
+scalar function, which can also be used within an SQL DDL statement, in order to automatically
+assign random identifiers to newly inserted records on the server side.
+
+In this spirit, it is suitable to be used as a ``PRIMARY KEY`` constraint for SQLAlchemy.
+
+A table schema like this
+
+.. code-block:: sql
+
+   CREATE TABLE "doc"."items" (
+     "id" STRING DEFAULT gen_random_text_uuid() NOT NULL PRIMARY KEY,
+     "name" STRING
+   )
+
+would translate into the following declarative model:
+
+    >>> class Item(Base):
+    ...
+    ...     __tablename__ = 'items'
+    ...
+    ...     id = sa.Column("id", sa.String, server_default=func.gen_random_text_uuid(), primary_key=True)
+    ...     name = sa.Column("name", sa.String)
+
+    >>> item = Item(name="Foobar")
+    >>> session.add(item)
+    >>> session.commit()
+    >>> item.id
+    ...
+
+
 .. _using-extension-types:
 
 Extension types