main/proto/live_sql_protocol.proto

/*
 * Copyright 2019 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";

package androidx.sqlite.inspection;

option java_package = "androidx.sqlite.inspection";
option java_outer_classname = "SqliteInspectorProtocol";

// --- Commands ---

// Generic Command object grouping all Inspector Command types. Expected in
// Inspector's onReceiveCommand.
message Command {
  // Wrapped specialised Command.
  oneof OneOf {
    TrackDatabasesCommand track_databases = 1;
    GetSchemaCommand get_schema = 2;
    QueryCommand query = 3;
    KeepDatabasesOpenCommand keep_databases_open = 4;
    AcquireDatabaseLockCommand acquire_database_lock = 5;
    ReleaseDatabaseLockCommand release_database_lock = 6;
  }
}

// Request for the Inspector to track database connections (existing and new)
// and notify of those via DatabaseOpenedEvent objects.
message TrackDatabasesCommand {}

// Request for the Inspector to return schema information for a given database.
message GetSchemaCommand {
  // Id uniquely identifying a connection to the database.
  int32 database_id = 1;
}

// Request for the Inspector to execute a query and return its results.
// TODO: add support for parameterised queries
message QueryCommand {
  // Id uniquely identifying a connection to the database.
  int32 database_id = 1;
  // Query to execute.
  string query = 2;
  // The query may include ?s, which will be replaced by values from
  // query_parameters, in the order that they appear in the query. Values will
  // be bound as Strings.
  repeated QueryParameterValue query_parameter_values = 3;
  // Approximate response size limit in bytes.
  // Best effort:
  // - can deviate from the value up to 40% due to encoding overheads
  // - in some cases can deviate by an extra ~2MB (max size of one row in Android SQLite)
  // When unset, or set to <= `0`, it is considered unbounded.
  int64 response_size_limit_hint = 4;
}

// Value of a parameter in QueryCommand. Currently only string and null values
// are supported.
message QueryParameterValue {
  oneof OneOf {
    string string_value = 1;
  }
}

// Request to prevent databases from being closed by the app
// (allowing for a larger time-window for inspection)
message KeepDatabasesOpenCommand {
  // True to enable the functionality; false to disable
  bool set_enabled = 1;
}

// Request to lock a database to prevent modifications on it
// (allowing for e.g. creating a consistent snapshot)
message AcquireDatabaseLockCommand {
  // Database to secure a lock on
  int32 database_id = 1;
}

// Request to release a previously acquired database lock (see AcquireDatabaseLockCommand)
message ReleaseDatabaseLockCommand {
  // Id of the lock to release (see AcquireDatabaseLockResponse)
  int32 lock_id = 1;
}

// --- Responses ---

// Generic Response object grouping all Inspector Response types to Command
// objects.
message Response {
  // Wrapped specialised Response.
  oneof OneOf {
    TrackDatabasesResponse track_databases = 1;
    GetSchemaResponse get_schema = 2;
    QueryResponse query = 3;
    KeepDatabasesOpenResponse keep_databases_open = 4;
    AcquireDatabaseLockResponse acquire_database_lock = 5;
    ReleaseDatabaseLockResponse release_database_lock = 6;
    ErrorOccurredResponse error_occurred = 400;
  }
}

// Object expected as a response to TrackDatabasesCommand.
message TrackDatabasesResponse {}

// Object expected as a response to GetSchemaCommand.
message GetSchemaResponse {
  repeated Table tables = 1;
}

// Schema information for a table or a view.
message Table {
  string name = 1;
  // True for a view; false for a regular table.
  bool is_view = 2;
  repeated Column columns = 3;
}

// Schema information for a table column.
message Column {
  string name = 1;
  // Column type affinity.
  string type = 2;
  // PRIMARY KEY constraint: zero for columns that are not part of the primary
  // key, or the index of the column in the primary key for columns that are
  // part of the primary key.
  int32 primary_key = 3;
  // NOT NULL constraint.
  bool is_not_null = 4;
  // UNIQUE constraint on its own (i.e. not as a part of
  // compound-unique-constraint-index).
  bool is_unique = 5;
}

// Object expected as a response to QueryCommand.
message QueryResponse {
  repeated Row rows = 1;
  // Names of columns in the result set
  repeated string column_names = 2;
}

// Query result row.
message Row {
  repeated CellValue values = 1;
}

// Query result cell.
message CellValue {
  // Resulting cell value depending on type affinity rules.
  oneof OneOf {
    double double_value = 1;
    int64 long_value = 2;
    string string_value = 3;
    bytes blob_value = 4;
  }
}

message KeepDatabasesOpenResponse {}

// Object expected as a response to AcquireDatabaseLockCommand.
message AcquireDatabaseLockResponse {
  // Id of the lock (allowing for releasing the lock later using ReleaseDatabaseLockRequest)
  int32 lock_id = 1;
}

// Object expected as a response to ReleaseDatabaseLockCommand.
message ReleaseDatabaseLockResponse {}

// General Error message.
// TODO: decide on a more fine-grained approach
message ErrorOccurredResponse {
  ErrorContent content = 1;
}

message ErrorContent {
  // Main error message.
  string message = 1;
  // Optional stack trace.
  string stack_trace = 2;
  // Recoverability information
  ErrorRecoverability recoverability = 3;
  // Error code
  enum ErrorCode {
    NOT_SET = 0;
    ERROR_UNKNOWN = 10;
    ERROR_UNRECOGNISED_COMMAND = 20;
    ERROR_DATABASE_VERSION_TOO_OLD = 30;
    ERROR_ISSUE_WITH_PROCESSING_QUERY = 40;
    ERROR_NO_OPEN_DATABASE_WITH_REQUESTED_ID = 50;
    ERROR_ISSUE_WITH_PROCESSING_NEW_DATABASE_CONNECTION = 60;
    ERROR_DB_CLOSED_DURING_OPERATION = 70;
    ERROR_ISSUE_WITH_LOCKING_DATABASE = 80;
  }
  ErrorCode error_code = 4;
}

// Recoverability of an error:
// - is_recoverable = true -> an error is recoverable (e.g. query syntax error)
// - is_recoverable = false -> an error is not recoverable (e.g. corrupt internal inspector state)
// - unset -> not enough information to determine recoverability (e.g. an issue that may or may not
//   prevent a user from continuing the session - and is left for the user to decide how to act on)
message ErrorRecoverability {
  oneof OneOf {
    bool is_recoverable = 1;
  }
}

// --- Events ---

// Generic Event object grouping all Inspector Event types. Expected in
// Connection's sendEvent method.
message Event {
  // Wrapped specialised Event.
  oneof OneOf {
    DatabaseOpenedEvent database_opened = 1;
    DatabaseClosedEvent database_closed = 2;
    DatabasePossiblyChangedEvent database_possibly_changed = 3;
    ErrorOccurredEvent error_occurred = 400;
  }
}

// Notification of a database connection established (new) / discovered
// (existing).
message DatabaseOpenedEvent {
  // Id uniquely identifying a connection to a database. Required to perform
  // requests on the database.
  int32 database_id = 1;
  // Path to db file or ":memory" if it is in-memory database.
  // Note: there is no guarantee that it is necessarily unique between databases.
  string path = 2;
}

// Notification of a database connection closed (database no longer query-able)
// TODO: consider consolidating with DatabaseOpenedEvent
message DatabaseClosedEvent {
  // Id uniquely identifying a connection to a database. Required to perform
  // requests on the database.
  int32 database_id = 1;
  // Path to db file or ":memory" if it is in-memory database.
  // Note: there is no guarantee that it is necessarily unique between databases.
  string path = 2;
}

// An event sent when an operation that could potentially change the contents of a database has
// been detected. The event might be used in triggering a refresh of currently displayed query
// results to keep the results current.
message DatabasePossiblyChangedEvent {
    // TODO: add database id
}

// General Error message.
// TODO: decide on a more fine-grained approach
message ErrorOccurredEvent {
  ErrorContent content = 1;
}