PolyScale’s partner integration make it simple to offer a fully autonomous database cache as part of your product offering. This can be utilizing PolyScale’s serverless edge network, or by deploying your own private PolyScale network, dedicated to your customers.
If you are interested in integrating with PolyScale, please contact us.
From an end user perspective, integrating PolyScale requires just a simple update to the database connection string; that is, rather than connect an application directly to a database, the traffic is routed via PolyScale as an intermediary.
The goal of the integration can be thought of as successfully providing the user with a valid PolyScale database connection string. This is achieved by making two changes to the origin connection string:
Hostname- update the hostname to use PolyScale’s edge network
Cache ID- provide the PolyScale unique cache identifier to identify where PolyScale should route the traffic to. The cache id is generated upon cache creation. The syntax of how this is included within the connection string varies depending upon database type. You can read more about getting connected here.
With this connection string context, the integration workflow can be broken down into three sections:
- OAuth Applications - using OAuth, validate a user is authorized to work with PolyScale
- Cache Creation - using the PolyScale API, create a new cache or utilize an existing cache to return the cache id.
- PolyScale Connection String - Using the unique cache identifier from step 2, generate and return a PolyScale connection string to the user
With a PolyScale connection string returned, you are then able to make the connection string available within the integrating application. For example, it may be saved as an environment variable.
The following sequence diagram provides an overview of the steps involved:
In order to create a cache, the PolyScale API (
api.polyscale.ai/v1/caches) requires the following inputs:
name- a name to identify the cache within PolyScale
type- the type of origin database
hostname- the hostname of the origin database
port- the port of the origin database
Note that no database
password is required. Once submitted via the API, PolyScale will return the unique cache id. It is then the requirement of your integrating application to generate a valid PolyScale connection string using the cache id to return to your user.
Depending upon whether your integrating application has access to the origin database connection string, will dictate if any of the required cache inputs will be manually input by the end user. For example, if the integrating application is a database provider, it is likely that the
port are all available without the user's interaction. If however your integrating application does not have these credentials, a web form could be used to collect these from the end user. Care should be taken to validate the form inputs; for example, validate that the database
PolyScale Connection String
With a cache id returned from the cache creation step, the final task is to construct a valid PolyScale connection string. This is simple string manipulation. The resulting connection string can then be saved for future use, making sure that it is treated in the same security context as the direct database connection string.
The format of the PolyScale connection string will take one of two forms depending upon the database type:
Postgres Connection String
To generate a valid PolyScale connection string for Postgres:
- set the hostname to use
- pass the cache id using the application_name parameter key
MySQL, MariaDB, MS SQL Connection Strings
To generate a valid connection string for all databases other than Postgres:
- set the hostname to use
- prepend the database username with the cache id and a hyphen
With OAuth applications you can grant third-party services access to your customer’s PolyScale resources via the PolyScale API.
There are two kinds of access scopes:
- read access - allows applications to view resources
- write access - allows applications to modify resources
The currently supported scopes are:
- caches:read - allows reading caches
- caches:write - allows creating, updating and deleting caches
- cacheRules:read - allows reading cache rules
- cacheRules:write - allows creating updating and deleting cache rules
Creating OAuth Applications
OAuth applications can be created at the PolyScale user level or the workspace level. Creating OAuth applications at a workspace level will enable all admin users of that workspace to manage the applications. User level applications can only be managed by that user.
To create an OAuth application at the user level go to Settings → Account → Integrations and press "Create" in the section titled "OAuth Apps". Set a name that helps your users identify your application. Make sure to also set the necessary scopes that your application needs and the redirect URIs you want to enable. Additionally you can add a URL to a logo and a homepage to help users identify your application.
After submitting the form, you'll be presented with the OAuth client id and client secret. Make sure to save the secret somewhere safe, as you'll not be able to see it again. You'll need to use the client id and client secret when interacting with the PolyScale OAuth server as required by the OAuth2.0 protocol.
Make sure to save the OAuth client secret somewhere safe, as you'll not be able to see it again.
To create an OAuth application at the workspace level open the workspace and go to Settings → Workspace → Integrations.
PolyScale OAuth integrations currently only supports the OAuth2.0 Authorization Code Grant type.
The PolyScale authorisation server is available at https://oauth.polyscale.ai.
Authorisation Path -
Token Path -
Authorizing OAuth Applications
When a third-party application requests consent for accessing your resources on your behalf you'll be prompted to select a workspace to authorize access on. The application will only be able to access resources associated with this workspace.
Make sure to also review the requested access scopes before authorizing the request.
Authorized OAuth applications will be listed under Settings → Account → Integrations. Here you can also revoke consent on a per-application basis or revoke consent for all applications. Revoking consent will invalidate any issued tokens to prevent the applications from accessing your resources.
Interacting with the PolyScale API
The PolyScale api uses bearer token authentication. Provide the OAuth2.0 access token in the Authorization header as