Build a Hello World App with CockroachDB and SQLAlchemy

This tutorial shows you how build a simple Hello World Python application with CockroachDB and the SQLAlchemy ORM.

Step 1. Install SQLAlchemy

To install SQLAlchemy, as well as a CockroachDB Python package that accounts for some differences between CockroachDB and PostgreSQL, run the following command:

$ pip install sqlalchemy sqlalchemy-cockroachdb psycopg2

You can substitute psycopg2 for other alternatives that include the psycopg python package.

For other ways to install SQLAlchemy, see the official documentation.

Step 2. Start CockroachDB

Choose whether to run a temporary local cluster or a free CockroachDB cluster on CockroachDB Serverless (beta). The instructions below will adjust accordingly.

Create a free cluster

  1. If you haven't already, sign up for a CockroachDB Cloud account.
  2. Log in to your CockroachDB Cloud account.
  3. On the Clusters page, click Create Cluster.
  4. On the Create your cluster page, select CockroachDB Serverless.


    This cluster will be free forever.

  5. Click Create your free cluster.

Your cluster will be created in approximately 20-30 seconds.

Set up your cluster connection

Once your cluster is created, the Connect to cluster-name dialog displays. Use the information provided in the dialog to set up your cluster connection for the SQL user that was created by default:

  1. In your terminal, run the second command from the dialog to create a new certs directory on your local machine and download the CA certificate to that directory:


    curl --create-dirs -o ~/.postgresql/root.crt -O<cluster-id>/cert

    Your cert file will be downloaded to ~/.postgres/root.crt.

    curl --create-dirs -o ~/.postgresql/root.crt -O<cluster-id>/cert

    Your cert file will be downloaded to ~/.postgres/root.crt.

    mkdir -p $env:appdata\.postgresql\; Invoke-WebRequest -Uri<cluster-id>/cert -OutFile $env:appdata\.postgresql\root.crt

    Your cert file will be downloaded to %APPDATA%/.postgres/root.crt.

  2. Copy the connection string provided, which will be used in the next steps (and to connect to your cluster in the future).


    This connection string contains your password, which will be provided only once. If you forget your password, you can reset it by going to the SQL Users page.


    cockroach sql --url 'postgresql://<username>:<password>@<serverless-host>:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<routing-id>'

    cockroach sql --url 'postgresql://<username>:<password>@<serverless-host>:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/.postgresql/root.crt&options=--cluster=<routing-id>'
    cockroach sql --url "postgresql://<username>:<password>@<serverless-host>:26257/defaultdb?sslmode=verify-full&sslrootcert=$env:appdata/.postgresql/root.crt&options=--cluster=<routing-id>"


    • <username> is the SQL user. By default, this is your CockroachDB Cloud account username.
    • <password> is the password for the SQL user. The password will be shown only once in the Connection info dialog after creating the cluster.
    • <serverless-host> is the hostname of the CockroachDB Serverless (beta) cluster.
    • <routing-id> identifies your tenant cluster on a multi-tenant host. For example, funny-skunk-123.
    • <cluster-id> is a unique string used to identify your cluster when downloading the CA certificate. For example, 12a3bcde-4fa5-6789-1234-56bc7890d123.

    You can find these settings in the Connection parameters tab of the Connection info dialog.

  1. If you haven't already, download the CockroachDB binary.
  2. Run the cockroach demo command:

    $ cockroach demo \

    This starts a temporary, in-memory cluster and opens an interactive SQL shell to the cluster. Any changes to the database will not persist after the cluster is stopped.


    If cockroach demo fails due to SSL authentication, make sure you have cleared any previously downloaded CA certificates from the directory ~/.postgresql.

  3. Take note of the (sql) connection string in the SQL shell welcome text:

    # Connection parameters:
    #   (webui)
    #   (sql)      postgres://demo:demo76950@
    #   (sql/unix) postgres://demo:demo76950@?host=%2Fvar%2Ffolders%2Fc8%2Fb_q93vjj0ybfz0fz0z8vy9zc0000gp%2FT%2Fdemo070856957&port=26257

Step 3. Get the code

Clone the code's GitHub repo:

$ git clone

The file contains all of the code for the sample Hello World app:

from sqlalchemy import create_engine
import urllib
import os

def connect(db_uri):
    engine = create_engine(db_uri)
    print('Hey! You successfully connected to your CockroachDB cluster.')

if __name__ == '__main__':
    conn_string = input('Enter your node\'s connection string:\n')
    # For cockroach demo:
    # cockroachdb://demo:<demo_password>@
    # For CockroachCloud:
    # cockroachdb://<username>:<password>@<globalhost>:26257/<cluster_name>.defaultdb?sslmode=verify-full&sslrootcert=<certs_dir>/<ca.crt>

        db_uri = os.path.expandvars(conn_string)
        db_uri = urllib.parse.unquote(db_uri)
        psycopg_uri = db_uri.replace(
            'postgresql://', 'cockroachdb://').replace(
                'postgres://', 'cockroachdb://')
    except Exception as e:
        print('Failed to connect to database.')

The main method of this program does the following:

  1. Attempts to connect to a running cluster, given a connection string.
  2. Prints a message to the terminal about the connection status.

Step 4. Run the code

To run the app:

$ python3

The terminal will prompt you for a connection string.

Copy and paste the connection string provided in the (sql) connection string from SQL shell welcome text, and replace the postgres prefix with cockroachdb.

For example:

Enter your node's connection string:

Copy and paste the connection string from the CockroachDB Cloud console, and replace the postgres prefix with cockroachdb. Make sure that the right username, password, and certificate are specified as well.

For example:

Enter your node's connection string:

Where you update the connection string as follows:

  • Replace <username> and <password> with a SQL username and password.
  • Replace <globalhost> with the name of the CockroachDB Serverless host (e.g.,
  • Replace <cluster-name> with the name of your cluster.
  • Replace <certs_directory> with the path to the cc-ca.crt file that you downloaded from the CockroachDB Cloud Console.

You must use the cockroachdb:// prefix in the URL passed to sqlalchemy.create_engine to make sure the CockroachDB dialect is used. Using the postgres:// URL prefix to connect to your CockroachDB cluster will not work.

After entering the connection string, the program will execute.

The output should look like this:

Hey! You successfully connected to your CockroachDB cluster.

See also

You might also be interested in the following pages:

YesYes NoNo