mirror of
https://git.postgresql.org/git/postgresql.git
synced 2026-02-15 10:57:02 +08:00
b3f0be788a
This commit implements OAUTHBEARER, RFC 7628, and OAuth 2.0 Device Authorization Grants, RFC 8628. In order to use this there is a new pg_hba auth method called oauth. When speaking to a OAuth- enabled server, it looks a bit like this: $ psql 'host=example.org oauth_issuer=... oauth_client_id=...' Visit https://oauth.example.org/login and enter the code: FPQ2-M4BG Device authorization is currently the only supported flow so the OAuth issuer must support that in order for users to authenticate. Third-party clients may however extend this and provide their own flows. The built-in device authorization flow is currently not supported on Windows. In order for validation to happen server side a new framework for plugging in OAuth validation modules is added. As validation is implementation specific, with no default specified in the standard, PostgreSQL does not ship with one built-in. Each pg_hba entry can specify a specific validator or be left blank for the validator installed as default. This adds a requirement on libcurl for the client side support, which is optional to build, but the server side has no additional build requirements. In order to run the tests, Python is required as this adds a https server written in Python. Tests are gated behind PG_TEST_EXTRA as they open ports. This patch has been a multi-year project with many contributors involved with reviews and in-depth discussions: Michael Paquier, Heikki Linnakangas, Zhihong Yu, Mahendrakar Srinivasarao, Andrey Chudnovsky and Stephen Frost to name a few. While Jacob Champion is the main author there have been some levels of hacking by others. Daniel Gustafsson contributed the validation module and various bits and pieces; Thomas Munro wrote the client side support for kqueue. Author: Jacob Champion <jacob.champion@enterprisedb.com> Co-authored-by: Daniel Gustafsson <daniel@yesql.se> Co-authored-by: Thomas Munro <thomas.munro@gmail.com> Reviewed-by: Daniel Gustafsson <daniel@yesql.se> Reviewed-by: Peter Eisentraut <peter@eisentraut.org> Reviewed-by: Antonin Houska <ah@cybertec.at> Reviewed-by: Kashif Zeeshan <kashi.zeeshan@gmail.com> Discussion: https://postgr.es/m/d1b467a78e0e36ed85a09adf979d04cf124a9d4b.camel@vmware.com
295 lines
7.9 KiB
Plaintext
295 lines
7.9 KiB
Plaintext
<!-- doc/src/sgml/postgres.sgml -->
|
|
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
|
|
[
|
|
|
|
<!ENTITY % version SYSTEM "version.sgml">
|
|
%version;
|
|
<!ENTITY % filelist SYSTEM "filelist.sgml">
|
|
%filelist;
|
|
|
|
<!ENTITY commit_baseurl "https://postgr.es/c/">
|
|
<!ENTITY reference SYSTEM "reference.sgml">
|
|
|
|
<!--
|
|
Zero-width space. Use this to allow line breaks at desirable places in
|
|
table cells, examples, etc. without causing an unwanted space when the
|
|
break is not needed in a wider output rendering.
|
|
-->
|
|
<!ENTITY zwsp "​">
|
|
|
|
]>
|
|
|
|
<book id="postgres">
|
|
<title>PostgreSQL &version; Documentation</title>
|
|
|
|
<bookinfo>
|
|
<corpauthor>The PostgreSQL Global Development Group</corpauthor>
|
|
<productname>PostgreSQL</productname>
|
|
<productnumber>&version;</productnumber>
|
|
&legal;
|
|
</bookinfo>
|
|
|
|
&intro;
|
|
|
|
<part id="tutorial">
|
|
<title>Tutorial</title>
|
|
|
|
<partintro>
|
|
<para>
|
|
Welcome to the <productname>PostgreSQL</productname> Tutorial. The
|
|
tutorial is intended to give an introduction
|
|
to <productname>PostgreSQL</productname>, relational database
|
|
concepts, and the SQL language. We assume some general knowledge about
|
|
how to use computers and no particular Unix or programming experience is
|
|
required. This tutorial is intended to provide hands-on experience with
|
|
important aspects of the <productname>PostgreSQL</productname> system.
|
|
It makes no attempt to be a comprehensive treatment of the topics it covers.
|
|
</para>
|
|
|
|
<para>
|
|
After you have successfully completed this tutorial you will want to
|
|
read the <xref linkend="sql"/> section to gain a better understanding
|
|
of the SQL language, or <xref linkend="client-interfaces"/> for
|
|
information about developing applications with
|
|
<productname>PostgreSQL</productname>. Those who provision and
|
|
manage their own PostgreSQL installation should also read <xref linkend="admin"/>.
|
|
</para>
|
|
</partintro>
|
|
|
|
&start;
|
|
&query;
|
|
&advanced;
|
|
|
|
</part>
|
|
|
|
<part id="sql">
|
|
<title>The SQL Language</title>
|
|
|
|
<partintro>
|
|
<para>
|
|
This part describes the use of the <acronym>SQL</acronym> language
|
|
in <productname>PostgreSQL</productname>. We start with
|
|
describing the general syntax of <acronym>SQL</acronym>, then
|
|
how to create tables, how to populate the database, and how to
|
|
query it. The middle part lists the available data types and
|
|
functions for use in <acronym>SQL</acronym> commands. Lastly,
|
|
we address several aspects of importance for tuning a database.
|
|
</para>
|
|
|
|
<para>
|
|
The information is arranged so that a novice user can
|
|
follow it from start to end and gain a full understanding of the topics
|
|
without having to refer forward too many times. The chapters are
|
|
intended to be self-contained, so that advanced users can read the
|
|
chapters individually as they choose. The information is presented
|
|
in narrative form with topical units. Readers looking for a complete
|
|
description of a particular command are encouraged to review
|
|
the <xref linkend="reference"/>.
|
|
</para>
|
|
|
|
<para>
|
|
Readers should know how to connect to a
|
|
<productname>PostgreSQL</productname> database and issue
|
|
<acronym>SQL</acronym> commands. Readers that are unfamiliar with
|
|
these issues are encouraged to read <xref linkend="tutorial"/>
|
|
first. <acronym>SQL</acronym> commands are typically entered
|
|
using the <productname>PostgreSQL</productname> interactive terminal
|
|
<application>psql</application>, but other programs that have
|
|
similar functionality can be used as well.
|
|
</para>
|
|
</partintro>
|
|
|
|
&syntax;
|
|
&ddl;
|
|
&dml;
|
|
&queries;
|
|
&datatype;
|
|
&func;
|
|
&typeconv;
|
|
&indices;
|
|
&textsearch;
|
|
&mvcc;
|
|
&perform;
|
|
∥
|
|
|
|
</part>
|
|
|
|
<part id="admin">
|
|
<title>Server Administration</title>
|
|
|
|
<partintro>
|
|
<para>
|
|
This part covers topics that are of interest to a
|
|
<productname>PostgreSQL</productname> administrator. This includes
|
|
installation, configuration of the server, management of users
|
|
and databases, and maintenance tasks. Anyone running
|
|
<productname>PostgreSQL</productname> server, even for
|
|
personal use, but especially in production, should be familiar
|
|
with these topics.
|
|
</para>
|
|
|
|
<para>
|
|
The information attempts to be in the order in which
|
|
a new user should read it. The chapters are self-contained and
|
|
can be read individually as desired. The information is presented
|
|
in a narrative form in topical units. Readers looking for a complete
|
|
description of a command are encouraged to review the
|
|
<xref linkend="reference"/>.
|
|
</para>
|
|
|
|
<para>
|
|
The first few chapters are written so they can be understood
|
|
without prerequisite knowledge, so new users who need to set
|
|
up their own server can begin their exploration. The rest of this
|
|
part is about tuning and management; that material
|
|
assumes that the reader is familiar with the general use of
|
|
the <productname>PostgreSQL</productname> database system. Readers are
|
|
encouraged review the <xref linkend="tutorial"/> and <xref
|
|
linkend="sql"/> parts for additional information.
|
|
</para>
|
|
</partintro>
|
|
|
|
&installbin;
|
|
&installation;
|
|
&runtime;
|
|
&config;
|
|
&client-auth;
|
|
&user-manag;
|
|
&manage-ag;
|
|
&charset;
|
|
&maintenance;
|
|
&backup;
|
|
&high-availability;
|
|
&monitoring;
|
|
&wal;
|
|
&logical-replication;
|
|
&jit;
|
|
®ress;
|
|
|
|
</part>
|
|
|
|
<part id="client-interfaces">
|
|
<title>Client Interfaces</title>
|
|
|
|
<partintro>
|
|
<para>
|
|
This part describes the client programming interfaces distributed
|
|
with <productname>PostgreSQL</productname>. Each of these chapters can be
|
|
read independently. There are many external programming
|
|
interfaces for client programs that are distributed separately. They
|
|
contain their own documentation (<xref linkend="external-projects"/>
|
|
lists some of the more popular ones). Readers of this part should be
|
|
familiar with using <acronym>SQL</acronym> to manipulate
|
|
and query the database (see <xref linkend="sql"/>) and of course
|
|
with the programming language of their choice.
|
|
</para>
|
|
</partintro>
|
|
|
|
&libpq;
|
|
&lobj;
|
|
&ecpg;
|
|
&infoschema;
|
|
|
|
</part>
|
|
|
|
<part id="server-programming">
|
|
<title>Server Programming</title>
|
|
|
|
<partintro>
|
|
<para>
|
|
This part is about extending the server functionality with
|
|
user-defined functions, data types, triggers, etc. These are
|
|
advanced topics which should be approached only after all
|
|
the other user documentation about <productname>PostgreSQL</productname> has
|
|
been understood. Later chapters in this part describe the server-side
|
|
programming languages available in the
|
|
<productname>PostgreSQL</productname> distribution as well as
|
|
general issues concerning server-side programming. It
|
|
is essential to read at least the earlier sections of <xref
|
|
linkend="extend"/> (covering functions) before diving into the
|
|
material about server-side programming.
|
|
</para>
|
|
</partintro>
|
|
|
|
&extend;
|
|
&trigger;
|
|
&event-trigger;
|
|
&rules;
|
|
|
|
&xplang;
|
|
&plsql;
|
|
&pltcl;
|
|
&plperl;
|
|
&plpython;
|
|
|
|
&spi;
|
|
&bgworker;
|
|
&logicaldecoding;
|
|
&replication-origins;
|
|
&archive-modules;
|
|
&oauth-validators;
|
|
|
|
</part>
|
|
|
|
&reference;
|
|
|
|
<part id="internals">
|
|
<title>Internals</title>
|
|
|
|
<partintro>
|
|
<para>
|
|
This part contains assorted information that might be of use to
|
|
<productname>PostgreSQL</productname> developers.
|
|
</para>
|
|
</partintro>
|
|
|
|
&arch-dev;
|
|
&catalogs;
|
|
&system-views;
|
|
&protocol;
|
|
&sources;
|
|
&nls;
|
|
&plhandler;
|
|
&fdwhandler;
|
|
&tablesample-method;
|
|
&custom-scan;
|
|
&geqo;
|
|
&tableam;
|
|
&indexam;
|
|
&wal-for-extensions;
|
|
&indextypes;
|
|
&storage;
|
|
&transaction;
|
|
&bki;
|
|
&planstats;
|
|
&backup-manifest;
|
|
|
|
</part>
|
|
|
|
<part id="appendixes">
|
|
<title>Appendixes</title>
|
|
|
|
&errcodes;
|
|
&datetime;
|
|
&keywords;
|
|
&features;
|
|
&release;
|
|
&contrib;
|
|
&external-projects;
|
|
&sourcerepo;
|
|
&docguide;
|
|
&limits;
|
|
&acronyms;
|
|
&glossary;
|
|
&color;
|
|
&obsolete;
|
|
|
|
</part>
|
|
|
|
&biblio;
|
|
<index id="bookindex"></index>
|
|
|
|
</book>
|