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_
.
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 theDBOS__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 theDBOS__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
.
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 thecreate.sql
anddrop.sql
files. Defaults to current directory if not specified.--app-version <string>
/--no-app-version
: Overrides theDBOS__APPVERSION
environment variable. For more details, see Stored Procedure Versioning above.