A database connection is represented by the PySide.QtSql.QSqlDatabase class. This class provides an interface for accessing a database through the connection. The connection is accomplished through Qt's supported database drivers which are derived from the PySide.QtSql.QSqlDriver class. The QSqlDriver class is an abstract base class for accessing specific SQL databases, and should be used with QSqlDatabase. As with any other PySide feature that supports customization, it is also possible to create our own SQL drivers by sub-classing the QSqlDriver class and re-implementing its virtual functions.

Before explaining the concept of connecting to databases, we will see the types of database access provided by PySide. The access is provided at two levels, a high-level access using QSqlTableModel or QSqlRelationalTableModel, and a low-level access using QSqlQuery. The former one uses model/view architecture and provides a high-level interface for reading and writing database records from a table. The latter one is based on executing and manipulating SQL queries directly on the QSqlDatabase class. This class can accept DML statements, such as SELECT, INSERT, UPDATE, and DELETE, as well as DDL statements, such as CREATE, ALTER, and DROP. It can also be used to execute database-specific commands which are not standard SQL, for example, SET DATESTYLE=ISO for PostgreSQL.

The connection to the database in an application can take at any point when it is required to. But, in most of the applications it is done after the creation of the QApplication object, and before the main form is created or shown. This way, we can inform users ahead of the unsuccessful connection and thus prevent them from executing database specific actions that will otherwise go waste. A connection is created by calling the static QSqlDatabase.addDatabase() function, by giving the name of the database driver that we want to use and optionally, a connection name. A database connection is identified by the connection name that we specify and not by the database name. It is possible for us to create multiple database connections at a time and differentiate them by the connection name. It is also correct to create a connection without a name, by making it a default connection. Once a connection object has been created, we can move on to set other necessary attributes such as, database's name, username, password, host, and port details, and other connect options, if necessary. Once this is complete, we can activate the connection to the database with the help of the QSqlDatabase.open() function call. The following code presents the series of steps that we have discussed in creating and activating a connection:

db = QSqlDatabase.addDatabase("QMYSQL")
db.setHostName("testServer")
db.setDatabaseName("sampledb")
db.setUserName("test")
db.setPassword("pass123")
ok = db.open()

In the preceding code, the addDatabase() function can be given an optional second parameter which specifies the connection name given as follows:

db = QSqlDatabase.addDatabase("QMYSQL", "myConn")

However, when using SQLite, it is enough to specify only the database name. Usually, this will be a filename but it can be the special name ":memory:" to specify using an in-memory database. When the open() call is executed on the connection, the file will be created if it does not exist. So, the code for connecting to the SQLite database using the SQLite driver for PySide, QSQLITE is:

db = QSqlDatabase.addDatabase("QSQLITE")
db.setDatabaseName("test.db")
ok = db.open()

This will create a connection with the SQLite database file test.db. We should take care of handling the connection errors by checking the return value of the db.open() function. It is good practice to notify the users upfront about any errors.

Once the connection is established, we can get the list of the tables, its primary index, and meta-information about the table's fields with their specific functions. The QSqlDatabase.removeDatabase() function is called with a connection name to remove a connection.