will detail the usage API of the :class:`.Engine` and similar, typically for non-ORM
applications.
-
.. _supported_dbapis:
Supported Databases
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
-<http://rfc.net/rfc1738.html>`_ 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
+<http://rfc.net/rfc1738.html>`_, 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')
# 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')
# 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')
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')
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://<nohostname>/<path>
# where <path> 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::
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:
For more information on connection pooling, see :ref:`pooling_toplevel`.
-
.. _custom_dbapi_args:
Custom DBAPI connect() arguments
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
=========================
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
: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
=================
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
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,
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
