vitess.io/vitess@v0.16.2/go/vt/vttablet/queryservice/queryservice.go (about)

     1  /*
     2  Copyright 2019 The Vitess Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  // Package queryservice contains the interface for the service definition
    18  // of the Query Service.
    19  package queryservice
    20  
    21  import (
    22  	topodatapb "vitess.io/vitess/go/vt/proto/topodata"
    23  
    24  	"context"
    25  
    26  	"vitess.io/vitess/go/sqltypes"
    27  
    28  	binlogdatapb "vitess.io/vitess/go/vt/proto/binlogdata"
    29  	querypb "vitess.io/vitess/go/vt/proto/query"
    30  )
    31  
    32  // QueryService is the interface implemented by the tablet's query service.
    33  // All streaming methods accept a callback function that will be called for
    34  // each response. If the callback returns an error, that error is returned
    35  // back by the function, except in the case of io.EOF in which case the stream
    36  // will be terminated with no error. Streams can also be terminated by canceling
    37  // the context.
    38  // This API is common for both server and client implementations. All functions
    39  // must be safe to be called concurrently.
    40  type QueryService interface {
    41  	// Transaction management
    42  
    43  	// Begin returns the transaction id to use for further operations
    44  	Begin(ctx context.Context, target *querypb.Target, options *querypb.ExecuteOptions) (TransactionState, error)
    45  
    46  	// Commit commits the current transaction
    47  	Commit(ctx context.Context, target *querypb.Target, transactionID int64) (int64, error)
    48  
    49  	// Rollback aborts the current transaction
    50  	Rollback(ctx context.Context, target *querypb.Target, transactionID int64) (int64, error)
    51  
    52  	// Prepare prepares the specified transaction.
    53  	Prepare(ctx context.Context, target *querypb.Target, transactionID int64, dtid string) (err error)
    54  
    55  	// CommitPrepared commits the prepared transaction.
    56  	CommitPrepared(ctx context.Context, target *querypb.Target, dtid string) (err error)
    57  
    58  	// RollbackPrepared rolls back the prepared transaction.
    59  	RollbackPrepared(ctx context.Context, target *querypb.Target, dtid string, originalID int64) (err error)
    60  
    61  	// CreateTransaction creates the metadata for a 2PC transaction.
    62  	CreateTransaction(ctx context.Context, target *querypb.Target, dtid string, participants []*querypb.Target) (err error)
    63  
    64  	// StartCommit atomically commits the transaction along with the
    65  	// decision to commit the associated 2pc transaction.
    66  	StartCommit(ctx context.Context, target *querypb.Target, transactionID int64, dtid string) (err error)
    67  
    68  	// SetRollback transitions the 2pc transaction to the Rollback state.
    69  	// If a transaction id is provided, that transaction is also rolled back.
    70  	SetRollback(ctx context.Context, target *querypb.Target, dtid string, transactionID int64) (err error)
    71  
    72  	// ConcludeTransaction deletes the 2pc transaction metadata
    73  	// essentially resolving it.
    74  	ConcludeTransaction(ctx context.Context, target *querypb.Target, dtid string) (err error)
    75  
    76  	// ReadTransaction returns the metadata for the specified dtid.
    77  	ReadTransaction(ctx context.Context, target *querypb.Target, dtid string) (metadata *querypb.TransactionMetadata, err error)
    78  
    79  	// Execute for query execution
    80  	Execute(ctx context.Context, target *querypb.Target, sql string, bindVariables map[string]*querypb.BindVariable, transactionID, reservedID int64, options *querypb.ExecuteOptions) (*sqltypes.Result, error)
    81  	// StreamExecute for query execution with streaming
    82  	StreamExecute(ctx context.Context, target *querypb.Target, sql string, bindVariables map[string]*querypb.BindVariable, transactionID int64, reservedID int64, options *querypb.ExecuteOptions, callback func(*sqltypes.Result) error) error
    83  
    84  	// Combo methods, they also return the transactionID from the
    85  	// Begin part. If err != nil, the transactionID may still be
    86  	// non-zero, and needs to be propagated back (like for a DB
    87  	// Integrity Error)
    88  	BeginExecute(ctx context.Context, target *querypb.Target, preQueries []string, sql string, bindVariables map[string]*querypb.BindVariable, reservedID int64, options *querypb.ExecuteOptions) (TransactionState, *sqltypes.Result, error)
    89  	BeginStreamExecute(ctx context.Context, target *querypb.Target, preQueries []string, sql string, bindVariables map[string]*querypb.BindVariable, reservedID int64, options *querypb.ExecuteOptions, callback func(*sqltypes.Result) error) (TransactionState, error)
    90  
    91  	// Messaging methods.
    92  	MessageStream(ctx context.Context, target *querypb.Target, name string, callback func(*sqltypes.Result) error) error
    93  	MessageAck(ctx context.Context, target *querypb.Target, name string, ids []*querypb.Value) (count int64, err error)
    94  
    95  	// VStream streams VReplication events based on the specified filter.
    96  	VStream(ctx context.Context, request *binlogdatapb.VStreamRequest, send func([]*binlogdatapb.VEvent) error) error
    97  
    98  	// VStreamRows streams rows of a table from the specified starting point.
    99  	VStreamRows(ctx context.Context, request *binlogdatapb.VStreamRowsRequest, send func(*binlogdatapb.VStreamRowsResponse) error) error
   100  
   101  	// VStreamResults streams results along with the gtid of the snapshot.
   102  	VStreamResults(ctx context.Context, target *querypb.Target, query string, send func(*binlogdatapb.VStreamResultsResponse) error) error
   103  
   104  	// StreamHealth streams health status.
   105  	StreamHealth(ctx context.Context, callback func(*querypb.StreamHealthResponse) error) error
   106  
   107  	// HandlePanic will be called if any of the functions panic.
   108  	HandlePanic(err *error)
   109  
   110  	ReserveBeginExecute(ctx context.Context, target *querypb.Target, preQueries []string, postBeginQueries []string, sql string, bindVariables map[string]*querypb.BindVariable, options *querypb.ExecuteOptions) (ReservedTransactionState, *sqltypes.Result, error)
   111  
   112  	ReserveBeginStreamExecute(ctx context.Context, target *querypb.Target, preQueries []string, postBeginQueries []string, sql string, bindVariables map[string]*querypb.BindVariable, options *querypb.ExecuteOptions, callback func(*sqltypes.Result) error) (ReservedTransactionState, error)
   113  
   114  	ReserveExecute(ctx context.Context, target *querypb.Target, preQueries []string, sql string, bindVariables map[string]*querypb.BindVariable, transactionID int64, options *querypb.ExecuteOptions) (ReservedState, *sqltypes.Result, error)
   115  
   116  	ReserveStreamExecute(ctx context.Context, target *querypb.Target, preQueries []string, sql string, bindVariables map[string]*querypb.BindVariable, transactionID int64, options *querypb.ExecuteOptions, callback func(*sqltypes.Result) error) (ReservedState, error)
   117  
   118  	Release(ctx context.Context, target *querypb.Target, transactionID, reservedID int64) error
   119  
   120  	// GetSchema returns the table definition for the specified tables.
   121  	GetSchema(ctx context.Context, target *querypb.Target, tableType querypb.SchemaTableType, tableNames []string, callback func(schemaRes *querypb.GetSchemaResponse) error) error
   122  
   123  	// Close must be called for releasing resources.
   124  	Close(ctx context.Context) error
   125  }
   126  
   127  type TransactionState struct {
   128  	TransactionID       int64
   129  	TabletAlias         *topodatapb.TabletAlias
   130  	SessionStateChanges string
   131  }
   132  
   133  type ReservedState struct {
   134  	ReservedID  int64
   135  	TabletAlias *topodatapb.TabletAlias
   136  }
   137  
   138  type ReservedTransactionState struct {
   139  	ReservedID          int64
   140  	TransactionID       int64
   141  	TabletAlias         *topodatapb.TabletAlias
   142  	SessionStateChanges string
   143  }