pgAdmin 4

pgAdmin 4 is a rewrite of the popular pgAdmin3 management tool for the
PostgreSQL (http://www.postgresql.org) database.

In the following documentation and examples, $PGADMIN4_SRC/ is used to denote
the top-level directory of a copy of the pgAdmin source tree, either from a
tarball or a git checkout.

Architecture

pgAdmin 4 is written as a web application in Python, using jQuery and Bootstrap
for the client side processing and UI. On the server side, Flask is being
utilised.

Although developed using web technologies, pgAdmin 4 can be deployed either on
a web server using a browser, or standalone on a workstation. The runtime/
subdirectory contains an NWjs based runtime application intended to allow this,
which will execute the Python server and display the UI.

Building the Runtime

To build the runtime, the following packages must be installed:

• NodeJS 12+
• Yarn

Change into the runtime directory, and run yarn install. This will install the
dependencies required.

In order to use the runtime in a development environment, you'll need to copy
dev_config.json.in file to dev_config.json, and edit the paths to the Python
executable and pgAdmin.py file, otherwise the runtime will use the default
paths it would expect to find in the standard package for your platform.

You can then execute the runtime by running something like:

node_modules/nw/nwjs/nw .

or on macOS:

node_modules/nw/nwjs/nwjs.app/Contents/MacOS/nwjs .

Configuring the Python Environment

In order to run the Python code, a suitable runtime environment is required.
Python version 3.7 and later are currently supported. It is recommended that a
Python Virtual Environment is setup for this purpose, rather than using the
system Python environment. On Linux and Mac systems, the process is fairly
simple - adapt as required for your distribution:

1. Create a virtual environment in an appropriate directory. The last argument is
   the name of the environment; that can be changed as desired:

bash $ python3 -m venv venv

1. Now activate the virtual environment:

bash $ source venv/bin/activate

1. Some of the components used by pgAdmin require a very recent version of pip,
   so update that to the latest:

bash $ pip install --upgrade pip

1. Ensure that a PostgreSQL installation's bin/ directory is in the path (so
   pg_config can be found for building psycopg3), and install the required
   packages:

bash (venv) $ PATH=$PATH:/usr/local/pgsql/bin pip install -r $PGADMIN4_SRC/requirements.txt

If you are planning to run the regression tests, you also need to install
additional requirements from web/regression/requirements.txt:

bash (venv) $ pip install -r $PGADMIN4_SRC/web/regression/requirements.txt

1. Create a local configuration file for pgAdmin. Edit
   $PGADMIN4_SRC/web/config_local.py and add any desired configuration options
   (use the config.py file as a reference - any settings duplicated in
   config_local.py will override those in config.py). A typical development
   configuration may look like:

   ```python
   from config import *

   Debug mode

   DEBUG = True

   App mode

   SERVER_MODE = True

   Enable the test module

   MODULE_BLACKLIST.remove('test')

   Log

   CONSOLE_LOG_LEVEL = DEBUG
   FILE_LOG_LEVEL = DEBUG

   DEFAULT_SERVER = '127.0.0.1'

   UPGRADE_CHECK_ENABLED = True

   Use a different config DB for each server mode.

   if SERVER_MODE == False:
   SQLITE_PATH = os.path.join(
   DATA_DIR,
   'pgadmin4-desktop.db'
   )
   else:
   SQLITE_PATH = os.path.join(
   DATA_DIR,
   'pgadmin4-server.db'
   )
   ```

This configuration allows easy switching between server and desktop modes
for testing.

1. The initial setup of the configuration database is interactive in server
   mode, and non-interactive in desktop mode. You can run it either by
   running:

bash (venv) $ python3 $PGADMIN4_SRC/web/setup.py

or by starting pgAdmin 4:

bash (venv) $ python3 $PGADMIN4_SRC/web/pgAdmin4.py

Whilst it is possible to automatically run setup in desktop mode by running
the runtime, that will not work in server mode as the runtime doesn't allow
command line interaction with the setup program.

At this point you will be able to run pgAdmin 4 from the command line in either
server or desktop mode, and access it from a web browser using the URL shown in
the terminal once pgAdmin has started up.

Setup of an environment on Windows is somewhat more complicated unfortunately,
please see pkg/win32/README.txt for complete details.

Building the Web Assets

pgAdmin is dependent on a number of third party Javascript libraries. These,
along with it's own Javascript code, SCSS/CSS code and images must be
compiled into a "bundle" which is transferred to the browser for execution
and rendering. This is far more efficient than simply requesting each
asset as it's needed by the client.

To create the bundle, you will need the 'yarn' package management tool to be
installed. Then, you can run the following commands on a *nix system to
download the required packages and build the bundle:

(venv) $ cd $PGADMIN4_SRC
(venv) $ make install-node
(venv) $ make bundle

On Windows systems (where "make" is not available), the following commands
can be used:

C:\> cd $PGADMIN4_SRC\web
C:\$PGADMIN4_SRC\web> yarn install
C:\$PGADMIN4_SRC\web> yarn run bundle

Creating pgAdmin themes

To create a pgAdmin theme, you need to create a directory under
web/pgadmin/static/scss/resources.
Copy the sample file _theme.variables.scss.sample to the new directory and
rename it to _theme.variables.scss. Change the desired hexadecimal values of
the colors and bundle pgAdmin. You can also add a preview image in the theme
directory with the name as \

$ source venv/bin/activate
(venv) $ pip install Sphinx
(venv) $ pip install sphinxcontrib-youtube

(venv) $ make docs

(venv) $ make src

(venv) $ make pip

(venv) $ cd $PGADMIN4_SRC/web

(venv) $ FLASK_APP=pgAdmin4.py flask db revision