databricks-sqlalchemy 1.0.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

databricks/sqlalchemy/test_local/test_parsing.py

@@ -0,0 +1,160 @@
+import pytest
+from databricks.sqlalchemy._parse import (
+    extract_identifiers_from_string,
+    extract_identifier_groups_from_string,
+    extract_three_level_identifier_from_constraint_string,
+    build_fk_dict,
+    build_pk_dict,
+    match_dte_rows_by_value,
+    get_comment_from_dte_output,
+    DatabricksSqlAlchemyParseException,
+)
+
+
+# These are outputs from DESCRIBE TABLE EXTENDED
+@pytest.mark.parametrize(
+    "input, expected",
+    [
+        ("PRIMARY KEY (`pk1`, `pk2`)", ["pk1", "pk2"]),
+        ("PRIMARY KEY (`a`, `b`, `c`)", ["a", "b", "c"]),
+        ("PRIMARY KEY (`name`, `id`, `attr`)", ["name", "id", "attr"]),
+    ],
+)
+def test_extract_identifiers(input, expected):
+    assert (
+        extract_identifiers_from_string(input) == expected
+    ), "Failed to extract identifiers from string"
+
+
+@pytest.mark.parametrize(
+    "input, expected",
+    [
+        (
+            "FOREIGN KEY (`pname`, `pid`, `pattr`) REFERENCES `main`.`pysql_sqlalchemy`.`tb1` (`name`, `id`, `attr`)",
+            [
+                "(`pname`, `pid`, `pattr`)",
+                "(`name`, `id`, `attr`)",
+            ],
+        )
+    ],
+)
+def test_extract_identifer_batches(input, expected):
+    assert (
+        extract_identifier_groups_from_string(input) == expected
+    ), "Failed to extract identifier groups from string"
+
+
+def test_extract_3l_namespace_from_constraint_string():
+    input = "FOREIGN KEY (`parent_user_id`) REFERENCES `main`.`pysql_dialect_compliance`.`users` (`user_id`)"
+    expected = {
+        "catalog": "main",
+        "schema": "pysql_dialect_compliance",
+        "table": "users",
+    }
+
+    assert (
+        extract_three_level_identifier_from_constraint_string(input) == expected
+    ), "Failed to extract 3L namespace from constraint string"
+
+
+def test_extract_3l_namespace_from_bad_constraint_string():
+    input = "FOREIGN KEY (`parent_user_id`) REFERENCES `pysql_dialect_compliance`.`users` (`user_id`)"
+
+    with pytest.raises(DatabricksSqlAlchemyParseException):
+        extract_three_level_identifier_from_constraint_string(input)
+
+
+@pytest.mark.parametrize("tschema", [None, "some_schema"])
+def test_build_fk_dict(tschema):
+    fk_constraint_string = "FOREIGN KEY (`parent_user_id`) REFERENCES `main`.`some_schema`.`users` (`user_id`)"
+
+    result = build_fk_dict("some_fk_name", fk_constraint_string, schema_name=tschema)
+
+    assert result == {
+        "name": "some_fk_name",
+        "constrained_columns": ["parent_user_id"],
+        "referred_schema": tschema,
+        "referred_table": "users",
+        "referred_columns": ["user_id"],
+    }
+
+
+def test_build_pk_dict():
+    pk_constraint_string = "PRIMARY KEY (`id`, `name`, `email_address`)"
+    pk_name = "pk1"
+
+    result = build_pk_dict(pk_name, pk_constraint_string)
+
+    assert result == {
+        "constrained_columns": ["id", "name", "email_address"],
+        "name": "pk1",
+    }
+
+
+# This is a real example of the output from DESCRIBE TABLE EXTENDED as of 15 October 2023
+RAW_SAMPLE_DTE_OUTPUT = [
+    ["id", "int"],
+    ["name", "string"],
+    ["", ""],
+    ["# Detailed Table Information", ""],
+    ["Catalog", "main"],
+    ["Database", "pysql_sqlalchemy"],
+    ["Table", "exampleexampleexample"],
+    ["Created Time", "Sun Oct 15 21:12:54 UTC 2023"],
+    ["Last Access", "UNKNOWN"],
+    ["Created By", "Spark "],
+    ["Type", "MANAGED"],
+    ["Location", "s3://us-west-2-****-/19a85dee-****/tables/ccb7***"],
+    ["Provider", "delta"],
+    ["Comment", "some comment"],
+    ["Owner", "some.user@example.com"],
+    ["Is_managed_location", "true"],
+    ["Predictive Optimization", "ENABLE (inherited from CATALOG main)"],
+    [
+        "Table Properties",
+        "[delta.checkpoint.writeStatsAsJson=false,delta.checkpoint.writeStatsAsStruct=true,delta.minReaderVersion=1,delta.minWriterVersion=2]",
+    ],
+    ["", ""],
+    ["# Constraints", ""],
+    ["exampleexampleexample_pk", "PRIMARY KEY (`id`)"],
+    [
+        "exampleexampleexample_fk",
+        "FOREIGN KEY (`parent_user_id`) REFERENCES `main`.`pysql_dialect_compliance`.`users` (`user_id`)",
+    ],
+]
+
+FMT_SAMPLE_DT_OUTPUT = [
+    {"col_name": i[0], "data_type": i[1]} for i in RAW_SAMPLE_DTE_OUTPUT
+]
+
+
+@pytest.mark.parametrize(
+    "match, output",
+    [
+        (
+            "PRIMARY KEY",
+            [
+                {
+                    "col_name": "exampleexampleexample_pk",
+                    "data_type": "PRIMARY KEY (`id`)",
+                }
+            ],
+        ),
+        (
+            "FOREIGN KEY",
+            [
+                {
+                    "col_name": "exampleexampleexample_fk",
+                    "data_type": "FOREIGN KEY (`parent_user_id`) REFERENCES `main`.`pysql_dialect_compliance`.`users` (`user_id`)",
+                }
+            ],
+        ),
+    ],
+)
+def test_filter_dict_by_value(match, output):
+    result = match_dte_rows_by_value(FMT_SAMPLE_DT_OUTPUT, match)
+    assert result == output
+
+
+def test_get_comment_from_dte_output():
+    assert get_comment_from_dte_output(FMT_SAMPLE_DT_OUTPUT) == "some comment"

databricks/sqlalchemy/test_local/test_types.py

@@ -0,0 +1,161 @@
+import enum
+
+import pytest
+import sqlalchemy
+
+from databricks.sqlalchemy.base import DatabricksDialect
+from databricks.sqlalchemy._types import TINYINT, TIMESTAMP, TIMESTAMP_NTZ
+
+
+class DatabricksDataType(enum.Enum):
+    """https://docs.databricks.com/en/sql/language-manual/sql-ref-datatypes.html"""
+
+    BIGINT = enum.auto()
+    BINARY = enum.auto()
+    BOOLEAN = enum.auto()
+    DATE = enum.auto()
+    DECIMAL = enum.auto()
+    DOUBLE = enum.auto()
+    FLOAT = enum.auto()
+    INT = enum.auto()
+    INTERVAL = enum.auto()
+    VOID = enum.auto()
+    SMALLINT = enum.auto()
+    STRING = enum.auto()
+    TIMESTAMP = enum.auto()
+    TIMESTAMP_NTZ = enum.auto()
+    TINYINT = enum.auto()
+    ARRAY = enum.auto()
+    MAP = enum.auto()
+    STRUCT = enum.auto()
+
+
+# Defines the way that SQLAlchemy CamelCase types are compiled into Databricks SQL types.
+# Note: I wish I could define this within the TestCamelCaseTypesCompilation class, but pytest doesn't like that.
+camel_case_type_map = {
+    sqlalchemy.types.BigInteger: DatabricksDataType.BIGINT,
+    sqlalchemy.types.LargeBinary: DatabricksDataType.BINARY,
+    sqlalchemy.types.Boolean: DatabricksDataType.BOOLEAN,
+    sqlalchemy.types.Date: DatabricksDataType.DATE,
+    sqlalchemy.types.DateTime: DatabricksDataType.TIMESTAMP_NTZ,
+    sqlalchemy.types.Double: DatabricksDataType.DOUBLE,
+    sqlalchemy.types.Enum: DatabricksDataType.STRING,
+    sqlalchemy.types.Float: DatabricksDataType.FLOAT,
+    sqlalchemy.types.Integer: DatabricksDataType.INT,
+    sqlalchemy.types.Interval: DatabricksDataType.TIMESTAMP_NTZ,
+    sqlalchemy.types.Numeric: DatabricksDataType.DECIMAL,
+    sqlalchemy.types.PickleType: DatabricksDataType.BINARY,
+    sqlalchemy.types.SmallInteger: DatabricksDataType.SMALLINT,
+    sqlalchemy.types.String: DatabricksDataType.STRING,
+    sqlalchemy.types.Text: DatabricksDataType.STRING,
+    sqlalchemy.types.Time: DatabricksDataType.STRING,
+    sqlalchemy.types.Unicode: DatabricksDataType.STRING,
+    sqlalchemy.types.UnicodeText: DatabricksDataType.STRING,
+    sqlalchemy.types.Uuid: DatabricksDataType.STRING,
+}
+
+
+def dict_as_tuple_list(d: dict):
+    """Return a list of [(key, value), ...] from a dictionary."""
+    return [(key, value) for key, value in d.items()]
+
+
+class CompilationTestBase:
+    dialect = DatabricksDialect()
+
+    def _assert_compiled_value(
+        self, type_: sqlalchemy.types.TypeEngine, expected: DatabricksDataType
+    ):
+        """Assert that when type_ is compiled for the databricks dialect, it renders the DatabricksDataType name.
+
+        This method initialises the type_ with no arguments.
+        """
+        compiled_result = type_().compile(dialect=self.dialect)  # type: ignore
+        assert compiled_result == expected.name
+
+    def _assert_compiled_value_explicit(
+        self, type_: sqlalchemy.types.TypeEngine, expected: str
+    ):
+        """Assert that when type_ is compiled for the databricks dialect, it renders the expected string.
+
+        This method expects an initialised type_ so that we can test how a TypeEngine created with arguments
+        is compiled.
+        """
+        compiled_result = type_.compile(dialect=self.dialect)
+        assert compiled_result == expected
+
+
+class TestCamelCaseTypesCompilation(CompilationTestBase):
+    """Per the sqlalchemy documentation[^1] here, the camel case members of sqlalchemy.types are
+    are expected to work across all dialects. These tests verify that the types compile into valid
+    Databricks SQL type strings. For example, the sqlalchemy.types.Integer() should compile as "INT".
+
+    Truly custom types like STRUCT (notice the uppercase) are not expected to work across all dialects.
+    We test these separately.
+
+    Note that these tests have to do with type **name** compiliation. Which is separate from actually
+    mapping values between Python and Databricks.
+
+    Note: SchemaType and MatchType are not tested because it's not used in table definitions
+
+    [1]: https://docs.sqlalchemy.org/en/20/core/type_basics.html#generic-camelcase-types
+    """
+
+    @pytest.mark.parametrize("type_, expected", dict_as_tuple_list(camel_case_type_map))
+    def test_bare_camel_case_types_compile(self, type_, expected):
+        self._assert_compiled_value(type_, expected)
+
+    def test_numeric_renders_as_decimal_with_precision(self):
+        self._assert_compiled_value_explicit(
+            sqlalchemy.types.Numeric(10), "DECIMAL(10)"
+        )
+
+    def test_numeric_renders_as_decimal_with_precision_and_scale(self):
+        self._assert_compiled_value_explicit(
+            sqlalchemy.types.Numeric(10, 2), "DECIMAL(10, 2)"
+        )
+
+
+uppercase_type_map = {
+    sqlalchemy.types.ARRAY: DatabricksDataType.ARRAY,
+    sqlalchemy.types.BIGINT: DatabricksDataType.BIGINT,
+    sqlalchemy.types.BINARY: DatabricksDataType.BINARY,
+    sqlalchemy.types.BOOLEAN: DatabricksDataType.BOOLEAN,
+    sqlalchemy.types.DATE: DatabricksDataType.DATE,
+    sqlalchemy.types.DECIMAL: DatabricksDataType.DECIMAL,
+    sqlalchemy.types.DOUBLE: DatabricksDataType.DOUBLE,
+    sqlalchemy.types.FLOAT: DatabricksDataType.FLOAT,
+    sqlalchemy.types.INT: DatabricksDataType.INT,
+    sqlalchemy.types.SMALLINT: DatabricksDataType.SMALLINT,
+    sqlalchemy.types.TIMESTAMP: DatabricksDataType.TIMESTAMP,
+    TINYINT: DatabricksDataType.TINYINT,
+    TIMESTAMP: DatabricksDataType.TIMESTAMP,
+    TIMESTAMP_NTZ: DatabricksDataType.TIMESTAMP_NTZ,
+}
+
+
+class TestUppercaseTypesCompilation(CompilationTestBase):
+    """Per the sqlalchemy documentation[^1], uppercase types are considered to be specific to some
+    database backends. These tests verify that the types compile into valid Databricks SQL type strings.
+
+    [1]: https://docs.sqlalchemy.org/en/20/core/type_basics.html#backend-specific-uppercase-datatypes
+    """
+
+    @pytest.mark.parametrize("type_, expected", dict_as_tuple_list(uppercase_type_map))
+    def test_bare_uppercase_types_compile(self, type_, expected):
+        if isinstance(type_, type(sqlalchemy.types.ARRAY)):
+            # ARRAY cannot be initialised without passing an item definition so we test separately
+            # I preserve it in the uppercase_type_map for clarity
+            assert True
+        else:
+            self._assert_compiled_value(type_, expected)
+
+    def test_array_string_renders_as_array_of_string(self):
+        """SQLAlchemy's ARRAY type requires an item definition. And their docs indicate that they've only tested
+        it with Postgres since that's the only first-class dialect with support for ARRAY.
+
+        https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.ARRAY
+        """
+        self._assert_compiled_value_explicit(
+            sqlalchemy.types.ARRAY(sqlalchemy.types.String), "ARRAY<STRING>"
+        )

{databricks_sqlalchemy-1.0.1.dist-info → databricks_sqlalchemy-2.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: databricks-sqlalchemy
-Version: 1.0.1
+Version: 2.0.0
 Summary: Databricks SQLAlchemy plugin for Python
 License: Apache-2.0
 Author: Databricks
@@ -14,14 +14,17 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: databricks_sql_connector_core (>=4.0.0)
-Requires-Dist: sqlalchemy (>=1.3.24,<2.0.0)
+Requires-Dist: sqlalchemy (>=2.0.21)
 Project-URL: Bug Tracker, https://github.com/databricks/databricks-sqlalchemy/issues
 Project-URL: Homepage, https://github.com/databricks/databricks-sqlalchemy
 Description-Content-Type: text/markdown
 
-## Databricks dialect for SQLALchemy 1.0
+## Databricks dialect for SQLALchemy 2.0
 
-The Databricks dialect for SQLAlchemy serves as bridge between [SQLAlchemy](https://www.sqlalchemy.org/) and the Databricks SQL Python driver. A working example demonstrating usage can be found in `example.py`.
+The Databricks dialect for SQLAlchemy serves as bridge between [SQLAlchemy](https://www.sqlalchemy.org/) and the Databricks SQL Python driver. A working example demonstrating usage can be found in `examples/sqlalchemy.py`.
+
+## Usage with SQLAlchemy <= 2.0
+A SQLAlchemy 1.4 compatible dialect was first released in connector [version 2.4](https://github.com/databricks/databricks-sql-python/releases/tag/v2.4.0). Support for SQLAlchemy 1.4 was dropped from the dialect as part of `databricks-sql-connector==3.0.0`. To continue using the dialect with SQLAlchemy 1.x, you can use `databricks-sql-connector^2.4.0`.
 
 
 ## Installation
@@ -29,7 +32,7 @@ The Databricks dialect for SQLAlchemy serves as bridge between [SQLAlchemy](http
 To install the dialect and its dependencies:
 
 ```shell
-pip install databricks-sqlalchemy~=1.0
+pip install databricks-sqlalchemy
 ```
 
 If you also plan to use `alembic` you can alternatively run:
@@ -62,45 +65,41 @@ access_token = os.getenv("DATABRICKS_TOKEN")
 catalog = os.getenv("DATABRICKS_CATALOG")
 schema = os.getenv("DATABRICKS_SCHEMA")
 
-if sqlalchemy.__version__.startswith("1.3"):
-	# SQLAlchemy 1.3.x fails to parse the http_path, catalog, and schema from our connection string
-	# Pass these in as connect_args instead
-
-	conn_string = f"databricks://token:{access_token}@{host}"
-	connect_args = dict(catalog=catalog, schema=schema, http_path=http_path)
-	all_connect_args = {**extra_connect_args, **connect_args}
-	engine = create_engine(conn_string, connect_args=all_connect_args)
-else:
-	engine = create_engine(
-		f"databricks://token:{access_token}@{host}?http_path={http_path}&catalog={catalog}&schema={schema}",
-		connect_args=extra_connect_args,
-	)
-
+engine = create_engine(
+    f"databricks://token:{access_token}@{host}?http_path={http_path}&catalog={catalog}&schema={schema}"
+    )
 ```
 
 ## Types
 
-The [SQLAlchemy type hierarchy](https://docs.sqlalchemy.org/en/13/core/type_basics.html) contains backend-agnostic type implementations (represented in CamelCase) and backend-specific types (represented in UPPERCASE). The majority of SQLAlchemy's [CamelCase](https://docs.sqlalchemy.org/en/13/core/type_basics.html#the-camelcase-datatypes) types are supported. This means that a SQLAlchemy application using these types should "just work" with Databricks.
+The [SQLAlchemy type hierarchy](https://docs.sqlalchemy.org/en/20/core/type_basics.html) contains backend-agnostic type implementations (represented in CamelCase) and backend-specific types (represented in UPPERCASE). The majority of SQLAlchemy's [CamelCase](https://docs.sqlalchemy.org/en/20/core/type_basics.html#the-camelcase-datatypes) types are supported. This means that a SQLAlchemy application using these types should "just work" with Databricks.
 
 |SQLAlchemy Type|Databricks SQL Type|
 |-|-|
-[`BigInteger`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.BigInteger)| [`BIGINT`](https://docs.databricks.com/en/sql/language-manual/data-types/bigint-type.html)
-[`LargeBinary`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.LargeBinary)| (not supported)|
-[`Boolean`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Boolean)| [`BOOLEAN`](https://docs.databricks.com/en/sql/language-manual/data-types/boolean-type.html)
-[`Date`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Date)| [`DATE`](https://docs.databricks.com/en/sql/language-manual/data-types/date-type.html)
-[`DateTime`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.DateTime)| [`TIMESTAMP_NTZ`](https://docs.databricks.com/en/sql/language-manual/data-types/timestamp-ntz-type.html)|
-[`Enum`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Enum)| (not supported)|
-[`Float`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Float)| [`FLOAT`](https://docs.databricks.com/en/sql/language-manual/data-types/float-type.html)
-[`Integer`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Integer)| [`INT`](https://docs.databricks.com/en/sql/language-manual/data-types/int-type.html)
-[`Numeric`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Numeric)| [`DECIMAL`](https://docs.databricks.com/en/sql/language-manual/data-types/decimal-type.html)|
-[`PickleType`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.PickleType)| (not supported)|
-[`SmallInteger`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.SmallInteger)| [`SMALLINT`](https://docs.databricks.com/en/sql/language-manual/data-types/smallint-type.html)
-[`String`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.String)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
-[`Text`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Text)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
-[`Time`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Time)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
-[`Unicode`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Unicode)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
-[`UnicodeText`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.UnicodeText)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
-[`Uuid`](https://docs.sqlalchemy.org/en/13/core/type_basics.html#sqlalchemy.types.Uuid)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)
+[`BigInteger`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.BigInteger)| [`BIGINT`](https://docs.databricks.com/en/sql/language-manual/data-types/bigint-type.html)
+[`LargeBinary`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.LargeBinary)| (not supported)|
+[`Boolean`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Boolean)| [`BOOLEAN`](https://docs.databricks.com/en/sql/language-manual/data-types/boolean-type.html)
+[`Date`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Date)| [`DATE`](https://docs.databricks.com/en/sql/language-manual/data-types/date-type.html)
+[`DateTime`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.DateTime)| [`TIMESTAMP_NTZ`](https://docs.databricks.com/en/sql/language-manual/data-types/timestamp-ntz-type.html)|
+[`Double`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Double)| [`DOUBLE`](https://docs.databricks.com/en/sql/language-manual/data-types/double-type.html)
+[`Enum`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Enum)| (not supported)|
+[`Float`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Float)| [`FLOAT`](https://docs.databricks.com/en/sql/language-manual/data-types/float-type.html)
+[`Integer`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Integer)| [`INT`](https://docs.databricks.com/en/sql/language-manual/data-types/int-type.html)
+[`Numeric`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Numeric)| [`DECIMAL`](https://docs.databricks.com/en/sql/language-manual/data-types/decimal-type.html)|
+[`PickleType`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.PickleType)| (not supported)|
+[`SmallInteger`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.SmallInteger)| [`SMALLINT`](https://docs.databricks.com/en/sql/language-manual/data-types/smallint-type.html)
+[`String`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.String)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
+[`Text`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Text)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
+[`Time`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Time)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
+[`Unicode`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Unicode)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
+[`UnicodeText`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.UnicodeText)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)|
+[`Uuid`](https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Uuid)| [`STRING`](https://docs.databricks.com/en/sql/language-manual/data-types/string-type.html)
+
+In addition, the dialect exposes three UPPERCASE SQLAlchemy types which are specific to Databricks:
+
+- [`databricks.sqlalchemy.TINYINT`](https://docs.databricks.com/en/sql/language-manual/data-types/tinyint-type.html)
+- [`databricks.sqlalchemy.TIMESTAMP`](https://docs.databricks.com/en/sql/language-manual/data-types/timestamp-type.html)
+- [`databricks.sqlalchemy.TIMESTAMP_NTZ`](https://docs.databricks.com/en/sql/language-manual/data-types/timestamp-ntz-type.html)
 
 
 ### `LargeBinary()` and `PickleType()`
@@ -113,6 +112,24 @@ Support for `CHECK` constraints is not implemented in this dialect. Support is p
 
 SQLAlchemy's `Enum()` type depends on `CHECK` constraints and is therefore not yet supported.
 
+### `DateTime()`, `TIMESTAMP_NTZ()`, and `TIMESTAMP()`
+
+Databricks Runtime provides two datetime-like types: `TIMESTAMP` which is always timezone-aware and `TIMESTAMP_NTZ` which is timezone agnostic. Both types can be imported from `databricks.sqlalchemy` and used in your models.
+
+The SQLAlchemy documentation indicates that `DateTime()` is not timezone-aware by default. So our dialect maps this type to `TIMESTAMP_NTZ()`. In practice, you should never need to use `TIMESTAMP_NTZ()` directly. Just use `DateTime()`.
+
+If you need your field to be timezone-aware, you can import `TIMESTAMP()` and use it instead.
+
+_Note that SQLAlchemy documentation suggests that you can declare a `DateTime()` with `timezone=True` on supported backends. However, if you do this with the Databricks dialect, the `timezone` argument will be ignored._
+
+```python
+from sqlalchemy import DateTime
+from databricks.sqlalchemy import TIMESTAMP
+
+class SomeModel(Base):
+    some_date_without_timezone  = DateTime()
+    some_date_with_timezone     = TIMESTAMP()
+```
 
 ### `String()`, `Text()`, `Unicode()`, and `UnicodeText()`
 
@@ -137,7 +154,7 @@ class SomeModel(Base):
 
 Identity and generated value support is currently limited in this dialect.
 
-When defining models, SQLAlchemy types can accept an [`autoincrement`](https://docs.sqlalchemy.org/en/13/core/metadata.html#sqlalchemy.schema.Column.params.autoincrement) argument. In our dialect, this argument is currently ignored. To create an auto-incrementing field in your model you can pass in an explicit [`Identity()`](https://docs.sqlalchemy.org/en/13/core/defaults.html#identity-ddl) instead.
+When defining models, SQLAlchemy types can accept an [`autoincrement`](https://docs.sqlalchemy.org/en/20/core/metadata.html#sqlalchemy.schema.Column.params.autoincrement) argument. In our dialect, this argument is currently ignored. To create an auto-incrementing field in your model you can pass in an explicit [`Identity()`](https://docs.sqlalchemy.org/en/20/core/defaults.html#identity-ddl) instead.
 
 Furthermore, in Databricks Runtime, only `BIGINT` fields can be configured to auto-increment. So in SQLAlchemy, you must use the `BigInteger()` type.
 
@@ -151,6 +168,10 @@ class SomeModel(Base):
 
 When calling `Base.metadata.create_all()`, the executed DDL will include `GENERATED ALWAYS AS IDENTITY` for the `id` column. This is useful when using SQLAlchemy to generate tables. However, as of this writing, `Identity()` constructs are not captured when SQLAlchemy reflects a table's metadata (support for this is planned).
 
+## Parameters
+
+`databricks-sql-connector` supports two approaches to parameterizing SQL queries: native and inline. Our SQLAlchemy 2.0 dialect always uses the native approach and is therefore limited to DBR 14.2 and above. If you are writing parameterized queries to be executed by SQLAlchemy, you must use the "named" paramstyle (`:param`). Read more about parameterization in `docs/parameters.md`.
+
 ## Usage with pandas
 
 Use [`pandas.DataFrame.to_sql`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_sql.html) and [`pandas.read_sql`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_sql.html#pandas.read_sql) to write and read from Databricks SQL. These methods both accept a SQLAlchemy connection to interact with Databricks.
@@ -181,7 +202,7 @@ with engine.connect() as conn:
     df.to_sql('squares',conn)
 ```
 
-## [`PrimaryKey()`](https://docs.sqlalchemy.org/en/13/core/constraints.html#sqlalchemy.schema.PrimaryKeyConstraint) and [`ForeignKey()`](https://docs.sqlalchemy.org/en/13/core/constraints.html#defining-foreign-keys)
+## [`PrimaryKey()`](https://docs.sqlalchemy.org/en/20/core/constraints.html#sqlalchemy.schema.PrimaryKeyConstraint) and [`ForeignKey()`](https://docs.sqlalchemy.org/en/20/core/constraints.html#defining-foreign-keys)
 
 Unity Catalog workspaces in Databricks support PRIMARY KEY and FOREIGN KEY constraints. _Note that Databricks Runtime does not enforce the integrity of FOREIGN KEY constraints_. You can establish a primary key by setting `primary_key=True` when defining a column.
 

databricks_sqlalchemy-2.0.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+CHANGELOG.md,sha256=3y1Bi07K7cXfMbmEN4Pfpbpz_G7irzxBQrGbqzGwC5c,226
+databricks/sqlalchemy/__init__.py,sha256=Gk3XC5OCzq7LuxMVpxK3t4q0rkflXJ8uJRJh9uusMqc,185
+databricks/sqlalchemy/_ddl.py,sha256=c0_GwfmnrFVr4-Ls14fmdGUUFyUok_GW4Uo45hLABFc,3983
+databricks/sqlalchemy/_parse.py,sha256=C0Q0_87PknCibRjs3ewPL5dimwQqaW_vr4nMxMsS220,13048
+databricks/sqlalchemy/_types.py,sha256=EqC_TWWY7mDw9EM2AVZnPrw5DD6G-vBV7wiwX4tcBcM,11753
+databricks/sqlalchemy/base.py,sha256=KcjfHMH0NsceYE2NRxrePtf5T1uw9u8JHofRdbnAKS4,15619
+databricks/sqlalchemy/dependency_test/test_dependency.py,sha256=oFv2oW0e0ScpiKbmXHwpIuYf7mWpj4BiVShiLvw2b2k,938
+databricks/sqlalchemy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+databricks/sqlalchemy/pytest.ini,sha256=ImutflUjkhByVNWCQ18Todj6XTvgJAQX_v7fD-gWHhU,106
+databricks/sqlalchemy/requirements.py,sha256=OobunAEwZ9y2dvSQLOmdgJciVn9xGlY9NAFfszPCTU0,9018
+databricks/sqlalchemy/setup.cfg,sha256=ImutflUjkhByVNWCQ18Todj6XTvgJAQX_v7fD-gWHhU,106
+databricks/sqlalchemy/test/_extra.py,sha256=ZMbqkdw9_sTRrcmuOssZoaZjNsaM-L1Z8tlumOoipMg,1955
+databricks/sqlalchemy/test/_future.py,sha256=7ZKdl2-hPVgkNUtq-mVS1DWsI5Y8N4fEnwxXfFnTqCU,12658
+databricks/sqlalchemy/test/_regression.py,sha256=MI6Jlmnw-DYmyY-mHfrscNQ8l3UEDaPXC7J3R2uKI9o,5412
+databricks/sqlalchemy/test/_unsupported.py,sha256=ORi3FvzjGDx3KK62KysJFaEI4zfAw3JdbpVbT5oCCYM,16061
+databricks/sqlalchemy/test/conftest.py,sha256=wauk1PYW_epp5-CKA2HbcTk_Ke3i8XpCnHB7UJLIRoE,597
+databricks/sqlalchemy/test/overrides/_componentreflectiontest.py,sha256=OAaFx_l3sHuUn322NuyzpBq1SquvHCyXIvk5NxDXNv8,7042
+databricks/sqlalchemy/test/overrides/_ctetest.py,sha256=u4jSIMrZY2dCSvBRhk9RsiObx1GB3RoFuLRByC212VU,1026
+databricks/sqlalchemy/test/test_suite.py,sha256=kQfqmoXROaMNi6RebaPKS6MFabzSU5Rz-YPo84CImIQ,492
+databricks/sqlalchemy/test_local/__init__.py,sha256=gphvzZ0Cb4Kz7rPRHHULanKyyjKgFt7zmGGYvcuGxys,131
+databricks/sqlalchemy/test_local/conftest.py,sha256=b6LThokKLJrCfe7207A6NvF2MYnGOmajwtVILCWj1qY,951
+databricks/sqlalchemy/test_local/e2e/MOCK_DATA.xlsx,sha256=9zqXUDGzgS2yjPz8x0uFsJU6kQTqdVRKKfJrEBHTZuY,59837
+databricks/sqlalchemy/test_local/e2e/test_basic.py,sha256=wLP28vz2H9wz0dS52_iXbRwu0Zoh0wTEN9MOj2xJiOQ,16749
+databricks/sqlalchemy/test_local/test_ddl.py,sha256=L5V1NoW9dT-7BHcaB97FQOw9ZFvo0g2_FIPKqOzlECM,3198
+databricks/sqlalchemy/test_local/test_parsing.py,sha256=pSTAnWyA44vDTEZ-_HnfwEr3QbA2Kmzn1yU5q1GqMts,5017
+databricks/sqlalchemy/test_local/test_types.py,sha256=Uey-z4ypzD5ykClBQs7XNW9KArHPbZU2cAk3EYD9jS0,6749
+databricks_sqlalchemy-2.0.0.dist-info/LICENSE,sha256=WgVm2VpfZ3CsUfPndD2NeCrEIcFA4UB-YnnW4ejxcbE,11346
+databricks_sqlalchemy-2.0.0.dist-info/METADATA,sha256=qjj_K1tWMMn7qGvzae8IhbabCSNWeWa0TTyq919wjVc,13073
+databricks_sqlalchemy-2.0.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+databricks_sqlalchemy-2.0.0.dist-info/entry_points.txt,sha256=AAjpsvZbVcoMAcWLIesoAT5FNZhBEcIhxdKknVua3jw,74
+databricks_sqlalchemy-2.0.0.dist-info/RECORD,,