Skip to main content

DBOS Quickstart

Here's how to get a simple "Hello, Database!" application up and running in less than five minutes. First we'll show you how to run it locally, then we'll show you how to deploy it serverlessly to DBOS Cloud!

System Requirements​

DBOS Transact requires:

To install these requirements (assuming you don't already have them installed):

Installing Node.js

Copy and run the following commands in your terminal to install Node.js:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

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

nvm install 20
nvm use 20

Installing Postgres

You can install Postgres locally or launch it in a Docker container.

Follow this official guide to install Postgres on macOS.

Project Initialization​

To initialize a new DBOS application, run the following command:

npx -y @dbos-inc/create@latest -n <app-name>

Application names should be 3 to 30 characters long and contain only lowercase letters and numbers, dashes, and underscores.

This creates a folder for your application, configures its layout, and installs required dependencies. If successful, it should print Application initialized successfully!. By default, it instantiates a "Hello, Database!" application which greets users and tracks the count of greetings per user.

Running Locally​

DBOS applications can run anywhere, but they always need to connect to a Postgres database. You can connect to a Postgres database you installed or launch Postgres in a Docker container.

In your terminal, change to your application directory and run this command to connect your application to your Postgres database:

cd <application-folder>
npx dbos configure

The command will prompt you for your Postgres server hostname and port and for your Postgres username. If you locally installed Postgres with the default settings, you can select the default hostname (localhost), port (5432), and username (postgres).

Then, set the PGPASSWORD environment variable to your Postgres password:

export PGPASSWORD=<your-postgres-password>

Next, let's create some tables in your database by running a schema migration:

npx dbos migrate

If successful, the migration should print Migration successful!.

Finally, build and run the app:

npm run build
npx dbos 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.

Deploying to DBOS Cloud​

Now, let's serverlessly deploy your application to DBOS Cloud. First, you need an account.

If you already have a DBOS Cloud account (for example, you signed up for one on our website), you can log in to it. From your DBOS application directory, run the following command:

npx dbos-cloud login

Provisioning a Cloud Database Instance​

Next, let's provision a Postgres database instance your applications can connect to! You should choose a database instance name, username and password. Both the database instance name and username must be 3 to 16 characters long and contain only lowercase letters, numbers and underscores. The database password must contain at least 8 characters. Run this command and choose your database password when prompted:

npx dbos-cloud db provision <database-instance-name> -U <database-username>

If successful, the command should print Database successfully provisioned!. For more information on cloud database management, check out our guide.

info

The Postgres database instance you just provisioned can host multiple independent databases for different applications. By default, this quickstart application uses the hello database, but this is configurable in dbos-config.yaml

Deploying an Application​

Now, we're ready to deploy your application to DBOS Cloud! First, register your application by running this command, using your database instance name from the last step:

npx dbos-cloud app register -d <database-instance-name>

If successful, the command should print Successfully registered <app-name>!

Finally, deploy your application to run it in the cloud!

npx dbos-cloud app deploy

If successful, the command will print Successfully deployed <app-name>! Access your application at <URL> The URL should look like https://<username>-<app-name>.cloud.dbos.dev/ Your application is now live at that URL! If you ever forget the URL, you can retrieve it by running npx dbos-cloud app status.

To see that your app is working, visit <URL>/greeting/dbos in your browser. For example, if your username is mike and your app name is hello, visit https://mike-hello.cloud.dbos.dev/greeting/dbos. You should see the same message you saw locally: Hello, dbos! You have been greeted 1 times. Each time you refresh the page, the counter should go up by one.

info

You don't have to worry about configuring database server connection parameters like hostname or password to deploy an application to the cloud—DBOS automatically applies the connection information of your cloud database instance.

Congratulations, you've successfully deployed your first application to DBOS Cloud!

Next, to learn how to build your own application, check out our programming quickstart.