{"id":22837263,"url":"https://github.com/cake-contrib/cake.sqlserver","last_synced_at":"2025-08-30T17:12:39.342Z","repository":{"id":45606224,"uuid":"67621207","full_name":"cake-contrib/Cake.SqlServer","owner":"cake-contrib","description":"Cake Build aliases for working with SQL Server","archived":false,"fork":false,"pushed_at":"2024-01-18T18:22:14.000Z","size":2516,"stargazers_count":30,"open_issues_count":6,"forks_count":17,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-07-29T00:44:41.154Z","etag":null,"topics":["augustoproiete","cake","cake-addin","cake-build","cakebuild","hacktoberfest","localdb","sql-server","trailmax"],"latest_commit_sha":null,"homepage":"https://cakebuild.net/extensions/cake-sqlserver/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cake-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-07T15:46:06.000Z","updated_at":"2024-06-24T17:37:18.000Z","dependencies_parsed_at":"2024-06-18T22:59:39.100Z","dependency_job_id":"f3ec62e4-a8c9-4af2-9e7f-3ca609e8fd99","html_url":"https://github.com/cake-contrib/Cake.SqlServer","commit_stats":null,"previous_names":["amvsoftware/cake.sqlserver"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/cake-contrib/Cake.SqlServer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cake-contrib%2FCake.SqlServer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cake-contrib%2FCake.SqlServer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cake-contrib%2FCake.SqlServer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cake-contrib%2FCake.SqlServer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cake-contrib","download_url":"https://codeload.github.com/cake-contrib/Cake.SqlServer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cake-contrib%2FCake.SqlServer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272878320,"owners_count":25008336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["augustoproiete","cake","cake-addin","cake-build","cakebuild","hacktoberfest","localdb","sql-server","trailmax"],"created_at":"2024-12-12T23:16:10.752Z","updated_at":"2025-08-30T17:12:39.326Z","avatar_url":"https://github.com/cake-contrib.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cake.SqlServer\r\n\r\nCake Build addin for working with SqlServer and LocalDb.\r\n\r\n[![Build status](https://ci.appveyor.com/api/projects/status/wgbuq8pw180w42t2/branch/master?svg=true)](https://ci.appveyor.com/project/trailmax/cake-sqlserver/branch/master)\r\n[![NuGet version](https://badge.fury.io/nu/cake.sqlserver.svg)](https://badge.fury.io/nu/cake.sqlserver)\r\n\r\nShow me the codez: [integration tests](https://github.com/AMVSoftware/Cake.SqlServer/blob/master/tests.cake) for live up to date examples.\r\nOr look through XML-generated documentation on [Cakebuild.net site](http://cakebuild.net/dsl/sqlserver/).\r\n\r\n* [General Functionality](#general-functionality)\r\n* [Working With Backup files](#working-with-backup-files)\r\n* [Working with BACPAC and DACPAC](#working-with-bacpac-and-dacpac)\r\n* [Working with LocalDB](#working-with-localdb)\r\n* [Usage](#usage)\r\n* [Reason to Develop](#reason-to-develop)\r\n\r\n\r\n# General Functionality\r\n\r\n### Database Exists\r\n```c#\r\nDatabaseExists(string connectionString, string databaseName)\r\n```\r\nReturn true if the database exists, false otherwise.\r\n\r\n### Create Database\r\n```c#\r\nCreateDatabase(string connectionString, string databaseName)\r\n```\r\nCreates database. If database with this name exists - SqlException is thrown.\r\n\r\n```c#\r\nvar createSettings = new CreateDatabaseSettings()\r\n                        .WithPrimaryFile(@\"C:\\MyPath\\MyCakeTest.mdf\")\r\n                        .WithLogFile(@\"C:\\MyPath\\MyCakeTest.ldf\");\r\nCreateDatabase(masterConnectionString, \"CreateCakeTest\", createSettings);\r\n```\r\nCreates a database with the specified primary and log files locations.\r\n\r\n### Create Database If Not Exist\r\n```c#\r\nCreateDatabaseIfNotExists(string connectionString, string databaseName)\r\n```\r\n\r\nHere we check if the database exists first, if it does not exists - create it. Does not do anything if database with this name already exists.\r\n\r\n```c#\r\nvar createSettings = new CreateDatabaseSettings()\r\n                        .WithPrimaryFile(@\"C:\\MyPath\\MyCakeTest.mdf\")\r\n                        .WithLogFile(@\"C:\\MyPath\\MyCakeTest.ldf\");\r\nCreateDatabaseIfNotExists(masterConnectionString, \"MyCakeTest\", createSettings)\r\n```\r\nThis will check if database does not yet exist and will create a new one. And will place primary data file and log file into specified locations.\r\n\r\n\r\n### Drop Database\r\n```c#\r\nDropDatabase(string connectionString, string databaseName)\r\n```\r\n\r\nBasically executes `Drop Database databasename` with some fail-safes. Actually it sets the database into offline mode - to cut off all existing connections. Then sets the database back online and then drops it.\r\nReason for this dance - you can't drop a database if there are existing connections to the database.\r\n\r\n### Drop and Create Database\r\n```c#\r\nDropAndCreateDatabase(String connectionString, String databaseName)\r\n```\r\n\r\nSimply a short-hand for `DropDatabase(); CreateDatabase();`. I found these calls frequently together to create a short-hand.\r\n\r\n```c#\r\nvar createSettings = new CreateDatabaseSettings()\r\n                        .WithPrimaryFile(@\"C:\\MyPath\\MyCakeTest.mdf\")\r\n                        .WithLogFile(@\"C:\\MyPath\\MyCakeTest.ldf\");\r\nDropAndCreateDatabase(masterConnectionString, \"MyCakeTest\", createSettings)\r\n```\r\nThis will drop and re-create the database with provided locations for data and log files.\r\n\r\n### Execute Sql Command\r\n```c#\r\nExecuteSqlCommand(String connectionString, string sqlCommands);\r\nExecuteSqlCommand(SqlConnection connection, string sqlCommands);\r\n```\r\n\r\nDoes what it says on the tin: executes the sql query. But this method accommodates for `Go` within scripts. Usually executing long queries from .Net won't work when query has `GO` inside. This one does know what to do with it.\r\n\r\n### Execute Command from SQL File\r\n```c#\r\nExecuteSqlFile(String connectionString, string sqlFile);\r\nExecuteSqlFile(SqlConnection connection, string sqlFile);\r\n```\r\nReads sql file and executes commands from it. Executes parts of scripts separated by `GO` as a separate command executions.\r\n\r\n### Open Connection for Use in Multiple Operations\r\n```c#\r\nOpenSqlConnection(String connectionString)\r\n```\r\n\r\nAllows you to use the same connection for multiple SQL commands. Close the connection (by disposing) once you're finished with it.\r\nExample:\r\n\r\n```c#\r\nusing (var connection = OpenSqlConnection(@\"Data Source=(localdb)\\MSSqlLocalDb;Initial Catalog=MyDatabase\"))\r\n{\r\n    ExecuteSqlCommand(connection, \"...\");\r\n    ExecuteSqlFile(connection, \"./somePath/MyScript.sql\");\r\n}\r\n```\r\n\r\n### Set Default Execution Timeout\r\n```c#\r\nSetSqlCommandTimeout(int commandTimeout)\r\n```\r\n\r\nAllows you to specify the command timeout in seconds for all commands. This is used to set the `CommandTimeout` property on the underlying `SqlCommand`.\r\n\r\n```c#\r\nSetSqlCommandTimeout(60);\r\nusing (var connection = OpenSqlConnection(@\"Data Source=(localdb)\\MSSqlLocalDb;Initial Catalog=MyDatabase\"))\r\n{\r\n    ExecuteSqlCommand(connection, \"...\"); // \u003c- execute long-running command\r\n}\r\n```\r\n\r\n# Working With Backup files\r\n\r\n### Restore Database Backup File\r\n```c#\r\nRestoreSqlBackup(String connectionString, FilePath backupFile, RestoreSqlBackupSettings settings)\r\nRestoreSqlBackup(String connectionString, FilePath backupFile)\r\n```\r\n\r\nRestores the database from a `.bak` file. Options include to rename the target database, specify path where the data/log files are stored and ability to replace existing database.\r\n\r\nIf new database name is not provided, db-name is extracted from the backup file; if new storage location for data files is not provided, system default folder is used.\r\n\r\nExample:\r\n\r\n```c#\r\nTask(\"Restore-Database\")\r\n\t.Does(() =\u003e {\r\n\t\tvar connString = @\"data source=(localdb)\\MSSqlLocalDb\";\r\n\r\n\t\tvar backupFilePath = new FilePath(@\".\\src\\Tests\\TestData\\multiFileBackup.bak\");\r\n\t\tbackupFilePath = backupFilePath.MakeAbsolute(Context.Environment);\r\n\r\n\t\tRestoreSqlBackup(connString, backupFilePath, new RestoreSqlBackupSettings()\r\n\t\t\t{\r\n\t\t\t\tNewDatabaseName = \"RestoredFromTest.Cake\",\r\n\t\t\t\tNewStorageFolder = new DirectoryPath(System.IO.Path.GetTempPath()), // place files in special location\r\n\t\t\t});\r\n\t});\r\n```\r\n\r\n### Restore split Database backups and split differential backups\r\n```c#\r\nRestoreMultipleSqlBackup(String connectionString, RestoreSqlBackupSettings settings, IList\u003cFilePath\u003e backupFiles, IList\u003cFilePath\u003e differentialBackupFiles = null)\r\n```\r\n\r\nRestores from a list of `.bak` files. The options and behavior are the same as for RestoreSqlBackup.\r\nIf a set of differential backup files are specified the task will first restore the full backup and then restore the differential backup files with appropriate restore settings for the two steps.\r\nThe option BackupSetFile and DifferentialBackupSetFile (both are null by default) can be used to explicitely specify the desired backup set for the full backups and the differential backups.\r\n\r\nExample:\r\n\r\n```c#\r\nTask(\"Restore-Split-Database\")\r\n    .Does(() =\u003e\r\n    {\r\n        var connString = @\"data source=(localdb)\\MSSqlLocalDb\";\r\n        var backupFile1 = new FilePath(\"C:/tmp/myBackup1.bak\");\r\n        var backupFile2 = new FilePath(\"C:/tmp/myBackup2.bak\");\r\n        var backupFileList = new List\u003cFilePath\u003e {backupFile1, backupFile2};\r\n        var diffBackupFile1 = new FilePath(\"C:/tmp/myDiffBackup1.bak\");\r\n        var diffBackupFile2 = new FilePath(\"C:/tmp/myDiffBackup2.bak\");\r\n        var diffBackupFileList = new List\u003cFilePath\u003e {diffBackupFile1, diffBackupFile2};\r\n        RestoreMultipleSqlBackup(connString, new RestoreSqlBackupSettings()\r\n           {\r\n                 NewDatabaseName = \"RestoredFromTest.Cake\",\r\n                 NewStorageFolder = new DirectoryPath(System.IO.Path.GetTempPath()), // place files in Temp folder\r\n                 WithReplace = true, // tells sql server to discard non-backed up data when overwriting existing database\r\n                 BackupSetFile = 1, // tells which backup set file to use for backupFile*\r\n                 DifferentialBackupSetFile = 1, // tells which backup set file to use for diffBackupFile*\r\n           }, backupFileList, diffBackupFileList);\r\n    });\r\n```\r\n\r\n### Backup Database\r\n```c#\r\nBackupDatabase(string connectionString, string databaseName, BackupDatabaseSettings settings)\r\n```\r\n\r\nBackup a database to a `.bak` file. Options all you to compress the backup file and specify the path (or the specific filename).\r\n\r\nExample:\r\n\r\n```c#\r\nTask(\"Backup-Database\")\r\n    .Does(() =\u003e\r\n    {\r\n        var connString = @\"data source=(localdb)\\MSSqlLocalDb\";\r\n        var databaseName = \"MyDatabase\";\r\n        BackupDatabase(connString, databaseName, new BackupDatabaseSettings()\r\n           {\r\n                 Compress = false,\r\n\t\t\t\t // you can specify either a folder or a file\r\n                 Path = System.IO.Path.GetTempPath()\r\n           });\r\n    });\r\n```\r\n\r\n# Working with BACPAC and DACPAC\r\n\r\nThis addin includes a thin wrapper around `Microsoft.SqlServer.DacFx` to provide ability to work with BACPAC and DACPAC files\r\n\r\n### Working with BACPAC files\r\n\r\nTo create a bacpac file from a database call:\r\n\r\n```c#\r\nTask(\"Create-Bacpac\")\r\n\t.Does(() =\u003e{\r\n\t\tvar connString = @\"data source=(localdb)\\MSSqlLocalDb\";\r\n\r\n\t\tvar dbName = \"ForBacpac\";\r\n\r\n        var resultingFile = new FilePath(@\".\\ForBacpac.bacpac\");\r\n\r\n\t\tCreateBacpacFile(connString, dbName, resultingFile);\r\n\t});\r\n```\r\n\r\nTo restore from bacpac file into a database use this:\r\n\r\n```c#\r\nTask(\"Restore-From-Bacpac\")\r\n\t.Does(() =\u003e{\r\n\t\tvar connString = @\"data source=(localdb)\\MSSqlLocalDb\";\r\n\r\n\t\tvar dbName = \"FromBacpac\";\r\n\r\n\t\tvar file = new FilePath(@\".\\path\\to\\my.bacpac\");\r\n\r\n\t\tRestoreBacpac(connString, dbName, file);\r\n\t})\r\n```\r\n\r\n### Working with DACPAC files\r\n\r\nTo extract a dacpac file from a database call:\r\n\r\n```c#\r\nTask(\"Extract-Dacpac\")\r\n\t.Does(() =\u003e{\r\n\t\tvar connString = @\"data source=(localdb)\\MSSqlLocalDb\";\r\n\r\n\t\tvar dbName = \"ForDacpac\";\r\n\r\n\t\tCreateDatabase(connString, dbName);\r\n\r\n\t\tvar settings = new ExtractDacpacSettings(\"MyAppName\", \"2.0.0.0\") {\r\n\t\t\tOutputFile = new FilePath(@\".\\TestData\\Nsaga.dacpac\")\r\n\t\t};\r\n\r\n\t\tExtractDacpacFile(connString, dbName, settings);\r\n\t});\r\n});\r\n```\r\n\r\nTo publish from dacpac file into a database use this:\r\n\r\n```c#\r\nTask(\"Create-Bacpac\")\r\n\t.Does(() =\u003e{\r\n\t\tvar connString = @\"data source=(localdb)\\MSSqlLocalDb\";\r\n\r\n\t\tvar dbName = \"ForDacpac\";\r\n\r\n\t\tvar file = new FilePath(@\".\\src\\Tests\\TestData\\Nsaga.dacpac\");\r\n\r\n\t\tvar settings = new PublishDacpacSettings {\r\n\t\t\tGenerateDeploymentScript = true\r\n\t\t};\r\n\r\n\t\tPublishDacpacFile(connString, dbName, file, settings);\r\n\t});\r\n});\r\n```\r\n\r\n# Working with LocalDB\r\nSamples show here are using `LocalDb\\v12.0`. This used to be default name for LocalDB instance when installed with SQL Server 2012. Since Sql Server 2014 the default name for LocalDB instance is `MSSQLLocalDB`, making the default instance name for LocalDB looking like this: `(LocalDB)\\MSSQLLocalDB`. So before using `v12.0` double check what instance you have installed and go from there.\r\n\r\nThis package includes a wrapper for working with LocalDB. LocalDB is a lightweight SQL Server version that is great for running tests against.\r\n\r\nAlso please don't be alarmed that all the examples are using LocalDB. The plugin is capable of working with any SQL Server installation. This package includes commands to `Create`, `Start`, `Stop` and `Delete` instances of LocalDB. To be used like this:\r\n\r\n```c#\r\n#addin \"nuget:?package=Cake.SqlServer\"\r\n\r\nTask(\"Create-LocalDB\")\r\n     .Does(() =\u003e\r\n     {\r\n\t\t// creates and starts instance\r\n\t\t// you don't need to start the instance separately\r\n        LocalDbCreateInstance(\"Cake-Test\");\r\n     });\r\n\r\nTask(\"Start-LocalDB\")\r\n     .Does(() =\u003e\r\n     {\r\n        LocalDbStartInstance(\"Cake-Test\");\r\n    });\r\n\r\nTask(\"Stop-LocalDB\")\r\n     .Does(() =\u003e\r\n     {\r\n        LocalDbStopInstance(\"Cake-Test\");\r\n    });\r\n\r\nTask(\"Delete-LocalDB\")\r\n     .Does(() =\u003e\r\n     {\r\n        LocalDbDeleteInstance(\"Cake-Test\");\r\n    });\r\n```\r\n\r\n\r\n# Usage\r\n\r\nYou can also check our [integration tests](https://github.com/AMVSoftware/Cake.SqlServer/blob/master/tests.cake) for live examples.\r\n\r\n\r\n### Gotchas\r\n\r\nRemember to always add `@` before your connection strings. Some connection strings (i.e. `(localdb)\\MSSqlLocalDb`) can contain backward slash `\\` and that is an escape symbol in C#. So you need to always add `@` before the string:\r\n\r\n\tvar connString = @\"(localdb)\\MSSqlLocalDb\";\r\n\r\n`\\v` is the C# escape sequence for vertical tab which is not what you want. Using the verbatim string syntax `@` prevents escape sequences from being interpreted and you get what you expect, verbatim `\\` and `v` characters.\r\n\r\n### Generating Connection String\r\n\r\nIf you have complex connection strings, please consider using [SqlConnectionStringBuilder](https://msdn.microsoft.com/en-us/library/system.data.sqlclient.sqlconnectionstringbuilder)\r\nfor creating your connection strings:\r\n\r\n```c#\r\n var connectionString = new SqlConnectionStringBuilder\r\n {\r\n    DataSource = @\"(LocalDb)\\MSSQLLocalDB\",\r\n    InitialCatalog = databaseName,\r\n }.ToString();\r\n```\r\nThis class adds a lot of sugar around creating a connection string.\r\n\r\n### Creating Temp Database and Clean Up\r\n\r\nThis script is courtesy of [Joseph Musser](https://github.com/jnm2)\r\n\r\nIf you need to create and delete the database inside of your build script you can use this nice trick.\r\n\r\nSomewhere your cake script (usually I put it in `lib.cake` and reference it from the main script via `#load \"./lib.cake\"`) put this class:\r\n\r\n```c#\r\npublic static class On\r\n{\r\n    public static IDisposable Dispose(Action action)\r\n    {\r\n        return new OnDisposeAction(action);\r\n    }\r\n\r\n\r\n    private sealed class OnDisposeAction : IDisposable\r\n    {\r\n        private Action action;\r\n\r\n        public OnDisposeAction(Action action)\r\n        {\r\n            this.action = action;\r\n        }\r\n\r\n        public void Dispose()\r\n        {\r\n            var exchange = System.Threading.Interlocked.Exchange(ref action, null);\r\n            if (exchange != null)\r\n            {\r\n                exchange.Invoke();\r\n            }\r\n        }\r\n    }\r\n}\r\n```\r\n\r\nThen in your actual cake script you can do:\r\n```c#\r\nIDisposable TempDatabase(string connectionString, string databaseName)\r\n{\r\n    CreateDatabaseIfNotExists(connectionString, databaseName);\r\n    return On.Dispose(() =\u003e DropDatabase(connectionString, databaseName));\r\n}\r\n```\r\nand\r\n\r\n```c#\r\nvar masterConnectionString = @\"data source=(LocalDb)\\MSSQLLocalDB;\";\r\nvar databaseName = \"Tests\";\r\nusing (TempDatabase(masterConnectionString, databaseName))\r\n{\r\n    var connectionString = @\"data source=(LocalDb)\\MSSQLLocalDB;Database=Tests\";\r\n\r\n    ExecuteSqlCommand(connectionString, \"select * from products.......\");\r\n    // execute your SQL operations\r\n    // or run tests\r\n}\r\n```\r\nThis technique will make sure your temp database will be dropped after the payload/integration tests are executed.\r\n\r\n# Reason to Develop\r\nThere is already a project that does similar things: [Cake.SqlTools](https://github.com/SharpeRAD/Cake.SqlTools). I have tried it and it was not enough for my purposes. I did look into extending functionality, but the way the project is structured - it won't let me do what I would like to do. The great idea in that project - be able to switch between MySql and SqlServer with a change of a single parameter.\r\n\r\nBut I wanted to implement things like creating a database if it does not exist. And syntax for that in MySql and SqlServer is different. So if I wanted to extend that project I had to come up with the same functionality in MySql. But I don't use MySql, hell I don't even have it installed on my dev-machines any more.\r\n\r\n# How To Contribute\r\n\r\nInstall [.Net Framwork 4.7.2 Developer Pack](https://www.microsoft.com/net/download/thank-you/net472-developer-pack)\r\n\r\nOpen a command prompt in the root folder, and run these commands (Only need to run this once for any project. It will allow powershell scripts to execute):\r\n\r\n```\r\npowershell Set-ExecutionPolicy RemoteSigned -Scope CurrentUser\r\npowershell Get-ExecutionPolicy -List\r\n```\r\n\r\n# Running Cake Scripts\r\n\r\n```\r\n# compile and run unit tests\r\npowershell .\\build.ps1 --target run-unit-tests\r\n\r\n# publish NUGET package\r\npowershell .\\build.ps1\r\n```\r\n\r\n## Discussion\r\n\r\nFor questions and to discuss ideas \u0026 feature requests, use the [GitHub discussions on the Cake GitHub repository](https://github.com/cake-build/cake/discussions), under the [Extension Q\u0026A](https://github.com/cake-build/cake/discussions/categories/extension-q-a) category.\r\n\r\n[![Join in the discussion on the Cake repository](https://img.shields.io/badge/GitHub-Discussions-green?logo=github)](https://github.com/cake-build/cake/discussions)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcake-contrib%2Fcake.sqlserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcake-contrib%2Fcake.sqlserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcake-contrib%2Fcake.sqlserver/lists"}