Skip to main content

DBOS SDK Quickstart

Here's how to get a simple DBOS "Hello, Database!" application up and running in less than five minutes!

System Requirements

The DBOS SDK requires Node.js 20 or later. To install (assuming you don't already have Node.js installed), copy and run the following commands in your terminal:

curl -o- | bash

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/" ] && \. "$NVM_DIR/" # This loads nvm

nvm install 20
nvm use 20

This tutorial uses Docker to launch a Postgres database. To install (assuming you don't already have Docker installed):

An easy way to install Docker on MacOS is through Docker Desktop.

After installing Docker, close and reopen your terminal to apply any changes. Then, verify Docker is working by running:

docker run hello-world

Project Initialization

To initialize a new DBOS application, run the following command, choosing a project name with no spaces or special characters:

npx @dbos-inc/dbos-sdk init -n <project-name>

This creates a folder for your project, configures its layout, and installs required dependencies. If successful, it should print Application initialized successfully!.

Getting Started

By default, dbos-sdk init instantiates a "Hello, Database!" application which greets users and tracks the count of greetings per user. First, we'll show you how to build and run it, then we'll show you how to extend it with more powerful features.

Before you can launch your app, you need a database. DBOS works with any Postgres database, but to make things easier, we've provided a nifty script that starts a Docker Postgres container and creates a database:

cd <project-name>
export PGPASSWORD=dbos

If successful, the script should print Database started successfully!.

Then, let's run a database migration to create some tables:

npx dbos-sdk migrate

If successful, the migration should print Migration successful!.

Next, build and run the app:

npm run build
npx dbos-sdk start

To see that it's working, visit this URL in your browser: http://localhost:3000/greeting/dbos. You should get this message: Hello, dbos! You have been greeted 1 times. Each time you refresh the page, the counter should go up by one!

Congratulations! You just launched your first DBOS application. Next, we'll learn how to build a new application ourselves.