Welcome to our narrative tutorial

The Sorcerer of Aittador

Trouble is brewing on the planet of Aittador. An evil Star Sorcerer named Brog is plotting destruction, and soon it will be up to a few brave souls to defeat him. Grab your laser gun and follow this narrative tutorial, where you’ll learn how to build a Typescript sample app on CockroachDB Serverless (and enter a raffle for a chance to win CockroachDB Serverless swag!).

How it works:

  1. Follow along with the narrative
  2. In each chapter, complete the tasks
  3. You’ll learn how to build a Typescript sample app on CockroachDB Serverless.

Chapter 1: The Sorcerer

Today is a dark day. The evil Star Sorcerer named Brog, who’s been plaguing the planet of Aittador for years, attacked the capital city and kidnapped your best friend, Sam. The sorcerer retreated to the Obsidian Mountains with the threat he’ll be back to destroy the planet once and for all. You’re the only one brave enough to track him down.

Task #1: Gather your hoverbike and laser gun

  1. If you haven't already, sign up for a CockroachDB Serverless account.
  2. Log in to your CockroachDB Serverless account.
  3. On the Clusters page, click Create Cluster.
  4. On the Create your cluster page, select the Free Plan.
    Note: This cluster will be free.
  5. (Optional) Select a cloud provider (GCP or AWS) in the Additional configuration section.
  6. Click Create your free cluster. Your cluster will be created in approximately 20-30 seconds.

You’re ready to embark on your quest! You bid farewell to your friends and family, hop on your hoverbike, and head towards the Obsidian Mountains.

Chapter 2: Star Magic

After an arduous journey into the Obsidian Mountains, where you used your skills with a laser gun to fight off flesh-eating bats and one very large lizard, you find Brog’s tower. The tower is guarded by two droids who soon fall victim to your wiley bribes. They give you crucial information in exchange for your hoverbike.

Turns out you’ve arrived just in time. Tonight, Brog will use star magic to steal Sam’s soul and gain the power he needs to destroy the planet. The droids, who are giddy with excitement about their new bike, help you distract Brog. You sneak into the tower.

Task #1: Disable the cyber lock on Sam’s prison cell

Once your cluster is created, the Connection info 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. Choose your OS from the dropdown menu
  2. In your terminal, run the first command from the Connection Info dialog to download the CockroachDB client, if you haven’t already done it before.
  3. 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
  4. On the Connection info dialog, copy the connection string provided, which will be used in the next steps (and to connect to your cluster in the future).
  5. Warning: 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.

Phew, that was close! You and Sam manage to flee the cave while Brog is distracted, and you run down the mountain.

Chapter 3: A Journey

Huddling on the barren slopes of the lower Obsidian Mountains, you and Sam recount your adventures. While captive, Sam learned that Shime Stones, radioactive rocks found deep in the Fire Spits, are the only thing that can kill Brog. You must journey to the Fire Spits and find several hundred blue, green, and red stones to defeat the sorcerer.

Before you start your journey, you’ve got to buy a new hoverbike and a vault—a box that can safely store radioactive material.

Task #1: Head to the nearest town to buy a hoverbike and a vault

  1. It’s time to download the CockroachDB binary if you haven’t already
  2. Follow the instructions on the Connection info dialog box to install the binary

Task #2: Journey to the Fire Spits

  1. Start the built-in SQL shell using the connection string you got from the Console earlier.
  2. In the connection string copied from the Console, your username, password and cluster name are pre-populated. Replace the certs_dir placeholder with the path to the certs directory that you created earlier.
  3. In the SQL shell, create the vault database that your application will use:

You’ve made it to the Fire Spits! Ash rains down, fires burn, and lava pits bubble. Suddenly your hoverbike stops working. Its machinery is clogged by ash. You and Sam continue on foot, searching for Shime Stones.

Chapter 4: Shime Stones

There—you see colorful glowing lights between boulders! The smoke is choking you and your boots are melting, but now isn’t the time to stop. You must prepare the vault, and then you and Sam must quickly collect as many blue, green, and red stones as possible.

Task #1: Prepare the vault

  1. Clone the code's GitHub repository
  2. Open the ormconfig.ts file, and edit the ORM configuration parameters:
    • Replace the value for host with the name of the host (e.g., host: 'free-tier.gcp-us-central1.cockroachlabs.cloud' ).
    • Replace the value for port with the port to your cluster.
    • Replace the value for username with the username from the connection string.
    • Replace the value for password with the password for your user.
    • Replace the value for database with the database that you created earlier, suffixed with the name of the cluster (e.g., database: '{cluster_name}.vault ).
    • Edit the fs.readFileSync('certs/cc-ca.crt').toString() call to use the path to the cc-ca.crt file that you downloaded from the Console.

Task 2: Collect the Shime Stones

  1. Open a terminal window, and install the Node.js pg driver:
    npm install pg --save
  2. Navigate to the top directory of the application project (e.g., hello-world-typescript-typeorm), and initialize the project:
    npm i
  3. Start the application:
    npm start
  4. You should see the following output in your terminal:
    Collected 1000 blue Shime Stones.
    Collected 250 green Shime Stones.
    Collected 400 red Shime Stones.

You collected the stones! Relief surges through you, before you realize your hoverbike is broken. How will you and Sam get back to the city? Suddenly, an ear-splitting shriek tears open the sky. A gigantic beast circles overhead, half eagle and half robot. It’s Vaskralla, a legendary monster of Aittador. But instead of eating you, she tells you to hop on her back, because Brog is attacking the capital at this very moment.

Chapter 5: Battling Brog

Your beloved planet stretches out below as you fly over the empty plains, dark Obsidian Mountains, and lush valley that holds the capital. Then you spot smoke and red flames burning the city. It’s Star Sorcerer fire!

Vaskralla swoops between the towers searching for Brog. Buildings collapse and smoke billows. Far below on the streets, people run for their lives screaming. There—a lone figure stands atop City Hall. Hovercraft swarm around the sorcerer, shooting lasers, but the lasers bounce right off him. You must defeat Brog now or never.

You shoot the Shime Stones from the vault. They hit Brog in the chest, vaporizing him. The red fires snuff out. Silence falls over the city, and you realize you did it. You saved Aittador!

You and Sam are awarded Aittador’s highest honors, and the city throws a lavish party to celebrate. You invite the droids, who arrive on your old hoverbike. You invite Vaskralla, who terrifies everyone but turns out to be a great dancer. The party runs all night and into the next day, because for the first time in years, the planet of Aittador is safe.

Task #1: Roll the dice

Enter the raffle for a chance to win CockroachDB Serverless swag!

Task #2: Celebrate with your peers

  1. Join the CockroachDB Community Slack
  2. Introduce yourself in the #introductions channel 👋

Task #3: Choose your next adventure

This is only the beginning of your journey. You’re a recognized hero now, so you can conquer whatever you want!

  1. Try another tutorial
  2. Take a Cockroach University class
  3. Learn from a tech talk