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
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 -p 127.0.0.1:8081:8081 --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-extra-17 if you want an image with a lot more batteries included.
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 default HTTP server at localhost:8081
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/omnigresOmnigres extensions can also be downloaded and installed in any postgres installation with file system access.
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:8081
Hello, world!Python (Flask) implementation
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))To connect the endpoint:
insert into omni_httpd.urlpattern_router (match, handler)
values (omni_httpd.urlpattern('/'), 'my_handler'::regproc);NB: Please note that you will need to follow Python setup steps for the time being before our CLI tooling is ready.
Plain SQL
You can also achieve the same using plain SQL with very little setup.
create function my_handler()
returns omni_httpd.http_outcome
return omni_httpd.http_response('Hello world!');
insert into omni_httpd.urlpattern_router (match, handler)
values (omni_httpd.urlpattern('/'), 'my_handler'::regproc);Now, let's make it more personal and let it greet the requester by name.
$ curl "localhost:8081?name=John"
Hello, John!Python (Flask) implementation
from flask import request # we need to access `request`
@app.route('/')
def hello():
return f"Hello, {request.args.get('name', 'world')}!"Plain SQL
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.
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 and Omni interface | ✅ First release candidate | Advanced adapter for Postgres extensions |
| omni_service | ✅ First release candidate | Uniform service management bus |
| omni_test | ✅ First release candidate | Testing framework |
| omni_schema | ✅ First release candidate | Application schema management |
| omni_credentials | ✅ First release candidate | Application credential management |
| omni_id | ✅ First release candidate | Identity types |
| omni_aws | ✅ First release candidate | AWS APIs |
| omni_cloudevents | ✅ First release candidate | CloudEvents support |
| omni_json | ✅ First release candidate | JSON toolkit |
| omni_yaml | ✅ First release candidate | YAML toolkit |
| omni_xml | ✅ First release candidate | XML toolkit |
| omni_http | ✅ First release candidate | Common HTTP types library |
| omni_httpd, omni_web | ✅ First release candidate | Serving HTTP in Postgres and building services in SQL |
| omni_rest | ✅ First release candidate | Out-of-the-box REST API provider |
| omni_session | ✅ First release candidate | Session management |
| 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_sqlite | ✅ First release candidate | Embedded SQLite |
| omni_vfs | ☑️ Initial prototype | Virtual File System interface |
| omni_containers | ☑️ Initial prototype | Managing containers |
| omni_manifest | ☑️ Initial prototype | Improved extension installation |
| omni_types | ✅ First release candidate | Advanced Postgres typing techniques (sum types, etc.) |
| omni_seq | ✅ First release candidate | Extended Postgres sequence tooling |
| omni_var | ✅ First release candidate | Variable management |
| omni_txn | ✅ First release candidate | Transaction management |
| omni_python | ☑️ Initial prototype | First-class Python Development Experience |
| omni_regex | ✅ First release candidate | Feature-rich regular expresssions |
| omni_os | ☑️ Initial prototype | Access to the operating system |
| omni_worker | ✅ First release | Generalized worker pool |
| omni_polyfill | ✅ First release | Provides polyfills for older versions of Postgres |
| omni_git | 🥼 Early experiments (unpublished) | Postgres Git client |
| omni_reactive | 🗓️ Haven't started yet | Reactive queries |
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
Dependencies for Fedora
- Packages:
git cmake gcc g++ cpan openssl-devel openssl-devel-engine python-devel openssl bison flex readline-devel zlib-devel netcat - CMake flags:
-DOPENSSL_CONFIGURED=1
Dependencies for macOS
- XCode Command Line Tools:
xcode-select --install - Homebrew packages:
cmake openssl python
cmake -S . -B build
cmake --build build --parallel
cd build && make -j psql_<COMPONENT_NAME> # for example, `psql_omni_id`To install extensions into your target Postgres:
cmake --build build --parallel --target install_extensions
# Or, individually,
cmake --build build --parallel --target install_<COMPONENT_NAME>_extensioncmake not picking up Python version you want?
To use a specific Python build use the cmake flag Python3_EXECUTABLE:
cmake -S . -B build -DPython3_EXECUTABLE=/path/to/python
Build fails for whatever other reason?
Remove build and .pg directories for a clean rebuild:
rm -rf .pg build
# in the build directory
CTEST_PARALLEL_LEVEL=$(nproc) make -j $(nproc) all testOnce you are ready to contribute, please check out the contribution guidelines.