vitess.io/vitess@v0.16.2/doc/design-docs/APIScope.md (about)

     1  # API Scope
     2  
     3  This document describes the scope of the Vitess APIs, and how they map to
     4  traditional concepts like database and tables.
     5  
     6  ## Introduction
     7  
     8  Vitess is exposed as a single database by clients, but can be composed of any
     9  arbitrary number of databases, some of them possibly sharded with large numbers
    10  of shards. It is not obvious to map this system with clients that expect only a
    11  single database.
    12  
    13  ## Shard Names and Key Ranges
    14  
    15  For unsharded keyspaces, or custom sharded keyspaces, the shard names have
    16  traditionally been numbers e.g. `0`. (It is important to note that Vitess *does
    17  not* interpret these shard names, including name `0`, as range-based shard.)
    18  
    19  For keyspaces that are sharded by keyrange, we use the range as the shard
    20  name. For instance `40-80` contains all records whose sharding key is between
    21  0x40..... and 0x80....
    22  
    23  The conventions Vitess follow is:
    24  
    25  * if a single shard should be targeted, the shard name should be used. This
    26    allows single-shard keyspaces and custom sharded keyspaces to be accessed.
    27  
    28  * if a subset of the data should be targeted, and we are using ranged-based
    29    sharding, then a key range should be used. Vitess is then responsible for
    30    mapping the keyrange to a list of shards, and for any aggregation.
    31  
    32  ## Execute API
    33  
    34  The main entry point of a Vitess cluster is the `Execute` call (or StreamExecute
    35  for streaming queries). It takes a keyspace, a tablet type, and a query. The
    36  VSchema helps Vitess route the query to the right shard and tablet type. This is
    37  the most transparent way of accessing Vitess. Keyspace is the database, and
    38  inside the query, a table is referenced either just by name, or by
    39  `keyspace.name`.
    40  
    41  We are adding a `shard` parameter to this entry point. It will work as follows:
    42  
    43  * TODO(sougou) document this.
    44  
    45  We want to add support for DBA statements:
    46  
    47  * DDL statements in the short term will be sent to all shards of a
    48    keyspace. Note for complex schema changes, using Schema Swap is recommended.
    49    Longer term, we want to instead trigger a workflow that will use the best
    50    strategy for the schema change.
    51  
    52  * Read-only statements (like `describe table`) will be sent to the first shard
    53    of the keyspace. This somewhat assumes the schema is consistent across all
    54    shards, which may or may not be true. Guaranteeing schema consistency across
    55    shards is however out of scope for this.
    56  
    57  * Read-only statements that return table statistics (like data size, number of
    58    rows, ...) will need to be scattered and aggregated across all shards. The
    59    first version of the API won't support this.
    60  
    61  We also want to add support for routing sequence queries through this Execute
    62  query (right now only the VSchema engine can use a sequence).
    63  
    64  Then, we also want to support changing the VSchema via SQL-like statements, like
    65  `ALTER TABLE ADD VINDEX()`.
    66  
    67  ## Client Connectors
    68  
    69  Client connectors (like JDBC) usually have a connection string that describes
    70  the connection. It usually includes the keyspace and the tablet type, and uses
    71  the Execute API.
    72  
    73  ## MySQL Server Protocol API
    74  
    75  vtgate now exposes an API endpoint that implements the regular MySQL server
    76  protocol. All calls are forwarded to the Execute API. The database provided on
    77  the connection is used as the keyspace, if any. The tablet type used is PRIMARY/MASTER.
    78  
    79  ## Update Stream and Message Stream
    80  
    81  These APIs are meant to target a keyspace and optionally a subset of its shards.
    82  
    83  * The keyspace is provided in the API.
    84  
    85  * To specify the shard, two options are provided:
    86  
    87    * a shard name, to target an individual shard by name.
    88    
    89    * a key range, to target a subset of shards in a way that will survive a
    90      resharding event.
    91  
    92  Note the current implementation for these services only supports a key range
    93  that exactly maps to one shard. We want to make that better and support
    94  aggregating multiple shards in a keyrange.