Add docs

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__

docs/guides/index.md

@@ -10,4 +10,5 @@ pagination-classes
 custom-clis
 config-schema
 sql-tap
+sql-target
 ```

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
+```

docs/reference.rst

@@ -152,3 +152,4 @@ Other
     :template: class.rst
 
     connectors.sql.SQLToJSONSchema
+    connectors.sql.JSONSchemaToSQL

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."""