extras.sql_base — SQL Database Service base class

---

Includes an abstract base class that can be used to easily create SQL services.

class extras.sql_base.SQLService(*, local_driver: str | None = None, local_options: Mapping[str, str] | str | None = None, default_database: str)

Abstract base class for SQL services. Inherits from SingleEndpointService, RunMixin, and AsyncRunMixin.

Parameters:

• local_driver – the driver to use for local connections by default.

• local_options – the options to use for local connections by default.

• default_database – the default database to use for connections during startup. Should be a database name that is guaranteed to exist during startup.

INTERNAL_PORT: int

The internal port exposed by the service container. Must be set by subclasses.

DIALECT: str

The SQL dialect to use when connecting. Must be set by subclasses.

LOCAL_HOSTNAME: str = 'localhost'

The hostname to use for local connections. Overridable by subclasses.

DEFAULT_START_RETRYSPEC: RetrySpec = RetrySpec(attempts=20)

The default retry spec to use when starting the service. Overridable by subclasses.

abstract userpass() → Tuple[str, str]

Returns a tuple of (username, password) for the service, with admin permissions.

create_database(name: str)

Creates a database with the given name.

Raises:

ValueError if the database already exists.

drop_database(name: str)

Drops the database with the given name.

database_exists(name) → bool

Returns whether the database with the given name exists.

external_port() → int

Returns the external port of the service, respective to its INTERNAL_PORT.

local_connection_string(dialect: str = ..., driver: str | None = ..., *, database: str, options: str | Mapping[str, str] | None = ...) → str

Returns a connection string for a local connection to the service. Used to connect to a database from the main process.

Parameters:

• dialect – The SQL dialect to use. Defaults to DIALECT.

• driver – The driver to use. Defaults to the local_driver as set in the constructor.

• database – The database to connect to.

• options – The driver-specific options to use. Defaults to the local_options as set in the constructor. If is a mapping, all whitespaces in the values will be converted to plus signs.

container_connection_string(hostname: str, dialect: str = ..., driver: str | None = None, *, database: str, options: str | Mapping[str, str] | None = None) → str

Returns a connection string for a connection to the service. Used to connect to a database from a container over a shared network.

Parameters:

• hostname – The hostname of the database container within the shared network.

• dialect – The SQL dialect to use. Defaults to DIALECT.

• driver – The driver to use. Defaults to None.

• database – The database to connect to.

• options – The driver-specific options to use. Defaults to None. If is a mapping, all whitespaces in the values will be converted to plus signs.

host_connection_string(dialect: str = ..., driver: str | None = None, *, database: str, options: str | Mapping[str, str] | None = None) → str

Returns a connection string for a connection to the service. Used to connect to a database from a container over the docker host.

Parameters:

• dialect – The SQL dialect to use. Defaults to DIALECT.

• driver – The driver to use. Defaults to None.

• database – The database to connect to.

• options – The driver-specific options to use. Defaults to None. If is a mapping, all whitespaces in the values will be converted to plus signs.

database(name: str) → Database

Returns a database with the given name. Will create the database if it does not exist.

Note

can be used as a context manager, to ensure deletion of the database.

with service.database('my_database') as db:
    assert service.database_exists('my_database')
    ...
assert not service.database_exists('my_database')

class extras.sql_base.Database

Represents a database within an SQL service. Created by the SQLService.database() method. Can be used as a context manager, to ensure deletion of the database.

Note

In most cases, a Database instance ensures that the database exists when it is created. However it is possible to drop the database after the instance is created. Users should take care to not drop a database that is referenced by a live Database instance.

local_connection_string(...) → str

container_connection_string(...) → str

host_connection_string(...) → str

Returns a connection string for a connection to the database. All parameters are the same as in the corresponding SQLService method, except for database, which is the same as name of the database.

__exit__(...)

Deletes the database.