Integration support

AutosyncDB can be used to provide updates in a variety of cases. You can build a database update package and include it in an application version update that will be sent to the client for in-place deployment. It can also be used to deploy database schema changes on a SaaS server just right from a project folder to keep one version-source database in sync with all client databases on the server, or add it to your DevOps ecosystem and be able for example to set up a deployment of updates at night (dev to test, test to production). All such operations are performed as separate tasks and are available both in the application and through a command line.

Command Line Interface

Command line to deploy database schema changes

AutosyncDB can be run in a regular mode as an MDI application, in a dialog mode as Package Wizard, or in the background with or without user interaction. The required mode is determined based on the command line verb parameter and the type of file passed to it.

Command line interface covers all available task types. Format:

%ProgramFiles%\DreamTeam\AutosyncDB\AutosyncDB.exe [parameter1 [value1]] [parameter2 [value2]] ...

Parameters can be with or without values, depending on the specific parameter. Parameter values must be escaped as required by Windows. Put values with white spaces in "double quotes". Escape double quotes in values with a backslash in front of them (\").

Regular mode

CategoryParameterContentDescription
Verb Path to project file, sql file list, database structure file, directorySame as "/open", but without a verb word.

In this case, the first parameter must be a file path
/openCommand shell Open command
/editPath to package fileCommand shell Edit command. Unpack a project from the package file and open a task for it

Wizard and background modes

The Package Wizard mode is available only for database update packages and is the default open mode for them. It works internally as the background "/sync" mode, but with a user-friendly dialog interface and the ability to change some basic settings.

CategoryParameterContentDescription
Verb Path to package fileSame as "/open", but without a verb word.

In this case, the first parameter must be a file path
/openCommand shell Open command. Execute a task for the project in the package file in Package Wizard
/syncPath to project or package fileExecute a task for the project in the background
/texportPath to project fileExport the target database structure to a file in the background
/sexportPath to project fileExport the source databae structure to a file in the background
/buildPath to project fileBuild a package from the project in the background
Interactive Mode [1] By default, the application can only interact with the user to show error messages. An additional parameter is not required in this case
/quietDisallow user interaction
/interactiveAllow user interaction
Environment /taskTask nameCustom task name.

The name of a task and the name of its output directory are the same. The path to the project is known. Use this parameter to set the task output directory and be able to determine the full path to it, and therefore to the execution results (log, scripts, reports)
/notifySystem process id or nameProcess to notify.

This is usually a parent process that started the task and must be notified of its progress and results.
/customidUnique stringCustom id of the task and its process.

Can be used by the parent process to determine which of the launched tasks is sending it a notification.
/owtaskOverwrite (delete) the output directory of the task with the name specified in the "/task" parameter, if it already exists.

This parameter will be useful if you run the task several times in a row or constantly and want to overwrite the previous results. Otherwise, if the directory exists, the task will fail.
/tempDirectory pathA directory for unpacking a project from the package file
/pbuildPath to package fileCustom path to build a package file
Data Source Defaults /dsSQL Server name or addressThe default value for "/tds" and "/sds" if they are not specified
/useridUser IdThe default value for "/tuserid" and "/suserid" if they are not specified
/pwdPasswordThe default value for "/tpwd" and "/spwd" if they are not specified.

If "User Id" is specified without this parameter, the application will try to obtain the password from the internal storage associated with the current Windows account of the task process. To make this possible, in the application under this user and with the same credentials in Connection Form, remember the password and connect successfully at least once. This way you can avoid passing the password as clear text.
/ctimeoutSecondsConnection timeout to SQL Server
/dtimeoutSecondsSQL query (batch) timeout
Target Database /tselectSelect a target database before starting.

This parameter temporarily suppresses restrictions on user interaction modes and shows Connection Form
/tdefault [1]Allow the use of target database specified in the project file.

This parameter serves as a precaution to avoid unintentionally executing a task on an incorrectly selected database
/tdsSQL Server name or addressSQL server of the target database
/tuseridUser IdUser Id to connect to the server.

If this parameter and "/userid" are not specified, than the current Windows account credentials of the task process will be used for authentication (Integrated Security=true)
/tpwdPasswordPassword to connect to the server.

Everything described for "/pwd" applies to this parameter as well
/tcatalogInitial CatalogTarget database name
/tcsConnection stringConnection string of the target database.

The "Initial Catalog" must be set to correctly identify the target database
/tpathPath to database structure or package fileTarget database file path
Source Database /sselectSelect a source database before starting.

This parameter temporarily suppresses restrictions on user interaction modes and shows Connection Form
/sdsSQL Server name or addressSQL server of the source database
/suseridUser IdUser Id to connect to the server

If this parameter and "/userid" are not specified, than the current Windows account credentials of the task process will be used for authentication (Integrated Security=true)
/spwdPasswordPassword to connect to the server.

Everything described for "/pwd" applies to this parameter as well
/scatalogInitial CatalogSource database name
/scsConnection stringConnection string of the source database.

The "Initial Catalog" must be set to correctly identify the source database
/spathPath to database structure or package fileSource database file path

[1] - Not allowed in Package Wizard, only for the background mode.

Examples

Run the task for a project in the background

"/sync" simply runs the task as it saved in a project file. When preparing a task to be called in the background, pay attention to the Execute scripts and Create SQL script\EXECUTE settings, which are responsible for enabling the update.

Same servers, Windows auth
/sync C:\Apps\Support\v5_0_193\Support.audbproj /quiet /ds dbs\SQL2019 /tcatalog support_work /scatalog support_v5_0_193
Same servers, SQL Server auth
/sync C:\Apps\Support\v5_0_193\Support.audbproj /quiet /ds dbs\SQL2019 /userid sa /pwd "secret 1" /tcatalog support_work /scatalog support_v5_0_193
Different servers, SQL Server auth
/sync C:\Apps\Support\v5_0_193\Support.audbproj /quiet /tds dbs\SQL2019 /tuserid sa /tpwd "secret 1" /tcatalog support_work /sds dbtest\SQL2016 /suserid user1 /spwd "secret 2" /scatalog support_v5_0_193
Different servers, SQL Server auth, with remembered passwords
/sync C:\Apps\Support\v5_0_193\Support.audbproj /quiet /tds dbs\SQL2019 /tuserid sa /tcatalog support_work /sds 192.168.0.1,1433 /suserid user1 /scatalog support_test
Use databases specified in project file, interactive
/sync C:\Apps\Support\v5_0_193\Support.audbproj /interactive /tdefault
Source db specified in project file, Windows auth, task name
/sync C:\Apps\Support\v5_0_193\Support.audbproj /quiet /task support-daily-202112080230 /tds dbs\SQL2019 /tcatalog db_support_test
Source db specified in project file, Windows auth, parent process id (1416), timeouts
/sync C:\Apps\Support\v5_0_193\Support.audbproj /quiet /task support-daily /owtask /notify 1416 /customid support-daily-2021-12-08 /tds dbs\sql2019 /tcatalog db_support_test /ctimeout 30 /dtimeout 14400
Let me choose databases, show errors only
/sync C:\Apps\Support\v5_0_193\Support.audbproj /tselect /sselect
Source db specified in project file, target db via connection string
/sync C:\Apps\Support\v5_0_193\Support.audbproj /quiet /task 0123456789 /tcs "Data Source=192.168.0.1,1433;Initial Catalog=support_work;Integrated Security=true;Pooling=false;Application Name=NightUpdateProc"
Project from update package, parent process id (4212)
/sync C:\Apps\Enterprise\v4.60\db-create.audbp /task 20211208091427 /notify 4212 /temp C:\Users\Administrator\AppData\Local\Temp\db-update /tds 192.168.0.193\SQL2016 /tcatalog DB_Enterprise_Test /tuserid sa /ctimeout 7 /dtimeout 120 /tpwd "secret 3"

Export database structure to a file

/texport C:\Apps\Enterprise\v4.60\db-create.audbproj /quiet /task 2021-12-07_17-03 /tpath D:\Updates\Enterprise\v4.60\db-create.audbp /tds 192.168.0.193\SQL2016 /tcatalog DB_Enterprise_Test /tuserid sa /tpwd "secret 1"

Build database update package

Source db specified in project file, interactive
/build C:\Apps\Enterprise\v4.60\db-create.audbproj /interactive /pbuild C:\Apps\Enterprise\v4.60\db-create.audbp
Specify source database to export schema
/build C:\Apps\Enterprise\v4.60\db-create.audbproj /quiet /pbuild C:\Apps\Enterprise\v4.60\db-create.audbp /sds 192.168.0.193\SQL2016 /scatalog DB_Enterprise_Test /suserid sa /spwd "secret 1"

Package Wizard

Automatic connection to preset target database
/open C:\Apps\Enterprise\v4.60\db-create.audbp /tds 192.168.0.193\SQL2019 /tcatalog DB_Enterprise_Test

Application exit codes

The wizard and background modes are single-task modes in which the code returned by a process to the system reports the result of the task.

NameValueDescription
Standard error codes
SUCCEEDED0Task completed successfully
UNEXPECTED0x8000FFFFAn unexpected error has occurred. Please restart the application!
OUTOFMEMORY0x8007000EOut of memory!
INVALID_FUNCTION0xFFFFFFFFIt looks like the process was deliberately terminated (for example in Windows Task Manager).
HANDLED0x80131600A handled error is occurred
Application-defined error codes
CANNOT_UPGRADE_APP0xA000000AAutosyncDB cannot update its settings. There is another launched version of the application, or this launch is performed in the background mode (completely hidden or as a wizard). Close all other launched instances of the application and try starting AutosyncDB in a regular way as an MDI application first.
OUT_OF_LICENSE0xA000000BThis operation is restricted or not provided under the terms of the current license.
COULD_NOT_OBTAIN_PROCESS_FOR_NOTIFICATIONS0xA000000CCould not obtain the process for notifications.
NEWER_PROJECT_FORMAT0xA000000DThe project file was created by a different version of this application. Not all parameters can be applied. Most likely, you should update the application to be able to work with it.
CONFIGURATION_REQUIRED0xA000000EAutosyncDB requires additional configuration. Try running the app in a regular way as an MDI application first.
COMMANDLINE_INVALID0xA0000014Invalid command line arguments!
COMMANDLINE_PATH_INVALID0xA0000015Invalid path in command line argument.
COMMANDLINE_TASKNAME_INVALID0xA0000016Invalid task name in command line argument.
TASKNAME_EXISTS0xA000001EA task with this name already exists.
CANCELED_BY_USER0xA000001FCanceled by user.
TARGET_NOT_SPECIFIED0xA0000020A target database is not specified.
TARGET_NOT_CONNECTED0xA0000021Failed to establish connection to the target database.
TARGET_NOT_SUPPORTED0xA0000022The version of the selected SQL server is not supported. Minimum required version is MS SQL Server® 2005.
SOURCE_NOT_SPECIFIED0xA0000023A source database is not specified.
SOURCE_NOT_CONNECTED0xA0000024Failed to establish a connection to the source database.
SOURCE_NOT_SUPPORTED0xA0000025The version of the selected SQL server is not supported. Minimum required version is MS SQL Server® 2005.
Task launch error codes
TASK_FAILED_TO_LOAD0xA0000032Failed to load the project.
TASK_FAILED_TO_START0xA0000033Failed to start the task.
Task completion error codes
TASK_DONE_WITH_ERRORS0xA0000034The task has been done with errors.
TASK_FAILED_ERROR_LIMIT_EXCEEDED0xA0000035Failed to complete the task, because the error limit has been exceeded.
TASK_FAILED_ABORTED_BY_USER0xA0000036The task has been aborted by user.
TASK_FAILED0xA0000037The task failed.
Approval test error codes
TARGET_FAILED_TO_GET_APPROVAL0xA000003DFailed to get approval for the target database.
TARGET_WRONG_PRODUCT0xA000003EThe target database does not belong to this product.
TARGET_WRONG_PRODUCT_CONFIGURATION0xA000003FThe target database has a different product configuration.
TARGET_IS_TOO_OLD0xA0000040The target database version is lower than this update supports.
TARGET_IS_TOO_NEW0xA0000041The target database version is higher than this update supports.
TARGET_IS_NOT_VALID_FOR_OPERATION0xA0000042The target database is not valid for this update.
TARGET_APPROVAL_CODE_70xA0000043The target database is not valid for this update.
TARGET_APPROVAL_CODE_80xA0000044The target database is not valid for this update.
TARGET_APPROVAL_CODE_90xA0000045The target database is not valid for this update.
TARGET_APPROVAL_CODE_100xA0000046The target database is not valid for this update.
TARGET_APPROVAL_CODE_110xA0000047The target database is not valid for this update.
TARGET_APPROVAL_CODE_120xA0000048The target database is not valid for this update.
TARGET_APPROVAL_CODE_130xA0000049The target database is not valid for this update.
TARGET_APPROVAL_CODE_140xA000004AThe target database is not valid for this update.
TARGET_APPROVAL_CODE_150xA000004BThe target database is not valid for this update.

Interacting with task process

For deeper integration, there is also a window-procedure-based interface that allows interprocess interaction between the foreground window of client application and the task process. It uses SendMessage and PostMessage functions to send the registered WM_AUTOSYNCDB_COMMAND, WM_AUTOSYNCDB_NOTIFY window messages and the standard WM_COPYDATA message. You can implement this interface in your update application to be able to subscribe to specific notifications from running task processes and stop it on demand.

You can learn more about all this from the "TMon" demo project. This is a simple WinForms application that helps you create the right command line, shows you how to start, control and receive notifications from task processes.
TMon sources (includes TMon.exe),
TMon sources.