postgrest / plmustache

Logic-less templates for Postgres

plmustache

A PostgreSQL extension that provides a language handler for Mustache templates using https://gitlab.com/jobol/mustach.

Roadmap

• variable interpolation
• sections
  • bools
  • arrays
• partials
• inheritance
• lambdas

Features

Variables

Variables are handled as per the mustache spec, a {{key}} variable will be interpolated.

create or replace function win_money(you text, qt money, at timestamptz) returns text as $$
Hello {{you}}!
You just won {{qt}} at {{at}}.
$$ language plmustache;

select win_money('Slonik', '12000', now());
                         win_money
-----------------------------------------------------------
 Hello Slonik!                                            +
 You just won $12,000.00 at 2023-12-04 07:44:26.915735-05.
(1 row)

Escaped and Unescaped

A double mustache {{key}} will be escaped and a triple mustache {{{key}}} will not be escaped.

create or replace function escape_me(tag text) returns text as $$
{{tag}}
$$ language plmustache;

select escape_me('<script>evil()</script>');
              escape_me
-------------------------------------
 &lt;script&gt;evil()&lt;/script&gt;
(1 row)

create or replace function do_not_escape_me(tag text) returns text as $$
{{{tag}}}
$$ language plmustache;

select do_not_escape_me('<script>evil()</script>');
    do_not_escape_me
-------------------------
 <script>evil()</script>
(1 row)

Sections

create or replace function show_cat(cat text, show bool default true) returns text as $$
{{#show}}
A cat appears, it's {{cat}}.
{{/show}}
{{^show}}
A mysterious cat is hiding.
{{/show}}
$$ language plmustache;

select show_cat('Mr. Sleepy');
            show_cat
---------------------------------
 A cat appears, it's Mr. Sleepy.+

(1 row)

select show_cat('Mr. Sleepy', false);
          show_cat
-----------------------------
 A mysterious cat is hiding.+

(1 row)

Installation

Clone the repo and submodules:

git clone --recurse-submodules https://github.com/PostgREST/plmustache

Build mustach:

cd mustach
make && sudo make install
sudo ldconfig

Build plmustache:

cd ..

make && sudo make install

Then on SQL you can do:

CREATE EXTENSION plmustache;

plmustache is tested on Postgres 12, 13, 14, 15, 16.

Development

For testing on your local database:

make installcheck

For an isolated and reproducible enviroment you can use Nix.

$ nix-shell

$ with-pg-15 psql

$ with-pg-15 make installcheck

plmustache's Issues

Mustache comments are not handled well

Proof:

create or replace function hello(x text) returns text as $$
Hello, {{! ignore me }} {{x}}
$$ language plmustache;

select hello('foo');
  hello  
---------
 Hello, 
(1 row)

Comment structure documented at https://github.com/mustache/spec/blob/master/specs/comments.yml

Strangely, mustache-c is considering comments as /* comment */

https://github.com/x86-64/mustache-c/blob/master/src/parser.l#L33

handle sections for composites

Should be like:

create type person (name text, lastname text);

create or replace function hello(p person) returns text as $$
Hello, {{#p}} {{name}} {{/p}}
$$ language plmustache;

select hello('(John,Doe)');
Hello John

select hello(null);
Hello

According to https://github.com/mustache/spec/blob/master/specs/sections.yml#L56-L60

handle sections for arrays

Should be like:

create or replace function hello(xs text[]) returns text as $$
Hello, {{#xs}} {{.}} {{/xs}}
$$ language plmustache;

select hello(ARRAY['a', 'b', 'c']);
Hello a b c

According to https://github.com/mustache/spec/blob/master/specs/sections.yml#L181-L186

mustach submodule is not navigable on GitHub UI

Problem

Clicking on the mustach folder gets you nowhere. Likely because the repo is hosted on gitlab.

Solution

Upload the mustach repo on the PostgREST org and make it clear it's a mirror of https://gitlab.com/jobol/mustach

handle partials by calling other (plmustache) functions

Since it doesn't make sense to load partials from file, it would be great if other functions could be called via partials:

create or replace function hello() returns text as $$
Hello, {{>world}}
$$ language plmustache;

create or replace function world() returns text as $$
World
$$ language plmustache;

select hello();
Hello, World

It should even be possible to pass arguments to those functions via blocks and parents:

create or replace function hello(subject text) returns text as $$
Hello, {{subject}}
$$ language plmustache;

create or replace function hello_world() returns text as $$
{{<hello}}
  {{$subject}}World{{/subject}}
{{/hello}}
$$ language plmustache;

select hello();
Hello, World

Neither blocks, nor parents are supported by jobol/mustach, yet. I opened an issue about it.

I don't think it's possible to override the default "file loader" either, so that probably needs some changes in jobol/mustach, too.

handle sections for booleans

Should be like:

create or replace function hello(x1 text, only_if bool) returns text as $$
Hello, {{#only_if}} {{x1}} {{/only_if}}
$$ language plmustache;

select hello('John', true);
Hello John

select hello('John', false);
Hello

According to https://github.com/mustache/spec/blob/master/specs/sections.yml#L38-L48

Dependency tracking

BEGIN ATOMIC works like this right now:

create table person (
	firstname text,
	lastname text
);

create function foo(person) returns text begin atomic select $1.firstname || $1.lastname; end;

select foo('(x,y)');
 foo 
-----
 xy
(1 row)

After a column rename, the function keeps working:

alter table person rename column lastname to last_name;

select foo('(x,y)');
 foo 
-----
 xy
(1 row)

This because it automatically updates the function body:

\df+ foo

BEGIN ATOMIC                               +
 SELECT (($1).firstname || ($1).last_name);+
END                                         

If the foo function were to be created with language sql, it wouldn't work that way:

create or replace function foo(person) returns text as $$
	select $1.firstname || $1.lastname;
$$ language sql;

select foo('(x,y)');

ERROR:  column "lastname" not found in data type person
LINE 2: select $1.firstname || $1.lastname;

Not sure if we can achieve the BEGIN ATOMIC behavior, but could we at least fail if a column is renamed? Maybe by inserting an entry into pg_depend?

This will make more sense once #2 is done.

It would also be a compelling reason to do HTML rendering on the database.

Escape the single quote

Problem

The single quote ' should be escaped. This is not on the mustache spec but most implementations have it. Also the mustache spec maintainers are open to add this restriction. See mustache/spec#69.

Solution

Patch https://gitlab.com/jobol/mustach to escape the single quote to '.

logo for plmustache

Maybe just combine the mustache logo with slonik logo.

Nix workflow is clunky

Problem

To compile, right now I do:

$ nix-shell

And to recompile:

$ <Ctr-C to exit>
$ nix-shell # again

Proposal

Similarly to the postgrest repo, a:

$ plmustache-watch plmustache-build

Would be ideal. Even just a plmustache-build command where exiting manually is not needed would be an improvement.

Handle variables with composite types

Problem

Right now is not possible to get a composite type members.

Solution

Support mustache dotted names https://github.com/mustache/spec/blob/master/specs/interpolation.yml#L162-L167 like so:

create function print_person(p person) returns text as $$
Hello, {{p.name}} {{p.lastname}}
$$ language plmustache;

Related work - move to `jobol/mustach`

Did you consider using https://gitlab.com/jobol/mustach instead of mutache-c? Seems to be actively maintained.. and from first glance seems to have implemented more of the spec?

At the same time, I found this:

https://github.com/RekGRpth/pg_mustach

Maybe this can be extended on?

Syntax highlighting doesn't work when storing mustache files in function definitions

Problem

As it can be seen on https://github.com/PostgREST/plmustache?tab=readme-ov-file#sections, regular syntax highlighting for mustache files doesn't work.

Solution

Add a psql command that can obtain the function body from another file.

\create_function from ./templates/hello.mustache hello(arg text) returns int LANGUAGE plmustache

I've submitted this on https://www.postgresql.org/message-id/CAGRrpzZnoWY-kK_0qK-OY%3D-e0eDqhc5kdFSkuxN0mxe9iuiz0Q%40mail.gmail.com

It can also be tried on this branch https://github.com/steve-chavez/postgresql/tree/cf with:

$ nix-shell
$ pg-build && with-pg psql

\create_function from ./src/pl/plpython/data/max.py public.max(a int, b int) returns int language plpython3u

select max(3, 4);

Alternatives

• A special syntax highlighter for postgres functions with different langs in VIM? This would have to be done for various editors/IDEs though.
• Another executable besides psql that deploys the functions based on mustache files.