From: Mike Bayer Date: Fri, 24 Jan 2014 00:38:46 +0000 (-0500) Subject: - doc updates, include links to create_engine from tutorials, cleanup X-Git-Tag: rel_0_8_5~43 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=802b9adc41b0f16e7ada02dbbe90f8d823095574;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - doc updates, include links to create_engine from tutorials, cleanup and modernize the engines chapter a bit Conflicts: doc/build/changelog/changelog_09.rst doc/build/orm/tutorial.rst --- diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index 8d34ab5c62..fb0320474c 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -39,7 +39,6 @@ covers the details of configuring an :class:`.Engine`. The next section, :ref: will detail the usage API of the :class:`.Engine` and similar, typically for non-ORM applications. - .. _supported_dbapis: Supported Databases @@ -51,48 +50,36 @@ of others require an additional install of a separate dialect. See the section :ref:`dialect_toplevel` for information on the various backends available. - - -.. _create_engine_args: - -Engine Creation API -=================== - -Keyword options can also be specified to :func:`~sqlalchemy.create_engine`, -following the string URL as follows: - -.. sourcecode:: python+sql - - db = create_engine('postgresql://...', encoding='latin1', echo=True) - -.. autofunction:: sqlalchemy.create_engine - -.. autofunction:: sqlalchemy.engine_from_config +.. _database_urls: Database Urls ============= -SQLAlchemy indicates the source of an Engine strictly via `RFC-1738 -`_ style URLs, combined with optional keyword -arguments to specify options for the Engine. The form of the URL is:: +The :func:`.create_engine` function produces an :class:`.Engine` object based +on a URL. These URLs follow `RFC-1738 +`_, and usually can include username, password, +hostname, database name as well as optional keyword arguments for additional configuration. +In some cases a file path is accepted, and in others a "data source name" replaces +the "host" and "database" portions. The typical form of a database URL is:: dialect+driver://username:password@host:port/database -Dialect names include the identifying name of the SQLAlchemy dialect which -include ``sqlite``, ``mysql``, ``postgresql``, ``oracle``, ``mssql``, and -``firebird``. The drivername is the name of the DBAPI to be used to connect to +Dialect names include the identifying name of the SQLAlchemy dialect, +a name such as ``sqlite``, ``mysql``, ``postgresql``, ``oracle``, or ``mssql``. +The drivername is the name of the DBAPI to be used to connect to the database using all lowercase letters. If not specified, a "default" DBAPI will be imported if available - this default is typically the most widely -known driver available for that backend (i.e. cx_oracle, pysqlite/sqlite3, -psycopg2, mysqldb). For Jython connections, specify the `zxjdbc` driver, which -is the JDBC-DBAPI bridge included with Jython. +known driver available for that backend. -.. autofunction:: sqlalchemy.engine.url.make_url +Examples for common connection styles follow below. For a full index of +detailed information on all included dialects as well as links to third-party dialects, see +:ref:`dialect_toplevel`. Postgresql ---------- -The Postgresql dialect uses psycopg2 as the default DBAPI:: +The Postgresql dialect uses psycopg2 as the default DBAPI. pg8000 is +also available as a pure-Python substitute:: # default engine = create_engine('postgresql://scott:tiger@localhost/mydatabase') @@ -103,15 +90,13 @@ The Postgresql dialect uses psycopg2 as the default DBAPI:: # pg8000 engine = create_engine('postgresql+pg8000://scott:tiger@localhost/mydatabase') - # Jython - engine = create_engine('postgresql+zxjdbc://scott:tiger@localhost/mydatabase') - More notes on connecting to Postgresql at :ref:`postgresql_toplevel`. MySQL ----- -The MySQL dialect uses mysql-python as the default DBAPI:: +The MySQL dialect uses mysql-python as the default DBAPI. There are many +MySQL DBAPIs available, including MySQL-connector-python and OurSQL:: # default engine = create_engine('mysql://scott:tiger@localhost/foo') @@ -119,6 +104,9 @@ The MySQL dialect uses mysql-python as the default DBAPI:: # mysql-python engine = create_engine('mysql+mysqldb://scott:tiger@localhost/foo') + # MySQL-connector-python + engine = create_engine('mysql+mysqlconnector://scott:tiger@localhost/foo') + # OurSQL engine = create_engine('mysql+oursql://scott:tiger@localhost/foo') @@ -127,7 +115,7 @@ More notes on connecting to MySQL at :ref:`mysql_toplevel`. Oracle ------ -cx_oracle is usually used here:: +The Oracle dialect uses cx_oracle as the default DBAPI:: engine = create_engine('oracle://scott:tiger@127.0.0.1:1521/sidname') @@ -138,24 +126,33 @@ More notes on connecting to Oracle at :ref:`oracle_toplevel`. Microsoft SQL Server -------------------- -There are a few drivers for SQL Server, currently PyODBC is the most solid:: +The SQL Server dialect uses pyodbc as the default DBAPI. pymssql is +also available:: + + # pyodbc + engine = create_engine('mssql+pyodbc://scott:tiger@mydsn') - engine = create_engine('mssql+pyodbc://mydsn') + # pymssql + engine = create_engine('mssql+pymssql://scott:tiger@hostname:port/dbname') More notes on connecting to SQL Server at :ref:`mssql_toplevel`. SQLite ------ -SQLite connects to file based databases. The same URL format is used, omitting -the hostname, and using the "file" portion as the filename of the database. -This has the effect of four slashes being present for an absolute file path:: +SQLite connects to file-based databases, using the Python built-in +module ``sqlite3`` by default. + +As SQLite connects to local files, the URL format is slightly different. +The "file" portion of the URL is the filename of the database. +For a relative file path, this requires three slashes:: # sqlite:/// # where is relative: engine = create_engine('sqlite:///foo.db') - # or absolute, starting with a slash: +And for an absolute file path, *four* slashes are used:: + engine = create_engine('sqlite:////absolute/path/to/foo.db') To use a SQLite ``:memory:`` database, specify an empty URL:: @@ -167,11 +164,20 @@ More notes on connecting to SQLite at :ref:`sqlite_toplevel`. Others ------ -See :ref:`dialect_toplevel`, the top-level page for all dialect +See :ref:`dialect_toplevel`, the top-level page for all additional dialect documentation. -URL API --------- +.. _create_engine_args: + +Engine Creation API +=================== + +.. autofunction:: sqlalchemy.create_engine + +.. autofunction:: sqlalchemy.engine_from_config + +.. autofunction:: sqlalchemy.engine.url.make_url + .. autoclass:: sqlalchemy.engine.url.URL :members: @@ -198,7 +204,6 @@ application, rather than creating a new one for each connection. For more information on connection pooling, see :ref:`pooling_toplevel`. - .. _custom_dbapi_args: Custom DBAPI connect() arguments diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index ee49701dbc..b785f9b9d4 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -77,6 +77,28 @@ and want less output generated, set it to ``False``. This tutorial will format the SQL behind a popup window so it doesn't get in our way; just click the "SQL" links to see what's being generated. +The return value of :func:`.create_engine` is an instance of +:class:`.Engine`, and it represents the core interface to the +database, adapted through a :term:`dialect` that handles the details +of the database and :term:`DBAPI` in use. In this case the SQLite +dialect will interpret instructions to the Python built-in ``sqlite3`` +module. + +.. sidebar:: Lazy Connecting + + The :class:`.Engine`, when first returned by :func:`.create_engine`, + has not actually tried to connect to the database yet; that happens + only the first time it is asked to perform a task against the database. + +The first time a method like :meth:`.Engine.execute` or :meth:`.Engine.connect` +is called, the :class:`.Engine` establishes a real :term:`DBAPI` connection to the +database, which is then used to emit the SQL. + +.. seealso:: + + :ref:`database_urls` - includes examples of :func:`.create_engine` + connecting to several kinds of databases with links to more information. + Define and Create Tables ========================= diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index c824333e7d..c8a1606a0b 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -64,10 +64,12 @@ and want less output generated, set it to ``False``. This tutorial will format the SQL behind a popup window so it doesn't get in our way; just click the "SQL" links to see what's being generated. -The return value of :func:`.create_engine` is an instance of :class:`.Engine`, and it represents -the core interface to the database, adapted through a **dialect** that handles the details -of the database and DBAPI in use. In this case the SQLite dialect will interpret instructions -to the Python built-in ``sqlite3`` module. +The return value of :func:`.create_engine` is an instance of +:class:`.Engine`, and it represents the core interface to the +database, adapted through a :term:`dialect` that handles the details +of the database and :term:`DBAPI` in use. In this case the SQLite +dialect will interpret instructions to the Python built-in ``sqlite3`` +module. The :class:`.Engine` has not actually tried to connect to the database yet; that happens only the first time it is asked to perform a task against the database. We can illustrate @@ -86,6 +88,11 @@ connection pool where it will be reused on subsequent statement executions. Whi :class:`.Engine` here, this isn't typically necessary when using the ORM, where the :class:`.Engine`, once created, is used behind the scenes by the ORM as we'll see shortly. +.. seealso:: + + :ref:`database_urls` - includes examples of :func:`.create_engine` + connecting to several kinds of databases with links to more information. + Declare a Mapping ================= diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index 0a5a96784a..b5963edbca 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -93,25 +93,32 @@ def create_engine(*args, **kwargs): The standard calling form is to send the URL as the first positional argument, usually a string - that indicates database dialect and connection arguments. + that indicates database dialect and connection arguments:: + + + engine = create_engine("postgresql://scott:tiger@localhost/test") + Additional keyword arguments may then follow it which establish various options on the resulting :class:`.Engine` and its underlying :class:`.Dialect` and :class:`.Pool` - constructs. + constructs:: + + engine = create_engine("mysql://scott:tiger@hostname/dbname", + encoding='latin1', echo=True) The string form of the URL is - ``dialect+driver://user:password@host/dbname[?key=value..]``, where + ``dialect[+driver]://user:password@host/dbname[?key=value..]``, where ``dialect`` is a database name such as ``mysql``, ``oracle``, ``postgresql``, etc., and ``driver`` the name of a DBAPI, such as ``psycopg2``, ``pyodbc``, ``cx_oracle``, etc. Alternatively, the URL can be an instance of :class:`~sqlalchemy.engine.url.URL`. ``**kwargs`` takes a wide variety of options which are routed - towards their appropriate components. Arguments may be specific - to the :class:`.Engine`, the underlying :class:`.Dialect`, as well as - the :class:`.Pool`. Specific dialects also accept keyword - arguments that are unique to that dialect. Here, we describe the - parameters that are common to most :func:`.create_engine()` usage. + towards their appropriate components. Arguments may be specific to + the :class:`.Engine`, the underlying :class:`.Dialect`, as well as the + :class:`.Pool`. Specific dialects also accept keyword arguments that + are unique to that dialect. Here, we describe the parameters + that are common to most :func:`.create_engine()` usage. Once established, the newly resulting :class:`.Engine` will request a connection from the underlying :class:`.Pool` once @@ -121,11 +128,13 @@ def create_engine(*args, **kwargs): is received. The :func:`.create_engine` call itself does **not** establish any actual DBAPI connections directly. - See also: + .. seealso:: + + :doc:`/core/engines` - :doc:`/core/engines` + :doc:`/dialects/index` - :ref:`connections_toplevel` + :ref:`connections_toplevel` :param case_sensitive=True: if False, result column names will match in a case-insensitive fashion, that is,