Fork me on GitHub

Quick Links


Download


FAQ


Latest Docs


Get Help


Screenshots

FAQ

General

Configuration

Troubleshooting

General

What is pgAdmin 4?

pgAdmin is a management tool for PostgreSQL and derivative relational databases such as EnterpriseDB's EDB Advanced Server. It may be run either as a web or desktop application. For more information on the features offered, please see the Features and Screenshots pages.

What browsers does pgAdmin support?

The following browsers are supported with pgAdmin, when run on Linux, macOS or Windows. We regularly test with a subset of the available versions, and aim to fix issues found with any of them.

  • Chrome 90+
  • Firefox 78+
  • Edge 91+
  • Safari 14+

Other browsers may work but are not tested and issues reported when using them with pgAdmin may not be fixed.

Why doesn't pgAdmin use the native File management dialogues?

This is largely for a couple of reasons:

  • As pgAdmin is a web application, it can only interact with the local filesystem in ways that are allowed by modern web browsers. This limits what is possible for security; essentially files can only be "downloaded" or "uploaded" (through a form). There is no way to simply save an update to a file by hitting a Save button, nor is it possible to save the working directory for example.
  • When running in server mode, files are read from and stored on the server to enable users to work with the same data whatever machine they happen to be using. There are no "native dialogues" for working with files stored on a web server in this way, so we have to implement our own.

We have done extensive evaluation and testing of various ways of managing files in pgAdmin 4, and have consistently found that using our own dialogues provides the best experience (one that we continue to refine and improve with user feedback).

What is the Master Password, and how do I use it or remove it?

The Master Password is used to securely encrypt any credentials that you choose to save when using pgAdmin. Without the Master Password (or something similar that is supplied by the user), the encryption keys must be generated from data that is stored on-disk in a location known to pgAdmin. By examining the source code another user with the ability to access the encrypted passwords and the data used to generate the keys would be able to decrypt the saved passwords.

Unfortunately this ability isn't limited to administrative users of the machine(s) containing the saved passwords and key data as you might immediately think. Malware that may have been inadvertently installed may be able to transmit the saved password database and key data to an attacker. Such malware could be part of another piece of software or something installed utilising a browser vulnerability for example.

The Master Password mitigates this problem by ensuring that the key data is never stored on disk.

I know my system is secure and can't possibly get infected with malware. Can I disable the Master Password? Yes, though we strongly advise against doing so! To do so, find the config.py file that is part of your pgAdmin installation. This is normally in a top-level directory called web. In the same directory, create a file called config_local.py, and add a line that reads:

MASTER_PASSWORD_REQUIRED=False

If the file already exists, edit it, and add the line. When you restart pgAdmin, the Master Password will be disabled and passwords will be encrypted in an insecure manner which will protect them against "shoulder surfing", but will not prevent anyone from decrypting them fairly easily.

But why can't I disable the Master Password from the GUI? By requiring a change to the main configuration for pgAdmin, we allow system administrators to enforce a security policy which is often a requirement in corporate or other secure environments. At present there are no general mechanisms in pgAdmin to allow administrators to control which user preferences (those options which can be configured through the GUI) can or cannot be changed.

Configuration

What are Server Mode and Desktop Mode?

When deploying pgAdmin on a web server for multiple users, it is run in server mode (SERVER_MODE = True). This mode requires each user to have an account in pgAdmin, with their own password. Users are required to login to pgAdmin in order to use it. One or more users may be configured as an administrator and will be able to add or remove other users. For more information, please see the Server Deployment and User Management documentation.

To allow running in desktop mode (SERVER_MODE = False), a runtime application is provided to host and display the pgAdmin code (sometimes referred to as the application server). In this mode, each user runs their own instance of pgAdmin, thus no authentication or user management is required. For more information, please see the Desktop Deployment documentation.

What should I set the Binary Path configuration option to so I can make and restore backups?

pgAdmin can utilise PostgreSQL utilities such as pg_dump, pg_restore to enable users to take backups and restore them, as well as run other maintenance operations. The directory path in which these utilities can be found must be provided to pgAdmin to enable these features - see File -> Preferences -> Paths -> Binary paths. You can specify separate paths for the PostgreSQL and EDB Advanced Server binaries. In server mode, the binaries must be installed on the server hosting pgAdmin, whilst in desktop mode they must be on the local machine (that is running pgAdmin).

The binary utilities are typically shipped with the database server packages for your platform. Future versions of pgAdmin may include them in some desktop packages.

Troubleshooting

How do I enable logging in pgAdmin 4?

The default log settings for pgAdmin will write warnings and errors to a logfile, the location of which depends on the platform:

  • Linux/MacOS: ~/.pgadmin/pgadmin4.log
  • Windows: %APPDATA%\pgAdmin\pgadmin4.log

To override the log settings, create a file called config_local.py in the web/ directory of the installation, alongside the existing config.py. This file can be used to override any of the settings in config.py (which shouldn't be edited). To modify the logging settings, create a file similar to the following:

import logging

# Application log level - one of:
#   CRITICAL 50
#   ERROR    40
#   WARNING  30
#   SQL      25
#   INFO     20
#   DEBUG    10
#   NOTSET    0
CONSOLE_LOG_LEVEL = logging.DEBUG
FILE_LOG_LEVEL = logging.DEBUG

# Log format.
CONSOLE_LOG_FORMAT = '%(asctime)s: %(levelname)s\t%(name)s:\t%(message)s'
FILE_LOG_FORMAT = '%(asctime)s: %(levelname)s\t%(name)s:\t%(message)s'

# Log file name
LOG_FILE = '/desired/path/to/pgadmin4.log'

Once the configuration change has been made, pgAdmin must be restarted.

When I open the Query Tool or (other tools) in a new tab, I get "Connection to server lost" or "CSRF tokens do not match" on Safari versions >= 12

This has been seen mostly on Safari browser versions >= 12, though it can happen with other browsers with non-standard configurations. It's reported that from v12 CFNetwork/Webkit which are used by Safari erroneously treat the "SameSite=none" as the equivalent of "Samesite=strict". Essentially, whilst Safari recognizes the SameSite cookie attribute starting with version 12, their implementation has a bug. For more information, see this post on the Apple forums and this WebKit bug.

To work around this issue, create a config_system.py as shown in the documentation, and add the following options:

SESSION_COOKIE_SAMESITE = None
SESSION_COOKIE_SECURE = True

Note: These changes will disable security options in pgAdmin. This should be used as a last resort, if and only if you have clients that are using Safari and are affected by this issue, and who cannot use an alternate browser.

How do I start pgAdmin such that it outputs a log to the console?

If you're running in server mode, or directly using Python, then console logs will be sent directly to the tty under which the application is started.

In desktop mode, the process varies depending on the platform:

  • Linux: Start the desktop runtime from the command line, e.g. /usr/local/pgadmin4/bin/pgadmin4, adjusting the path as necessary.
  • MacOS: Start the desktop runtime from the command line, e.g. /Applications/pgAdmin\ 4.app/Contents/MacOS/pgAdmin4, adjusting the path as necessary.
  • Windows: Console logs can be written to a file from the command line on Windows, e.g. "C:\Program Files\pgAdmin 4\v2\runtime\pgAdmin4.exe" > %TEMP%\pgadmin-console.log will write a log to %TEMP%\pgadmin-console.log.

Note that you may need to adjust the CONSOLE_LOG_LEVEL option in config_local.py to see useful information in the log. See this FAQ for more information.

Why does pgAdmin seem to use a lot of CPU cycles?

pgAdmin 4's architecture will naturally require more CPU and memory than a traditional native desktop application, however, pgAdmin 4 also includes continually updating dashboards that weren't present in pgAdmin III. The dashboards update each graph every second by default, even if they are not visible (to avoid gaps in the data). CPU usage may be noticably reduced by adjusting the refresh speed of the graphs to a longer period, such as ten seconds. This can be done under File -> Preferences -> Paths -> Dashboards -> Graphs. After changes have been made, you may need to navigate to a different dashboard instance for the changes to take effect.

When pgAdmin runs in desktop mode on my Windows PC, I just see unformatted text on the left of the window. Why?

This behaviour has been observed by a number of users on Windows. Essentially what is happening is that the browser is ignoring the stylesheets that properly format the display. In all cases seen, this was because a registry setting on the machine had been set to an incorrect value, possibly by the installation of a particular editor. To resolve the issue, use the Windows Registry Editor to reset the value of "HKEY_CLASSES_ROOT\.css\Content Type" to "text/css" (without the quotes), and then restart pgAdmin.

On macOS, I get an error like: "pgAdmin 4 is damaged and cannot be opened"

This has been seen mostly on older versions of macOS (e.g. 10.10). Unfortunately the error message is usually misleading, and the digital signature of the application will validate correctly. The actual problem is typically that the operating system is configured to only allow running of apps from the Apple App store.

To change this setting, open the Preferences Panel and then browse to Security and Privacy. From there, change the Allow apps downloaded from setting to App Store and identified developers (more secure) or Anywhere (less secure).

Note that the available options and their labels vary from release to release of macOS, and may not be exactly as described above.