Skip to main content

Install PolyScale

Prerequisites​

The self hosted version of PolyScale requires Docker. The PolyScale Private Cache Endpoint (PCE) runs within a Docker container to provide low-latency, local caching.

Each PCE requires an outbound port of 5671 to be open for control plane access.

Installation​

Step 1: Create a PolyScale API Key​

After signing up for a free PolyScale account, create an API Key from within the PolyScale User Interface.

To create an API Key, click on Settings underneath the dropdown at the top right of the PolyScale application to go to the Workspace Settings page.

From the Workspace Settings page, select API Keys on the left hand side, and then click Create new at the top right. On the Create API Key window, be sure to check the permission for Self Hosted Trial.

Create API KeyCheck the "Self Hosted Trial" permission.
tip

Once you create the API Key, be sure to store it somewhere safe as you can not view it again.

Step 2: Download the PCE​

Download the PCE docker image with the following command:

docker pull ghcr.io/polyscale/pce:stable

Step 3: Start the PCE​

Use the command below to start running the PCE container:

docker run -e PCE_API_KEY='YOUR_API_KEY' -p 3306:9000 -p 5432:9000 -p 3307:9001 -p 1433:9020 ghcr.io/polyscale/pce:stable

This command will start the local PolyScale cache in Docker and map the internal ports of the PCE to familiar external ports as shown below. You can of course amend these as required.

  • MySQL: 3306
  • MariaDB: 3307
  • PostgreSQL: 5432
  • SQL Server: 1433

Step 4: Create a PolyScale cache​

A Polyscale account can have one or more caches defined. A cache simply identifies a database origin via a hostname and port that you wish to cache data for. Typically you create a cache per database for simplicity.

To create a new cache, click the New Cache button in the upper right of the caches dashboard and enter the hostname and port of the database you wish to connect to.

New cache buttonClick the New Cache button
Create new CacheEnter the origin database hostname and port
tip

Cache creation for use with the PCE is identical to the process for connecting a cache using the PolyScale Serverless. However, if your database is not accessible publicly, at present the network test that runs when a cache is created will fail. This does not mean you have a configuration problem; it just means that your database is not publicly accessible. To use the PCE, ensure that your database host specified in your cache configuration is accessible from the Docker machine running the PCE.

Step 5: Connect to the PCE​

To connect to the origin database via PolyScale simply update any client applications as follows:

5.1 Use a PolyScale database hostname and port:​

Hostname: 127.0.0.1​

The PolyScale user interface indicates that psedge.global is the hostname to use to connect to PolyScale. However, to connect using the PCE, use the host of your Docker container (which by default should be 127.0.0.1).

Port:​

  • MySQL: 9000
  • MariaDB: 9001
  • PostgreSQL: 9010
  • SQL Server: 9020

5.2 Provide a PolyScale Cache ID as part of the connection string:​

The Cache ID can be found under the Settings tab of any cache (as detailed in Step 4 above). For MySQL, MariaDB and SQL Server, this is prepended to the database username separated with a hyphen (see example below). For PostgreSQL, an application_name property containing the PolyScale Cache ID is required as part of the connection string e.g. application_name=MY_CACHE_ID.

MySQL Example​

If the cache ID provided by PolyScale is 8794d0be-4cbf-4ac2-b230-28e524782405 and the origin database username is foobar, the database username to connect via PolyScale would be 8794d0be-4cbf-4ac2-b230-28e524782405-foobar.

Postgres Example​

For example, your connection string would be: postgres://DB_USERNAME:DB_PASSWORD@127.0.0.1:5432/DB_NAME?application_name=CACHE_ID for a Postgres database.

That's it - you now have PolyScale running locally, configured to automatically cache queries to your database.

PCE Configuration Options​

The PCE can be configured as part of the command line using the -e option, the following configuration options are available:

  • PCE_API_KEY: This is the only required setting and is your API KEY to connect to the PolyScale control plane.
  • PCE_TAG: If you run multiple PCEs on your network using the PCE_TAG option will aid in distinguishing metric traffic in the PolyScale webapp.
  • PCE_CACHE_SIZE: Size of the cache in bytes, default is 2GB.
  • PCE_CACHE_PATH: Location on the filesystem where cached data is stored.

If you have your own certificates and wish to have your application verify them (MaTLS) then you need to provide credentials to the PCE

  • PCE_PRIVATE_KEY: Private key for this PCE signed by your trusted authority.
  • PCE_CERT_CHAIN: The certificate chain PCE can use to verify your applications certificates.