Merge branch 'main' into 1695_bug_fix_datetype_stream_maps

.github/workflows/release.yml

@@ -65,7 +65,7 @@ jobs:
         name: Packages
         path: dist
     - name: Publish
-      uses: pypa/[email protected].0
+      uses: pypa/[email protected].1
 
   upload-to-release:
     name: Upload files to release

.github/workflows/version_bump.yml

@@ -84,7 +84,7 @@ jobs:
 
     - name: Create Pull Request
       if: ${{ github.event.inputs.dry_run == 'false' }}
-      uses: peter-evans/create-pull-request@v6
+      uses: peter-evans/create-pull-request@v7
       id: create-pull-request
       with:
         token: ${{ secrets.MELTYBOT_GITHUB_AUTH_TOKEN }}

.pre-commit-config.yaml

@@ -50,7 +50,7 @@ repos:
   - id: check-readthedocs
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.6.3
+  rev: v0.6.4
   hooks:
   - id: ruff
     args: [--fix, --exit-non-zero-on-fix, --show-fixes]

cookiecutter/mapper-template/{{cookiecutter.mapper_id}}/.pre-commit-config.yaml

@@ -18,19 +18,19 @@ repos:
   - id: trailing-whitespace
 
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.29.1
+  rev: 0.29.2
   hooks:
   - id: check-dependabot
   - id: check-github-workflows
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.5.6
+  rev: v0.6.4
   hooks:
   - id: ruff
     args: [--fix, --exit-non-zero-on-fix, --show-fixes]
   - id: ruff-format
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.11.1
+  rev: v1.11.2
   hooks:
   - id: mypy

cookiecutter/tap-template/{{cookiecutter.tap_id}}/.pre-commit-config.yaml

@@ -18,20 +18,20 @@ repos:
   - id: trailing-whitespace
 
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.29.1
+  rev: 0.29.2
   hooks:
   - id: check-dependabot
   - id: check-github-workflows
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.5.6
+  rev: v0.6.4
   hooks:
   - id: ruff
     args: [--fix, --exit-non-zero-on-fix, --show-fixes]
   - id: ruff-format
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.11.1
+  rev: v1.11.2
   hooks:
   - id: mypy
     additional_dependencies:

cookiecutter/target-template/{{cookiecutter.target_id}}/.pre-commit-config.yaml

@@ -18,20 +18,20 @@ repos:
   - id: trailing-whitespace
 
 - repo: https://github.com/python-jsonschema/check-jsonschema
-  rev: 0.29.1
+  rev: 0.29.2
   hooks:
   - id: check-dependabot
   - id: check-github-workflows
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.5.6
+  rev: v0.6.4
   hooks:
   - id: ruff
     args: [--fix, --exit-non-zero-on-fix, --show-fixes]
   - id: ruff-format
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.11.1
+  rev: v1.11.2
   hooks:
   - id: mypy
     additional_dependencies:

docs/classes/singer_sdk.connectors.sql.SQLToJSONSchema.rst

@@ -0,0 +1,8 @@
+singer_sdk.connectors.sql.SQLToJSONSchema
+=========================================
+
+.. currentmodule:: singer_sdk.connectors.sql
+
+.. autoclass:: SQLToJSONSchema
+    :members:
+    :special-members: __init__, __call__

docs/conf.py

@@ -158,6 +158,10 @@
         "https://json-schema.org/understanding-json-schema/reference/%s",
         "%s",
     ),
+    "column_type": (
+        "https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.%s",
+        "%s",
+    ),
 }
 
 # -- Options for intersphinx -----------------------------------------------------------

docs/guides/index.md

@@ -9,4 +9,5 @@ porting
 pagination-classes
 custom-clis
 config-schema
+sql-tap
 ```

docs/guides/sql-tap.md

@@ -0,0 +1,58 @@
+# Building SQL taps
+
+## Mapping SQL types to JSON Schema
+
+Starting with version `0.41.0`, the Meltano Singer SDK provides a clean way to map SQL types to JSON Schema. This is useful when the SQL dialect you are using has custom types that need to be mapped accordingly to JSON Schema.
+
+### Default type mapping
+
+The Singer SDK automatically handles the most common SQLAlchemy column types, using [`functools.singledispatchmethod`](inv:python:py:class:#functools.singledispatchmethod) to process each type. See the [`SQLToJSONSchema`](connectors.sql.SQLToJSONSchema) reference documentation for details.
+
+### Custom type mapping
+
+If the class above doesn't cover all the types supported by the SQLAlchemy dialect in your tap, you can subclass it and override or extend with a new method for the type you need to support:
+
+```python
+import functools
+
+from sqlalchemy import Numeric
+from singer_sdk import typing as th
+from singer_sdk.connectors import SQLConnector
+from singer_sdk.connectors.sql import SQLToJSONSchema
+
+from my_sqlalchemy_dialect import VectorType
+
+
+class CustomSQLToJSONSchema(SQLToJSONSchema):
+    @SQLToJSONSchema.to_jsonschema.register
+    def custom_number_to_jsonschema(self, column_type: Numeric):
+        """Override the default mapping for NUMERIC columns.
+
+        For example, a scale of 4 translates to a multipleOf 0.0001.
+        """
+        return {"type": ["number"], "multipleOf": 10**-column_type.scale}
+
+    @SQLToJSONSchema.to_jsonschema.register(VectorType)
+    def vector_to_json_schema(self, column_type):
+        """Custom vector to JSON schema."""
+        return th.ArrayType(th.NumberType()).to_dict()
+```
+
+````{tip}
+You can also use a type annotation to specify the type of the column when registering a new method:
+
+```python
+@SQLToJSONSchema.to_jsonschema.register
+def vector_to_json_schema(self, column_type: VectorType):
+    return th.ArrayType(th.NumberType()).to_dict()
+```
+````
+
+Then, you need to use your custom type mapping in your connector:
+
+```python
+class MyConnector(SQLConnector):
+    @functools.cached_property
+    def sql_to_jsonschema(self):
+        return CustomSQLToJSONSchema()
+```

docs/reference.rst

@@ -143,3 +143,12 @@ Batch
 
     batch.BaseBatcher
     batch.JSONLinesBatcher
+
+Other
+-----
+
+.. autosummary::
+    :toctree: classes
+    :template: class.rst
+
+    connectors.sql.SQLToJSONSchema