Installing, Upgrading, and Un-installing
Prev |  | Next

## Installing, Upgrading, and Un-installing

There are two steps to installation. First, getting and preparing the code and, when installing as an extension, installing into the OS, and, second, loading into one or more databases.

| Note
Installing Isok into the OS, which is necessary when installing as an extension, typically requires elevated OS-level privileges, such as `root` privileges. The examples given do not include the assumption of elevated privileges, or show the use of any particulars, such as the sudo command, needed to assume such privileges. Similarly, the examples do not include the connection parameters (usernames, passwords, hosts, database names, etc.) which may be needed to connect to a database.

Regardless of how Isok is installed, we recommend you install it in a dedicated `schema`. Dedicating a schema to Isok has a number of benefits, not the least of which is simplified access control to mitigate security concerns.[6] When a schema is created, only the owner can access its content. This is sufficient protection, assuming care is taken using the ISOK_QUERIES.Role and ISOK_QUERIES.Search_Path columns. (Or, if these features are disabled.)

### Requirements

Isok installs on PostgreSQL version 10 or later, although PostgreSQL versions no longer supported by The PostgreSQL Global Development Group may get reduced support.

### Quick-Start

Most people should do a normal install, which installs Isok as an extension.

If you're running a managed instance of PostgreSQL, in the cloud or otherwise, and don't have access to the machine running the PostgreSQL cluster, you'll need to install from SQL.

#### Normal Install

- Login to the machine running your PostgreSQL database

- Download the pg_isok distribution

- unzip pg_isok-*.zip

- cd into the directory produced

- sudo make install

- Execute SQL like:

  CREATE SCHEMA isok;
  CREATE EXTENSION pg_isok SCHEMA isok;

#### SQL Install

Download the Isok zip file, unzip it, and cd into its directory.

Choose the name of the schema into which you wish to install Isok. Generate Isok's SQL with:

make TARGET_SCHEMA=myschema sql/pg_isok_cloud--VERSION.sql

Where `VERSION` is the version of Isok you are installing.

Create the schema you've chosen, if it does not exist, and execute the SQL found in the `sql/pg_isok_cloud--VERSION.sql` file.

### Preparing, While Logged-In to Un*x

Installing as an extension requires that the installation be done while logged into the PostgreSQL server's machine. Or, at minimum, while the current working directory is within the server's filesystem.

Installing from SQL, as is necessary when the PostgreSQL's server's filesystem is unavailable, must be done from a machine able to work as a PostgreSQL client.

When installing from SQL, the recommended download is the Isok zip file “distribution” from PGXN.org. It is "pre-built", and so does not require installation of any build tooling. If you have this, after unzipping, you can skip over the next sections, which cover disabling features, and cloud installation, and skip straight to Installing in the PostgreSQL Server's OS.

It is also possible to clone the Isok git repository, but be forewarned. Working from the git repository requires the installation of considerable tooling.

| Note
Any rebuild of Isok requires the installation of the m4 macro pre-processor.[7] Your operating system almost surely makes available an `m4` package. Only the "pre-built" PGXN distribution can be installed without the use of m4.

| Note
One would expect to be able to use pgxnclient for installation. However, it has limitations that make it difficult to use.

#### Re-Building to Disable Features

If desired, some potentially dangerous features of Isok can be disabled at build time.

These are the make variables that control the build options:

DISABLE_ROLE

  Disable the ability to SET ROLE from ISOK_QUERIES.

DISABLE_SEARCH_PATH

  Disable the ability to SET the search_path.

To use these variables, set them to any value when running make. For example, to disable all optional features run:

make DISABLE_ROLE=y DISABLE_SEARCH_PATH=y

The build configuration is documented in the doc/pg_isok--${VERSION}.config file, and installed with the rest of the documentation.

#### Building for and Installing in The Cloud (Installing From SQL)

If you are running in the cloud, or some other managed instance where you do not have permissions on the host running PostgreSQL, you will not be able to install Isok as an extension. In these cases you can still install Isok, but you must first build its SQL and then manually execute it.

Of course, this installation method can always be used, as there is always a way to execute SQL.

To build a “cloud version” of Isok, suitable for installation by SQL execution, you would type something like:

make TARGET_SCHEMA=isok pg_isok_cloud--$(cat VERSION).sql

The resulting sql file is in the sql/ directory.

To customize the build, any of the above variables may also be set. The TARGET_SCHEMA variable must be set; the objects produced by the generated SQL must be located within a designated `schema`. It is highly recommended that the TARGET_SCHEMA be lower-case and otherwise be a PostgreSQL name which does not require quoting.

To install, first create the `schema` and then execute the sql. The command line interaction, if you use the psql command line client interface, would look something like:

    $ psql
    psql (15.13 (Debian 15.13-0+deb12u1))
    Type "help" for help.

    me=> CREATE SCHEMA isok;   -- The TARGET_SCHEMA used to build the sql
    CREATE SCHEMA
    me=> \i sql/pg_isok_cloud--1.0.0.sql
    <lots of output redacted>
    me=> \q
    $

You must re-build different SQL, with a different TARGET_SCHEMA, to install a second instance of Isok into a different schema.

#### Installing in the PostgreSQL Server's OS

With appropriate OS-level permissions, run:

make install

With this step complete, you are ready to install the Isok extension into any schema of any database in the cluster.

If you have more than one cluster installed on the machine, Isok is installed into the default cluster, the one reported on if you execute pg_config.

To install into a different cluster you must first find the pg_config command belonging to the cluster you wish to install into. The output of pg_config --bindir may be helpful in this regard. It shows the path to the default cluster's pg_config.

Having found the full path to the pg_config command of the target cluster, install Isok into that cluster (as `root`) with something like:

make PG_CONFIG=/usr/lib/bin/postgresql/15/bin/pg_config install

#### Running Regression Tests

Once an extension has been installed in the OS, regression tests can be run to test whether Isok is operating correctly. Running the regression tests when Isok is installed by SQL execution is unsupported.

The same build variables must be set when running the regression tests as when the system was built. (The PGXN distribution sets no variables, the default.) Should you set a different collection of variables than when building, some tests will fail and others may fail to run at all.

The following example runs the default set of regression tests:

make installcheck

### Loading Into PostgreSQL

The CREATE EXTENSION command is used to install Isok, as in the following example:

CREATE SCHEMA isok;
CREATE EXTENSION pg_isok SCHEMA isok;

### Upgrading

Upgrading Isok is done just like upgrading any other PostgreSQL extension.

First, download the new version and install it into the OS. If you have re-built to disable features then don't forget to do that again before installing into the OS.

After OS installation upgrade with:

ALTER EXTENSION pg_isok UPDATE;

This needs to be done in every database in which Isok has been installed.

### Uninstalling

#### Uninstalling From the OS

Uninstalling from the OS does the opposite of installing. It removes the extension from the PostgreSQL server's filesystem.

To uninstall using make, run:

make uninstall

To uninstall with `pgxnclient`, run:

pgxn uninstall pg_isok

Because Isok is pure SQL, uninstalling it from the OS does not remove any functionality from existing instances installed with CREATE EXTENSION. Uninstalling does, however, remove the ability to use the CREATE EXTENSION to install Isok in a database.

#### Uninstalling From PostgreSQL

Running:

DROP EXTENSION pg_isok;

removes the extension from all schemas in the current database.

To remove an installation of Isok from an individual schema, drop the schema with DROP SCHEMA schemaname CASCADE;.

[6] The downside to installing in a schema is that when writing SQL you must either set your search_path or qualify names, by prepending the object name with the schema name and a period. For example, without setting a search path, if you installed into a schema named isok, instead of SELECT * FROM run_isok_queries();, you would have to write SELECT * FROM isok.run_isok_queries();.

[7] Possibly, the GNU m4 implementation is required. This is what PostgreSQL requires, and alternatives have not been tested.

Prev |  | Next
A Start-To-Finish Set of Examples | Home | An Overview of the Tables

Page generated: 2025-12-15T15:11:24-06:00.