Installing from Pre-Built Release¶
The release page has precompiled binaries for Mac OS X, Windows, and several Linux distros. Extract the tarball and run the binary inside with no arguments to see usage instructions:
# Untar the release (available at https://github.com/begriffs/postgrest/releases/latest) $ tar zxf postgrest-[version]-[platform].tar.xz # Try running it $ ./postgrest # You should see a usage help message
Building from Source¶
When a prebuilt binary does not exist for your system you can build the project from source. You’ll also need to do this if you want to help with development. Stack makes it easy. It will install any necessary Haskell dependencies on your system.
Install Stack for your platform
Install Library Dependencies
Operating System Dependencies Ubuntu/Debian libpq-dev CentOS/Fedora/Red Hat postgresql-devel, zlib-devel BSD postgresql95-server
Build & install in one step
git clone https://github.com/begriffs/postgrest.git cd postgrest stack build --install-ghc sudo stack install --allow-different-user --local-bin-path /usr/local/bin
- Check that the server is installed:
If you want to run the test suite, stack can do that too:
Running the Server¶
postgrest postgres://user:pass@host:port/db -a anon_user [other flags]
The user in the connection string is the “authenticator role,” i.e. a role which is used temporarily to switch into other roles depending on the authentication request JWT. For simple APIs you can use the same role for authenticator and anonymous.
The complete list of options:
- -p, --port
- The port on which the server will listen for HTTP requests. Defaults to 3000.
- -a, --anonymous (required)
- The database role used to execute commands for those requests which provide no JWT authorization.
- -s, --schema
- The db schema which you want to expose as an API. For historical reasons it defaults to 1, but you're more likely to want to choose a value of public.
- -j, --jwt-secret
- The secret passphrase used to encrypt JWT tokens. Defaults to secret but do not use the default in production! Load-balanced PostgREST servers should share the same secret.
- -o, --pool
- Max connections to use in db pool. Defaults to to 10, but you should find an optimal value for your db by running the SQL command show max\_connections;
- -m, --max-rows
- Max number of rows to return in a read request. The default is no limit.
Hiding Password from Process List
Passing the database password and JWT secret as naked
parameters might not be a good idea because the parameters are
visible in a
ps listing. One solution is to set
environment variables such as PASS and use
in the connection string. Another is to use a user-specific
postgrest on the same machine as PostgreSQL, it is also
possible to connect to the database using the Unix
socket and the
as an alternative to TCP/IP communication and authentication with a
The Peer Authentication grants access to the database to any Unix user who connects as a user of the same name in the database. Since the empty host resolves to the Unix socket and the password can be omitted in this case, the command line is reduced to:
sudo -u user postgrest postgres://user@/db [flags]
sudo -u user command runs the following command as given
If you create a Unix user
postgrest and a database user
postgrest for example, the command becomes:
sudo -u postgrest postgrest postgres://postgrest@/db [flags]
postgrest is the Unix user name, the second
is the name of the executable, the third
postgrest is the name of
the database user.
Install via Homebrew (Mac OS X)¶
You can use the Homebrew package manager to install PostgREST on Mac
# Ensure brew is up to date brew update # Check for any problems with brew's setup brew doctor # Install the postgrest package brew install postgrest
This will automatically install PostgreSQL as a dependency (see the Installing PostgreSQL section for setup instructions). The process tends to take up to 15 minutes to install the package and its dependencies.
After installation completes, the tool is added to your $PATH and can be used from anywhere with:
To use PostgREST you will need an underlying database (PostgreSQL version 9.3 or greater is required). You can use something like Amazon RDS but installing your own locally is cheaper and more convenient for development.