CockroachDB Connection Basics

When creating a new CockroachDB instance on the ObjectRocket service, there are a few things you need to know before you connect to your instance.

CockroachDB Connection Checklist

In order to connect to your instance, you will need a few things:

  1. Your Instance Connection String: Each instance is set up with one database connection string. You can find this in the CONNECT tab of the instance details in Mission Control . See the CockroachDB Connection Strings section below for more information.
  2. Open Firewall IPs: By default all traffic to your ObjectRocket instance is blocked. You must configure your instance to allow traffic from the IPs/CIDRs you will be connecting from. See the Firewall Configuration section below for more information.
  3. A Database: Our CockroachDB instances do not come with a default database, so you must create databases via our UI/API. See the Database Configuration section below for more information.
  4. A User: By default an ObjectRocket instance is not configured with any customer-usable users, so you must create them via our UI/API. See the CockroachDB Users section below for more information.

How to Connect

Though each client has a different format, the easiest way to test your connection is to use a command line client. CockroachDB is wire compatible with PostgreSQL, so you can connect via the psql command line client. If you’ve completed the steps above, you can test your connection with the following command:

psql 'postgres://<yourusername>:<yourpassword>@ingress.<yourclustername>.launchpad.objectrocket.cloud:<yourport#>/<database>?sslmode=require'

CockroachDB Connection Strings

When your ObjectRocket instance is created, it is given a unique hostname and port combination.

Once your instance has finished building, connection strings can be found in the CONNECT tab of the instance details screen, in Mission Control .

_images/cockroachdb_connectstring.png

In general, your CockroachDB connection string will look something like:

postgres://<USERNAME>:<PASSWORD>@ingress.<clustername>.launchpad.objectrocket.cloud:<yourport#>/<DBNAME>?sslmode=require

CockroachDB Connection Strings

For all CockroachDB instances, we provide a connection string for the instance datastore and a separate connection string for the CockroachDB admin dashboard:

  • CockroachDB: This is the main connection string to use for database connections. It load-balances across all nodes in the region.
  • CockroachDB Admin: This is URL for the admin dashboard for viewing instance stats and management information.

CockroachDB Users

Creating your first CockroachDB user

By default, your CockroachDB instance on ObjectRocket does not have any users created. You must create users via the ObjectRocket API or GUI.

  1. From Mission Control, click Users from the Instances page, or go to the USERS tab of the instance details page.
  2. Enter a username and password for your admin user.
  3. You can verify your user has been created in the USERS tab of the instance details page.

The admin dashboard uses the same users as the database itself, so the users created here can be used in both places.

_images/cockroachdb_user.png

Certificate Authentication

In addition to password authentication, for additional security, we also support client certificates. With client certificates you use a digital certificate that is signed by our service to connect, rather than a simple password. Digital certificates are unique and much more difficult to compromise than a standard password.

The detailed process for enabling certificate authentication is documented in our API documentation , but a summary of the process is below:

  1. Create a new user as described above. You can leave the password blank on this user if you wish.
  2. Using an existing RSA key pair (or by generating a new one) generate a Certificate Signing Request (CSR) file
  3. Submit the CSR file via our API/UI to generate a client certificate.
  4. Use your private key and and the generated client certificate to authenticate with CockroachDB

When connecting via certificate auth, your connection string will look something like:

psql 'postgres://<username>@ingress.<clustername>.launchpad.objectrocket.cloud:<yourport#>/<dbname>?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.<username>.crt&sslkey=path/to/client.<username>.key'

CockroachDB Databases

You must first create any databases that you plan to use on your CockroachDB instance via our UI or API. You can create multiple databases per instance and manage them via our UI or API.

Creating Databases

To create a new database, follow the steps below:

  1. Find your instance in the Mission Control Instances page.
  2. Select Databases from the instance in the list, or click on the button in the DATABASES tab of the instance details screen.
  3. In the popout, enter the database name and click the confirm button.
  4. At any time, you can see the databases for your instance in the DATABASES tab of the instance details screen.

Deleting Databases

To remove a database from your CockroachDB instance:

  1. Find your instance in Mission Control Instances page.
  2. Navigate to the Databases tab of the instance details screen for the instance you would like to modify.
  3. Find the database you would like to remove from the list.
  4. Click on the red trash can next to the instance

Warning

Deleting a database deletes all of the data in the database

Firewall Configuration

When you create a new CockroachDB instance, all access to the instance is blocked, except for the IP you accessed the UI from when creating the instance.

At any time you can add and remove additional IP addresses or CIDRs to the Firewall Configuration.

Adding Firewall IPs

To open up additional IPs and CIDRs to access your instance, follow the steps below:

  1. Find your instance in Mission Control Instances page.
  2. Select Firewall from the instance in the list, or click on the button in the FIREWALL tab of the instance details screen.
  3. In the popout, either directly add an IP (e.g. 1.2.3.4) or CIDR (e.g. 1.2.3.4/24) in the CIDR field, or use one of the ALLOW ANY IP or USE MY IP shortcuts.
  4. Enter a name for this IP so you can identify it later
  5. Select a role for this IP. We allow you to set different IPs for each connection string, so the role determines which connection string the firewall will be opened for.
  6. At any time, you can see the configure Firewall IPs for your instance in the FIREWALL tab of the instance details screen.
_images/cockroachdb_acl.png

Warning

Though we give you the option to allow any IP (0.0.0.0/0) to your instance, we don’t recommend using it long-term. Though your instance is still protected by a username/password, it still poses a risk to the security of your instance since anyone can try to connect.

Removing Firewall IPs

To remove access for existing IPs and CIDRs from your instance, follow the steps below:

  1. Find your instance in Mission Control Instances page.
  2. Navigate to the FIREWALL tab of the instance details screen for the instance you would like to modify.
  3. Find the IP you would like to remove from the list.
  4. Click on the red trash can next to the instance