From 05ae3f1c605a4a7a040a93e47e783a66220cef1f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edgar=20Ram=C3=ADrez-Mondrag=C3=B3n?= <edgarrm358@gmail.com>
Date: Fri, 25 Oct 2024 11:45:00 -0600
Subject: [PATCH] Add docs

---
 ...ger_sdk.connectors.sql.JSONSchemaToSQL.rst |  8 +++
 docs/guides/index.md                          |  1 +
 docs/guides/sql-target.md                     | 52 +++++++++++++++++++
 docs/reference.rst                            |  1 +
 singer_sdk/connectors/sql.py                  |  7 ++-
 5 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 docs/classes/singer_sdk.connectors.sql.JSONSchemaToSQL.rst
 create mode 100644 docs/guides/sql-target.md

diff --git a/docs/classes/singer_sdk.connectors.sql.JSONSchemaToSQL.rst b/docs/classes/singer_sdk.connectors.sql.JSONSchemaToSQL.rst
new file mode 100644
index 000000000..82ad1c544
--- /dev/null
+++ b/docs/classes/singer_sdk.connectors.sql.JSONSchemaToSQL.rst
@@ -0,0 +1,8 @@
+singer_sdk.connectors.sql.JSONSchemaToSQL
+=========================================
+
+.. currentmodule:: singer_sdk.connectors.sql
+
+.. autoclass:: JSONSchemaToSQL
+    :members:
+    :special-members: __init__, __call__
\ No newline at end of file
diff --git a/docs/guides/index.md b/docs/guides/index.md
index 60a94e8d5..f754908a2 100644
--- a/docs/guides/index.md
+++ b/docs/guides/index.md
@@ -10,4 +10,5 @@ pagination-classes
 custom-clis
 config-schema
 sql-tap
+sql-target
 ```
diff --git a/docs/guides/sql-target.md b/docs/guides/sql-target.md
new file mode 100644
index 000000000..b6cdb5bb5
--- /dev/null
+++ b/docs/guides/sql-target.md
@@ -0,0 +1,52 @@
+# Building SQL targets
+
+## Mapping JSON Schema to SQL types
+
+Starting with version `0.42.0`, the Meltano Singer SDK provides a clean way to map JSON Schema to SQL types. This is useful when the SQL dialect needs to do special handling for certain JSON Schema types.
+
+### Custom JSON Schema mapping
+
+If the default [`JSONSchemaToSQL`](connectors.sql.JSONSchemaToSQL) instance doesn't cover all the types supported by the SQLAlchemy dialect in your target, you can override the {attr}`SQLConnector.jsonschema_to_sql <singer_sdk.SQLConnector.jsonschema_to_sql>` property and register a new type handler for the type you need to support:
+
+```python
+import functools
+
+import sqlalchemy as sa
+from singer_sdk import typing as th
+from singer_sdk.connectors import JSONSchemaToSQL, SQLConnector
+
+from my_sqlalchemy_dialect import VectorType
+
+
+def custom_array_to_sql(jsonschema: dict) -> VectorType | sa.types.ARRAY:
+    """Custom mapping for arrays of numbers."""
+    if items := jsonschema.get("items"):
+        if items.get("type") == "number":
+            return VectorType()
+
+    return sa.types.VARCHAR()
+
+
+class MyConnector(SQLConnector):
+    @functools.cached_property
+    def jsonschema_to_sql(self):
+        to_sql = JSONSchemaToSQL()
+        to_sql.register_type_handler("array", custom_array_to_sql)
+        return to_sql
+```
+
+### Custom string format mapping
+
+You can also register a new format handler for custom string formats:
+
+```python
+from my_sqlalchemy_dialect import URI
+
+
+class MyConnector(SQLConnector):
+    @functools.cached_property
+    def jsonschema_to_sql(self):
+        to_sql = JSONSchemaToSQL()
+        to_sql.register_format_handler("uri", URI)
+        return to_sql
+```
diff --git a/docs/reference.rst b/docs/reference.rst
index eeaf1b53a..71e0d6ddb 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -152,3 +152,4 @@ Other
     :template: class.rst
 
     connectors.sql.SQLToJSONSchema
+    connectors.sql.JSONSchemaToSQL
diff --git a/singer_sdk/connectors/sql.py b/singer_sdk/connectors/sql.py
index 4687e888c..0aa09e770 100644
--- a/singer_sdk/connectors/sql.py
+++ b/singer_sdk/connectors/sql.py
@@ -204,7 +204,12 @@ def boolean_to_jsonschema(self, column_type: sa.types.Boolean) -> dict:  # noqa:
 
 
 class JSONSchemaToSQL:
-    """A configurable mapper for converting JSON Schema types to SQLAlchemy types."""
+    """A configurable mapper for converting JSON Schema types to SQLAlchemy types.
+
+    This class provides a mapping from JSON Schema types to SQLAlchemy types.
+
+    .. versionadded:: 0.42.0
+    """
 
     def __init__(self) -> None:
         """Initialize the mapper with default type mappings."""