gino.engine module¶

class gino.engine.GinoConnection(dialect, sa_conn, stack=None)¶

Bases: object

Represents an actual database connection.

This is the root of all query API like all(), first(), one(), one_or_none(), scalar() or status(), those on engine or query are simply wrappers of methods in this class.

Usually instances of this class are created by GinoEngine.acquire().

Note

GinoConnection may refer to zero or one underlying database connection - when a GinoConnection is acquired with lazy=True, the underlying connection may still be in the pool, until a query API is called or get_raw_connection() is called.

Oppositely, one underlying database connection can be shared by many GinoConnection instances when they are acquired with reuse=True. The actual database connection is only returned to the pool when the root GinoConnection is released. Read more in GinoEngine.acquire() method.

See also

Engine and Connection

async all(clause, *multiparams, **params)¶

Runs the given query in database, returns all results as a list.

This method accepts the same parameters taken by SQLAlchemy execute(). You can pass in a raw SQL string, or any SQLAlchemy query clauses.

If the given query clause is built by CRUD models, then the returning rows will be turned into relevant model objects (Only one type of model per query is supported for now, no relationship support yet). See execution_options() for more information.

If the given parameters are parsed as “executemany” - bulk inserting multiple rows in one call for example, the returning result from database will be discarded and this method will return None.

property dialect¶: The Dialect in use, inherited from the engine created this connection.

execution_options(**opt)¶

Set non-SQL options for the connection which take effect during execution.

This method returns a copy of this GinoConnection which references the same underlying database connection, but with the given execution options set on the copy. Therefore, it is a good practice to discard the copy immediately after use, for example:

row = await conn.execution_options(model=None).first(User.query)

This is very much the same as SQLAlchemy execution_options(), it actually does pass the execution options to the underlying SQLAlchemy Connection. Furthermore, GINO added a few execution options:

Parameters

return_model – Boolean to control whether the returning results should be loaded into model instances, where the model class is defined in another execution option model. Default is True.
model – Specifies the type of model instance to create on return. This has no effect if return_model is set to False. Usually in queries built by CRUD models, this execution option is automatically set. For now, GINO only supports loading each row into one type of model object, relationships are not supported. Please use multiple queries for that. None for no postprocessing (default).
timeout – Seconds to wait for the query to finish. None for no time out (default).
loader –
A loader expression to load the database rows into specified objective structure. It can be either:
- A model class, so that the query will yield model instances of this class. It is your responsibility to make sure all the columns of this model is selected in the query.
- A Column instance, so that each result will be only a single value of this column. Please note, if you want to achieve fetching the very first value, you should use first() instead of scalar(). However, using directly scalar() is a more direct way.
- A tuple nesting more loader expressions recursively.
- A callable() function that will be called for each row to fully customize the result. Two positional arguments will be passed to the function: the first is the row instance, the second is a context object which is only present if nested else None.
- A Loader instance directly.
- Anything else will be treated as literal values thus returned as whatever they are.

async first(clause, *multiparams, **params)¶

Runs the given query in database, returns the first result.

If the query returns no result, this method will return None.

See all() for common query comments.

async get_raw_connection(*, timeout=None)¶

Get the underlying database connection, acquire one if none present.

Parameters: timeout – Seconds to wait for the underlying acquiring
Returns: Underlying database connection instance depending on the dialect in use
Raises: TimeoutError if the acquiring timed out

iterate(clause, *multiparams, **params)¶

Creates a server-side cursor in database for large query results.

Cursors must work within transactions:

async with conn.transaction():
    async for user in conn.iterate(User.query):
        # handle each user without loading all users into memory

Alternatively, you can manually control how the cursor works:

async with conn.transaction():
    cursor = await conn.iterate(User.query)
    user = await cursor.next()
    users = await cursor.many(10)

See also

GinoEngine.acquire()

async scalar(clause, *multiparams, **params)¶

Runs the given query in database, returns the first result.

If the query returns no result, this method will return None.

See all() for common query comments.

schema_for_object = <sqlalchemy.sql.schema._SchemaTranslateMap object>¶: A SQLAlchemy compatibility attribute, don’t use it for now, it bites.

async status(clause, *multiparams, **params)¶

Runs the given query in database, returns the query status.

The returning query status depends on underlying database and the dialect in use. For asyncpg it is a string, you can parse it like this: https://git.io/v7oze

transaction(*args, **kwargs)¶

Starts a database transaction.

There are two ways using this method: managed as an asynchronous context manager:

async with conn.transaction() as tx:
    # run query in transaction

or manually awaited:

tx = await conn.transaction()
try:
    # run query in transaction
    await tx.commit()
except Exception:
    await tx.rollback()
    raise

Where the tx is an instance of the GinoTransaction class, feel free to read more about it.

In the first managed mode, the transaction is automatically committed on exiting the context block, or rolled back if an exception was raised which led to the exit of the context. In the second manual mode, you’ll need to manually call the commit() or rollback() methods on need.

If this is a lazy connection, entering a transaction will cause a new database connection acquired if none was present.

Transactions may support nesting depending on the dialect in use. For example in asyncpg, starting a second transaction on the same connection will create a save point in the database.

For now, the parameters are directly passed to underlying database driver, read asyncpg.connection.Connection.transaction() for asyncpg.

class gino.engine.GinoEngine(dialect, pool, loop, logging_name=None, echo=None, execution_options=None)¶

Bases: object

Connects a Pool and Dialect together to provide a source of database connectivity and behavior.

A GinoEngine object is instantiated publicly using the gino.create_engine() function or db.set_bind() method.

See also

Engine and Connection

acquire(*, timeout=None, reuse=False, lazy=False, reusable=True)¶

Acquire a connection from the pool.

There are two ways using this method - as an asynchronous context manager:

async with engine.acquire() as conn:
    # play with the connection

which will guarantee the connection is returned to the pool when leaving the async with block; or as a coroutine:

conn = await engine.acquire()
try:
    # play with the connection
finally:
    await conn.release()

where the connection should be manually returned to the pool with conn.release().

Within the same context (usually the same Task, see also Transaction), a nesting acquire by default re

Parameters

timeout – Block up to timeout seconds until there is one free connection in the pool. Default is None - block forever until succeeded. This has no effect when lazy=True, and depends on the actual situation when reuse=True.
reuse – Reuse the latest reusable acquired connection (before it’s returned to the pool) in current context if there is one, or borrow a new one if none present. Default is False for always borrow a new one. This is useful when you are in a nested method call series, wishing to use the same connection without passing it around as parameters. See also: Transaction. A reusing connection is not reusable even if reusable=True. If the reused connection happened to be a lazy one, then the reusing connection is lazy too.
lazy – Don’t acquire the actual underlying connection yet - do it only when needed. Default is False for always do it immediately. This is useful before entering a code block which may or may not make use of a given connection object. Feeding in a lazy connection will save the borrow-return job if the connection is never used. If setting reuse=True at the same time, then the reused connection - if any - applies the same laziness. For example, reusing a lazy connection with lazy=False will cause the reused connection to acquire an underlying connection immediately.
reusable – Mark this connection as reusable or otherwise. This has no effect if it is a reusing connection. All reusable connections are placed in a stack, any reusing acquire operation will always reuse the top (latest) reusable connection. One reusable connection may be reused by several reusing connections - they all share one same underlying connection. Acquiring a connection with reusable=False and reusing=False makes it a cleanly isolated connection which is only referenced once here.

Returns

A GinoConnection object.

async all(clause, *multiparams, **params)¶

Acquires a connection with reuse=True and runs all() on it. reuse=True means you can safely do this without borrowing more than one underlying connection:

async with engine.acquire():
    await engine.all('SELECT ...')

The same applies for other query methods.

async close()¶: Close the engine, by closing the underlying pool.

compile(clause, *multiparams, **params)¶: A shortcut for compile() on the dialect, returns raw SQL string and parameters according to the rules of the dialect.

connection_cls¶

Customizes the connection class to use, default is GinoConnection.

alias of GinoConnection

property current_connection¶

Gets the most recently acquired reusable connection in the context. None if there is no such connection.

Returns: GinoConnection

property dialect¶: Read-only property for the Dialect of this engine.

async first(clause, *multiparams, **params)¶: Runs first(), See all().

iterate(clause, *multiparams, **params)¶

Creates a server-side cursor in database for large query results.

This requires that there is a reusable connection in the current context, and an active transaction is present. Then its GinoConnection.iterate() is executed and returned.

async one(clause, *multiparams, **params)¶: Runs one(), See all().

async one_or_none(clause, *multiparams, **params)¶: Runs one_or_none(), See all().

property raw_pool¶: Read-only access to the underlying database connection pool instance. This depends on the actual dialect in use, Pool of asyncpg for example.

repr(color=False)¶

async scalar(clause, *multiparams, **params)¶: Runs scalar(), See all().

async status(clause, *multiparams, **params)¶: Runs status(). See also all().

transaction(*args, timeout=None, reuse=True, reusable=True, **kwargs)¶

Borrows a new connection and starts a transaction with it.

Different to GinoConnection.transaction(), transaction on engine level supports only managed usage:

async with engine.transaction() as tx:
    # play with transaction here

Where the implicitly acquired connection is available as tx.connection.

By default, transaction() acquires connection with reuse=True and reusable=True, that means it by default tries to create a nested transaction instead of a new transaction on a new connection. You can change the default behavior by setting these two arguments.

The other arguments are the same as transaction() on connection.

See also

GinoEngine.acquire()

GinoConnection.transaction()

GinoTransaction