Skip to main content

Getting Connected

Overview​

Hostname and Port​

To connect any database client application to PolyScale, firstly, update the database hostname to use the domain psedge.global. Select the appropriate port based on the database type:

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

Cache Identifier​

Finally, any database client must specify a PolyScale cache identifier (found in the user interface under the cache Settings tab or via the API). This tells PolyScale which cache to use and therefore which upstream database to connect to. The method of how this is specified as part of the database connection credentials is database specific. See below for details on each database.

PolyScale Cache IdentifierPolyScale Cache Identifier

MySQL, MariaDB and SQL Server​

To connect to a MySQL, MariaDB or SQL Server database via PolyScale, a database username must be provided that contains the polyscale cache identifier. The cache id can be found under the Settings tab of each cache within the user interface.

Simply prepend the cache id to the origin database username, separated by a hyphen.

Example​

If the username provided by PolyScale is abc and the origin database username is foobar, the database username to connect via PolyScale would be abc-foobar.

Testing MySQL Connectivity​

CLI Example​

mysql -h psedge.global \
-u [cacheid]-[dbuser] \
--ssl-mode=REQUIRED -p

PostgreSQL​

For PostgreSQL databases, PolyScale supports two options for passing the cache identifier as part of the connection string. If you have access to the Postgres connection URI (typically this is an environment variable for web applications, microservices etc.), an additional application_name parameter is appended to the connection string (see Option 1 below).

Sometimes it's not possible to modify the connection URI, such as in desktop tools where a UI dictates the available parameters. In these situations a specific database username can be created that is utilized by PolyScale (see Option 2 below).

Option 1 - Append application_name​

Append an application_name parameter to the connection string containing the PolyScale cache identifier. The cache id can be found under the Settings tab of each cache within the user interface.

Example​

Append the application_name key with the PolyScale cache id value to the connection string:

postgresql:///mydb?host=localhost&port=5433&application_name=[polyscale_cache_id]

Read more about PostgreSQL connection strings from the PostgreSQL documentation here and more about the application_name parameter here.

tip

If it is required to use the application_name property, simply prepend the PolyScale cache id to the desired application name separated by a hyphen and it will be passed to the PostgreSQL server as normal.

For example: application_name=POLYSCALE_CACHE_ID-my_app_name

Option 2 - Database Username​

PolyScale can also use a cache identifier specified as the database username. In this case, a database user must be created with a username identical to the cache id provided by PolyScale.

For example, if the cache id is 8255a89a-4365-4e64-8e78-38db272d8fdd:

CREATE USER "8255a89a-4365-4e64-8e78-38db272d8fdd" WITH ENCRYPTED PASSWORD 'foo';

GRANT ALL PRIVILEGES ON DATABASE employees TO "8255a89a-4365-4e64-8e78-38db272d8fdd";
The database name can optionally be appended by a hyphen and any other

string. This can be useful for identifying PolyScale database users.

For example, if the cache ID was 8255a89a-4365-4e64-8e78-38db272d8fdd, the database user could be named 8255a89a-4365-4e64-8e78-38db272d8fdd-fooBar :::

When creating a database user and granting privileges, be sure to only grant the minimum needed for the purpose.

:::

Testing PostgreSQL Connectivity​

CLI Example​

psql "host=psedge.global \
sslmode=require \
port=5432 \
user='dbuser' \
dbname='dbname' \
application_name='POLYSCALE_CACHE_ID'"
Desktop Clients

If you would like to test connectivity using a a desktop client application, we recommend JetBrains DataGrip as it supports setting the application_name property. See this tutorial for further information.

MongoDB​

To connect to MongoDB via PolyScale, an appName parameter is appended to the connection string and the cache identifier is passed as the value. Two additional parameters must also be passed: directConnection=true&tls=true

MongoDB Connection StringMongoDB Connection String

PolyScale supports all versions (release 5.0 or later) of MongoDB including MongoDB Atlas.

When connecting to a MongoDB cluster, PolyScale handles navigating which machine on the cluster to connect to. It is important to include the directConnection=true parameter. The MongoDB protocol relies on the client side to be aware of, and continuously observe changes in the cluster configuration. By using this parameter, you ensure that your connection goes directly to PolyScale and then PolyScale manages which upstream server to connect to for writes and non-cached reads.

GraphQL​

Queries should be made as they would directly to the underlying GraphQL server, but replacing the host with psedge.global Eg: https://yourgraphqlserver.com/graphql → https://psedge.global/graphql The endpoint is psedge.global. Include a header of: x-polyscale-cacheid with a value of the cache id.