Viz Engine Documentation

[Athenasby Regalado]

Theabove engine creates a Dialect object tailored towardsPostgreSQL, as well as a Pool object which will establish aDBAPI connection at localhost:5432 when a connection request is firstreceived. Note that the Engine and its underlyingPool do not establish the first actual DBAPI connectionuntil the Engine.connect() or Engine.begin()methods are called. Either of these methods may also be invoked by otherSQLAlchemy Engine dependent objects such as the ORMSession object when they first require database connectivity.In this way, Engine and Pool can be said tohave a lazy initialization behavior.

The Engine, once created, can either be used directly to interact with the database,or can be passed to a Session object to work with the ORM. This sectioncovers the details of configuring an Engine. The next section, Working with Engines and Connections,will detail the usage API of the Engine and similar, typically for non-ORMapplications.

SQLAlchemy includes many Dialect implementations for variousbackends. Dialects for the most common databases are included with SQLAlchemy; a handfulof others require an additional install of a separate dialect.

When constructing a fully formed URL string to pass tocreate_engine(), special characters such as those that maybe used in the user and password need to be URL encoded to be parsed correctly..This includes the @ sign.

As an alternative to escaping special characters in order to create a completeURL string, the object passed to create_engine() may instead be aninstance of the URL object, which bypasses the parsingphase and can accommodate for unescaped strings directly. See the nextsection for an example.

The value passed to create_engine() may be an instance ofURL, instead of a plain string, which bypasses the need for stringparsing to be used, and therefore does not need an escaped URL string to beprovided.

The string form of the URL isdialect[+driver]://user:password@host/dbname[?key=value..], wheredialect is a database name such as mysql, oracle,postgresql, etc., and driver the name of a DBAPI, such aspsycopg2, pyodbc, cx_oracle, etc. Alternatively,the URL can be an instance of URL.

**kwargs takes a wide variety of options which are routedtowards their appropriate components. Arguments may be specific tothe Engine, the underlying Dialect,as well as thePool. Specific dialects also accept keyword arguments thatare unique to that dialect. Here, we describe the parametersthat are common to most create_engine() usage.

Once established, the newly resulting Engine willrequest a connection from the underlying Pool onceEngine.connect() is called, or a method which depends on itsuch as Engine.execute() is invoked. ThePool in turnwill establish the first actual DBAPI connection when this requestis received. The create_engine() call itself does notestablish any actual DBAPI connections directly.

This hook is not as flexible as the newerDialectEvents.do_connect() hook which allows completecontrol over how a connection is made to the database, given the fullset of URL arguments and state beforehand.

The create_engine.isolation_level parameter isin contrast to theConnection.execution_options.isolation_levelexecution option, which may be set on an individualConnection, as well as the same parameter passed toEngine.execution_options(), where it may be used to createmultiple engines with different isolation levels that share a commonconnection pool and dialect.

Changed in version 2.0: Thecreate_engine.isolation_levelparameter has been generalized to work on all dialects which supportthe concept of isolation level, and is provided as a more succinct,up front configuration switch in contrast to the execution optionwhich is more of an ad-hoc programmatic option.

The cache is pruned of its least recently used items when its size reachesN * 1.5. Defaults to 500, meaning the cache will always store at least500 SQL statements when filled, and will grow up to 750 items at whichpoint it is pruned back down to 500 by removing the 250 least recentlyused items.

URLs are typically constructed from a fully formatted URL string, where themake_url() function is used internally by thecreate_engine() function in order to parse the URL string intoits individual components, which are then used to construct a newURL object. When parsing from a formatted URL string, the parsingformat generally followsRFC-1738, with some exceptions.

Changed in version 1.4: The URL object is now an immutable object. Tocreate a URL, use the make_url() orURL.create() function / method. To modifya URL, use methods likeURL.set() andURL.update_query_dict() to return a newURL object with modifications. See notes for thischange at The URL object is now immutable.

Returns attributes of this url (host, database, username,password, port) as a plain dictionary. The attribute names areused as the keys by default. Unset or false attributes are omittedfrom the final dictionary.

For cases where special connection methods are needed, in the vast majorityof cases, it is most appropriate to use one of several hooks at thecreate_engine() level in order to customize this process. Theseare described in the following sub-sections.

All Python DBAPIs accept additional arguments beyond the basics of connecting.Common parameters include those to specify character set encodings and timeoutvalues; more complex data includes special DBAPI constants and objects and SSLsub-parameters. There are two rudimentary means of passing these argumentswithout complexity.

Simple string values, as well as some numeric values and boolean flags, may beoften specified in the query string of the URL directly. A common example ofthis is DBAPIs that accept an argument encoding for character encodings,such as most MySQL DBAPIs:

Beyond manipulating the parameters passed to connect(), we can furthercustomize how the DBAPI connect() function itself is called using theDialectEvents.do_connect() event hook. This hook is passed the full*args, **kwargs that the dialect would send to connect(). Thesecollections can then be modified in place to alter how they are used:

DialectEvents.do_connect() is also an ideal way to dynamicallyinsert an authentication token that might change over the lifespan of anEngine. For example, if the token gets generated byget_authentication_token() and passed to the DBAPI in a tokenparameter, this could be implemented as:

The DialectEvents.do_connect() hook supersedes the previouscreate_engine.creator hook, which remains available.DialectEvents.do_connect() has the distinct advantage that thecomplete arguments parsed from the URL are also passed to the user-definedfunction which is not the case with create_engine.creator.

This section assumes familiarity with the above linked logging module. Alllogging performed by SQLAlchemy exists underneath the sqlalchemynamespace, as used by logging.getLogger('sqlalchemy'). When logging hasbeen configured (i.e. such as via logging.basicConfig()), the generalnamespace of SA loggers that can be turned on is as follows:

sqlalchemy.engine - controls SQL echoing. Set to logging.INFO forSQL query output, logging.DEBUG for query + result set output. Thesesettings are equivalent to echo=True and echo="debug" oncreate_engine.echo, respectively.

sqlalchemy.pool - controls connection pool logging. Set tologging.INFO to log connection invalidation and recycle events; set tologging.DEBUG to additionally log all pool checkins and checkouts.These settings are equivalent to pool_echo=True and pool_echo="debug"on create_engine.echo_pool, respectively.

sqlalchemy.orm - controls logging of various ORM functions to the extentthat logging is used within the ORM, which is generally minimal. Set tologging.INFO to log some top-level information on mapper configurations.

The logger name of instance such as an Engine orPool defaults to using a truncated hex identifierstring. To set this to a specific name, use thecreate_engine.logging_name andcreate_engine.pool_logging_name withsqlalchemy.create_engine(); the name will be appended to the logging namesqlalchemy.engine.Engine:

The create_engine.logging_name andcreate_engine.pool_logging_name parameters may also be used inconjunction with create_engine.echo andcreate_engine.echo_pool. However, an unavoidable double loggingcondition will occur if other engines are created with echo flags set to Trueand no logging name. This is because a handler will be added automaticallyfor sqlalchemy.engine.Engine which will log messages both for the name-lessengine as well as engines with logging names. For example:

For this use case, the log message itself generated by theConnection and Result objects may beaugmented with additional tokens such as transaction or request identifiers.The Connection.execution_options.logging_token parameteraccepts a string argument that may be used to establish per-connection trackingtokens:

The Connection.execution_options.logging_token parametermay also be established on engines or sub-engines viacreate_engine.execution_options or Engine.execution_options().This may be useful to apply different logging tokens to different componentsof an application without creating new engines:

The logging emitted by Engine also indicates an excerptof the SQL parameters that are present for a particular statement. To preventthese parameters from being logged for privacy purposes, enable thecreate_engine.hide_parameters flag:

The visual aspects of the Unity Editor including camerasA component which creates an image of a particular viewpoint in your scene. The output is either drawn to the screen or captured as a texture. More info

See in Glossary and lighting.

Simulation of 3D motion, mass, gravity and collisionsA collision occurs when the physics engine detects that the colliders of two GameObjects make contact or overlap, when at least one has a Rigidbody component and is in motion. More info

See in Glossary.

3a8082e126