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:latest
# Now you can connect to it:
psql -h localhost -p 5432 -U omnigres omnigres # password is `omnigres`

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