Connect to a database

#The hostname

Every database gets a hostname of its own, in its hostname field:

db-7k2q9x4m1a.af-abj-2.db.pantechdynamics.com

It points at the database's private address (private_ip), and keeps pointing at it for the database's life, so put the hostname, not the address, in your connection strings. It is ordinary public DNS with a 60-second TTL: it resolves from anywhere, but the address it gives is reachable only from your own network.

The port is the engine's usual one, also in the database's port field: 5432 for PostgreSQL, 3306 for MySQL and MariaDB.

#Where it can be reached from

A database never has a public address, so a client has to be on the same private network, and inside one of its access rules.

#In a VPC (af-abj-2)

A database in af-abj-2 lives in one of your VPC's subnets, like a VM in a VPC. Every machine in that VPC can reach it, as long as its address is in an access rule. The default rule is the whole VPC range, so out of the box every machine in the VPC can connect.

The database's rules are also applied to its subnet's network ACL, as rules of its own, numbered after yours, so a deny rule of yours still wins. A network ACL applies to the whole subnet, so a rule that admits a range to the database's port admits it to that port on every machine in the same subnet. Put databases in a subnet of their own if that matters to you.

To reach a database from outside the VPC, such as from your laptop, go through a machine in the VPC: an SSH tunnel, or a VPN you run there.

$ ssh -L 5432:db-7k2q9x4m1a.af-abj-2.db.pantechdynamics.com:5432 ubuntu@<a machine in the VPC>$ psql "host=localhost port=5432 user=dbadmin dbname=defaultdb"

#Standard zone (af-abj-1)

A database in af-abj-1 sits on a private network for databases (10.250.0.0/20), never on the public network your standard VPSes use. A standard VPS reaches it through a second, private network interface on that network, which you add with POST /instances/{instance_id}/private-network.

In short:

1. Make sure the VPS's security group admits nothing from 10.250.0.0/20. The default group's ICMP from anywhere rule, and any rule open to 0.0.0.0/0, has to be narrowed first.
2. Add the interface, and read the VPS's private_network_ip once it is attached.
3. Bring the interface up in the VPS with DHCP, without taking its routes or DNS.
4. Add <private_network_ip>/32 to the database's access rules.

Every step, with the security group rules to use and the netplan file, is in connect a standard VPS to a database.

To reach the database from your laptop, tunnel through such a VPS, as in a VPC:

$ ssh -L 5432:db-3h8w1c6r0b.af-abj-1.db.pantechdynamics.com:5432 ubuntu@<the VPS's public address>

#Connect

Use the admin login (admin_username, dbadmin by default) and its password.

$ psql "host=db-7k2q9x4m1a.af-abj-2.db.pantechdynamics.com port=5432 user=dbadmin dbname=defaultdb"

postgresql://dbadmin:<password>@db-7k2q9x4m1a.af-abj-2.db.pantechdynamics.com:5432/defaultdb

$ mysql -h db-7k2q9x4m1a.af-abj-2.db.pantechdynamics.com -P 3306 -u dbadmin -p

mysql://dbadmin:<password>@db-7k2q9x4m1a.af-abj-2.db.pantechdynamics.com:3306/

Passwords never contain spaces, quotes or backslashes, so they are safe in a shell and in a connection string. A generated one is letters and digits only.

#If it does not connect

• It times out. The client's address is not in an access rule, or the client is not on the database's network. In af-abj-1, check the VPS's private interface is up (ip -br addr) and its private_network_ip is in a rule. Check the database's effective_access_rules (its own rules plus what its security groups add) and ignored_security_group_rules, and in a VPC, your own network ACL rules.
• The hostname does not resolve. hostname is null until the database is first running, or a resolver is refusing private answers (see above).
• Authentication fails. Check admin_username on the database, then reset the password.
• It stopped working after a rule change. Removing a rule also ends the connections already open from that range.

The codes the API can return, and what to do about each, are on the errors page.