elefast 0.1.0a1__tar.gz

elefast-0.1.0a1/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: elefast
+Version: 0.1.0a1
+Summary: Database testing toolkit integrating Postgres, SQLAlchemy, Pytest and Docker
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education :: Testing
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Database
+Requires-Dist: sqlalchemy>=2.0.45
+Requires-Dist: docker>=7.1.0 ; extra == 'docker'
+Requires-Dist: filelock>=3.20.3 ; extra == 'docker'
+Requires-Python: >=3.14
+Provides-Extra: docker
+Description-Content-Type: text/markdown
+
+> [!WARNING]  
+> Alpha-level software.
+
+# Elefast 🐘⚡
+
+Using an actual database for testing is nice, but setting everything up can be a pain.
+Generating the schema, isolating the state, and supporting parallel execution while keeping everything reasonably quick.
+Elefast helps you by providing utilities for all of these tasks
+
+To learn more, visit [the documentation](https://niclasvaneyk.github.io/elefast/getting-started) or run through the quickstart guide below.
+
+## Quickstart
+
+Install the package from PyPi through your package manager
+
+```shell
+uv add 'elefast[docker]'
+```
+
+add the recommended set of fixtures to your `conftest.py`
+
+```shell
+mkdir tests/ && uv run elefast init >> tests/conftest.py
+```
+
+create a test using your new set of fixtures
+
+```python
+# tests/test_something_with_the_database.py
+from sqlalchemy import Connection, text
+
+def test_database_math(db_connection: Connection):
+    result = db_connection.execute(text("SELECT 1 + 1")).scalar_one()
+    assert result == 2
+```
+
+When you now run `pytest`, we'll automatically start a Docker container (if one is not already running), and pass a database connection into the test

elefast-0.1.0a1/README.md

@@ -0,0 +1,37 @@
+> [!WARNING]  
+> Alpha-level software.
+
+# Elefast 🐘⚡
+
+Using an actual database for testing is nice, but setting everything up can be a pain.
+Generating the schema, isolating the state, and supporting parallel execution while keeping everything reasonably quick.
+Elefast helps you by providing utilities for all of these tasks
+
+To learn more, visit [the documentation](https://niclasvaneyk.github.io/elefast/getting-started) or run through the quickstart guide below.
+
+## Quickstart
+
+Install the package from PyPi through your package manager
+
+```shell
+uv add 'elefast[docker]'
+```
+
+add the recommended set of fixtures to your `conftest.py`
+
+```shell
+mkdir tests/ && uv run elefast init >> tests/conftest.py
+```
+
+create a test using your new set of fixtures
+
+```python
+# tests/test_something_with_the_database.py
+from sqlalchemy import Connection, text
+
+def test_database_math(db_connection: Connection):
+    result = db_connection.execute(text("SELECT 1 + 1")).scalar_one()
+    assert result == 2
+```
+
+When you now run `pytest`, we'll automatically start a Docker container (if one is not already running), and pass a database connection into the test

elefast-0.1.0a1/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "elefast"
+version = "0.1.0a1"
+description = "Database testing toolkit integrating Postgres, SQLAlchemy, Pytest and Docker"
+readme = "README.md"
+authors = []
+requires-python = ">=3.14"
+dependencies = [
+    "sqlalchemy>=2.0.45",
+]
+license = "MIT"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Framework :: AsyncIO",
+    "Framework :: Pytest",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Education :: Testing",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Database",
+]
+
+[project.optional-dependencies]
+docker = [
+    "docker>=7.1.0",
+    "filelock>=3.20.3",
+]
+
+[project.scripts]
+elefast = "elefast.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "zensical>=0.0.15",
+]
+
+[tool.uv.workspace]
+members = [
+    "examples/fastapi-async",
+    "examples/simple-sync",
+]

elefast-0.1.0a1/src/elefast/__init__.py

@@ -0,0 +1,17 @@
+from elefast.asyncio import (
+    AsyncDatabase,
+    AsyncDatabaseServer,
+    CanBeTurnedIntoAsyncEngine,
+)
+from elefast.sync import DatabaseServer, Database, CanBeTurnedIntoEngine
+
+__all__ = [
+    "AsyncDatabase",
+    "AsyncDatabaseServer",
+    "BasicAsyncDatabaseServer",
+    "BasicDatabaseServer",
+    "Database",
+    "DatabaseServer",
+    "CanBeTurnedIntoEngine",
+    "CanBeTurnedIntoAsyncEngine",
+]

elefast-0.1.0a1/src/elefast/asyncio.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import time
+from asyncio import sleep
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager
+from uuid import uuid4
+
+from sqlalchemy import URL, MetaData, NullPool, text
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from elefast.errors import DatabaseNotReadyError
+
+type CanBeTurnedIntoAsyncEngine = AsyncEngine | URL | str
+
+
+class AsyncDatabase(AbstractAsyncContextManager):
+    def __init__(
+        self,
+        engine: AsyncEngine,
+        server: AsyncDatabaseServer,
+        sessionmaker_factory: Callable[
+            [AsyncEngine], Callable[[], AsyncSession]
+        ] = async_sessionmaker,
+    ) -> None:
+        self.engine = engine
+        self.server = server
+        self.sessionmaker = sessionmaker_factory(self.engine)
+        assert self.engine.url.database
+        self.name = self.engine.url.database
+
+    async def __aexit__(self, exc_type, exc, tb):
+        await self.drop()
+
+    @property
+    def url(self) -> URL:
+        return self.engine.url
+
+    async def drop(self) -> None:
+        await self.engine.dispose()
+        await self.server.drop_database(self.name)
+
+    def session(self) -> AsyncSession:
+        return self.sessionmaker()
+
+
+class AsyncDatabaseServer:
+    def __init__(
+        self, engine: CanBeTurnedIntoAsyncEngine, metadata: MetaData | None = None
+    ) -> None:
+        self._metadata = metadata
+        self._engine = _build_engine(engine)
+        self._template_db_name: str | None = None
+
+    @property
+    def url(self) -> URL:
+        return self._engine.url
+
+    async def ensure_is_ready(
+        self, timeout: int | float = 30, interval: int | float = 0.5
+    ) -> None:
+        deadline = time.monotonic() + timeout
+        attempts = 0
+
+        while True:
+            try:
+                async with self._engine.connect() as conn:
+                    await conn.execute(text("SELECT 1"))
+                return
+            except Exception as error:
+                attempts += 1
+                if time.monotonic() >= deadline:
+                    raise DatabaseNotReadyError(
+                        f"Reached the configured timeout of {timeout} seconds after {attempts} attempts connecting to the database."
+                    ) from error
+                await sleep(interval)
+
+    async def create_database(self) -> AsyncDatabase:
+        template_db = self._template_db_name
+        if template_db is None:
+            engine = await _prepare_async_database(self._engine)
+            if self._metadata:
+                async with engine.begin() as connection:
+                    await connection.run_sync(self._metadata.drop_all)
+                    await connection.run_sync(self._metadata.create_all)
+            await engine.dispose()
+            template_db = engine.url.database
+            assert isinstance(template_db, str)
+            self._template_db_name = template_db
+
+        engine = await _prepare_async_database(self._engine, template=template_db)
+        return AsyncDatabase(engine=engine, server=self)
+
+    async def drop_database(self, name: str) -> None:
+        async with self._engine.begin() as connection:
+            statement = f'DROP DATABASE "{name}"'
+            await connection.execute(text(statement))
+
+
+async def _prepare_async_database(
+    engine: AsyncEngine, encoding: str = "utf8", template: str | None = None
+) -> AsyncEngine:
+    database = f"pytest-elephantastic-{uuid4()}"
+    async with engine.begin() as connection:
+        statement = (
+            f"CREATE DATABASE \"{database}\" ENCODING '{encoding}' TEMPLATE template0"
+            if template is None
+            else f'CREATE DATABASE "{database}" WITH TEMPLATE "{template}"'
+        )
+        await connection.execute(text(statement))
+        await connection.commit()
+    return create_async_engine(engine.url.set(database=database))
+
+
+def _build_engine(input: CanBeTurnedIntoAsyncEngine) -> AsyncEngine:
+    if isinstance(input, AsyncEngine):
+        return input
+    if isinstance(input, URL | str):
+        return create_async_engine(
+            input, isolation_level="autocommit", poolclass=NullPool
+        )
+    raise TypeError()

elefast-0.1.0a1/src/elefast/cli/__init__.py

@@ -0,0 +1,11 @@
+from elefast.cli.parser import build_parser
+
+
+def main():
+    cli = build_parser()
+    args = cli.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

elefast-0.1.0a1/src/elefast/cli/docker.py

@@ -0,0 +1,20 @@
+from elefast.cli.types import ParentParser
+
+
+def install_docker_command_if_available(commands: ParentParser) -> None:
+    try:
+        import elefast.docker  # noqa: F401
+    except Exception:
+        return
+
+    parser = commands.add_parser(
+        "docker",
+        help="Utilities for managing elefasts docker container",
+        description="A helpful description.",  # TODO
+    )
+    parser.add_argument("--reuse", action="store_true")
+    parser.set_defaults(func=docker_command)
+
+
+def docker_command(args) -> None:
+    print(args)

elefast-0.1.0a1/src/elefast/cli/init.py

@@ -0,0 +1,134 @@
+from argparse import Namespace
+from sys import stderr
+
+from elefast.cli.types import ParentParser
+
+# NOTE: psycopg can do both, so we cannot infer anything.
+STRICTLY_ASYNC_DRIVERS = ["asyncpg", "aiopg"]
+STRICTLY_SYNC_DRIVERS = ["psycopg2", "pg8000"]
+
+
+def install_init_command(commands: ParentParser) -> None:
+    init_command_parser = commands.add_parser(
+        "init",
+        help="Helps you the recommended default fixtures",
+        description="Helps you get started with the recommended default fixtures by printing them to the screen. The output of this command is intended to be redirected into a file (e.g. `elefast init > conftest.py && mv conftest.py tests/`) If you omit the flags, you'll be prompted for values.",
+    )
+    init_command_parser.set_defaults(func=init_command)
+    init_command_parser.add_argument(
+        "--driver", help="The name of the driver you intend to use."
+    )
+    init_command_parser.add_argument(
+        "--async",
+        action="append_const",
+        dest="async_preference",
+        const=True,
+        help="Use async methods and classes where necessary. Inferred from the driver if not passed explicitly.",
+    )
+    init_command_parser.add_argument(
+        "--sync",
+        action="append_const",
+        dest="async_preference",
+        const=False,
+        help="Use sync methods and classes. Inferred from the driver if not passed explicitly.",
+    )
+    init_command_parser.add_argument(
+        "--no-interaction",
+        action="store_true",
+        help="Use defaults instead of asking interactive questions for options",
+    )
+
+
+def init_command(args: Namespace):
+    _init_command(
+        driver=args.driver,
+        allow_interaction=not args.no_interaction,
+        async_preference=args.async_preference or [],
+    )
+
+
+def _init_command(
+    driver: str | None,
+    allow_interaction: bool,
+    async_preference: list[bool],
+):
+    driver = _figure_out_driver(driver)
+    use_async = _figure_out_if_we_should_use_async(
+        driver, async_preference, allow_interaction
+    )
+
+    class_prefix = "Async" if use_async else ""
+    maybe_async = "async " if use_async else ""
+    maybe_await = "await " if use_async else ""
+    template = f'''
+import os
+    
+import pytest
+from elefast import {class_prefix}Database, {class_prefix}DatabaseServer, docker
+
+
+@pytest.fixture(scope="session")
+def db_server() -> {class_prefix}DatabaseServer:
+    explicit_url = os.getenv("TESTING_DB_URL")
+    db_url = explicit_url if explicit_url else docker.postgres("{driver}")
+    # If you have a shared Base-class, import it above and use
+    # `metadata=YourBaseClass.metadata` below.
+    return {class_prefix}DatabaseServer(db_url, metadata=None)
+
+
+@pytest.fixture
+{maybe_async}def db(db_server: {class_prefix}DatabaseServer): 
+    {maybe_async}with {maybe_await}db_server.create_database() as database:
+        yield database
+
+
+@pytest.fixture
+{maybe_async}def db_connection(db: {class_prefix}Database):
+    {maybe_async}with db.engine.begin() as connection:
+        yield connection
+
+
+@pytest.fixture
+{maybe_async}def db_session(db: {class_prefix}Database):
+    {maybe_async}with db.session() as session:
+        yield session
+    '''
+    print(template.strip() + "\n")
+
+
+def _figure_out_driver(driver: str | None) -> str:
+    if driver:
+        return driver
+
+    for name in STRICTLY_SYNC_DRIVERS + STRICTLY_ASYNC_DRIVERS + ["psycopg"]:
+        from importlib.util import find_spec
+
+        if find_spec(name):
+            print(
+                f"Using '{name}' as the driver, since no explit --driver argument was passed, and {name} is installed.",
+                file=stderr,
+            )
+            return name
+
+    print(
+        "No --driver was passed and no popular one was found in installed packages. Falling back to psycopg2...",
+        file=stderr,
+    )
+    return "psycopg2"
+
+
+def _figure_out_if_we_should_use_async(
+    driver: str, async_preference: list[bool], allow_interaction: bool
+) -> bool:
+    if async_preference == []:
+        if driver in STRICTLY_ASYNC_DRIVERS:
+            return True
+        elif driver in STRICTLY_SYNC_DRIVERS:
+            return False
+        elif not allow_interaction:
+            return False
+        else:
+            print("Are you intending to use asyncio? [y/N]: ", file=stderr)
+            return "y" in input()
+
+    return any(async_preference)

elefast-0.1.0a1/src/elefast/cli/parser.py

@@ -0,0 +1,17 @@
+from elefast.cli.docker import install_docker_command_if_available
+from elefast.cli.init import install_init_command
+from argparse import ArgumentParser
+
+DESCRIPTION = """
+A helpful description
+""".strip()
+
+
+def build_parser() -> ArgumentParser:
+    cli = ArgumentParser(prog="elefast", description=DESCRIPTION)
+    commands = cli.add_subparsers(required=True, title="subcommands")
+
+    install_init_command(commands)
+    install_docker_command_if_available(commands)
+
+    return cli

elefast-0.1.0a1/src/elefast/cli/types.py

@@ -0,0 +1,3 @@
+from argparse import _SubParsersAction, ArgumentParser
+
+type ParentParser = _SubParsersAction[ArgumentParser]

elefast-0.1.0a1/src/elefast/docker/__init__.py

@@ -0,0 +1,8 @@
+"""
+This module is part of the 'docker' extra and needs to be explicitly installed
+before it is safe to use!
+"""
+
+from elefast.docker.integration import postgres
+
+__all__ = ["postgres"]

elefast-0.1.0a1/src/elefast/docker/configuration.py

@@ -0,0 +1,45 @@
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Optimizations:
+    """
+    Configuration overrides that make Postgres more suitable for fast testing runs.
+    """
+
+    tmpfs_size_mb: int | None = 512
+    fsync_off: bool = True
+    synchronous_commit_off: bool = True
+    full_page_writes_off: bool = True
+    wal_level_minimal: bool = True
+    disable_wal_senders: bool = True
+    disable_archiving: bool = True
+    autovacuum_off: bool = True
+    jit_off: bool = True
+    no_locale: bool = True
+    shared_buffers_mb: int | None = 128
+    work_mem_mb: int | None = None
+    maintenance_work_mem_mb: int | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Container:
+    name: str = "elefast"
+    image: str = "postgres"
+    version: str = "latest"
+    ports: dict[str, str] = field(default_factory=lambda: {"5432": "5432"})
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Credentials:
+    user: str = "postgres"
+    password: str = "elefast"
+    host: str = "127.0.0.1"
+    port: int = 5432
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Configuration:
+    container: Container = Container()
+    credentials: Credentials = Credentials()
+    optimizations: Optimizations = Optimizations()

elefast-0.1.0a1/src/elefast/docker/integration.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+from tempfile import gettempdir
+from filelock import FileLock
+from docker import DockerClient
+from elefast.docker.orchestration import ensure_db_server_started
+from elefast.docker.configuration import Configuration
+from sqlalchemy import URL
+
+
+def postgres(
+    driver: str,
+    docker: DockerClient | None = None,
+    config: Configuration | None = None,
+    keep_container_around: bool = True,
+) -> URL:
+    docker = docker if docker else DockerClient.from_env()
+    config = config if config else Configuration()
+
+    with FileLock(Path(gettempdir()) / "elefast-docker.lock"):
+        ensure_db_server_started(
+            docker=docker, config=config, keep_container_around=keep_container_around
+        )
+    return URL.create(
+        drivername=f"postgresql+{driver}",
+        username=config.credentials.user,
+        password=config.credentials.password,
+        host=config.credentials.host,
+        port=config.credentials.port,
+    )

elefast-0.1.0a1/src/elefast/docker/orchestration.py

@@ -0,0 +1,83 @@
+from typing import cast
+
+from docker import DockerClient
+from docker.models.containers import Container
+
+from elefast.docker.configuration import Configuration
+
+
+def get_docker() -> DockerClient:
+    return DockerClient.from_env()
+
+
+def ensure_db_server_started(
+    docker: DockerClient | None = None,
+    config: Configuration | None = None,
+    keep_container_around: bool = False,
+) -> Container:
+    if docker is None:
+        docker = get_docker()
+    if config is None:
+        config = Configuration()
+
+    if container := get_db_server_container(docker, config.container.name):
+        return container
+    return start_db_server_container(docker, config, keep_container_around)
+
+
+def get_db_server_container(docker: DockerClient, name: str) -> Container | None:
+    containers = cast(list[Container], docker.containers.list())
+    for container in containers:
+        if container.name == name:
+            return container
+
+
+def start_db_server_container(
+    docker: DockerClient, config: Configuration, keep_container_around: bool
+) -> Container:
+    optimizations = config.optimizations
+    command: list[str] = []
+    env: dict[str, str] = {
+        "POSTGRES_USER": config.credentials.user,
+        "POSTGRES_PASSWORD": config.credentials.password,
+    }
+
+    if optimizations.fsync_off:
+        command += ["-c", "fsync=off"]
+    if optimizations.synchronous_commit_off:
+        command += ["-c", "synchronous_commit=off"]
+    if optimizations.full_page_writes_off:
+        command += ["-c", "full_page_writes=off"]
+    if optimizations.wal_level_minimal:
+        command += ["-c", "wal_level=minimal"]
+    if optimizations.disable_wal_senders:
+        command += ["-c", "max_wal_senders=0"]
+    if optimizations.disable_archiving:
+        command += ["-c", "archive_mode=off"]
+    if optimizations.autovacuum_off:
+        command += ["-c", "autovacuum=off"]
+    if optimizations.jit_off:
+        command += ["-c", "jit=off"]
+    if optimizations.shared_buffers_mb is not None:
+        command += ["-c", f"shared_buffers={optimizations.shared_buffers_mb}MB"]
+    if optimizations.work_mem_mb is not None:
+        command += ["-c", f"work_mem={optimizations.work_mem_mb}MB"]
+    if optimizations.maintenance_work_mem_mb is not None:
+        command += [
+            "-c",
+            f"maintenance_work_mem={optimizations.maintenance_work_mem_mb}MB",
+        ]
+    if optimizations.no_locale:
+        env["POSTGRES_INITDB_ARGS"] = "--no-locale"
+
+    return docker.containers.run(
+        image=f"{config.container.image}:{config.container.version}",
+        name=config.container.name,
+        ports=config.container.ports,
+        environment=env,
+        tmpfs={"/var/lib/postgresql": f"rw,size={optimizations.tmpfs_size_mb}m"}
+        if optimizations.tmpfs_size_mb is not None
+        else {},
+        remove=not keep_container_around,
+        detach=True,
+    )

elefast-0.1.0a1/src/elefast/errors.py

@@ -0,0 +1,6 @@
+class ElefastError(Exception):
+    """The base class for errors of elefat"""
+
+
+class DatabaseNotReadyError(ElefastError):
+    """We tried to connect to the DB, but even after lots of attempts we could not run a simple query."""

elefast-0.1.0a1/src/elefast/sync.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+from uuid import uuid4
+import time
+from elefast.errors import DatabaseNotReadyError
+
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+
+from sqlalchemy import URL, Engine, MetaData, text, create_engine, NullPool
+from sqlalchemy.orm import Session, sessionmaker
+
+
+type CanBeTurnedIntoEngine = Engine | URL | str
+
+
+class Database(AbstractContextManager):
+    def __init__(
+        self,
+        engine: Engine,
+        server: DatabaseServer,
+        sessionmaker_factory: Callable[[Engine], Callable[[], Session]] = sessionmaker,
+    ) -> None:
+        self.engine = engine
+        self.server = server
+        self.sessionmaker = sessionmaker_factory(self.engine)
+        assert self.engine.url.database
+        self.name = self.engine.url.database
+
+    def __exit__(self, exc_type, exc, tb):
+        self.drop()
+
+    @property
+    def url(self) -> URL:
+        return self.engine.url
+
+    def drop(self) -> None:
+        self.engine.dispose()
+        self.server.drop_database(self.name)
+
+    def session(self) -> Session:
+        return self.sessionmaker()
+
+
+class DatabaseServer:
+    def __init__(
+        self,
+        engine: CanBeTurnedIntoEngine,
+        metadata: MetaData | None = None,
+    ) -> None:
+        self._metadata = metadata
+        self._engine = _build_engine(engine)
+        self._template_db_name: str | None = None
+
+    @property
+    def url(self) -> URL:
+        return self._engine.url
+
+    def ensure_is_ready(
+        self, timeout: int | float = 30, interval: int | float = 0.5
+    ) -> None:
+        deadline = time.monotonic() + timeout
+        attempts = 0
+
+        while True:
+            try:
+                with self._engine.connect() as conn:
+                    conn.execute(text("SELECT 1"))
+                return
+            except Exception as error:
+                attempts += 1
+                if time.monotonic() >= deadline:
+                    raise DatabaseNotReadyError(
+                        f"Reached the configured timeout of {timeout} seconds after {attempts} attempts connecting to the database."
+                    ) from error
+                time.sleep(interval)
+
+    def create_database(self) -> Database:
+        template_db = self._template_db_name
+        if template_db is None:
+            engine = _prepare_database(self._engine)
+            if self._metadata:
+                with engine.begin() as connection:
+                    self._metadata.drop_all(bind=connection)
+                    self._metadata.create_all(bind=connection)
+            engine.dispose()
+            template_db = engine.url.database
+            assert isinstance(template_db, str)
+            self._template_db_name = template_db
+
+        engine = _prepare_database(self._engine, template=template_db)
+        return Database(engine=engine, server=self)
+
+    def drop_database(self, name: str) -> None:
+        with self._engine.begin() as connection:
+            statement = f'DROP DATABASE "{name}"'
+            connection.execute(text(statement))
+
+
+def _build_engine(input: CanBeTurnedIntoEngine) -> Engine:
+    if isinstance(input, Engine):
+        return input
+    if isinstance(input, URL | str):
+        return create_engine(input, isolation_level="autocommit", poolclass=NullPool)
+    raise TypeError()
+
+
+def _prepare_database(
+    engine: Engine, encoding: str = "utf8", template: str | None = None
+) -> Engine:
+    database = f"pytest-elephantastic-{uuid4()}"
+    with engine.begin() as connection:
+        statement = (
+            f"CREATE DATABASE \"{database}\" ENCODING '{encoding}' TEMPLATE template0"
+            if template is None
+            else f'CREATE DATABASE "{database}" WITH TEMPLATE "{template}"'
+        )
+        connection.execute(text(statement))
+        connection.commit()
+    return create_engine(engine.url.set(database=database))