Setup pgAdmin development environment

pgAdmin is the most popular and feature rich Open Source administration and development platform for PostgreSQL. In this blog, I will walk you through how to set up the pgAdmin development environment on your machine. The code repository for pgAdmin 4 is: https://github.com/pgadmin-org/pgadmin4.

The steps mentioned below are pretty much the same for all the OS platforms.

Step 1: Install prerequisites and pull the code

To get started, we’ll need some tools. Install the below tools:

1. git (https://git-scm.com/downloads)
2. Install Node.js 16 and above (https://nodejs.org/en/download)
3. yarn (https://classic.yarnpkg.com/lang/en/docs/install)
4. Python 3.7 and above (https://www.python.org/downloads/)
5. PostgreSQL server (https://www.postgresql.org/download)

Once you’ve installed the above tools, go to a directory where pgAdmin4 source code folder should be put and then run the command:

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

This will create a folder called pgadmin4 in your directory.

Step 2: Install Python packages

The pgAdmin backend is developed in Python and to make the backend run we need to install Python requirements. To do so:

1. Make sure you have PostgreSQL bin directory in the PATH environment variable. This is important because the psycopg package depends on PG binaries for installation.
2. Open a cmd/terminal, create a Python virtual environment in an appropriate directory and activate it.
   • On Windows

     c:\>c:\Python37\python -m venv c:\path\to\myenv
     c:\>c:\path\to\myenv\Scripts\activate.bat

   • On MacOS or Linux

     $ python -m /path/to/myenv
     $ source path/to/myenv/bin/activate

3.  You can check python docs for more details on virtual environment https://docs.python.org/3/library/venv.html
4. On the same terminal go to the pgAdmin home directory and run the command

   (myenv) pip install -r requirements.txt

5. Once the command is completed successfully the pgAdmin backend server is ready.

Step 3: Install Javascript packages and bundle

pgAdmin is a web application and the front end UI is developed completely using Javascript. We will need to install JS packages required which are mentioned in the package.json file. To install those:

1. Go to the <pgAdmin root>/web directory.
2. Run the command

   yarn install

3. Once the command is completed successfully, we will compile and bundle pgAdmin JS files using the command.

   yarn run webpacker

4. The above command compiles only once. When working on pgAdmin front end code, we need JS code to be compiled continuously. For that, you can run the webpacker in watch mode using:

   yarn run webpacker --watch

5. To bundle the files for production ready builds, use the command

   yarn run bundle

Step 4: Start the pgAdmin app

Now that the front and back end setup is ready, we can start the app now. To to so:

1. Open the cmd/terminal where you have pgAdmin python virtual environment active.
2. Go to the <pgAdmin root>/web directory.
3. Run the command

   (myenv) python pgAdmin4.py

4. This will start the pgAdmin flask server and you should see an output like:

   Starting pgAdmin 4. Please navigate to http://127.0.0.1:5050 in your browser.
   
    * Serving Flask app 'pgadmin'
   
    * Debug mode: off

5. Open the browser and navigate to http://127.0.0.1:5050
6. pgAdmin is up and running here from source code.

Customize the pgAdmin config

It is sometimes needed to change certain configuration settings while working in a development environment. You can create a config_local.py file in the <pgAdmin root>/web directory and add the customizations. Use config.py file as a reference which is the default configuration. Any setting duplicated in config_local.py will override config.py. You need to restart the pgAdmin server to reflect the changes. A typical config_local would be:

import os
import logging

# Change pgAdmin data directory
DATA_DIR = '/Users/adityatoshniwal/.pgadmin_dev'

#Change pgAdmin server port
DEFAULT_SERVER_PORT = 5051

# Switch between server and desktop mode
SERVER_MODE = True

#Change pgAdmin config DB path
CONFIG_DATABASE_URI="postgresql://postgres:postgres@localhost:5436/pgadmin"

#Setup SMTP
MAIL_SERVER = 'smtp.gmail.com'
MAIL_PORT = 465
MAIL_USE_SSL = True
MAIL_USERNAME = 'user@gmail.com'
MAIL_PASSWORD = 'xxxxxxxxxx'

# Change log level
CONSOLE_LOG_LEVEL = logging.INFO
FILE_LOG_LEVEL = logging.INFO

Running in server mode

pgAdmin supports two different modes - Desktop and Server. By default, pgAdmin runs in desktop mode. To run the application in server mode:

1. Set SERVER_MODE = True in the config_local.py file.
2. Start the application from cmd/terminal.
3. pgAdmin will ask for email address and password for the first time login.
4. Open the browser and navigate to http://127.0.0.1:5050
5. You will see a login page. You can use the email address and password entered to login

Building the documentation

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

1. Assuming you have activated the pgAdmin virtual environment, run:

   (myenv)pip install Sphinx
   (myenv)pip install sphinxcontrib-youtube

    

2. Go to <pgAdmin root> directory
3. The docs then can be build using the command:
   • On MacOS or Linux

     (myenv) make docs

   • On Windows

     (myenv) python.exe <pgAdmin root>\docs\en_US\build_code_snippet.py
     (myenv) sphinx-build.exe <pgAdmin root>\docs\en_US <pgAdmin root>\docs\en_US\_build\html

Running the test cases

pgAdmin has hundreds of automated test cases to make sure things are not broken after the code changes. There are three types of tests - Javascript tests, API tests and GUI tests. Considering the scope of this blog, I will not go in much detail. You can check here - https://github.com/pgadmin-org/pgadmin4/blob/master/README.md on how to run the test cases.

Start Contributing

Contributing to open source projects is a great way to learn new technologies and tools. You might find an entirely new way of doing things that changes the way you approach programming. Projects like pgAdmin largely depend on contributions to add new features or fix bugs and help improve the tool and the open source community as a whole. Start contributing by raising the pull requests to  https://github.com/pgadmin-org/pgadmin4