PROJECT

9.16 PROJECT

The command in SQLcl for Database CI/CD extension is project. It contains several sub-commands that are used as part of the process to help developers manage database changes and create serialized transactions.

Syntax

project|proj [init|in] | [export|ex] | [config|cfg] | [gen-artifact|ga] |
[deploy|dp] | [release|re] | [verify|v] | [stage|st]

The following table provides a description of each sub-command.

Sub-Command	Description
init\|in	Initializes a new project. This command can be run in a new Git repository or in an existing repository.
config\|cfg	Enables you to view and manage your project configuration properties. This command allows you to look at the current configuration that is used by each of the `project` commands.
export\|ex	Exports database objects into your repository.
stage\|st	Creates Liquibase changelogs or changesets for all source files and custom SQL files. The `stage` command is used along with the `export` command.
release\|re	Moves the current set of work into a release state and starts a new body of work. The `release` command takes the contents of the dist/next folder and renames it to a given version number, then creates a new `next` folder under dist.
gen-artifact\|ga	Generates an artifact representing the current state of your project.
deploy\|dp	Deploys the artifact on a target database.
verify\|v	Provides the means to test various aspects of your project (snapshots, changes, overall project).

9.16.1 init

Initializes a new project.

Syntax

project|proj init|in {OPTIONS}

Options

Option	Description
Required
`-name\|-n <name>`	Specifies a name for the project.
Optional
`-schemas\|-s <schemas>`	Specifies a comma-separated list of schemas to export.
`-directory\|-d <directory>`	Specifies the path of the directory where the project should be created. If no path is specified, the project is created in the current directory.
`-connection-name\|-con <connection-name>`	Specifies the SQLcl connection name. If you do not provide a connection name and are connecting through a named connection, the system automatically adds that connection name to the `connectionName` configuration property. If no named connection is used, the `connectionName` property remains empty.
`-makeroot\|-mr`	Creates a root folder named after the project and stores all files in this directory.
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays in the output additional details about the current process.

Examples

Initialize a project with the following details:
- Project name: apexsb
- Schemas to export: apexsb_data,apexsb
- Directory: /workspace/projects/
- SQLcl connection name: apexsb_conn
```
SQL> project init -name apexsb -schemas apexsb_data,apexsb -d /workspace/projects -con apexsb_conn
```

9.16.2 export

Exports database objects to your repository.

Syntax

project|proj export|ex {OPTIONS}

Options

Option	Description
`-list\|-l`	Lists all objects in alphabetical order. The list of objects to export is output based on the current parameters.
`-objects\|-o <objects>`	Specifies comma-separated list of objects to export. For example, `HR.COUNTRIES`.
`-schemas\|-s <schemas>`	Specifies a comma-separated list of schemas to export. For example, `HR`.
`-threads\|-t <threads>`	Specifies the number of concurrent threads to use with cloned JDBC connections for executing `DBMS_METADATA.getDDL`. The default value is five.
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

Example

Export custom export filters from .dbtools/filters/project.filters.

SQL> project export -debug -list -objects REGIONS,COUNTRIES -schemas
HR,SCOTT -threads 4

9.16.3 config

Enables you to view and manage the project configuration properties.

Syntax

project|proj config|cfg {SUBCOMMAND} {OPTIONS}

Options

Option	Description
Required
`-list\|-li`	Lists your current configuration settings
Optional
`-name\|-n <name`	Specifies the config parameter name that can be used when filtering or editing.
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output .

Examples

List the configuration for the sqlcl.version parameter. Use -verbose to include default value and description.

project config -list -name sqlcl.version -verbose

Sub-Commands

The sub-commands are:

set: To add or update project configuration parameters.
delete: To remove a config parameter from the project configuration.

Add or Update a Configuration Parameter

Use the set command to add a new configuration parameter or update the existing one.

Syntax

project|proj config|cfg set|s {OPTIONS}

Options

Option	Description
Required
`-name\|-n <name>`	Specifies the name for the project.
`-value\|-va <value>`	Specifies the value that should be assigned to the configuration parameter.
Optional
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output .

Example

Set the parameter export.demo.demoComments to true.

SQL> project config set -name export.demo.demoComments -type BOOLEAN -value TRUE -verbose

Remove Configuration Parameter

Use the delete command to remove a configuration parameter from the project configuration.

Syntax

project|proj config|cfg  delete|d {OPTIONS}

Options

Option	Description
`-name\|-n <name>`	Specifies the configuration parameter name that can be used when filtering or editing.
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

9.16.4 gen-artifact

Generates an artifact representing the current state of your project.

Syntax

project|proj gen-artifact|ga {OPTIONS}

Options

Option	Description
`-name\|-n <name>`	Specifies a custom name for the artifact.
`-format\|-fo <format>`	Specifies the desired compression format. Supported values are, `zip` or `tgz`.
`-version\|-ve <version>`	Specifies the artifact version.
`-force\|-f`	Overwrites the artifact if it exists.
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

Example

Generate an artifact named R1-1 in zip format. The artifact is saved in the artifact folder.

SQL> project gen-artifact -name R1 -version 1 -format zip -verbose

9.16.5 deploy

Deploys the artifact on a target database.

Syntax

project|proj deploy|dp {OPTIONS}

Options

Option	Description
Required
`-file\|-fs <file> {FILE}`	Specifies the artifact file ___location path.
Optional
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

Example

Extract the artifact file from the specified path. The command executes @dist/install.sql and initiates the Liquibase installer on the target database.

SQL> project deploy -file /Users/user1/Desktop/project1/artifact/R1-1.zip -verbose

9.16.6 release

Moves the current set of work into a release state and starts a new body of work.

Syntax

project|proj release|re {OPTIONS}

Options

Option	Description
Required
`-version\|-ve <version>`	Specifies the release version to label the release.
Optional
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

Example

Package a unit of work into a release.

SQL> project release -version 1.0

9.16.7 verify

Tests various aspects of your project (snapshots, changes, overall project).

The sub-commands are:

verify-stage: To execute all the verify tests registered for the stage group.
snapshot: To execute all the verify tests registered for the snapshot group.

Verify Tests for the Stage Group

Use the verify-stage command to execute all the verify tests registered for the stage group.

Syntax

 project|proj verify|v verify-stage|st {OPTIONS}

Options

Option	Description
Optional
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

Verify Tests for the Snapshot Group

Use the snapshot command to execute all the verify tests registered for the snapshot group.

Syntax

project|proj verify|v snapshot|ss {OPTIONS}

Options

Option	Description
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

9.16.8 stage

Creates Liquibase changelogs or changesets for all source files and custom SQL files.

It is used along with the export command. It can also be used to add other custom changesets as part of the change. This generates a file to add SQL and SQLcl commands with a Liquibase SQL changeset header. This file will be added to the changelog hierarchy automatically.

Syntax

project|proj stage|st {SUBCOMMAND} {OPTIONS}

Options

Option	Description
`-branch-name\|-bn`	Specifies the branch name for comparison. If not provided, the value from the configuration file `(git.defaultBranch)` is used, with `develop` as the default.
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

Examples

Create a new directory under dist/releases/next specifying the branch name.

SQL> project stage -branch-name branch1

Add a Custom File to Stage

Use the add-custom command to add a custom file to stage.

Syntx

project|proj stage|st add-custom|ac {OPTIONS}

Options

Option	Description
Required
`-file-name\|-fn <file-name>`	Specifies the name for the custom file.
Optional
`-debug\|-de`	Displays the debug information in the output.
`-verbose\|-v`	Displays additional details about the current process, in the output.

Example

Add feature1.sql custom file.

SQL> project stage add-custom -file-name feature1.sql