Connections to databases are handled by the objects of the class connection. These objects represent database sessions in the application. The objects are created using the function connect() from the module psycopg2. This way of creating connections is defined by the DB API 2.0.

To specify the location and authenticate in the database, a connection string can be used, like this:

conn = connect("host=db_host user=some_user dbname=database "
               "password=$ecreT")

Alternatively, named parameters can be used, like this:

conn = connect(host="db_host", user="some_user", dbname="database",
               password="$ecreT")

Here, the connection would be established to the database named database, located at server db_host as user some_user identified by the password, $ecreT.

Optionally, the function connect() can take two parameters, which are connection_factory and cursor_factory. They can be used to specify a custom function that would create connections or cursors. This feature can be used to extend the default functionality; for example, if you want to log all the SQL queries that are executed by the application, a customized cursor class can be a good solution for this.

The connection object returned by the function connect is referred to by the variable conn in the preceding examples. The object is used to create cursor objects to execute queries and manage the database session. The most common methods of the class connection are as follows:

• commit(): This is used to commit the current transaction in the database. By default, psycopg2 will open a transaction before executing any command. For this reason, there is no method to explicitly begin a transaction.
• rollback(): This is used to roll back the current transaction.
• close(): This is used to disconnect from the database and close the connection.
• cancel(): This is used to cancel a current command. This can be executed from a different thread. This method is not defined in the DB API 2.0.

There are also a number of methods used to perform two-phase commit. Two-phase commit protocol is an algorithm that is used when several systems should perform a commit action or a rollback all together in a coordinated way. There are more fields (some of them are read-only) and methods of the class connection that can be used to check the state of the connection, set and get its properties, manage the transaction isolation level, and perform other operations.

An object of the class connection cat be instantiated with the context manager syntax, as follows:

with connect(host="db_host", user="some_user", dbname="database",
             password="$ecreT") as conn:
    cur = conn.cursor()
    ...

After the execution left the with-block, the connection will be closed automatically, regardless of whether the program continued normally or an exception was raised.