Get started with Elastic Database Tools
Applies to: Azure SQL Database
This document introduces you to the developer experience for the elastic database client library by helping you run a sample app. The sample app creates a simple sharded application and explores key capabilities of the Elastic Database Tools feature of Azure SQL Database. It focuses on use cases for shard map management, data-dependent routing, and multi-shard querying. The client library is available for .NET as well as Java.
- A Java Developer Kit (JDK), version 1.8 or later
- Maven
- SQL Database or a local SQL Server instance
To build the JAR files and get started with the sample project, do the following:
Clone the GitHub repository containing the client library, along with the sample app.
Edit the ./sample/src/main/resources/resource.properties file to set the following:
- TEST_CONN_USER
- TEST_CONN_PASSWORD
- TEST_CONN_SERVER_NAME
To build the sample project, in the ./sample directory, run the following command:
mvn install
To start the sample project, in the ./sample directory, run the following command:
mvn -q exec:java "-Dexec.mainClass=com.microsoft.azure.elasticdb.samples.elasticscalestarterkit.Program"
To learn more about the client library capabilities, experiment with the various options. Feel free to explore the code to learn about the sample app implementation.
Congratulations! You have successfully built and run your first sharded application by using Elastic Database Tools on Azure SQL Database. Use Visual Studio or SQL Server Management Studio to connect to your database and take a quick look at the shards that the sample created. You will notice new sample shard databases and a shard map manager database that the sample has created.
To add the client library to your own Maven project, add the following dependency in your POM file:
<dependency>
<groupId>com.microsoft.azure</groupId>
<artifactId>elastic-db-tools</artifactId>
<version>1.0.0</version>
</dependency>
- Visual Studio 2012 or later with C#. Download a free version at Visual Studio Downloads.
- NuGet 2.7 or later. To get the latest version, see Installing NuGet.
To install the library, go to Microsoft.Azure.SqlDatabase.ElasticScale.Client. The library is installed with the sample app that's described in the following section.
To download and run the sample, follow these steps:
Download the Elastic DB Tools for Azure SQL - Getting Started sample. Unzip the sample to a location that you choose.
To create a project, open the ElasticDatabaseTools.sln solution from the elastic-db-tools-master directory.
Set the ElasticScaleStarterKit project as the Startup Project.
In the ElasticScaleStarterKit project, open the App.config file. Then follow the instructions in the file to add your server name and your sign in information (username and password).
Build and run the application. When you are prompted, enable Visual Studio to restore the NuGet packages of the solution. This action downloads the latest version of the elastic database client library from NuGet.
To learn more about the client library capabilities, experiment with the various options. Note the steps that the application takes in the console output, and feel free to explore the code behind the scenes.
Congratulations! You have successfully built and run your first sharded application by using Elastic Database Tools on SQL Database. Use Visual Studio or SQL Server Management Studio to connect to your database and take a quick look at the shards that the sample created. You will notice new sample shard databases and a shard map manager database that the sample has created.
Important
We recommend that you always use the latest version of Management Studio so that you stay synchronized with updates to Azure and SQL Database. Update SQL Server Management Studio.
Managing shards and shard maps: The code illustrates how to work with shards, ranges, and mappings in the ShardManagementUtils.cs file. For more information, see Scale out databases with the shard map manager.
Data-dependent routing: Routing of transactions to the right shard is shown in the DataDependentRoutingSample.cs file. For more information, see Data-dependent routing.
Querying over multiple shards: Querying across shards is illustrated in the MultiShardQuerySample.cs file. For more information, see Multi-shard querying.
Adding empty shards: The iterative adding of new empty shards is performed by the code in the CreateShardSample.cs file. For more information, see Scale out databases with the shard map manager.
Splitting an existing shard: The capability to split shards is provided by the split-merge tool. For more information, see Moving data between scaled-out cloud databases.
Merging existing shards: Shard merges are also performed by using the split-merge tool. For more information, see Moving data between scaled-out cloud databases.
The Elastic Database Tools library is free. When you use Elastic Database Tools, you incur no additional charges beyond the cost of your Azure usage.
For example, the sample application creates new databases. The cost of this capability depends on the SQL Database edition you choose and the Azure usage of your application.
For pricing information, see SQL Database pricing details.
For more information about Elastic Database Tools, see the following articles:
- Code samples:
- Elastic Database Tools (.NET, Java)
- Elastic Database Tools for Azure SQL - Entity Framework Integration
- Blog: Elastic Scale announcement
- Discussion forum: Microsoft Q&A question page for Azure SQL Database
- To measure performance: Performance counters for shard map manager