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

    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;

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

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 at https://manager.pgxn.org/upload.

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