Installation
Prev |  | Next

## Installation

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.[1] 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 not get support.

### Quick-Start

The simplest way to get and prepare Isok is to use pgxnclient. Your operating system probably has a `pgxnclient` package available.

The `pgxnclient` package must be installed on the machine running your PostgreSQL server. 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 use another installation method.

After installing `pgxnclient`, the command:

pgxn install pg_isok

makes the Isok extension available to PostgreSQL. Then, executing SQL like:

CREATE SCHEMA isok;
CREATE EXTENSION pg_isok SCHEMA isok;

loads Isok into your database and makes it available for use.

### 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.

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.[2] Your operating system almost surely makes available an `m4` package.

Only the "pre-built" PGXN distribution can be installed without the use of m4.

#### 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 With 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, in order to install 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.

#### 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;

### 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 with `pgxnclient`, run:

pgxn uninstall pg_isok

To uninstall using make, run:

make uninstall

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 schema.

#### Uninstalling From PostgreSQL

Running:

DROP EXTENSION pg_isok;

removes the extension from all schemas in all PostgreSQL clusters.

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

[1] 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();.

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

Prev |  | Next
Introduction to Isok | Home | An Overview of the Isok Tables

Page generated: 2025-06-02T22:24:59-05:00.