Omnigres

Documentation | Bounties

Omnigres makes Postgres a developer-first application platform. You can deploy a single database instance and it can host your entire application, scaling as needed.

• Running application logic inside or next to the database instance
• Deployment provisioning (Git, containers, etc.)
• Database instance serves HTTP, WebSocket and other protocols
• In-memory and volatile on-disk caching
• Routine application building blocks (authentication, authorization, payments, etc.)
• Database-modeled application logic via reactive queries
• Automagic remote APIs and form handling
• Live data updates

Blogs and Publications

• Omnigres blog

:runner: Quick start

The fastest way to try Omnigres out is by using its container image:

docker volume create omnigres
docker run --name omnigres --mount source=omnigres,target=/var/lib/postgresql/data \
           -p 127.0.0.1:5432:5432 -p 127.0.0.1:8080:8080 --rm ghcr.io/omnigres/omnigres-17:latest
# Now you can connect to it:
psql -h localhost -p 5432 -U omnigres omnigres # password is `omnigres`

[!TIP] Replace ghcr.io/omnigres/omnigres-17 with ghcr.io/omnigres/omnigres-slim-17 if you want a smaller image.

Postgres parameters such as database, user or password can be overridden as per the "Environment Variables" section in postgres image instructions

You can access the HTTP server at localhost:8080

Building your own image

If you can't use the pre-built image (for example, you are running a fork or made changes), you can build the image yourself:

# Build the image
DOCKER_BUILDKIT=1 docker build . -t ghcr.io/omnigres/omnigres

Download omnigres extensions

Omnigres extensions can also be downloaded and installed in any postgres installation with file system access.

:wave: "Hello, world"

Here we expect you are running the container image, which has omni_httpd and omni_web extensions provisioned by default.

Let's start with a traditional example. Here we will instruct the handler that is provisioned by omni_httpd by default to use the enclosed query to greet the world.

Below, we'll show examples in Python and plain SQL (or PL/pgSQL). Support for more languages is coming!

$ curl localhost:8080
Hello, world!

from omni_python import pg
from flask import Flask
from omni_http.omni_httpd import flask

app = Flask('myapp')


@app.route('/')
def hello():
    return "Hello, world!"


handle = pg(flask.Adapter(app))

update omni_httpd.handlers
set
    query =
        $$select handle(request.*) from request$$;

update omni_httpd.handlers
set
    query =
        $$select omni_httpd.http_response('Hello, world!') from request$$;

Now, let's make it more personal and let it greet the requester by name.

$ curl "localhost:8080?name=John"
Hello, John!

from flask import request  # we need to access `request`


@app.route('/')
def hello():
    return f"Hello, {request.args.get('name', 'world')}!"

update omni_httpd.handlers
set
    query =
        $$select omni_httpd.http_response('Hello, ' || 
                   coalesce(omni_web.param_get(request.query_string, 'name'), 'world') || '!')
          from request$$;

This, of course, only barely scratches the surface, but it may give you a very high-level concept of how Omnigres web services can be built.

For a more complex example, that uses the underlying database and employs more real-world layout, check out this MOTD service example.

:building_construction: Component Roadmap

Below is the current list of components being worked on, experimented with and discussed. This list will change (and grow) over time.

:keyboard: Hacking

Building & using extensions

To build and run Omnigres, you would need:

• a recent C compiler
• OpenSSL 3.2 (optional, will be built if not available)
• cmake >= 3.25.1
• (optionally, to use omni_containers or run a full set of tests) a recent version of Docker

cmake -S . -B build
cmake --build build --parallel
make -j psql_<COMPONENT_NAME> # for example, `psql_omni_containers`

Troubleshooting

cmake -S . -B build -DPython3_EXECUTABLE=/path/to/python

rm -rf .pg build

Running tests

# in the build directory
CTEST_PARALLEL_LEVEL=$(nproc) make -j $(nproc) all test