Crates.io | postgrpc |
lib.rs | postgrpc |
version | 0.1.2 |
source | src |
created_at | 2022-08-20 21:51:24.395224 |
updated_at | 2022-08-21 19:11:51.706968 |
description | A JSON-transcoding-ready gRPC server for querying Postgres databases |
homepage | https://github.com/boilerplatter/postgrpc |
repository | https://github.com/boilerplatter/postgrpc |
max_upload_size | |
id | 649493 |
size | 2,007,649 |
Query your Postgres databases directly using gRPC, gRPC-web, or transcoded JSON.
Sometimes you want to use the full power of a Postgres database, but you aren't able to make direct connections or you don't want to write a custom API service that wraps your database queries. PostgRPC gives you the power of SQL over gRPC
or JSON, handling distributed transactions and connection management on your behalf.
PostgRPC fills a similar niche as the excellent PostgREST and PostGraphile projects. Unlike those projects, PostgRPC lets you use SQL directly rather than wrapping the interface in another query language (i.e. a REST DSL or GraphQL, respectively). In addition, PostgRPC lets you work with lower-level database constructs like transactions through the same gRPC
or JSON interface used to query your database.
gRPC
types to Postgres types. This includes leveraging Postgres's built-in type inference wherever possible.gRPC
service. For those that need more flexibility, the postgrpc
library is provided to handle custom connection pool logic.ROLE
can be done through an X-Postgres-Role
header (when the role-header
feature is enabled), and correctly deriving the value of that header is the responsibility of other services better suited to the task (e.g. Ory Oathkeeper)examples
directory).For binary installations, use cargo install postgrpc
. The compilation of the postgrpc
executable can be customized with --features
.
For library installations, use cargo add postgrpc
within a cargo
-managed Rust project.
The postgrpc
executable can be configured with the following environment variables:
HOST
: the host that the postgrpc
service uses. Defaults to 127.0.0.1
.PORT
: the port that the postgrpc
service uses. Defaults to 50051
.TERMINATION_PERIOD
: the number of milliseconds postgrpc
waits before shutting down on SIGTERM
signals. postgrpc
shuts down gracefully, waiting for requests to finish where possible. This value is useful for waiting for proxies like envoy
to drain, allowing postgrpc
to handle those requests without error as long as they take less than TERMINATION_PERIOD
milliseconds.In addition, the default connection pool can be configured with the following environment variables:
MAX_CONNECTION_POOL_SIZE
: the number of upstream database connections that the pool is allowed to hold onto. Defaults to 4x the number of CPUs available on the host machine.STATEMENT_TIMEOUT
: the number of milliseconds postgrpc
waits before aborting queries.RECYCLING_METHOD
: the recycling method run as connections are returned to the connection pool. Defaults to clean
.PGDBNAME
(required): the name of the Postgres database to connect to.PGHOST
: the host of the Postgres cluster to connect to. Defaults to localhost
.PGPASSWORD
(required): the password of the user to use when connecting to the Postgres database.PGPORT
: the port of the Postgres cluster to connect to. Defaults to 5432
.PGUSER
(required): the user to use when connecting to the Postgres database.PGAPPNAME
: the application label to use when connecting to the Postgres database. Defaults to postgrpc
.PGSSLMODE
: the sslmode
to use when connecting to the Postgres database. Supported values are disable
, prefer
, and require
.With PostgRPC running on the default port and host, grpcurl
can be used to query the database:
grpcurl \
-plaintext \
-d '{"statement":"select 1 + 1 as two"}' \
[::]:50051 postgres.Postgres/Query
# { "two": 2 }
To use a different (pre-existing) ROLE
than the one used to connect to the database initially, use the X-Postgres-Role
header:
grpcurl \
-plaintext \
-d '{"statement":"select current_user"}' \
-H 'X-Postgres-Role: my-other-user' \
[::]:50051 postgres.Postgres/Query
# { "current_user": "my-other-user" }
All examples can be run from the ./examples
directory using docker-compose
. Click on the links below to learn more about each example.
Contributions are welcome in the form of bug reporting, feature requests, software fixes, and documentation updates. Please submit all code contributions as pull requests through GitHub.
LISTEN
/NOTIFY
-based channelsMATERIALIZED VIEW
-based update streamsproto
generation for an alternative to the dynamic Query
interfaces