DbTool Database Commands

The database commands create, register, upgrade, and maintain the Cygna Auditor SQL Server databases.

For how to run DbTool, the common options, and the permissions it requires, see DbTool Command-Line Utility.

database list

Lists every database Cygna Auditor is configured to use, with the ID that the database upgrade and database maintain commands require.

Syntax

DbTool database list [options]

This command has no options other than the Common Options.

database create

Creates a new Cygna Auditor database and applies the full schema. You can specify an existing database only if it contains no tables.

Syntax

DbTool database create --server <SERVER> --database <DATABASE> [options]

Options

Option Description
-s, --server <SERVER> Required. Name of the SQL Server instance, for example SQL01 or SQL01\AUDITOR.
-d, --database <DATABASE> Required. Name of the database to create on --server.
-u, --user <ACCOUNT> SQL Server login to connect with. Omit this option to connect as the account running DbTool, using Windows authentication.
-p, --password <PASSWORD> Password for --user. Enter ? to be prompted for the password instead of typing it on the command line.
-c, --custom <ATTRIBUTES> Additional connection string attributes to append, for example "Encrypt=True; Connect Timeout=60".

Example

DbTool database create --server SQL01 --database CygnaAuditor

database add

Registers an existing Cygna Auditor database as an additional read-only event source, so that its events can be searched and reported on alongside the core database. DbTool validates the connection before it registers the database.

Requirements: You must be a Cygna Auditor Global Administrator.

Syntax

DbTool database add --server <SERVER> --database <DATABASE> --name <NAME> --type <TYPE> [options]

Options

Option Description
-s, --server <SERVER> Required. Name of the SQL Server instance, for example SQL01 or SQL01\AUDITOR.
-d, --database <DATABASE> Required. Name of the database on --server.
-n, --name <NAME> Required. Display name for this event source in the Cygna Auditor web console.
-t, --type <TYPE> Required. Type of database being registered, for example CygnaAuditor or CygnaAuditorArchive. If you enter a type that cannot be registered, DbTool lists the accepted values.
-u, --user <ACCOUNT> SQL Server login to connect with. Omit this option to connect as the account running DbTool, using Windows authentication.
-p, --password <PASSWORD> Password for --user. Enter ? to be prompted for the password instead of typing it on the command line.
-c, --custom <ATTRIBUTES> Additional connection string attributes to append, for example "Encrypt=True; Connect Timeout=60".

Example

DbTool database add --server SQL01 --database CygnaArchive2024 --name "Archive 2024" --type CygnaAuditorArchive

database remove

Unregisters a database so that Cygna Auditor stops reading from it. The SQL Server database itself is not changed.

You cannot remove a database that is the target of a purge or archive rule.

Requirements: You must be a Cygna Auditor Global Administrator.

Syntax

DbTool database remove --name <NAME>

This command has no options other than the Common Options.

database rename

Renames a database on SQL Server.

This command does not update the Cygna Auditor configuration. After you rename a database, point Cygna Auditor at the new name with database set-core (for the core database) or database add (for an additional event source).

Syntax

DbTool database rename --server <SERVER> --database <DATABASE> --name <NEW_NAME> [options]

Options

Option Description
-s, --server <SERVER> Required. Name of the SQL Server instance, for example SQL01 or SQL01\AUDITOR.
-d, --database <DATABASE> Required. Current name of the database on --server.
-n, --name <NEW_NAME> Required. New name for the database. A database with this name must not already exist on --server.
-u, --user <ACCOUNT> SQL Server login to connect with. Omit this option to connect as the account running DbTool, using Windows authentication.
-p, --password <PASSWORD> Password for --user. Enter ? to be prompted for the password instead of typing it on the command line.

Example

DbTool database rename --server SQL01 --database CygnaAuditor --name CygnaAuditorOld

database set-core

Points Cygna Auditor at a different core database by updating the service connection point (serviceConnectionPoint) in Active Directory and the local configuration file.

Requirements: The account that writes to Active Directory needs write access to the service connection point under this server's computer object; you need local administrator rights on this server.

Syntax

DbTool database set-core --server <SERVER> --database <DATABASE> [options]

Options

Option Description
-s, --server <SERVER> Required. Name of the SQL Server instance, for example SQL01 or SQL01\AUDITOR.
-d, --database <DATABASE> Required. Name of the database that becomes the new Cygna Auditor core database.
-u, --user <ACCOUNT> SQL Server login to connect with. Omit this option to connect as the account running DbTool, using Windows authentication.
-p, --password <PASSWORD> Password for --user. Enter ? to be prompted for the password instead of typing it on the command line.
-c, --custom <ATTRIBUTES> Additional connection string attributes to append, for example "Encrypt=True; Connect Timeout=60".
-t, --types <TYPES> Comma-separated list of the connection strings to update: Platform, AD, FS, O365. Default: all four.
-f, --forest <FOREST> Active Directory forest that contains this server's computer object. Default: the forest this computer belongs to.
-a, --account <ACCOUNT> Account used to write the service connection point in Active Directory. Default: the account running DbTool.
-w, --account-password <PASSWORD> Password for --account. Enter ? to be prompted for the password instead of typing it on the command line.

Example

DbTool database set-core --server SQL01 --database CygnaAuditor

database test

Opens a connection to the configured core database and reports the server, database, authentication type, and schema version it finds. Run this command first when Cygna Auditor cannot reach SQL Server.

Syntax

DbTool database test

This command has no options other than the Common Options.

database upgrade

Applies any outstanding schema scripts to an existing Cygna Auditor database or archive database. Get the database ID from database list.

Requirements: You must be a Cygna Auditor Global Administrator.

Syntax

DbTool database upgrade --database <ID> [options]

Options

Option Description
-d, --database <ID> Required. ID of the registered database to upgrade, as shown by database list.
-i, --indexes Also create the new indexes introduced by this release. Creating indexes can take a long time on a large database, so it is not done by default.
--reapply Run every schema script, including scripts that have already been applied. Use this option to repair a database whose stored procedures or other objects have been changed outside Cygna Auditor.

Example

DbTool database upgrade --database 1a5f0c48-0b1e-4c7a-9f2d-6b3c8e5a4d10 --indexes

database maintain

Rebuilds fragmented indexes and reclaims free space in one database. Get the database ID from database list.

Syntax

DbTool database maintain --database <ID> [options]

Options

Option Description
-d, --database <ID> Required. ID of the registered database to maintain, as shown by database list.
-f, --fragmentation <PERCENT> Rebuild indexes that are fragmented by more than this percentage. Default: 25.
-s, --space <PERCENT> Shrink database files that contain more than this percentage of free space. Default: 3.

Example

DbTool database maintain --database 1a5f0c48-0b1e-4c7a-9f2d-6b3c8e5a4d10 --fragmentation 30

database purge-cleanup

Runs the purge and archive cleanup scripts, which find and delete orphaned records left behind by earlier purges. Use --export to review the scripts without running them.

Requirements: You must be a Cygna Auditor Global Administrator.

Syntax

DbTool database purge-cleanup [options]

Options

Option Description
-b, --blocksize <ROWS> Number of rows each pass can delete. Smaller blocks hold locks for less time on a busy server. Default: 500.
-m, --minutes <MINUTES> Maximum time each cleanup script can run. A script stops earlier when it runs out of matching rows. Default: 10.
-p, --parallel <COUNT> Number of cleanup scripts to run at the same time. Increase this only on a server with spare SQL Server capacity. Default: 2.
-e, --export Write the generated cleanup scripts out for review without running them.

Example

DbTool database purge-cleanup --blocksize 1000 --minutes 30