Skip to main content

DBOS Compiler

The DBOS Compiler helps you deploy your DBOS applications with Stored Procedures to PostgreSQL (including your DBOS Cloud database).

Installation

To install the latest Cloud CLI version for your application, run the following command in your package root:

npm install --save-dev @dbos-inc/dbos-compiler

Stored Procedure Versioning

Since @StoredProcedure functions must be tied to a specific application version, both DBOS Transact and the DBOS Compiler are version aware. By default, the application version is specified via the DBOS__APPVERSION environment variable, but can also be controlled via command line parameters. When a application version is specified, the DBOS Compiler will automatically prefix generated stored procedures with v and the application version. Likewise, DBOS Transact will automatically invoke prefixed versions of the deployed stored procedures when the application version is specified. For example, if the application version was 1720214256655, all of the stored procedures generated by would be prefixed with v1720214256655_.

info

DBOS Cloud cleans up the database deployed stored procedures for older application versions via a background task. You do not need to cleanup DBOS cloud deployed stored procedure versions yourself.

Commands


npx dbosc deploy

Description: This command deploys the stored procedure functions from a DBOS application to the PostgreSQL database specified in the configuration file. You must deploy your stored procedures to the database before running your DBOS application.

Arguments:

  • tsconfigPath: path to the DBOS application's tsconfig.json file. If this argument is not provided, dbosc will use the tsconfig.json file from the appDirectory (if specified) or the current directory.

Parameters:

  • -d, --appDir <application-directory>: The path to your application root directory.
  • --app-version <string> / --no-app-version: Overrides the DBOS__APPVERSION environment variable. For more details, see Stored Procedure Versioning above.

npx dbosc drop

This command drops the DBOS application's stored procedures from the PostgreSQL database specified in the configuration file.

Arguments:

  • tsconfigPath: path to the DBOS application's tsconfig.json file. If this argument is not provided, dbosc will use the tsconfig.json file from the appDirectory (if specified) or the current directory.

Parameters:

  • -d, --appDir <application-directory>: The path to your application root directory.
  • --app-version <string> / --no-app-version: Overrides the DBOS__APPVERSION environment variable. For more details, see Stored Procedure Versioning above.

npx dbosc compile

This command generates create.sql and drop.sql files containing the SQL commands to deploy or drop the DBOS application stored procedures. This command can be useful to integrate DBOS into an environment where you can't deploy stored procedures to the database automatically with dbosc deploy.

warning

This command will overwrite existing create.sql and drop.sql files in the output directory.

Arguments:

  • tsconfigPath: path to the DBOS application's tsconfig.json file. If this argument is not provided, dbosc will use the tsconfig.json file from the current directory.

Parameters:

  • -o, --out <string>: The path of the directory where the compiler will generate the create.sql and drop.sql files. Defaults to current directory if not specified.
  • --app-version <string> / --no-app-version: Overrides the DBOS__APPVERSION environment variable. For more details, see Stored Procedure Versioning above.