Repository files navigation

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

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

pgAdmin 4 is written as a web application with Python(Flask) on the server sideand ReactJS, HTML5 with CSS for the client side processing and UI.

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

1. Install Node.js 20 and above (https://nodejs.org/en/download)
2. yarn (https://yarnpkg.com/getting-started/install)
3. Python 3.9 and above (https://www.python.org/downloads/)
4. PostgreSQL server (https://www.postgresql.org/download)

Start by enabling Corepack, if it isn't already;this will add the yarn binary to your PATH:

corepackenable

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

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

$cd$PGADMIN4_SRC$ make install-node$ make bundle

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

C:\> cd $PGADMIN4_SRC\webC:\$PGADMIN4_SRC\web> yarn installC:\$PGADMIN4_SRC\web> yarn run bundle

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

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

   $ python3 -m venv venv

2. Now activate the virtual environment:

   $source venv/bin/activate

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

   (venv) $ pip install --upgrade pip

4. Ensure that a PostgreSQL installation's bin/ directory is in the path (sopg_config can be found for building psycopg3), and install the requiredpackages:

   (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 installadditional requirements from web/regression/requirements.txt:

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

5. 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 inconfig_local.py will override those in config.py). A typical developmentconfiguration may look like:

   importosimportlogging# Change pgAdmin data directoryDATA_DIR='/Users/myuser/.pgadmin_dev'#Change pgAdmin server and portDEFAULT_SERVER='127.0.0.1'DEFAULT_SERVER_PORT=5051# Switch between server and desktop modeSERVER_MODE=True#Change pgAdmin config DB path in case external DB is used.CONFIG_DATABASE_URI="postgresql://postgres:postgres@localhost:5436/pgadmin"#Setup SMTPMAIL_SERVER='smtp.gmail.com'MAIL_PORT=465MAIL_USE_SSL=TrueMAIL_USERNAME='user@gmail.com'MAIL_PASSWORD='xxxxxxxxxx'# Change log levelCONSOLE_LOG_LEVEL=logging.INFOFILE_LOG_LEVEL=logging.INFO# Use a different config DB for each server mode.ifSERVER_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 modesfor testing.

6. The initial setup of the configuration database is interactive in servermode, and non-interactive in desktop mode. You can run it either byrunning:

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

   or by starting pgAdmin 4:

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

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

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

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

In order to build the docs, an additional Python package is required in thevirtual environment. This can be installed with the pip package manager:

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

The docs can then be built using the Makefile in$PGADMIN4_SRC, e.g.

(venv) $ make docs

The output can be found in$PGADMIN4_SRC/docs/en_US/_build/html/index.html

Change into the runtime directory, and runyarn install. This will install thedependencies required.

In order to use the runtime in a development environment, you'll need to copydev_config.json.in file todev_config.json, and edit the paths to the Pythonexecutable andpgAdmin.py file, otherwise the runtime will use the defaultpaths it would expect to find in the standard package for your platform.

You can then execute the runtime by running something like:

yarn run start

Most packages can be built using the Makefile in $PGADMIN4_SRC, provided allthe setup and configuration above has been completed.

To build a source tarball:

(venv) $ make src

To build a PIP Wheel, activate either a Python 3 virtual environment, configuredwith all the required packages, and then run:

(venv) $ make pip

To build the macOS AppBundle, please seepkg/mac/README.

To build the Windows installer, please seepkg/win32/README.txt.

In order to make changes to the SQLite DB, navigate to the 'web' directory:

(venv) $cd$PGADMIN4_SRC/web

Create a migration file with the following command:

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

This will create a file in: $PGADMIN4_SRC/web/migrations/versions/ .Add any changes to the 'upgrade' function.Increment the SCHEMA_VERSION in $PGADMIN4_SRC/web/pgadmin/model/init.py file.

There is no need to increment the SETTINGS_SCHEMA_VERSION.

Seehttps://www.pgadmin.org/support/ for support options.

If you would like to report a security issue with pgAdmin, please emailsecurity (at) pgadmin (dot) org.

Note that this address should only be used for reporting security issuesthat you believe you've found in the design or code of pgAdmin, pgAgent,and the pgAdmin website. It should not be used to ask security questions.

A GitHub project for pgAdmin 4 can be found at the address below:

https://github.com/pgadmin-org/pgadmin4

Please submit any changes as Pull Requests against themaster branch of thepgadmin-org/pgadmin4 repository.

If you wish to discuss pgAdmin 4, or contribute to the project, please use thepgAdmin Hackers mailing list:

pgadmin-hackers@postgresql.org