From fe92bf74c3d2be1a59986fc5c18bd4169f3017c5 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Thu, 27 Oct 2005 07:03:59 +0000 Subject: [PATCH] --- doc/build/components/formatting.myt | 2 +- doc/build/content/dbengine.myt | 53 +++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 1 deletion(-) diff --git a/doc/build/components/formatting.myt b/doc/build/components/formatting.myt index 1572998924..17146d171e 100644 --- a/doc/build/components/formatting.myt +++ b/doc/build/components/formatting.myt @@ -198,7 +198,7 @@ <%method paramtable> - +
<% m.content() %>
diff --git a/doc/build/content/dbengine.myt b/doc/build/content/dbengine.myt index 929059e4c7..4115084528 100644 --- a/doc/build/content/dbengine.myt +++ b/doc/build/content/dbengine.myt @@ -1,7 +1,60 @@ <%flags>inherit='document_base.myt' <&|doclib.myt:item, name="dbengine", description="Database Engines" &> +

A database engine is a subclass of sqlalchemy.engine.SQLEngine, and is the starting point for where SQLAlchemy provides a layer of abstraction on top of the various DBAPI2 database modules. It serves as an abstract factory for database-specific implementation objects as well as a layer of abstraction over the most essential tasks of a database connection, including connecting, executing queries, returning result sets, and managing transactions.

+ +

+ The average developer doesn't need to know anything about the interface or workings of a SQLEngine in order to use it. Simply creating one, and then specifying it when constructing tables and other SQL objects is all that's needed.

+ +

A SQLEngine is also a layer of abstraction on top of the connection pooling described in the previous section. While a DBAPI connection pool can be used explicitly alongside a SQLEngine, its not really necessary. Once you have a SQLEngine, you can retrieve pooled connections directly from its underlying connection pool via its own connection() method. However, if you're exclusively using SQLALchemy's SQL construction objects and/or object-relational mappers, all the details of connecting are handled by those libraries automatically. +

<&|doclib.myt:item, name="establishing", description="Establishing a Database Engine" &> +

+ Engines exist for SQLite, Postgres, and Oracle, using the Pysqlite, Psycopg (1 or 2), and cx_Oracle modules. Each engine imports its corresponding module which is required to be installed. For Postgres and Oracle, an alternate module may be specified at construction time as well. +

+

An example of connecting to each engine is as follows:

+ + <&|formatting.myt:code&> + import sqlalchemy.engine as engine + + # sqlite in memory + sqlite_engine = engine.create_engine('sqlite', ':memory:', {}, **opts) + + # sqlite using a file + sqlite_engine = engine.create_engine('sqlite', 'querytest.db', {}, **opts) + + # postgres + postgres_engine = engine.create_engine('postgres', + {'database':'test', + 'host':'127.0.0.1', + 'user':'scott', + 'password':'tiger'}, **opts) + + # oracle + oracle_engine = engine.create_engine('oracle', + {'dsn':'mydsn', + 'user':'scott', + 'password':'tiger'}, **opts) + + + +

Note that the general form of connecting to an engine is:

+ <&|formatting.myt:code&> + engine = sqlalchemy.engine.create_engine( + , + {}, + + ) + +

The second argument is a dictionary whose key/value pairs will be passed to the underlying DBAPI connect() method as keyword arguments. Any keyword argument supported by the DBAPI module can be in this dictionary.

<&|doclib.myt:item, name="options", description="Database Engine Options" &> +

The remaining arguments to create_engine are keyword arguments that are passed to the specific subclass of sqlalchemy.engine.SQLEngine being used, as well as the underlying sqlalchemy.pool.Pool instance. All of the options described in the previous section <&formatting.myt:link, path="pooling_configuration"&> can be specified, as well as engine-specific options:

+
    +
  • pool=None : an instance of sqlalchemy.pool.DBProxy to be used as the underlying source for connections (DBProxy is described in the previous section). If None, a default DBProxy will be created using the engine's own database module with the given arguments.
    • +
  • echo=False : if True, the SQLEngine will log all statements as well as a repr() of their parameter lists to the engines logger, which defaults to sys.stdout. A SQLEngine instances' "echo" data member can be modified at any time to turn logging on and off.
    • +
  • logger=None : a file-like object where logging output can be sent, if echo is set to True. This defaults to sys.stdout.
    • +
  • module=None : used by Oracle and Postgres, this is a reference to a DBAPI2 module to be used instead of the engine's default module. For Postgres, the default is psycopg2, or psycopg1 if 2 cannot be found. For Oracle, its cx_Oracle.
    • +
  • use_ansi=True : used only by Oracle; when False, the Oracle driver attempts to support a particular "quirk" of some Oracle databases, that the LEFT OUTER JOIN SQL syntax is not supported, and the "Oracle join" syntax of using <% "(+)=" |h%> must be used in order to achieve a LEFT OUTER JOIN. Its advised that the Oracle database be configured to have full ANSI support instead of using this feature.
    • +
\ No newline at end of file -- 2.47.2