PGXN

    pgxn install pg_isok

    CREATE SCHEMA isok;
    CREATE EXTENSION pg_isok SCHEMA isok;

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.

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

These are the make variables that control the build options:

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

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

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:

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.

With appropriate OS-level permissions, run:

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

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:

    CREATE SCHEMA isok;
    CREATE EXTENSION pg_isok SCHEMA isok;

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

To uninstall with pgxnclient, run:

To uninstall using make, run:

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.

Running:

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.