feat: Support conforming singer property names to target identifier constraints in SQL sinks

samples/sample_tap_hostile/__init__.py

@@ -0,0 +1,3 @@
+"""A sample tap for testing SQL target property name transformations."""
+
+from .hostile_tap import SampleTapHostile

samples/sample_tap_hostile/hostile_streams.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import random
+import string
+from typing import Iterable
+
+from singer_sdk import typing as th
+from singer_sdk.streams import Stream
+
+
+class HostilePropertyNamesStream(Stream):
+    """
+    A stream with property names that are not compatible as unescaped identifiers
+    in common DBMS systems.
+    """
+
+    name = "hostile_property_names_stream"
+    schema = th.PropertiesList(
+        th.Property("name with spaces", th.StringType),
+        th.Property("NameIsCamelCase", th.StringType),
+        th.Property("name-with-dashes", th.StringType),
+        th.Property("Name-with-Dashes-and-Mixed-cases", th.StringType),
+        th.Property("5name_starts_with_number", th.StringType),
+        th.Property("name_with_emoji_😈", th.StringType),
+    ).to_dict()
+
+    @staticmethod
+    def get_random_lowercase_string():
+        return "".join(random.choice(string.ascii_lowercase) for _ in range(10))
+
+    def get_records(self, context: dict | None) -> Iterable[dict | tuple[dict, dict]]:
+        return (
+            {
+                "name with spaces": self.get_random_lowercase_string(),
+                "NameIsCamelCase": self.get_random_lowercase_string(),
+                "name-with-dashes": self.get_random_lowercase_string(),
+                "Name-with-Dashes-and-Mixed-cases": self.get_random_lowercase_string(),
+                "5name_starts_with_number": self.get_random_lowercase_string(),
+                "name_with_emoji_😈": self.get_random_lowercase_string(),
+            }
+            for _ in range(10)
+        )

samples/sample_tap_hostile/hostile_tap.py

@@ -0,0 +1,24 @@
+"""A sample tap for testing SQL target property name transformations."""
+
+from typing import List
+
+from samples.sample_tap_hostile.hostile_streams import HostilePropertyNamesStream
+from singer_sdk import Stream, Tap
+from singer_sdk.typing import PropertiesList
+
+
+class SampleTapHostile(Tap):
+    """Sample tap for for testing SQL target property name transformations."""
+
+    name: str = "sample-tap-hostile"
+    config_jsonschema = PropertiesList().to_dict()
+
+    def discover_streams(self) -> List[Stream]:
+        """Return a list of discovered streams."""
+        return [
+            HostilePropertyNamesStream(tap=self),
+        ]
+
+
+if __name__ == "__main__":
+    SampleTapHostile.cli()

singer_sdk/__init__.py

@@ -4,13 +4,8 @@
 from singer_sdk.mapper_base import InlineMapper
 from singer_sdk.plugin_base import PluginBase
 from singer_sdk.sinks import BatchSink, RecordSink, Sink, SQLSink
-from singer_sdk.streams import (
-    GraphQLStream,
-    RESTStream,
-    SQLConnector,
-    SQLStream,
-    Stream,
-)
+from singer_sdk.sql import SQLConnector
+from singer_sdk.streams import GraphQLStream, RESTStream, SQLStream, Stream
 from singer_sdk.tap_base import SQLTap, Tap
 from singer_sdk.target_base import SQLTarget, Target
 

singer_sdk/helpers/_util.py

@@ -1,6 +1,7 @@
 """General helper functions, helper classes, and decorators."""
 
 import json
+import re
 from pathlib import Path, PurePath
 from typing import Any, Dict, Union, cast
 
@@ -25,3 +26,22 @@ def read_json_file(path: Union[PurePath, str]) -> Dict[str, Any]:
 def utc_now() -> pendulum.DateTime:
     """Return current time in UTC."""
     return pendulum.now(tz="UTC")
+
+
+def snakecase(string):
+    """Convert string into snake case.
+
+    Args:
+        string: String to convert.
+
+    Returns:
+        string: Snake cased string.
+    """
+    string = re.sub(r"[\-\.\s]", "_", str(string))
+    string = (
+        string[0].lower()
+        + re.sub(r"[A-Z]", lambda matched: f"_{matched.group(0).lower()}", string[1:])
+        if string
+        else string
+    )
+    return re.sub(r"_{2,}", "_", string).rstrip("_")

singer_sdk/sinks/core.py

@@ -71,7 +71,7 @@ def __init__(
         self.latest_state: dict | None = None
         self._draining_state: dict | None = None
         self.drained_state: dict | None = None
-        self.key_properties = key_properties or []
+        self._key_properties = key_properties or []
 
         # Tally counters
         self._total_records_written: int = 0
@@ -202,6 +202,15 @@ def datetime_error_treatment(self) -> DatetimeErrorTreatmentEnum:
         """
         return DatetimeErrorTreatmentEnum.ERROR
 
+    @property
+    def key_properties(self) -> list[str]:
+        """Return key properties.
+
+        Returns:
+            A list of stream key properties.
+        """
+        return self._key_properties
+
     # Record processing
 
     def _add_sdc_metadata_to_record(
@@ -423,6 +432,14 @@ def activate_version(self, new_version: int) -> None:
             "Ignoring."
         )
 
+    def setup(self) -> None:
+        """Perform any setup actions at the beginning of a Stream.
+
+        Setup is executed once per Sink instance, after instantiation. If a Schema
+        change is detected, a new Sink is instantiated and this method is called again.
+        """
+        pass
+
     def clean_up(self) -> None:
         """Perform any clean up actions required at end of a stream.