psycopg/psycopg2
1
1
Fork 0
mirror of https://github.com/psycopg/psycopg2.git synced 2024-11-29 04:13:43 +03:00
Code Issues Packages Projects Releases Wiki Activity

Improvements to the connect() docs

Browse Source 
- links updated to the current PG docs, which include the syntax as url
  and lists the parameters in a separate chapter
- more evident links to the PG docs
- mutually exclusive use of dsn and **kwargs specified

See ticket #143
This commit is contained in:
Daniele Varrazzo 2013-01-09 12:56:06 +00:00
parent 49af4fe539
commit e8db9954d1
1 changed files with 32 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/src/module.rst
View File

@ -16,11 +16,14 @@ The module interface respects the standard defined in the |DBAPI|_.
single: Port; Connection
single: DSN (Database Source Name)
.. function:: connect(dsn or params [, connection_factory] [, async=0])
.. function::
connect(dsn, connection_factory=None, async=False)
connect(\*\*kwargs, connection_factory=None, async=False)
Create a new database session and return a new `connection` object.
The connection parameters can be specified either as a string::
The connection parameters can be specified either as a `libpq connection
string`__ using the *dsn* parameter::
conn = psycopg2.connect("dbname=test user=postgres password=secret")
@ -28,9 +31,14 @@ The module interface respects the standard defined in the |DBAPI|_.
conn = psycopg2.connect(database="test", user="postgres", password="secret")
The two call styles are mutually exclusive: you cannot specify connection
parameters as keyword arguments together with a connection string; only
*connection_factory* and *async* are supported together with the *dsn*
argument.
The basic connection parameters are:
- `!dbname` -- the database name (only in dsn string)
- `!dbname` -- the database name (only in the *dsn* string)
- `!database` -- the database name (only as keyword argument)
- `!user` -- user name used to authenticate
- `!password` -- password used to authenticate
@ -38,26 +46,40 @@ The module interface respects the standard defined in the |DBAPI|_.
- `!port` -- connection port number (defaults to 5432 if not provided)
Any other connection parameter supported by the client library/server can
be passed either in the connection string or as keyword. See the
PostgreSQL documentation for a complete `list of supported parameters`__.
be passed either in the connection string or as keywords. The PostgreSQL
documentation contains the complete list of the `supported parameters`__.
Also note that the same parameters can be passed to the client library
using `environment variables`__.
.. __: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS
.. __: http://www.postgresql.org/docs/current/static/libpq-envars.html
.. __:
.. _connstring: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
.. __:
.. _connparams: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PARAMKEYWORDS
.. __:
.. _connenvvars: http://www.postgresql.org/docs/current/static/libpq-envars.html
Using the *connection_factory* parameter a different class or
connections factory can be specified. It should be a callable object
taking a *dsn* argument. See :ref:`subclassing-connection` for
taking a *dsn* string argument. See :ref:`subclassing-connection` for
details.
Using *async*\=1 an asynchronous connection will be created: see
Using *async*\=\ `!True` an asynchronous connection will be created: see
:ref:`async-support` to know about advantages and limitations.
.. versionchanged:: 2.4.3
any keyword argument is passed to the connection. Previously only the
basic parameters (plus `!sslmode`) were supported as keywords.
.. seealso::
- libpq `connection string syntax`__
- libpq supported `connection parameters`__
- libpq supported `environment variables`__
.. __: connstring_
.. __: connparams_
.. __: connenvvars_
.. extension::
The parameters *connection_factory* and *async* are Psycopg extensions