.. _db_interface:
******
Driver
******
`postgresql.driver` provides a PG-API, `postgresql.api`, interface to a
PostgreSQL server using PQ version 3.0 to facilitate communication. It makes
use of the protocol's extended features to provide binary datatype transmission
and protocol level prepared statements for strongly typed parameters.
`postgresql.driver` currently supports PostgreSQL servers as far back as 8.0.
Prior versions are not tested. While any version of PostgreSQL supporting
version 3.0 of the PQ protocol *should* work, many features may not work due to
absent functionality in the remote end.
For DB-API 2.0 users, the driver module is located at
`postgresql.driver.dbapi20`. The DB-API 2.0 interface extends PG-API. All of the
features discussed in this chapter are available on DB-API connections.
.. warning::
PostgreSQL versions 8.1 and earlier do not support standard conforming
strings. In order to avoid subjective escape methods on connections,
`postgresql.driver.pq3` enables the ``standard_conforming_strings`` setting
by default. Greater care must be taken when working versions that do not
support standard strings.
**The majority of issues surrounding the interpolation of properly quoted literals can be easily avoided by using parameterized statements**.
The following identifiers are regularly used as shorthands for significant
interface elements:
``db``
`postgresql.api.Connection`, a database connection. `Connections`_
``ps``
`postgresql.api.Statement`, a prepared statement. `Prepared Statements`_
``c``
`postgresql.api.Cursor`, a cursor; the results of a prepared statement.
`Cursors`_
``C``
`postgresql.api.Connector`, a connector. `Connectors`_
Establishing a Connection
=========================
There are many ways to establish a `postgresql.api.Connection` to a
PostgreSQL server using `postgresql.driver`. This section discusses those,
connection creation, interfaces.
`postgresql.open`
-----------------
In the root package module, the ``open()`` function is provided for accessing
databases using a locator string and optional connection keywords. The string
taken by `postgresql.open` is a URL whose components make up the client
parameters::
>>> import postgresql
>>> db = postgresql.open("pq://localhost/postgres")
This will connect to the host, ``localhost`` and to the database named
``postgres`` via the ``pq`` protocol. open will inherit client parameters from
the environment, so the user name given to the server will come from
``$PGUSER``, or if that is unset, the result of `getpass.getuser`--the username
of the user running the process. The user's "pgpassfile" will even be
referenced if no password is given::
>>> db = postgresql.open("pq://username:password@localhost/postgres")
In this case, the password *is* given, so ``~/.pgpass`` would never be
referenced. The ``user`` client parameter is also given, ``username``, so
``$PGUSER`` or `getpass.getuser` will not be given to the server.
Settings can also be provided by the query portion of the URL::
>>> db = postgresql.open("pq://user@localhost/postgres?search_path=public&timezone=mst")
The above syntax ultimately passes the query as settings(see the description of
the ``settings`` keyword in `Connection Keywords`). Driver parameters require a
distinction. This distinction is made when the setting's name is wrapped in
square-brackets, '[' and ']':
>>> db = postgresql.open("pq://user@localhost/postgres?[sslmode]=require&[connect_timeout]=5")
``sslmode`` and ``connect_timeout`` are driver parameters. These are never sent
to the server, but if they were not in square-brackets, they would be, and the
driver would never identify them as driver parameters.
The general structure of a PQ-locator is::
protocol://user:password@host:port/database?[driver_setting]=value&server_setting=value
Optionally, connection keyword arguments can be used to override anything given
in the locator::
>>> db = postgresql.open("pq://user:secret@host", password = "thE_real_sekrat")
Or, if the locator is not desired, individual keywords can be used exclusively::
>>> db = postgresql.open(user = 'user', host = 'localhost', port = 6543)
In fact, all arguments to `postgresql.open` are optional as all arguments are
keywords; ``iri`` is merely the first keyword argument taken by
`postgresql.open`. If the environment has all the necessary parameters for a
successful connection, there is no need to pass anything to open::
>>> db = postgresql.open()
For a complete list of keywords that `postgresql.open` can accept, see
`Connection Keywords`_.
For more information about the environment variables, see :ref:`pg_envvars`.
For more information about the ``pgpassfile``, see :ref:`pg_passfile`.
`postgresql.driver.connect`
---------------------------
`postgresql.open` is a high-level interface to connection creation. It provides
password resolution services and client parameter inheritance. For some
applications, this is undesirable as such implicit inheritance may lead to
failures due to unanticipated parameters being used. For those applications,
use of `postgresql.open` is not recommended. Rather, `postgresql.driver.connect`
should be used when explicit parameterization is desired by an application:
>>> import postgresql.driver as pg_driver
>>> db = pg_driver.connect(
... user = 'usename',
... password = 'secret',
... host = 'localhost',
... port = 5432
... )
This will create a connection to the server listening on port ``5432``
on the host ``localhost`` as the user ``usename`` with the password ``secret``.
.. note::
`connect` will *not* inherit parameters from the environment as libpq-based drivers do.
See `Connection Keywords`_ for a full list of acceptable keyword parameters and
their meaning.
Connectors
----------
Connectors are the supporting objects used to instantiate a connection. They
exist for the purpose of providing connections with the necessary abstractions
for facilitating the client's communication with the server, *and to act as a
container for the client parameters*. The latter purpose is of primary interest
to this section.
Each connection object is associated with its connector by the ``connector``
attribute on the connection. This provides the user with access to the
parameters used to establish the connection in the first place, and the means to
create another connection to the same server. The attributes on the connector
should *not* be altered. If parameter changes are needed, a new connector should
be created.
The attributes available on a connector are consistent with the names of the
connection parameters described in `Connection Keywords`_, so that list can be
used as a reference to identify the information available on the connector.
Connectors fit into the category of "connection creation interfaces", so
connector instantiation normally takes the same parameters that the
`postgresql.driver.connect` function takes.
.. note::
Connector implementations are specific to the transport, so keyword arguments
like ``host`` and ``port`` aren't supported by the ``Unix`` connector.
The driver, `postgresql.driver.default` provides a set of connectors for making
a connection:
``postgresql.driver.default.host(...)``
Provides a ``getaddrinfo()`` abstraction for establishing a connection.
``postgresql.driver.default.ip4(...)``
Connect to a single IPv4 addressed host.
``postgresql.driver.default.ip6(...)``
Connect to a single IPv6 addressed host.
``postgresql.driver.default.unix(...)``
Connect to a single unix domain socket. Requires the ``unix`` keyword which
must be an absolute path to the unix domain socket to connect to.
``host`` is the usual connector used to establish a connection::
>>> C = postgresql.driver.default.host(
... user = 'auser',
... host = 'foo.com',
... port = 5432)
>>> # create
>>> db = C()
>>> # establish
>>> db.connect()
If a constant internet address is used, ``ip
没有合适的资源?快使用搜索试试~ 我知道了~
Python库 | py-postgresql-1.0.1.tar.gz
1.该资源内容由用户上传,如若侵权请联系客服进行举报
2.虚拟产品一经售出概不退款(资源遇到问题,请及时私信上传者)
2.虚拟产品一经售出概不退款(资源遇到问题,请及时私信上传者)
版权申诉
0 下载量 2 浏览量
2022-04-13
04:06:27
上传
评论
收藏 643KB GZ 举报
温馨提示
共185个文件
py:114个
txt:22个
html:13个
资源分类:Python库 所属语言:Python 资源全名:py-postgresql-1.0.1.tar.gz 资源来源:官方 安装方法:https://lanzao.blog.csdn.net/article/details/101784059
资源推荐
资源详情
资源评论
收起资源包目录
Python库 | py-postgresql-1.0.1.tar.gz (185个子文件)
AUTHORS 578B
element3.c 16KB
buffer.c 12KB
structlib.c 12KB
functools.c 8KB
wirestate.c 7KB
module.c 3KB
basic.css 6KB
default.css 3KB
pygments.css 3KB
driver.doctree 404KB
lib.doctree 99KB
clientparameters.doctree 84KB
copyman.doctree 68KB
notifyman.doctree 54KB
bin.doctree 47KB
alock.doctree 31KB
gotchas.doctree 23KB
changes.doctree 16KB
index.doctree 9KB
admin.doctree 8KB
.gitignore 23B
driver.html 152KB
lib.html 43KB
copyman.html 31KB
clientparameters.html 29KB
notifyman.html 25KB
index.html 16KB
bin.html 15KB
alock.html 13KB
gotchas.html 12KB
changes.html 7KB
admin.html 6KB
search.html 3KB
genindex.html 3KB
jquery.js 54KB
searchindex.js 19KB
searchtools.js 12KB
doctools.js 6KB
LICENSE 2KB
environment.pickle 55KB
PKG-INFO 3KB
file.png 392B
plus.png 199B
minus.png 199B
pq3.py 82KB
test_driver.py 50KB
api.py 35KB
crypt.py 26KB
test_dbapi20.py 25KB
copyman.py 22KB
element3.py 21KB
xact3.py 21KB
test_types.py 19KB
test_copyman.py 19KB
test_protocol.py 18KB
exceptions.py 17KB
clientparameters.py 17KB
cluster.py 16KB
command.py 16KB
__init__.py 15KB
client3.py 15KB
lib.py 13KB
__init__.py 11KB
test_connect.py 10KB
dbapi20.py 10KB
test_optimized.py 9KB
riparse.py 9KB
test_ssl_connect.py 9KB
stdlib_datetime.py 9KB
configfile.py 8KB
string.py 7KB
test_configfile.py 7KB
installation.py 7KB
notifyman.py 7KB
test_string.py 6KB
conf.py 6KB
temporal.py 6KB
test_python.py 5KB
element.py 5KB
distutils.py 5KB
iri.py 5KB
geometry.py 4KB
alock.py 4KB
stdlib_decimal.py 4KB
test_lib.py 4KB
test_alock.py 4KB
message.py 4KB
pbuffer.py 4KB
test_notifyman.py 4KB
pg_python.py 3KB
versionstring.py 3KB
test_iri.py 3KB
socket.py 3KB
structlib.py 3KB
cursor_integrity.py 3KB
unittest.py 3KB
test_installation.py 2KB
__init__.py 2KB
bitwise.py 2KB
共 185 条
- 1
- 2
资源评论
挣扎的蓝藻
- 粉丝: 13w+
- 资源: 15万+
上传资源 快速赚钱
- 我的内容管理 展开
- 我的资源 快来上传第一个资源
- 我的收益 登录查看自己的收益
- 我的积分 登录查看自己的积分
- 我的C币 登录后查看C币余额
- 我的收藏
- 我的下载
- 下载帮助
安全验证
文档复制为VIP权益,开通VIP直接复制
信息提交成功