fix: support lake SQLAlchemy URLs

README.rst

@@ -1,5 +1,5 @@
 tidbcloudlake-sqlalchemy
-===================
+=========================
 
 TiDB Cloud Lake dialect for SQLAlchemy.
 
@@ -13,25 +13,16 @@ The package is installable through PIP::
 Usage
 -----
 
-The DSN format is similar to that of regular Postgres::
+Use a ``lake://`` URL with SQLAlchemy. The database name and warehouse are
+part of the URL::
 
-        from sqlalchemy import create_engine, text
-        from sqlalchemy.engine.base import Connection, Engine
-        engine = create_engine(
-            f"tidbcloudlake://{username}:{password}@{host_port_name}/{database_name}?sslmode=disable"
-        )
-        connection = engine.connect()
-        result = connection.execute(text("SELECT 1"))
-        assert len(result.fetchall()) == 1
-
-        import connector
-        cursor = connector.connect('tidbcloudlake://root:@localhost:8000?sslmode=disable').cursor()
-        cursor.execute('SELECT * FROM test')
-        # print(cursor.fetchone())
-        # print(cursor.fetchall())
-        for row in cursor:
-            print(row)
+    from sqlalchemy import create_engine, text
 
+    engine = create_engine(
+        "lake://<username>:<password>@<host>:443/default?warehouse=default"
+    )
+    with engine.connect() as connection:
+        assert connection.execute(text("SELECT 1")).scalar_one() == 1
 
 Merge Command Support
 ---------------------
@@ -44,7 +35,7 @@ The Merge command can be used as below::
         from sqlalchemy import MetaData, create_engine
         from tidbcloudlake_sqlalchemy.tidbcloudlake_dialect import Merge
 
-        engine = create_engine(db.url, echo=False)
+        engine = create_engine("lake://<username>:<password>@<host>:443/default?warehouse=default")
         session = sessionmaker(bind=engine)()
         connection = engine.connect()
 
@@ -64,18 +55,21 @@ The Merge command can be used as below::
 Copy Into Command Support
 ---------------------
 
-TiDB Cloud Lake SQLAlchemy supports copy into operations through it's CopyIntoTable and CopyIntoLocation methods. See `CopyIntoLocation <https://docs.pingcap.com/tidbcloudlake/copy-into-location/>`_ or `CopyIntoTable <https://docs.pingcap.com/tidbcloudlake/copy-into-table/>`_ for full documentation.
+TiDB Cloud Lake SQLAlchemy supports copy into operations through its
+``CopyIntoTable`` and ``CopyIntoLocation`` methods. See `CopyIntoLocation <https://docs.pingcap.com/tidbcloudlake/copy-into-location/>`_ or `CopyIntoTable <https://docs.pingcap.com/tidbcloudlake/copy-into-table/>`_ for full documentation.
 
 The CopyIntoTable command can be used as below::
 
+        import base64
+
         from sqlalchemy.orm import sessionmaker
         from sqlalchemy import MetaData, create_engine
         from tidbcloudlake_sqlalchemy import (
             CopyIntoTable, GoogleCloudStorage, ParquetFormat, CopyIntoTableOptions,
-            FileColumnClause, CSVFormat,
+            FileColumnClause, CSVFormat, Compression,
         )
 
-        engine = create_engine(db.url, echo=False)
+        engine = create_engine("lake://<username>:<password>@<host>:443/default?warehouse=default")
         session = sessionmaker(bind=engine)()
         connection = engine.connect()
 
@@ -134,13 +128,15 @@ The CopyIntoTable command can be used as below::
 
 The CopyIntoLocation command can be used as below::
 
+        import base64
+
+        from sqlalchemy import MetaData, create_engine, select
         from sqlalchemy.orm import sessionmaker
-        from sqlalchemy import MetaData, create_engine
         from tidbcloudlake_sqlalchemy import (
             CopyIntoLocation, GoogleCloudStorage, ParquetFormat, CopyIntoLocationOptions,
         )
 
-        engine = create_engine(db.url, echo=False)
+        engine = create_engine("lake://<username>:<password>@<host>:443/default?warehouse=default")
         session = sessionmaker(bind=engine)()
         connection = engine.connect()
 
@@ -169,38 +165,37 @@ The CopyIntoLocation command can be used as below::
 Table Options
 ---------------------
 
-TiDB Cloud Lake SQLAlchemy supports tidbcloudlake specific table options for Engine, Cluster Keys and Transient tables
+TiDB Cloud Lake SQLAlchemy supports Lake-specific table options for Engine, Cluster Keys and Transient tables
 
 The table options can be used as below::
 
-        from sqlalchemy import Table, Column
-        from sqlalchemy import MetaData, create_engine
+        from sqlalchemy import Column, Integer, MetaData, String, Table, cast, create_engine
 
-        engine = create_engine(db.url, echo=False)
+        engine = create_engine("lake://<username>:<password>@<host>:443/default?warehouse=default")
 
         meta = MetaData()
         # Example of Transient Table
         t_transient = Table(
             "t_transient",
             meta,
             Column("c1", Integer),
-            tidbcloudlake_transient=True,
+            lake_transient=True,
         )
 
         # Example of Engine
         t_engine = Table(
             "t_engine",
             meta,
             Column("c1", Integer),
-            tidbcloudlake_engine='Memory',
+            lake_engine='Memory',
         )
 
         # Examples of Table with Cluster Keys
         t_cluster_1 = Table(
             "t_cluster_1",
             meta,
             Column("c1", Integer),
-            tidbcloudlake_cluster_by=[c1],
+            lake_cluster_by=[c1],
         )
         #
         c = Column("id", Integer)
@@ -210,8 +205,7 @@ The table options can be used as below::
             meta,
             c,
             c2,
-            tidbcloudlake_cluster_by=[cast(c, String), c2],
+            lake_cluster_by=[cast(c, String), c2],
         )
 
         meta.create_all(engine)
-

setup.cfg

@@ -3,7 +3,7 @@ name = tidbcloudlake-sqlalchemy
 version = attr: tidbcloudlake_sqlalchemy.VERSION
 description = Sqlalchemy adapter for TiDB Cloud Lake
 long_description = file: README.rst
-long_description_content_type = text/markdown
+long_description_content_type = text/x-rst
 url = https://github.com/tidbcloud/lake-sqlalchemy
 author = TiDB Cloud
 license = Apache-2.0
@@ -37,8 +37,7 @@ where = .
 
 [options.entry_points]
 sqlalchemy.dialects =
-    tidbcloudlake = tidbcloudlake_sqlalchemy.tidbcloudlake_dialect:TiDBCloudLakeDialect
-    tidbcloudlake.tidbcloudlake = tidbcloudlake_sqlalchemy.tidbcloudlake_dialect:TiDBCloudLakeDialect
+    lake = tidbcloudlake_sqlalchemy.tidbcloudlake_dialect:TiDBCloudLakeDialect
 
 [options.extras_require]
 dev =
@@ -70,4 +69,4 @@ requirement_cls=tidbcloudlake_sqlalchemy.requirements:Requirements
 profile_file = .profiles.txt
 
 [db]
-default=tidbcloudlake://tidbcloudlake:tidbcloudlake@localhost:8000/default?sslmode=disable
+default=lake://tidbcloudlake:tidbcloudlake@localhost:8000/default?sslmode=disable

tests/conftest.py

@@ -1,8 +1,8 @@
 from sqlalchemy.dialects import registry
 import pytest
 
-registry.register("tidbcloudlake.tidbcloudlake", "tidbcloudlake_sqlalchemy.tidbcloudlake_dialect", "TiDBCloudLakeDialect")
-registry.register("tidbcloudlake", "tidbcloudlake_sqlalchemy.tidbcloudlake_dialect", "TiDBCloudLakeDialect")
+registry.register("lake", "tidbcloudlake_sqlalchemy.tidbcloudlake_dialect", "TiDBCloudLakeDialect")
+registry.register("lake.lake", "tidbcloudlake_sqlalchemy.tidbcloudlake_dialect", "TiDBCloudLakeDialect")
 
 pytest.register_assert_rewrite("sa.testing.assertions")
 

tests/integration/conftest.py

@@ -44,7 +44,7 @@ def engine(
     username: str, password: str, host_port_name: str, database_name: str
 ) -> Engine:
     return create_engine(
-        f"tidbcloudlake://{username}:{password}@{host_port_name}/{database_name}?sslmode=disable"
+        f"lake://{username}:{password}@{host_port_name}/{database_name}?sslmode=disable"
     )
 
 

tests/integration/test_sqlalchemy_integration.py

@@ -12,7 +12,7 @@ def test_set_params(
         self, username: str, password: str, database_name: str, host_port_name: str
     ):
         engine = create_engine(
-            f"tidbcloudlake://{username}:{password}@{host_port_name}/{database_name}?sslmode=disable"
+            f"lake://{username}:{password}@{host_port_name}/{database_name}?sslmode=disable"
         )
         connection = engine.connect()
         result = connection.execute(text("SELECT 1"))

tests/test_copy_into.py

@@ -33,7 +33,7 @@
 
 class CompileTiDBCloudLakeCopyIntoTableTest(fixtures.TestBase, AssertsCompiledSQL):
 
-    __only_on__ = "tidbcloudlake"
+    __only_on__ = "lake"
 
     def test_copy_into_table(self):
         m = MetaData()
@@ -208,7 +208,7 @@ def define_tables(cls, metadata):
             metadata,
             Column("id", Integer),
             Column("data", String(50)),
-            tidbcloudlake_engine='Random',
+            lake_engine='Random',
         )
         Table(
             "loaded",
@@ -265,4 +265,3 @@ def test_copy_into_stage_and_table(self, connection):
             eq_(result['first_error'], None)
             eq_(result['first_error_line'], None)
 
-