In order to set up a database connection, modify the file /etc/rstudio/database.conf. The file contains documentation about how to use it, and you can simply uncomment any lines that are relevant to your configuration. Note that because the file can contain sensitive information, such as a password or access token, this file must be user read/write only (file mask 600) and should be owned by root. On start up, Posit Workbench will attempt to set the permissions of the database.conf file to root:root 600.


By default, Posit Workbench creates a SQLite database for you automatically under the /var/lib/rstudio-server directory. For single-node installations, this is sufficient, but as stated before, will not be sufficient for load balanced deployments.

You should never specify a SQLite directory that is on shared storage, such as NFS. Per the SQLite documentation, this can cause data corruption.

Sample configuration:


# Directory in which the sqlite database will be written


If you wish to use PostgreSQL, you must create an empty database for Posit Workbench to connect to. You must not share this database with other products or services. If running an HA setup, it is strongly recommended to run the database on a separate server than the Posit Workbench services to ensure maximum availability. The minimum supported version is PostgreSQL 11. It requires a 1Ghz processor with 2GB of RAM, and 4GB of disk space.

Posit Workbench must be configured to connect to your PostgreSQL instance with a valid authentication method, such as SSL (TLS) certificate-based authentication. For more details on this and other PostgreSQL fundamentals, see the support article Install and Configure PostgreSQL for Posit Workbench / RStudio Server Pro and the PostgreSQL Certificate Authentication documentation.

Because the internal database can contain sensitive information, it is strongly recommended to configure your PostgreSQL instance to use SSL (TLS) encrypted connections. More information can be found in the Secure TCP/IP Connections with SSL section of the PostgreSQL documentation.

Password encryption is no longer supported

We have removed support for decrypting or providing encrypted database passwords for the internal PostgreSQL database used in Posit Workbench. Instead, we now strongly recommend a more robust authentication mechanism, such as SSL certificate-based authentication. When a password appears to be encrypted, Workbench will log a warning, and attempt to use it as an unencrypted password.

Sample configuration:



Available PostgreSQL connection string parameters are documented in the official PostgreSQL documentation.

SSL Certificate Authentication

SSL certificate authentication for the PostgreSQL database can be used with Posit Workbench, and is the recommended auth method to use. To use certificate authentication you must configure your PostgresSQL server for SSL connections and authentication. See the official PostgreSQL Certificate Authentication documentation for more information.

Once your certificates are set up with postgres, the connection-uri parameter in database.conf will need to include sslcert, sslkey, and sslrootcert parameters.

For example:

Common Name in the certificate must match the database username

The cn (Common Name) attribute of the certificate will be compared to the requested database user name in database.conf, and if they match the login will be allowed.

If they don’t match, you can specify a map in pg_ident.conf to map cns and usernames, for example:

posit-workbench your-common-name   postgres-username

You can then update pg_hba.conf to reference the map created above:

hostssl all            all                  cert  map=posit-workbench

For more information, see the PostgreSQL User Name Maps documentation.


If you need to, you can tell Posit Workbench to restrict itself to keeping its tables within a specific schema. You control this by giving PostgreSQL a search path as part of the URL by adding options=-csearch_path=<schema-name> to the connection-uri. If it’s the only item you’re adding, separate it from the rest of the URL with ? (just like the sslmode item above). Otherwise, separate it from other items with ‘&’.

For example:


Posit Workbench will refuse to start when given a schema that does not already exist. The schema must be owned by the connecting user or by a group that contains the connecting user.

PostgreSQL account

When setting up your PostgreSQL database for use with Posit Workbench, ensure that you do not use the default postgres user account that comes with a standard installation. This is to ensure that your database is secure. If using password authentication, aways ensure that whichever account that is used to access the database contains a strong password - do not use an account that has no password! You should also ensure that only one PostgreSQL user has access to the Posit Workbench database for maximum security.

PostgreSQL connection testing and troubleshooting

Once the settings have been entered in /etc/rstudio/database.conf, use the sudo rstudio-server verify-installation command to test connectivity and quickly view errors and warnings.

Connection pool

Posit Workbench will create a pool of connections to the database at startup. The size of this pool defaults to the number of logical CPUs on the host running Posit Workbench, up to 20. It is not generally recommended that you adjust the size of this pool manually unless you need to address a specific problem, such as exceeding a connection limit on the database or experiencing delays in Posit Workbench caused by unavailable connections.

If you do need to adjust the size of the pool, you can do so by setting pool-size in database.conf as follows: