23. Debugger Plugin Installation¶
23.1. Linux Installation¶
You can install from Debian PGDG repository or from standalone packages or compile from source.
- 1.1. Installing from Debian PGDG repository (recommended)
- 1.2. Installing from DEB/RPM packages
- 1.3. Compiling the extension from source
23.1.1. Installing from Debian PGDG repository¶
On Debian and Ubuntu systems, this is the recommended way of installing the OmniDB debugger for PostgreSQL PL/pgSQL functions and procedures.
23.1.1.1. Install Debian PGDG repository (if not already)¶
sudo echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list
sudo wget --quiet -O - https://apt.postgresql.org/pub/repos/apt/ACCC4CF8.asc | apt-key add -
23.1.1.2. Install omnidb_plugin for your PostgreSQL version X.Y¶
sudo apt install postgresql-X.Y-omnidb
23.1.1.3. Post-installation steps¶
23.1.1.3.1. Create omnidb_plugin extension (should be done by a superuser)¶
psql -d <database> -c 'CREATE EXTENSION omnidb_plugin'
23.1.1.3.2. Create sample functions (optional)¶
psql -d <database> -f sample_functions.sql
23.1.1.3.3. Next steps¶
Follow Post-installation steps in section 5.
23.1.2. Installing from DEB/RPM packages¶
23.1.2.1. Install the package¶
# For example, Debian-like 64 bits:
sudo dpkg -i omnidb-plugin_2.16.0-debian-amd64.deb
# For example, for CentOS-like 64 bits:
sudo rpm -ivU omnidb-plugin_2.16.0-centos-amd64.rpm
23.1.2.2. Create a symlink¶
# Find the PostgreSQL version and path for $libdir and create a link to the specific library. For example:
sudo ln -s /opt/omnidb-plugin/omnidb_plugin_96.so /usr/lib/postgresql/9.6/lib/omnidb_plugin.so
23.1.2.3. Set shared_preload_libraries¶
nano /etc/postgresql/X.Y/main/postgresql.conf
shared_preload_libraries = 'omnidb_plugin'
sudo systemctl restart postgresql
23.1.2.4. Post-installation steps¶
23.1.2.4.1. Create omnidb schema in your database (should be done by a superuser)¶
psql -d <database> -f debugger_schema.sql
23.1.2.4.2. Create sample functions (optional)¶
psql -d <database> -f sample_functions.sql
23.1.2.4.3. Next steps¶
Follow Post-installation steps in section 5.
23.1.3. Compiling the extension from source¶
23.1.3.1. Install headers for PostgreSQL and libpq¶
sudo apt install postgresql-server-dev-X.Y libpq-dev
23.1.3.2. Compile omnidb_plugin¶
make
23.1.3.3. Install omnidb_plugin¶
sudo make install
23.1.3.4. Set shared_preload_libraries¶
nano /etc/postgresql/X.Y/main/postgresql.conf
shared_preload_libraries = 'omnidb_plugin'
sudo systemctl restart postgresql
23.1.3.5. Post-installation steps¶
23.1.3.5.1. Create omnidb_plugin extension (should be done by a superuser)¶
psql -d <database> -c 'CREATE EXTENSION omnidb_plugin'
23.1.3.5.2. Create sample functions (optional)¶
psql -d <database> -f sample_functions.sql
23.1.3.5.3. Next steps¶
Follow Post-installation steps in section 5.
23.2. Windows Installation¶
23.2.1. Downloading the plugin¶
Download the zip corresponding to your architecture from the website.
23.2.2. Installing the plugin¶
Move the omnidb_plugin.dll corresponding to your PostgreSQL version to the folder lib, which is inside the folder where PostgreSQL was installed.
23.2.3. Set shared_preload_libraries¶
Change the file PostgreSQL_directory/data/postgresql.conf, including the following line:
shared_preload_libraries = 'omnidb_plugin'
Then restart PostgreSQL.
23.2.4. Post-installation steps¶
23.2.4.1. Create omnidb schema in your database (should be done by a superuser)¶
psql -d <database> -f debugger_schema.sql
23.2.4.2. Create sample functions (optional)¶
psql -d <database> -f sample_functions.sql
23.2.4.3. Next steps¶
Follow Post-installation steps in section 5.
23.3. FreeBSD Installation¶
23.3.1. Downloading the plugin¶
Download the tar.gz corresponding to your architecture from the website.
wget --no-check-certificate https://omnidb.org/dist/2.16.0/omnidb-plugin_2.16.0-freebsd.tar.gz
23.3.1. Installing the plugin¶
Move the omnidb_plugin.so corresponding to your PostgreSQL version to the folder lib, which is inside the folder where PostgreSQL was installed.
tar -xzvf omnidb-plugin_2.16.0-freebsd.tar.gz
cp omnidb-plugin_2.16.0-freebsd/omnidb_plugin_10.so /usr/local/lib/postgresql/omnidb_plugin.so
23.3.3. Set shared_preload_libraries¶
Change the file PostgreSQL_directory/data/postgresql.conf, including the following line:
shared_preload_libraries = 'omnidb_plugin'
Then restart PostgreSQL.
23.3.4. Post-installation steps¶
23.3.4.1. Create omnidb schema in your database (should be done by a superuser)¶
psql -d <database> -f debugger_schema.sql
23.3.4.2. Create sample functions (optional)¶
psql -d <database> -f sample_functions.sql
23.3.4.3. Next steps¶
Follow Post-installation steps in section 5.
23.4. MacOSX Installation¶
23.4.1. Limitations¶
If you have PostgreSQL installed in your Mac and want to also install OmniDB debugger, please be aware that currently we don’t offer any packages for the debugger for Mac OS X. Your only option is to compile and install from sources. It is not that hard, as you can see below.
23.4.2. Compiling the extension from source¶
23.4.2.1. Install SDK headers for Mac OS¶
sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /
23.4.2.2. If not installed, install PostgreSQL from Homebrew¶
This will also install PostgreSQL headers and libpq.
If brew is not installed yet, you can install it like this:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Then:
brew install postgresql
23.4.2.3. Compile omnidb_plugin¶
make
23.4.2.4. Install omnidb_plugin¶
sudo make install
23.4.2.5. Set shared_preload_libraries¶
vim /usr/local/var/postgres/postgresql.conf
shared_preload_libraries = 'omnidb_plugin'
brew services restart postgresql
23.4.2.6. Post-installation steps¶
23.4.2.6.1. Create omnidb_plugin extension (should be done by a superuser)¶
psql -d <database> -c 'CREATE EXTENSION omnidb_plugin'
23.4.2.6.2. Create sample functions (optional)¶
psql -d <database> -f sample_functions.sql
23.4.2.6.3. Next steps¶
Follow Post-installation steps in section 5.
23.5. Post-installation steps ** REQUIRED **¶
23.5.1. Grant privileges to each database user that will debug functions (should be done by a superuser)¶
Every database user that uses the debugger needs access to the debugger control tables.
psql -d <database> -c 'GRANT ALL ON SCHEMA omnidb TO <user>; GRANT ALL ON ALL TABLES IN SCHEMA omnidb TO <user>;'
23.5.2. Enable passwordless access to each database user that will debug functions¶
Every database user that uses the debugger needs local passwordless access to the target database. This is because the database will create an additional local connection to perform debugging operations.
We need to add a rule to pg_hba.conf of type host
, matching the PostgreSQL
user and database OmniDB is connected to. The method can be either trust
,
which is insecure and not recommended, or md5
.
trust¶
- Add a rule similar to:
# TYPE DATABASE USER ADDRESS METHOD
host <database> <user> 127.0.0.1/32 trust
host <database> <user> ::1/128 trust
md5¶
- Add rules similar to:
# TYPE DATABASE USER ADDRESS METHOD
host <database> <user> 127.0.0.1/32 md5
host <database> <user> ::1/128 md5
- Create a
.pgpass
file with a similar content:
localhost:<port>:<database>:<username>:<password>
More information about how .pgpass
works can be found here: https://www.postgresql.org/docs/11/static/libpq-pgpass.html