execsql2 2.1.2__py3-none-any.whl → 2.4.0__py3-none-any.whl

execsql/db/base.py

@@ -14,7 +14,11 @@ open :class:`Database` instances and tracks which connection is currently
 active.  It is the canonical ``_state.dbs`` object.
 """
 
+import contextlib
+import datetime
 import re
+from abc import ABC, abstractmethod
+from decimal import Decimal
 from typing import Any
 from collections.abc import Callable, Generator, Iterator
 
@@ -22,11 +26,40 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc
 import execsql.state as _state
 
+__all__ = ["Database", "DatabasePool"]
 
-class Database:
+
+def _default_dt_cast() -> dict[type, Callable]:
+    """Build the default type-cast mapping used by all database backends."""
+    from execsql.types import DT_Boolean, DT_Timestamp, DT_Date, DT_Decimal
+
+    return {
+        int: int,
+        float: float,
+        str: str,
+        bool: DT_Boolean().from_data,
+        datetime.datetime: DT_Timestamp().from_data,
+        datetime.date: DT_Date().from_data,
+        Decimal: DT_Decimal().from_data,
+        bytearray: bytearray,
+    }
+
+
+class Database(ABC):
     """Abstract base class for all database connections."""
 
-    dt_cast: dict[type, Callable] = {}  # populated per-subclass or in __init__
+    _dt_cast: dict[type, Callable] | None = None
+
+    @property
+    def dt_cast(self) -> dict[type, Callable]:
+        """Return the type-cast mapping, initialising it lazily on first access."""
+        if self._dt_cast is None:
+            self._dt_cast = _default_dt_cast()
+        return self._dt_cast
+
+    @dt_cast.setter
+    def dt_cast(self, value: dict[type, Callable]) -> None:
+        self._dt_cast = value
 
     def __init__(
         self,
@@ -57,22 +90,38 @@ class Database:
         )
 
     def name(self) -> str:
+        """Return a human-readable description of this connection (DBMS + server/file)."""
         if self.server_name:
             return f"{self.type.dbms_id}(server {self.server_name}; database {self.db_name})"
         else:
             return f"{self.type.dbms_id}(file {self.db_name})"
 
+    @abstractmethod
     def open_db(self) -> None:
-        from execsql.exceptions import DatabaseNotImplementedError
-
-        raise DatabaseNotImplementedError(self.name(), "open_db")
+        """Open the underlying database connection."""
+        ...
 
     def cursor(self):
+        """Return a new cursor, opening the connection first if it has not been opened yet."""
         if self.conn is None:
             self.open_db()
         return self.conn.cursor()
 
+    @contextlib.contextmanager
+    def _cursor(self):
+        """Context manager that yields a cursor and closes it on exit.
+
+        Works with any DB-API 2.0 cursor regardless of whether the driver
+        natively supports the context manager protocol.
+        """
+        curs = self.cursor()
+        try:
+            yield curs
+        finally:
+            curs.close()
+
     def close(self) -> None:
+        """Close the database connection, logging a warning if autocommit is off."""
         if self.conn:
             if not self.autocommit:
                 _state.exec_log.log_status_info(
@@ -87,24 +136,26 @@ class Database:
         return '"' + identifier.replace('"', '""') + '"'
 
     def paramsubs(self, paramcount: int) -> str:
+        """Return a comma-separated string of *paramcount* parameter placeholders."""
         return ",".join((self.paramstr,) * paramcount)
 
     def execute(self, sql: Any, paramlist: list | None = None) -> None:
-        # A shortcut to self.cursor().execute() that handles encoding.
-        # Whether or not encoding is needed depends on the DBMS.
+        """Execute *sql* (optionally with *paramlist*), updating ``$LAST_ROWCOUNT``.
+
+        Rolls back the current transaction and re-raises on any driver error.
+        """
         if type(sql) in (tuple, list):
             sql = " ".join(sql)
         try:
-            curs = self.cursor()
-            if paramlist is None:
-                curs.execute(sql)
-            else:
-                curs.execute(sql, paramlist)
-            try:
-                # DuckDB does not support the 'rowcount' attribute.
-                _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
-            except Exception:
-                pass  # Non-critical: some drivers lack rowcount support.
+            with self._cursor() as curs:
+                if paramlist is None:
+                    curs.execute(sql)
+                else:
+                    curs.execute(sql, paramlist)
+                try:
+                    _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
+                except Exception:
+                    pass  # Non-critical: some drivers lack rowcount support.
         except Exception:
             try:
                 self.rollback()
@@ -112,22 +163,26 @@ class Database:
                 pass  # Rollback is best-effort after a failed execute.
             raise
 
+    @abstractmethod
     def exec_cmd(self, querycommand: str) -> None:
-        from execsql.exceptions import DatabaseNotImplementedError
-
-        raise DatabaseNotImplementedError(self.name(), "exec_cmd")
+        """Execute a stored procedure or function by name."""
+        ...
 
     def autocommit_on(self) -> None:
+        """Enable autocommit mode so each statement is committed immediately."""
         self.autocommit = True
 
     def autocommit_off(self) -> None:
+        """Disable autocommit mode, grouping subsequent statements into a transaction."""
         self.autocommit = False
 
     def commit(self) -> None:
+        """Commit the current transaction if autocommit is enabled."""
         if self.conn and self.autocommit:
             self.conn.commit()
 
     def rollback(self) -> None:
+        """Roll back the current transaction; swallows errors (best-effort)."""
         if self.conn:
             try:
                 self.conn.rollback()
@@ -135,6 +190,7 @@ class Database:
                 pass  # Best-effort; connection may already be closed.
 
     def schema_qualified_table_name(self, schema_name: str | None, table_name: str) -> str:
+        """Return the quoted, optionally schema-qualified form of *table_name*."""
         table_name = self.type.quoted(table_name)
         if schema_name:
             schema_name = self.type.quoted(schema_name)
@@ -142,21 +198,22 @@ class Database:
         return table_name
 
     def select_data(self, sql: str) -> tuple[list[str], list]:
-        # Returns the results of the sql select statement.
-        curs = self.cursor()
-        try:
-            curs.execute(sql)
-        except Exception:
-            self.rollback()
-            raise
-        try:
-            _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
-        except Exception:
-            pass  # Non-critical: some drivers lack rowcount support.
-        rows = curs.fetchall()
-        return [d[0] for d in curs.description], rows
+        """Execute *sql* and return ``(column_names, rows)`` with all rows fetched into memory."""
+        with self._cursor() as curs:
+            try:
+                curs.execute(sql)
+            except Exception:
+                self.rollback()
+                raise
+            try:
+                _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
+            except Exception:
+                pass  # Non-critical: some drivers lack rowcount support.
+            rows = curs.fetchall()
+            return [d[0] for d in curs.description], rows
 
     def select_rowsource(self, sql: str) -> tuple[list[str], Generator]:
+        """Execute *sql* and return ``(column_names, row_generator)`` for streaming large result sets."""
         # Return 1) a list of column names, and 2) an iterable that yields rows.
         curs = self.cursor()
         try:
@@ -191,6 +248,7 @@ class Database:
         return [d[0] for d in curs.description], decode_row()
 
     def select_rowdict(self, sql: str) -> tuple[list[str], Iterator]:
+        """Execute *sql* and return ``(column_names, row_iterator)`` where each row is a ``dict``."""
         # Return an iterable that yields dictionaries of row data
         curs = self.cursor()
         try:
@@ -218,35 +276,35 @@ class Database:
         return hdrs, iter(dict_row, None)
 
     def schema_exists(self, schema_name: str) -> bool:
-        curs = self.cursor()
-        sql = f"SELECT schema_name FROM information_schema.schemata WHERE schema_name = {self.paramstr};"
-        curs.execute(sql, (schema_name,))
-        rows = curs.fetchall()
-        curs.close()
+        """Return ``True`` if *schema_name* exists in this database."""
+        with self._cursor() as curs:
+            sql = f"SELECT schema_name FROM information_schema.schemata WHERE schema_name = {self.paramstr};"
+            curs.execute(sql, (schema_name,))
+            rows = curs.fetchall()
         return len(rows) > 0
 
     def table_exists(self, table_name: str, schema_name: str | None = None) -> bool:
-        curs = self.cursor()
-        params: list = [table_name]
-        schema_clause = ""
-        if schema_name:
-            schema_clause = f" and table_schema={self.paramstr}"
-            params.append(schema_name)
-        sql = f"select table_name from information_schema.tables where table_name = {self.paramstr}{schema_clause};"
-        try:
-            curs.execute(sql, params)
-        except ErrInfo:
-            raise
-        except Exception:
-            self.rollback()
-            raise ErrInfo(
-                type="db",
-                command_text=sql,
-                exception_msg=exception_desc(),
-                other_msg=f"Failed test for existence of table {table_name} in {self.name()}",
-            )
-        rows = curs.fetchall()
-        curs.close()
+        """Return ``True`` if *table_name* (optionally in *schema_name*) exists."""
+        with self._cursor() as curs:
+            params: list = [table_name]
+            schema_clause = ""
+            if schema_name:
+                schema_clause = f" and table_schema={self.paramstr}"
+                params.append(schema_name)
+            sql = f"select table_name from information_schema.tables where table_name = {self.paramstr}{schema_clause};"
+            try:
+                curs.execute(sql, params)
+            except ErrInfo:
+                raise
+            except Exception as e:
+                self.rollback()
+                raise ErrInfo(
+                    type="db",
+                    command_text=sql,
+                    exception_msg=exception_desc(),
+                    other_msg=f"Failed test for existence of table {table_name} in {self.name()}",
+                ) from e
+            rows = curs.fetchall()
         return len(rows) > 0
 
     def column_exists(
@@ -255,92 +313,94 @@ class Database:
         column_name: str,
         schema_name: str | None = None,
     ) -> bool:
-        curs = self.cursor()
-        params: list = [table_name]
-        schema_clause = ""
-        if schema_name:
-            schema_clause = f" and table_schema={self.paramstr}"
-            params.append(schema_name)
-        params.append(column_name)
-        sql = (
-            f"select column_name from information_schema.columns "
-            f"where table_name={self.paramstr}{schema_clause} "
-            f"and column_name={self.paramstr};"
-        )
-        try:
-            curs.execute(sql, params)
-        except ErrInfo:
-            raise
-        except Exception:
-            self.rollback()
-            raise ErrInfo(
-                type="db",
-                command_text=sql,
-                exception_msg=exception_desc(),
-                other_msg=f"Failed test for existence of column {column_name} in table {table_name} of {self.name()}",
+        """Return ``True`` if *column_name* exists in *table_name* (optionally in *schema_name*)."""
+        with self._cursor() as curs:
+            params: list = [table_name]
+            schema_clause = ""
+            if schema_name:
+                schema_clause = f" and table_schema={self.paramstr}"
+                params.append(schema_name)
+            params.append(column_name)
+            sql = (
+                f"select column_name from information_schema.columns "
+                f"where table_name={self.paramstr}{schema_clause} "
+                f"and column_name={self.paramstr};"
             )
-        rows = curs.fetchall()
-        curs.close()
+            try:
+                curs.execute(sql, params)
+            except ErrInfo:
+                raise
+            except Exception as e:
+                self.rollback()
+                raise ErrInfo(
+                    type="db",
+                    command_text=sql,
+                    exception_msg=exception_desc(),
+                    other_msg=f"Failed test for existence of column {column_name} in table {table_name} of {self.name()}",
+                ) from e
+            rows = curs.fetchall()
         return len(rows) > 0
 
     def table_columns(self, table_name: str, schema_name: str | None = None) -> list[str]:
-        curs = self.cursor()
-        params: list = [table_name]
-        schema_clause = ""
-        if schema_name:
-            schema_clause = f" and table_schema={self.paramstr}"
-            params.append(schema_name)
-        sql = (
-            f"select column_name from information_schema.columns "
-            f"where table_name={self.paramstr}{schema_clause} "
-            f"order by ordinal_position;"
-        )
-        try:
-            curs.execute(sql, params)
-        except ErrInfo:
-            raise
-        except Exception:
-            self.rollback()
-            raise ErrInfo(
-                type="db",
-                command_text=sql,
-                exception_msg=exception_desc(),
-                other_msg=f"Failed to get column names for table {table_name} of {self.name()}",
+        """Return the ordered list of column names for *table_name*."""
+        with self._cursor() as curs:
+            params: list = [table_name]
+            schema_clause = ""
+            if schema_name:
+                schema_clause = f" and table_schema={self.paramstr}"
+                params.append(schema_name)
+            sql = (
+                f"select column_name from information_schema.columns "
+                f"where table_name={self.paramstr}{schema_clause} "
+                f"order by ordinal_position;"
             )
-        rows = curs.fetchall()
-        curs.close()
+            try:
+                curs.execute(sql, params)
+            except ErrInfo:
+                raise
+            except Exception as e:
+                self.rollback()
+                raise ErrInfo(
+                    type="db",
+                    command_text=sql,
+                    exception_msg=exception_desc(),
+                    other_msg=f"Failed to get column names for table {table_name} of {self.name()}",
+                ) from e
+            rows = curs.fetchall()
         return [row[0] for row in rows]
 
     def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
-        curs = self.cursor()
-        params: list = [view_name]
-        schema_clause = ""
-        if schema_name:
-            schema_clause = f" and table_schema={self.paramstr}"
-            params.append(schema_name)
-        sql = f"select table_name from information_schema.views where table_name = {self.paramstr}{schema_clause};"
-        try:
-            curs.execute(sql, params)
-        except ErrInfo:
-            raise
-        except Exception:
-            self.rollback()
-            raise ErrInfo(
-                type="db",
-                command_text=sql,
-                exception_msg=exception_desc(),
-                other_msg=f"Failed test for existence of view {view_name} in {self.name()}",
-            )
-        rows = curs.fetchall()
-        curs.close()
+        """Return ``True`` if *view_name* (optionally in *schema_name*) exists."""
+        with self._cursor() as curs:
+            params: list = [view_name]
+            schema_clause = ""
+            if schema_name:
+                schema_clause = f" and table_schema={self.paramstr}"
+                params.append(schema_name)
+            sql = f"select table_name from information_schema.views where table_name = {self.paramstr}{schema_clause};"
+            try:
+                curs.execute(sql, params)
+            except ErrInfo:
+                raise
+            except Exception as e:
+                self.rollback()
+                raise ErrInfo(
+                    type="db",
+                    command_text=sql,
+                    exception_msg=exception_desc(),
+                    other_msg=f"Failed test for existence of view {view_name} in {self.name()}",
+                ) from e
+            rows = curs.fetchall()
         return len(rows) > 0
 
     def role_exists(self, rolename: str) -> bool:
+        """Return ``True`` if *rolename* exists; subclasses must override this."""
         from execsql.exceptions import DatabaseNotImplementedError
 
         raise DatabaseNotImplementedError(self.name(), "role_exists")
 
     def drop_table(self, tablename: str) -> None:
+        """Drop *tablename* if it exists; *tablename* must already be schema-qualified and quoted."""
         # The 'tablename' argument should be schema-qualified and quoted as necessary.
         self.execute(f"drop table if exists {tablename} cascade;")
         self.commit()
@@ -353,6 +413,11 @@ class Database:
         column_list: list[str],
         tablespec_src: Callable,
     ) -> None:
+        """Bulk-insert rows from *rowsource* into *table_name* using the columns in *column_list*.
+
+        *rowsource* must be a generator yielding lists of values in column order.
+        *tablespec_src* is a zero-argument callable that returns the table's type specification.
+        """
         # The rowsource argument must be a generator yielding a list of values for the columns of the table.
         # The column_list argument must an iterable containing column names.  This may be a subset of
         # the names of columns in the rowsource.
@@ -382,87 +447,126 @@ class Database:
         curs = self.cursor()
         eof = False
         total_rows = 0
-        while True:
-            b = []
-            for _j in range(_state.conf.import_row_buffer):
-                try:
-                    line = next(rows)
-                except StopIteration:
-                    eof = True
-                else:
-                    if len(line) > len(ts_colnames):
-                        extra_err = True
-                        if _state.conf.del_empty_cols:
-                            any_non_empty = False
-                            for cno in range(len(ts_colnames), len(line)):
-                                if not (
-                                    line[cno] is None
-                                    or (
-                                        not _state.conf.empty_strings
-                                        and isinstance(line[cno], _state.stringtypes)
-                                        and len(line[cno].strip()) == 0
-                                    )
-                                    and _state.conf.del_empty_cols
-                                ):
-                                    any_non_empty = True
-                                    break
-                            extra_err = any_non_empty
-                        if extra_err:
-                            raise ErrInfo(
-                                type="error",
-                                other_msg=f"Too many data columns on line {{{line}}}",
-                            )
-                        else:
-                            line = line[: len(ts_colnames)]
-                    if not (len(line) == 1 and line[0] is None):
-                        if _state.conf.trim_strings or _state.conf.replace_newlines or not _state.conf.empty_strings:
-                            for i in range(len(line)):
-                                if line[i] is not None and isinstance(
-                                    line[i],
-                                    _state.stringtypes,
-                                ):
-                                    if _state.conf.trim_strings:
-                                        line[i] = line[i].strip()
-                                    if _state.conf.replace_newlines:
-                                        line[i] = re.sub(
-                                            r"[\s\t]*[\r\n]+[\s\t]*",
-                                            " ",
-                                            line[i],
+
+        # Optional rich progress bar for long-running imports.
+        use_progress = getattr(_state.conf, "show_progress", False)
+        progress_ctx = None
+        task_id = None
+        if use_progress:
+            try:
+                from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+                from rich.console import Console
+
+                progress_ctx = Progress(
+                    SpinnerColumn(),
+                    TextColumn("[bold blue]IMPORT[/bold blue] {task.description}"),
+                    TextColumn("{task.completed:,} rows"),
+                    TimeElapsedColumn(),
+                    console=Console(stderr=True),
+                )
+            except ImportError:
+                use_progress = False
+
+        def _import_loop() -> int:
+            nonlocal eof, total_rows, task_id
+            while True:
+                b = []
+                for _j in range(_state.conf.import_row_buffer):
+                    try:
+                        line = next(rows)
+                    except StopIteration:
+                        eof = True
+                    else:
+                        if len(line) > len(ts_colnames):
+                            extra_err = True
+                            if _state.conf.del_empty_cols:
+                                any_non_empty = False
+                                for cno in range(len(ts_colnames), len(line)):
+                                    if not (
+                                        line[cno] is None
+                                        or (
+                                            not _state.conf.empty_strings
+                                            and isinstance(line[cno], _state.stringtypes)
+                                            and len(line[cno].strip()) == 0
                                         )
-                                    if not _state.conf.empty_strings and line[i].strip() == "":
-                                        line[i] = None
-                        lt = [type_objs[i].from_data(val) if val is not None else None for i, val in enumerate(line)]
-                        lt = [type_mod_fn[i](v) if type_mod_fn[i] else v for i, v in enumerate(lt)]
-                        row = []
-                        for i, v in enumerate(lt):
-                            if incl_col[i]:
-                                row.append(v)
-                        add_line = True
-                        if not _state.conf.empty_rows:
-                            add_line = not all(c is None for c in row)
-                        if add_line:
-                            b.append(row)
-            if len(b) > 0:
-                try:
-                    curs.executemany(sql, b)
-                except ErrInfo:
-                    raise
-                except Exception:
-                    self.rollback()
-                    raise ErrInfo(
-                        type="db",
-                        command_text=sql,
-                        exception_msg=exception_desc(),
-                        other_msg=f"Can't load data into table {sq_name} of {self.name()} from line {{{line}}}",
-                    )
-                total_rows += len(b)
-                interval = _state.conf.import_progress_interval
-                if _state.exec_log and interval > 0 and total_rows % interval == 0:
-                    _state.exec_log.log_status_info(
-                        f"IMPORT into {sq_name}: {total_rows} rows imported so far.",
-                    )
-            if eof:
-                break
+                                        and _state.conf.del_empty_cols
+                                    ):
+                                        any_non_empty = True
+                                        break
+                                extra_err = any_non_empty
+                            if extra_err:
+                                raise ErrInfo(
+                                    type="error",
+                                    other_msg=f"Too many data columns on line {{{line}}}",
+                                )
+                            else:
+                                line = line[: len(ts_colnames)]
+                        if not (len(line) == 1 and line[0] is None):
+                            if (
+                                _state.conf.trim_strings
+                                or _state.conf.replace_newlines
+                                or not _state.conf.empty_strings
+                            ):
+                                for i in range(len(line)):
+                                    if line[i] is not None and isinstance(
+                                        line[i],
+                                        _state.stringtypes,
+                                    ):
+                                        if _state.conf.trim_strings:
+                                            line[i] = line[i].strip()
+                                        if _state.conf.replace_newlines:
+                                            line[i] = re.sub(
+                                                r"[\s\t]*[\r\n]+[\s\t]*",
+                                                " ",
+                                                line[i],
+                                            )
+                                        if not _state.conf.empty_strings and line[i].strip() == "":
+                                            line[i] = None
+                            lt = [
+                                type_objs[i].from_data(val) if val is not None else None for i, val in enumerate(line)
+                            ]
+                            lt = [type_mod_fn[i](v) if type_mod_fn[i] else v for i, v in enumerate(lt)]
+                            row = []
+                            for i, v in enumerate(lt):
+                                if incl_col[i]:
+                                    row.append(v)
+                            add_line = True
+                            if not _state.conf.empty_rows:
+                                add_line = not all(c is None for c in row)
+                            if add_line:
+                                b.append(row)
+                if len(b) > 0:
+                    try:
+                        curs.executemany(sql, b)
+                    except ErrInfo:
+                        raise
+                    except Exception as e:
+                        self.rollback()
+                        raise ErrInfo(
+                            type="db",
+                            command_text=sql,
+                            exception_msg=exception_desc(),
+                            other_msg=f"Can't load data into table {sq_name} of {self.name()} from line {{{line}}}",
+                        ) from e
+                    total_rows += len(b)
+                    if use_progress and progress_ctx is not None and task_id is not None:
+                        progress_ctx.update(task_id, completed=total_rows)
+                    interval = _state.conf.import_progress_interval
+                    if _state.exec_log and interval > 0 and total_rows % interval == 0:
+                        _state.exec_log.log_status_info(
+                            f"IMPORT into {sq_name}: {total_rows} rows imported so far.",
+                        )
+                if eof:
+                    break
+            return total_rows
+
+        if use_progress and progress_ctx is not None:
+            with progress_ctx:
+                task_id = progress_ctx.add_task(sq_name, total=None)
+                _import_loop()
+        else:
+            _import_loop()
+
         if _state.exec_log:
             _state.exec_log.log_status_info(
                 f"IMPORT into {sq_name} complete: {total_rows} rows imported.",
@@ -475,6 +579,7 @@ class Database:
         csv_file_obj: Any,
         skipheader: bool,
     ) -> None:
+        """Import a CSV/tabular file into *table_name*; column names must be compatible."""
         # Import a text (CSV) file containing tabular data to a table.  Columns must be compatible.
         if not self.table_exists(table_name, schema_name):
             raise ErrInfo(
@@ -517,11 +622,14 @@ class Database:
         column_name: str,
         file_name: str,
     ) -> None:
+        """Insert the raw binary content of *file_name* as a single row into *column_name* of *table_name*."""
         with open(file_name, "rb") as f:
             filedata = f.read()
         sq_name = self.schema_qualified_table_name(schema_name, table_name)
-        sql = f"insert into {sq_name} ({column_name}) values ({self.paramsubs(1)});"
-        self.cursor().execute(sql, (filedata,))
+        quoted_col = self.quote_identifier(column_name)
+        sql = f"insert into {sq_name} ({quoted_col}) values ({self.paramsubs(1)});"
+        with self._cursor() as curs:
+            curs.execute(sql, (filedata,))
 
 
 class DatabasePool:
@@ -538,6 +646,7 @@ class DatabasePool:
         return "DatabasePool()"
 
     def add(self, db_alias: str, db_obj: Database) -> None:
+        """Register *db_obj* under *db_alias*, setting it as initial/current if this is the first connection."""
         db_alias = db_alias.lower()
         if db_alias == "initial" and len(self.pool) > 0:
             raise ErrInfo(
@@ -561,25 +670,27 @@ class DatabasePool:
         self.pool[db_alias] = db_obj
 
     def aliases(self) -> list[str]:
-        # Return a list of the currently defined aliases
+        """Return a list of all currently registered database aliases."""
         return list(self.pool)
 
     def current(self) -> Database:
-        # Return the current db object.
+        """Return the currently active ``Database`` object."""
         return self.pool[self.current_db]
 
     def current_alias(self) -> str:
-        # Return the alias of the current db object.
+        """Return the alias string for the currently active database."""
         return self.current_db
 
     def initial(self) -> Database:
+        """Return the first ``Database`` that was added to the pool."""
         return self.pool[self.initial_db]
 
     def aliased_as(self, db_alias: str) -> Database:
+        """Return the ``Database`` registered under *db_alias*."""
         return self.pool[db_alias]
 
     def make_current(self, db_alias: str) -> None:
-        # Change the current database in use.
+        """Set the active database to *db_alias*; raises ``ErrInfo`` if the alias is unknown."""
         db_alias = db_alias.lower()
         if db_alias not in self.pool:
             raise ErrInfo(
@@ -589,6 +700,7 @@ class DatabasePool:
         self.current_db = db_alias
 
     def disconnect(self, alias: str) -> None:
+        """Close and remove the connection registered under *alias* from the pool."""
         if alias == self.current_db or (alias == "initial" and "initial" in self.pool):
             raise ErrInfo(
                 type="error",
@@ -599,6 +711,7 @@ class DatabasePool:
             del self.pool[alias]
 
     def closeall(self) -> None:
+        """Roll back and close every connection in the pool, then reset the pool to empty."""
         for alias, db in self.pool.items():
             nm = db.name()
             try: