Skip to content

Commit

Permalink
refactor(ddl): deprecate all *_schema methods
Browse files Browse the repository at this point in the history 
BREAKING CHANGE: We are removing the word `schema` in its hierarchical
sense. We use `database` to mean a collection of tables. The behavior of
all `*_database` methods now applies only to collections of tables and
never to collections of `database` (formerly `schema`)
* `CanListDatabases` abstract methods now all refer to
collections of tables.
* `CanCreateDatabases` abstract methods now all refer to
collections of tables.
* `list_databases` now takes a kwarg `catalog`.
* `create_database` now takes a kwarg `catalog`.
* `drop_database` now takes a kwarg `catalog`.
* `current_database` now refers to the current collection of tables.
* `CanCreateSchema` is deprecated and `create_schema`, `drop_schema`,
  `list_schemas`, and `current_schema` are deprecated and redirect to the
  corresponding method/property ending in `database`.
* We add a `CanListCatalog` and `CanCreateCatalog` that can list and
   create collections of `database`, respectively.
   The new methods are `list_catalogs`, `create_catalog`, `drop_catalog`,
* There is a new `current_catalog` property.

refactor(duckdb): catalog database switchover

refactor(snowflake): catalog database switchover

refactor(trino): catalog database switchover

refactor(postgres): catalog database switchover

refactor(oracle): catalog database switchover

refactor(mssql): catalog database switchover

refactor(bigquery): catalog database switchover

refactor(clickhouse): catalog database switchover

refactor(datafusion): catalog database switchover

refactor(mysql): catalog database switchover

refactor(exasol): catalog database switchover

refactor(risingwave): catalog database switchover

test(list_databases): add test for list_database contents
  • Loading branch information
@gforsyth
gforsyth committed Mar 25, 2024
1 parent 190b2c7 commit c43c0f1
Show file tree
Hide file tree
Showing 23 changed files with 635 additions and 406 deletions.
186 changes: 135 additions & 51 deletions ibis/backends/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -549,10 +549,21 @@ def to_delta(
write_deltalake(path, batch_reader, **kwargs)


class CanListDatabases(abc.ABC):
class CanListCatalog(abc.ABC):
@abc.abstractmethod
def list_databases(self, like: str | None = None) -> list[str]:
"""List existing databases in the current connection.
def list_catalogs(self, like: str | None = None) -> list[str]:
"""List existing catalogs in the current connection.
::: {.callout-note}
## Ibis does not use the word `schema` to refer to database hierarchy.
A collection of `table` is referred to as a `database`.
A collection of `database` is referred to as a `catalog`.
These terms are mapped onto the corresponding features in each
backend (where available), regardless of whether the backend itself
uses the same terminology.
:::
Parameters
----------
Expand All @@ -563,109 +574,182 @@ def list_databases(self, like: str | None = None) -> list[str]:
Returns
-------
list[str]
The database names that exist in the current connection, that match
The catalog names that exist in the current connection, that match
the `like` pattern if provided.
"""

@property
@abc.abstractmethod
def current_database(self) -> str:
"""The current database in use."""
def current_catalog(self) -> str:
"""The current catalog in use."""


class CanCreateDatabase(CanListDatabases):
class CanCreateCatalog(CanListCatalog):
@abc.abstractmethod
def create_database(self, name: str, force: bool = False) -> None:
"""Create a new database.
def create_catalog(self, name: str, force: bool = False) -> None:
"""Create a new catalog.
::: {.callout-note}
## Ibis does not use the word `schema` to refer to database hierarchy.
A collection of `table` is referred to as a `database`.
A collection of `database` is referred to as a `catalog`.
These terms are mapped onto the corresponding features in each
backend (where available), regardless of whether the backend itself
uses the same terminology.
:::
Parameters
----------
name
Name of the new database.
Name of the new catalog.
force
If `False`, an exception is raised if the database already exists.
If `False`, an exception is raised if the catalog already exists.
"""

@abc.abstractmethod
def drop_database(self, name: str, force: bool = False) -> None:
"""Drop a database with name `name`.
def drop_catalog(self, name: str, force: bool = False) -> None:
"""Drop a catalog with name `name`.
::: {.callout-note}
## Ibis does not use the word `schema` to refer to database hierarchy.
A collection of `table` is referred to as a `database`.
A collection of `database` is referred to as a `catalog`.
These terms are mapped onto the corresponding features in each
backend (where available), regardless of whether the backend itself
uses the same terminology.
:::
Parameters
----------
name
Database to drop.
Catalog to drop.
force
If `False`, an exception is raised if the database does not exist.
If `False`, an exception is raised if the catalog does not exist.
"""


class CanCreateSchema(abc.ABC):
class CanListDatabase(abc.ABC):
@abc.abstractmethod
def create_schema(
self, name: str, database: str | None = None, force: bool = False
def list_databases(
self, like: str | None = None, catalog: str | None = None
) -> list[str]:
"""List existing databases in the current connection.
::: {.callout-note}
## Ibis does not use the word `schema` to refer to database hierarchy.
A collection of `table` is referred to as a `database`.
A collection of `database` is referred to as a `catalog`.
These terms are mapped onto the corresponding features in each
backend (where available), regardless of whether the backend itself
uses the same terminology.
:::
Parameters
----------
like
A pattern in Python's regex format to filter returned database
names.
catalog
The catalog to list databases from. If `None`, the current catalog
is searched.
Returns
-------
list[str]
The database names that exist in the current connection, that match
the `like` pattern if provided.
"""

@property
@abc.abstractmethod
def current_database(self) -> str:
"""The current database in use."""


class CanCreateDatabase(CanListDatabase):
@abc.abstractmethod
def create_database(
self, name: str, catalog: str | None = None, force: bool = False
) -> None:
"""Create a schema named `name` in `database`.
"""Create a database named `name` in `catalog`.
Parameters
----------
name
Name of the schema to create.
database
Name of the database in which to create the schema. If `None`, the
current database is used.
Name of the database to create.
catalog
Name of the catalog in which to create the database. If `None`, the
current catalog is used.
force
If `False`, an exception is raised if the schema exists.
If `False`, an exception is raised if the database exists.
"""

@abc.abstractmethod
def drop_schema(
self, name: str, database: str | None = None, force: bool = False
def drop_database(
self, name: str, catalog: str | None = None, force: bool = False
) -> None:
"""Drop the schema with `name` in `database`.
"""Drop the database with `name` in `catalog`.
Parameters
----------
name
Name of the schema to drop.
database
Name of the database to drop the schema from. If `None`, the
current database is used.
catalog
Name of the catalog to drop the database from. If `None`, the
current catalog is used.
force
If `False`, an exception is raised if the schema does not exist.
If `False`, an exception is raised if the database does not exist.
"""

@abc.abstractmethod

# TODO: remove this for 10.0
class CanListSchema:
@util.deprecated(
instead="Use `list_databases` instead`", as_of="9.0", removed_in="10.0"
)
def list_schemas(
self, like: str | None = None, database: str | None = None
) -> list[str]:
"""List existing schemas in the current connection.
return self.list_databases(like=like, catalog=database)

Parameters
----------
like
A pattern in Python's regex format to filter returned schema
names.
database
The database to list schemas from. If `None`, the current database
is searched.
@property
@util.deprecated(
instead="Use `Backend.current_database` instead.",
as_of="9.0",
removed_in="10.0",
)
def current_schema(self) -> str:
return self.current_database

Returns
-------
list[str]
The schema names that exist in the current connection, that match
the `like` pattern if provided.

"""
class CanCreateSchema(CanListSchema):
@util.deprecated(
instead="Use `create_database` instead", as_of="9.0", removed_in="10.0"
)
def create_schema(
self, name: str, database: str | None = None, force: bool = False
) -> None:
self.create_database(name=name, catalog=database, force=force)

@property
@abc.abstractmethod
def current_schema(self) -> str:
"""Return the current schema."""
@util.deprecated(
instead="Use `drop_database` instead", as_of="9.0", removed_in="10.0"
)
def drop_schema(
self, name: str, database: str | None = None, force: bool = False
) -> None:
self.drop_database(name=name, catalog=database, force=force)


class BaseBackend(abc.ABC, _FileIOHandler):
Expand Down
Loading

0 comments on commit c43c0f1

Please sign in to comment.