INSTALL

PL/Ruby Installation
====================

PL/Ruby builds with PostgreSQL's extension build infrastructure (PGXS) and
links against a shared-library Ruby (MRI).


1. Prerequisites
----------------

  * PostgreSQL 11 or newer (tested on 11-18), including the server development
    files that provide pg_config (Debian/Ubuntu: postgresql-server-dev-NN;
    RPM: postgresqlNN-devel).

  * Ruby 3.x built as a shared library (ENABLE_SHARED=yes) with development
    headers.  On Debian/Ubuntu:

        sudo apt-get install ruby-dev

    Confirm the build is suitable with:

        ruby -rrbconfig -e 'puts RbConfig::CONFIG["ENABLE_SHARED"]'   # must be "yes"

  * A C compiler and GNU make.


2. Build and install
---------------------

PL/Ruby is on PGXN (https://pgxn.org/dist/plruby/), so with the PGXN client
(https://pgxn.github.io/pgxnclient/) the whole build is:

    pgxn install plruby

That downloads the distribution and runs the same PGXS build described here.
From a checkout, or to pass the overrides below:

    make
    sudo make install

The Makefile locates PostgreSQL via pg_config and Ruby via the "ruby" on PATH.
Override them if needed:

    make PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config RUBY=/usr/bin/ruby
    sudo make PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config install


3. Enable the language in a database
------------------------------------

    CREATE EXTENSION plruby;

The PGXN client runs the same statement with:

    pgxn load -d mydb plruby

PL/Ruby is an untrusted language, so the extension is superuser-only to install
and only superusers can create PL/Ruby functions.  See the SECURITY section of
README for why.


4. Run the regression tests (optional)
--------------------------------------

    make installcheck


5. The jsonb, hstore, and ltree transforms (optional)
-----------------------------------------------------

The jsonb_plruby/, hstore_plruby/, and ltree_plruby/ subdirectories each
build a separate extension providing TRANSFORM FOR TYPE jsonb (native Ruby
Hashes/Arrays), TRANSFORM FOR TYPE hstore (Ruby Hash of String => String/nil),
and TRANSFORM FOR TYPE ltree (Ruby Array of label Strings):

    cd jsonb_plruby        # or hstore_plruby, or ltree_plruby
    make
    sudo make install
    # in a database that has (or will get) plruby:
    #   CREATE EXTENSION jsonb_plruby CASCADE;
    #   CREATE EXTENSION hstore_plruby CASCADE;   -- also requires hstore
    #   CREATE EXTENSION ltree_plruby CASCADE;    -- also requires ltree

All three accept the same PG_CONFIG/RUBY overrides and have their own
"make installcheck".

"pgxn install plruby" builds only the top-level extension.  To add a transform
on top of it, unpack the distribution ("pgxn download plruby") or use a
checkout, and build the subdirectory as above.

6. Packaging for PGXN (maintainers)
-----------------------------------

META.json describes the distribution for PGXN (https://pgxn.org): its version,
the four extensions it provides, and where the sources live.  Build the release
archive from a committed tree with:

    make dist

That writes plruby-<version>.zip, taking the version from META.json, and the
archive expands into a single plruby-<version>/ directory, which is the shape
PGXN Manager expects.

Upload it at https://manager.pgxn.org/upload.  A new release shows up
on master.pgxn.org right away; pgxn.org and api.pgxn.org serve it after their
next mirror sync, so a 404 there for a short while is expected.

When cutting a release, keep the "version" field in META.json in step with
plruby.control and the CHANGELOG, the "provides" versions in step with the
per-extension .control files, and the PGXN badge version in README.