baseplate.clients.sqlalchemy
¶
SQLAlchemy is an ORM and general-purpose SQL engine for Python. It can work with many different SQL database backends. Reddit generally uses it to talk to PostgreSQL.
Example¶
To integrate SQLAlchemy with your application, add the appropriate client declaration to your context configuration:
baseplate.configure_context(
app_config,
{
...
"foo": SQLAlchemySession(),
...
}
)
configure it in your application’s configuration file:
[app:main]
...
# required: sqlalchemy URL describing a database to connect to
foo.url = postgresql://postgres.local:6543/bar
# optional: the name of a CredentialSecret holding credentials for
# authenticating to the database
foo.credentials_secret = secret/my_service/db-foo
...
and then use the attached Session
object in
request:
def my_method(request):
request.foo.query(MyModel).filter_by(...).all()
Configuration¶
-
class
baseplate.clients.sqlalchemy.
SQLAlchemySession
(secrets=None, **kwargs)[source]¶ Configure a SQLAlchemy Session.
This is meant to be used with
baseplate.Baseplate.configure_context()
.See
engine_from_config()
for available configuration settings.Parameters: secrets ( Optional
[SecretsStore
]) – Required if configured to use credentials to talk to the database.
-
baseplate.clients.sqlalchemy.
engine_from_config
(app_config, secrets=None, prefix='database.', **kwargs)[source]¶ Make an
Engine
from a configuration dictionary.The keys useful to
engine_from_config()
should be prefixed, e.g.database.url
, etc. Theprefix
argument specifies the prefix used to filter keys.Supported keys:
url
: the connection URL to the database, passed tomake_url()
to create theURL
used to connect to the database.
credentials_secret
(optional): the key used to retrieve the database- credentials from
secrets
as aCredentialSecret
. If this is supplied, any credentials given inurl
we be replaced by these.
pool_recycle
(optional): this setting causes the pool to recycle connections after- the given number of seconds has passed. It defaults to -1, or no timeout.
pool_pre_ping
(optional): when set to true, this setting causes- sqlalchemy to perform a liveness-check query each time a connection is checked out of the pool. If the liveness-check fails, the connection is gracefully recycled. This ensures severed connections are handled more gracefully, at the cost of doing a SELECT 1 at the start of each checkout. When used, this obviates most of the reasons you might use pool_recycle, and as such they shouldn’t normally be used simultaneously. Requires SQLAlchemy 1.3.
Return type: Engine
Classes¶
-
class
baseplate.clients.sqlalchemy.
SQLAlchemyEngineContextFactory
(engine)[source]¶ SQLAlchemy core engine context factory.
This factory will attach a SQLAlchemy
sqlalchemy.engine.Engine
to an attribute on theRequestContext
. All cursor (query) execution will automatically record diagnostic information.Additionally, the trace and span ID will be added as a comment to the text of the SQL statement. This is to aid correlation of queries with requests.
See also
The engine is the low-level SQLAlchemy API. If you want to use the ORM, consider using
SQLAlchemySessionContextFactory
instead.Parameters: engine ( Engine
) – A configured SQLAlchemy engine.
-
class
baseplate.clients.sqlalchemy.
SQLAlchemySessionContextFactory
(engine)[source]¶ SQLAlchemy ORM session context factory.
This factory will attach a new SQLAlchemy
sqlalchemy.orm.session.Session
to an attribute on theRequestContext
. All cursor (query) execution will automatically record diagnostic information.The session will be automatically closed, but not committed or rolled back, at the end of each request.
See also
The session is part of the high-level SQLAlchemy ORM API. If you want to do raw queries, consider using
SQLAlchemyEngineContextFactory
instead.Parameters: engine ( Engine
) – A configured SQLAlchemy engine.
Runtime Metrics¶
In addition to request-level metrics reported through spans, this wrapper reports connection pool statistics periodically via the Process-level metrics system. All metrics are prefixed as follows:
{namespace}.runtime.{hostname}.PID{pid}.clients.{name}
where namespace
is the application’s namespace, hostname
and pid
come from the operating system, and name
is the name given to
add_to_context()
when registering this
context factory.
The following metrics are reported:
pool.size
- The size limit for the connection pool.
pool.open_and_available
- How many connections have been established but are sitting available for use in the connection pool.
pool.in_use
- How many connections have been established and are currently checked out and being used.
pool.overflow
- How many connections beyond the pool size are currently being used. See
sqlalchemy.pool.QueuePool
for more information.