Använd data beroende routning för att dirigera en fråga till en lämplig databasUse data-dependent routing to route a query to an appropriate database

gäller för: Azure SQL Database

Data beroende routning är möjligheten att använda data i en fråga för att dirigera begäran till en lämplig databas.Data-dependent routing is the ability to use the data in a query to route the request to an appropriate database. Data beroende routning är ett grundläggande mönster när du arbetar med shardade-databaser.Data-dependent routing is a fundamental pattern when working with sharded databases. Kontexten för begäran kan också användas för att dirigera begäran, särskilt om horisontell partitionering-nyckeln inte är en del av frågan.The request context may also be used to route the request, especially if the sharding key is not part of the query. Varje specifik fråga eller transaktion i ett program som använder data beroende routning är begränsad till åtkomst till en databas per begäran.Each specific query or transaction in an application using data-dependent routing is restricted to accessing one database per request. För Azure SQL Database elastiska verktyg utförs denna routning med klassen ShardMapManager (Java, .net).For the Azure SQL Database elastic tools, this routing is accomplished with the ShardMapManager (Java, .NET) class.

Programmet behöver inte spåra olika anslutnings strängar eller DB-platser som är kopplade till olika data sektorer i shardade-miljön.The application does not need to track various connection strings or DB locations associated with different slices of data in the sharded environment. I stället öppnar Shard Map Manager anslutningar till rätt databaser vid behov, baserat på data i Shard-mappningen och värdet för horisontell partitionering-nyckeln som är målet för programmets begäran.Instead, the Shard Map Manager opens connections to the correct databases when needed, based on the data in the shard map and the value of the sharding key that is the target of the application’s request. Nyckeln är vanligt vis customer_id, tenant_id, date_key eller någon annan unik identifierare som är en grundläggande parameter för databas förfrågan.The key is typically the customer_id, tenant_id, date_key, or some other specific identifier that is a fundamental parameter of the database request.

Mer information finns i skala ut SQL Server med Data-Dependent routing.For more information, see Scaling Out SQL Server with Data-Dependent Routing.

Ladda ned klient biblioteketDownload the client library

Hämta:To download:

Använda en ShardMapManager i ett data beroende Dirigerings programUsing a ShardMapManager in a data-dependent routing application

Program ska instansiera ShardMapManager under initieringen med hjälp av Factory-anropet GetSQLShardMapManager (Java, .net).Applications should instantiate the ShardMapManager during initialization, using the factory call GetSQLShardMapManager (Java, .NET). I det här exemplet initieras både en ShardMapManager och en speciell ShardMap som den innehåller.In this example, both a ShardMapManager and a specific ShardMap that it contains are initialized. I det här exemplet visas metoderna GetSqlShardMapManager och GetRangeShardMap (Java, .net).This example shows the GetSqlShardMapManager and GetRangeShardMap (Java, .NET) methods.

ShardMapManager smm = ShardMapManagerFactory.getSqlShardMapManager(connectionString, ShardMapManagerLoadPolicy.Lazy);
RangeShardMap<int> rangeShardMap = smm.getRangeShardMap(Configuration.getRangeShardMapName(), ShardKeyType.Int32);
ShardMapManager smm = ShardMapManagerFactory.GetSqlShardMapManager(smmConnectionString, ShardMapManagerLoadPolicy.Lazy);
RangeShardMap<int> customerShardMap = smm.GetRangeShardMap<int>("customerMap"); 

Använd lägsta möjliga behörighet för att hämta Shard-kartanUse lowest privilege credentials possible for getting the shard map

Om ett program inte ändrar själva Shard-kartan ska de autentiseringsuppgifter som används i fabriks metoden ha Läs behörighet för den globala Shard Map -databasen.If an application is not manipulating the shard map itself, the credentials used in the factory method should have read-only permissions on the Global Shard Map database. Dessa autentiseringsuppgifter skiljer sig vanligt vis från autentiseringsuppgifter som används för att öppna anslutningar till Shard Map Manager.These credentials are typically different from credentials used to open connections to the shard map manager. Se även autentiseringsuppgifter som används för att få åtkomst till Elastic Database klient biblioteket.See also Credentials used to access the Elastic Database client library.

Anropa metoden OpenConnectionForKeyCall the OpenConnectionForKey method

Metoden ShardMap. OpenConnectionForKey (Java, .net) returnerar en anslutning som är klar för att utfärda kommandon till lämplig databas baserat på värdet för nyckel parametern.The ShardMap.OpenConnectionForKey method (Java, .NET) returns a connection ready for issuing commands to the appropriate database based on the value of the key parameter. Shard-information cachelagras i programmet av ShardMapManager, så dessa begär Anden brukar inte inkludera en databas sökning mot den globala Shard Map -databasen.Shard information is cached in the application by the ShardMapManager, so these requests do not typically involve a database lookup against the Global Shard Map database.

// Syntax:
public Connection openConnectionForKey(Object key, String connectionString, ConnectionOptions options)
// Syntax:
public SqlConnection OpenConnectionForKey<TKey>(TKey key, string connectionString, ConnectionOptions options)
  • Nyckel parametern används som en uppslags nyckel i Shard-kartan för att fastställa lämplig databas för begäran.The key parameter is used as a lookup key into the shard map to determine the appropriate database for the request.
  • ConnectionString används för att skicka endast användarautentiseringsuppgifter för önskad anslutning.The connectionString is used to pass only the user credentials for the desired connection. Inget databas namn eller server namn ingår i den här ConnectionString eftersom metoden bestämmer databasen och servern med hjälp av ShardMap.No database name or server name is included in this connectionString since the method determines the database and server using the ShardMap.
  • ConnectionOptions (Java, .net) måste anges till connectionOptions. kontrol lera om en miljö där Shard Maps kan ändras och rader kan flyttas till andra databaser som ett resultat av Split eller sammanslagnings åtgärder.The connectionOptions (Java, .NET) should be set to ConnectionOptions.Validate if an environment where shard maps may change and rows may move to other databases as a result of split or merge operations. Den här verifieringen innebär en kort fråga till den lokala Shard-kartan på mål databasen (inte till den globala Shard-mappningen) innan anslutningen skickas till programmet.This validation involves a brief query to the local shard map on the target database (not to the global shard map) before the connection is delivered to the application.

Om valideringen av den lokala Shard-kartan Miss lyckas (vilket indikerar att cacheminnet är felaktigt) frågar Shard Map Manager den globala Shard-mappningen för att hämta det nya korrekta värdet för sökningen, uppdaterar cachen och hämtar och returnerar lämplig databas anslutning.If the validation against the local shard map fails (indicating that the cache is incorrect), the Shard Map Manager queries the global shard map to obtain the new correct value for the lookup, update the cache, and obtain and return the appropriate database connection.

Använd connectionOptions. None när Shard mappnings ändringar inte förväntas när ett program är online.Use ConnectionOptions.None only when shard mapping changes are not expected while an application is online. I så fall kan de cachelagrade värdena alltid vara korrekta och det extra verifierings anropet för tur och retur till mål databasen kan hoppas över på ett säkert sätt.In that case, the cached values can be assumed to always be correct, and the extra round-trip validation call to the target database can be safely skipped. Detta minskar databas trafiken.That reduces database traffic. ConnectionOptions kan också ställas in via ett värde i en konfigurations fil för att indikera om horisontell partitionering-ändringar förväntas eller inte under en viss tids period.The connectionOptions may also be set via a value in a configuration file to indicate whether sharding changes are expected or not during a period of time.

I det här exemplet används värdet för en heltals nyckel som CustomerID med hjälp av ett ShardMap -objekt med namnet customerShardMap.This example uses the value of an integer key CustomerID, using a ShardMap object named customerShardMap.

int customerId = 12345;
int productId = 4321;
// Looks up the key in the shard map and opens a connection to the shard
try (Connection conn = shardMap.openConnectionForKey(customerId, Configuration.getCredentialsConnectionString())) {
    // Create a simple command that will insert or update the customer information
    PreparedStatement ps = conn.prepareStatement("UPDATE Sales.Customer SET PersonID = ? WHERE CustomerID = ?");

    ps.setInt(1, productId);
    ps.setInt(2, customerId);
    ps.executeUpdate();
} catch (SQLException e) {
    e.printStackTrace();
}
int customerId = 12345;
int newPersonId = 4321;

// Connect to the shard for that customer ID. No need to call a SqlConnection
// constructor followed by the Open method.
using (SqlConnection conn = customerShardMap.OpenConnectionForKey(customerId, Configuration.GetCredentialsConnectionString(), ConnectionOptions.Validate))
{
    // Execute a simple command.
    SqlCommand cmd = conn.CreateCommand();
    cmd.CommandText = @"UPDATE Sales.Customer
                        SET PersonID = @newPersonID WHERE CustomerID = @customerID";

    cmd.Parameters.AddWithValue("@customerID", customerId);cmd.Parameters.AddWithValue("@newPersonID", newPersonId);
    cmd.ExecuteNonQuery();
}  

Metoden OpenConnectionForKey returnerar en ny anslutning som redan är öppen till rätt databas.The OpenConnectionForKey method returns a new already-open connection to the correct database. Anslutningar som används på det här sättet kommer fortfarande att dra full nytta av anslutningspoolen.Connections utilized in this way still take full advantage of connection pooling.

OpenConnectionForKeyAsync-metoden (Java, .net) är också tillgänglig om programmet använder asynkron programmering.The OpenConnectionForKeyAsync method (Java, .NET) is also available if your application makes use asynchronous programming.

Integrera med tillfälligt fel hanteringIntegrating with transient fault handling

En bra idé att utveckla data åtkomst program i molnet är att se till att tillfälliga fel fångas av appen och att åtgärderna provas flera gånger innan ett fel utlöses.A best practice in developing data access applications in the cloud is to ensure that transient faults are caught by the app, and that the operations are retried several times before throwing an error. Tillfälligt fel hantering för moln program diskuteras vid hantering av tillfälliga fel (Java, .net).Transient fault handling for cloud applications is discussed at Transient Fault Handling (Java, .NET).

Hantering av tillfälliga fel kan fungera naturligt med mönster för Data-Dependent routning.Transient fault handling can coexist naturally with the Data-Dependent Routing pattern. Nyckel kravet är att försöka köra hela data åtkomst förfrågan på nytt, inklusive det använda block som hämtade den databaserade routningslänken.The key requirement is to retry the entire data access request including the using block that obtained the data-dependent routing connection. Föregående exempel kunde skrivas om på följande sätt.The preceding example could be rewritten as follows.

Exempel – data beroende routning med tillfälligt fel hanteringExample - data-dependent routing with transient fault handling

int customerId = 12345;
int productId = 4321;
try {
    SqlDatabaseUtils.getSqlRetryPolicy().executeAction(() -> {
        // Looks up the key in the shard map and opens a connection to the shard
        try (Connection conn = shardMap.openConnectionForKey(customerId, Configuration.getCredentialsConnectionString())) {
            // Create a simple command that will insert or update the customer information
            PreparedStatement ps = conn.prepareStatement("UPDATE Sales.Customer SET PersonID = ? WHERE CustomerID = ?");

            ps.setInt(1, productId);
            ps.setInt(2, customerId);
            ps.executeUpdate();
        } catch (SQLException e) {
            e.printStackTrace();
        }
    });
} catch (Exception e) {
    throw new StoreException(e.getMessage(), e);
}
int customerId = 12345;
int newPersonId = 4321;

Configuration.SqlRetryPolicy.ExecuteAction(() -> {

    // Connect to the shard for a customer ID.
    using (SqlConnection conn = customerShardMap.OpenConnectionForKey(customerId, Configuration.GetCredentialsConnectionString(), ConnectionOptions.Validate))
    {
        // Execute a simple command
        SqlCommand cmd = conn.CreateCommand();

        cmd.CommandText = @"UPDATE Sales.Customer
                            SET PersonID = @newPersonID
                            WHERE CustomerID = @customerID";

        cmd.Parameters.AddWithValue("@customerID", customerId);
        cmd.Parameters.AddWithValue("@newPersonID", newPersonId);
        cmd.ExecuteNonQuery();

        Console.WriteLine("Update completed");
    }
});

Paket som behövs för att implementera tillfälligt fel hantering hämtas automatiskt när du skapar ett exempel program för elastisk databas.Packages necessary to implement transient fault handling are downloaded automatically when you build the elastic database sample application.

Transaktionell konsekvensTransactional consistency

Transaktions egenskaper garanteras för alla åtgärder lokalt i en Shard.Transactional properties are guaranteed for all operations local to a shard. Till exempel körs transaktioner som skickas via data beroende routning inom omfånget för mål-Shard för anslutningen.For example, transactions submitted through data-dependent routing execute within the scope of the target shard for the connection. För närvarande finns det inga funktioner för att ange flera anslutningar i en transaktion, och därför finns det inga transaktions garantier för åtgärder som utförs i Shards.At this time, there are no capabilities provided for enlisting multiple connections into a transaction, and therefore there are no transactional guarantees for operations performed across shards.

Nästa stegNext steps

Om du vill koppla från en Shard, eller om du vill återansluta en Shard, se använda RecoveryManager-klassen för att åtgärda Shard mappnings problem.To detach a shard, or to reattach a shard, see Using the RecoveryManager class to fix shard map problems.

Ytterligare resurserAdditional resources

Använder du inte Elastic Database-verktyg ännu?Not using elastic database tools yet? Kolla i vår komma igång-guide.Check out our Getting Started Guide. För frågor kan du kontakta oss på sidan Microsoft Q&en fråga för SQL Database och för funktions förfrågningar kan du lägga till dem i SQL Database feedback-forumet.For questions, please reach out to us on the Microsoft Q&A question page for SQL Database and for feature requests, please add them to the SQL Database feedback forum.