monad-one/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 maintainer's blog

🏃 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

👋 "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:

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

Here we instruct the handler that is provisioned by omni_httpd by default to use the enclosed query to greet the world:

$ curl localhost:8080
Hello, world!

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

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

Now, it'll respond in a personalized manner if name query string parameter is provided:

$ curl localhost:8080
Hello, world!

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

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.

🏗️ Component Roadmap

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

Name	Status	Description
omni_schema	✅ First release candidate	Application schema management
omni_json	✅ First release candidate	JSON toolkit
omni_xml	✅ First release candidate	XML toolkit
omni_http	✅ First release candidate	Common HTTP types library
omni_httpd and omni_web	✅ First release candidate	Serving HTTP in Postgres and building services in SQL
omni_mimetypes	✅ First release candidate	MIME types and file extensions
omni_httpc	✅ First release candidate	HTTP client
omni_sql	🚧 Extremely limited API surface	Programmatic SQL manipulation
omni_vfs	☑️ Initial prototype	Virtual File System interface
omni_containers	☑️ Initial prototype	Managing containers
omni_ext and Dynpgext interface	☑️ Getting ready to become first release candidate	Advanced Postgres extension loader
omni_types	✅ First release candidate	Advanced Postgres typing techniques (sum types, etc.)
omni_seq	✅ First release candidate	Extended Postgres sequence tooling
omni_txn	✅ First release candidate	Transaction management
omni_python	☑️ Initial prototype	First-class Python Development Experience
omni_git	🥼 Early experiments (unpublished)	Postgres Git client
omni_reactive	🗓️ Haven't started yet	Reactive queries

⌨️ Hacking

Building & using extensions

To build and run Omnigres, you would currently need a recent C compiler, OpenSSL and cmake:

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

Running tests

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

Devenv.sh-based local development environment

Initial setup

Follow these guides:

https://devenv.sh/getting-started/
https://devenv.sh/automatic-shell-activation/
Run direnv allow in omnigres repo

Day-to-day development

cd into the repo. This brings in all dependencies.
To bring up development stack (Postgres with all extensions, etc.), run: devenv up

Once the development environment is running, you can connect to it by issuing:

pg -> this connects to Postgres through a UNIX socket, for maximum performance. CLI args forwarded.
pgclear -> removes the PGDATA folder contents. You want to restart devenv up after this so Postgres can reinitialize as per devenv.nix.

monad-one / omnigres