Connection Parameters by API

Overview

To connect to a SkySQL service:

  • The service must be Running

  • The client's IP address must be added to the service's IP Allowlist

  • The client must be configured with certain service details (such as host, port, username, and password) which can be retrieved by API or using the SkySQL Portal

These instructions use the skysqlcli utility to retrieve service information. Alternatively, you can use the SkySQL Portal.

Prerequisites

Set API Key

skysqlcli must be configured to use your API key.

To set the API key for skysqlcli with a key of YOUR_SKYSQL_API_KEY:

$ export SKYSQL_API_KEY='YOUR_SKYSQL_API_KEY'

For additional information, see "Authentication and Authorization".

Obtain Service ID

skysqlcli works using the id of your service.

To look up the id for a service with the name YOUR_SERVICE_NAME:

$ skysqlcli get services \
   --name 'YOUR_SERVICE_NAME' \
  | jq '{ "name": .[0].name, "id": .[0].id }'

{
  "name": "YOUR_SERVICE_NAME",
  "id": "db00000001"
}

Service Status

New services remain in a "Pending" status until the launch process is completed.

To connect to a SkySQL service, status must be "Running".

To check the service status for service ID db00000001:

$ skysqlcli get status 'db00000001' \
   | jq .

{
  "status": "Running"
}

Host and Port

To retrieve service details for service ID db00000001:

$ skysqlcli get service 'db00000001' \
   | jq '{ "provider": .provider, "host": .fqdn, "read_only_port": .read_only_port, "read_write_port": .read_write_port, "ssl_tls": .ssl_tls }'

{
  "provider": "Amazon AWS",
  "host": "YOUR_SERVICE_NAME.mdb0000001.db.skysql.net",
  "read_only_port": "",
  "read_write_port": "5001",
  "ssl_tls": "Enabled"
}

Read-Only Port

read_only_port is empty for services which only have a read_write_port

Certificate Authority Chain

If ssl_tls is Enabled, download the SkySQL CA chain for the service's cloud provider:

User Credentials

For initial connections to a SkySQL service, a database username and a default password are assigned when a new SkySQL service is launched.

To retrieve the default username and password for service ID db00000001:

$ skysqlcli get credentials 'db00000001' \
   | jq .

{
  "username": "DB00000001",
  "password": "SKYSQL_DEFAULT_PASSWORD"
}

For additional information on changing the default password, and creating your own database user accounts, see "Database User Accounts".

IP Allowlist

By default, SkySQL services block inbound connections. To enable connection from your client, the client's public IP address must be added to the IP Allowlist.

To add an IP address (CLIENT_IP_ADDRESS) to the allowlist for service ID db00000001:

$ skysqlcli create allowed-address 'db00000001' 'CLIENT_IP_ADDRESS/SUBNET_MASK'

Replace 'CLIENT_IP_ADDRESS' with the IP address or subnet that the client connects from and replace SUBNET_MASK with the corresponding subnet mask. If 'CLIENT_IP_ADDRESS' is a single IPv4 address, then SUBNET_MASK should be 32.

The status of the operation can be checked using the using the get allowlist-status command:

$ skysqlcli get allowlist-status 'db00000001' \
  | jq .

When the operation is complete, the output shows:

{
  "status": "Enforcing"
}

For additional information, see "IP Allowlist for Services".