SqliteDatabaseAPI

Top

The Sqlite Database API exposes functions that enable clients to manipulate data in a given Volt database.

Use the Sqlite Server API to create the database resource.

BulkUpdate()

Execute multiple SQL statements in a single transaction via a single RPC.

Request: SqlBulkUpdateRequest
Response: SqlBulkUpdateResponse

Execute()

Execute a single SQL statement. Any valid SQL is accepted. In order to execute non-SELECT statements, the caller must have the "write" permission.

Request: streaming SqlExecuteRequest
Response: streaming SqlExecuteResponse

ImportCSV()

Import CSV data into a table.

The import handler will inspect the incoming CSV data, infer the columns and data types required, and create and populate the SQL table.

The CSV must contain a header row containing the column names and at least one row of data so that the types can be inferred.

The importer assumes all data in any given CSV file relates to a single table.

The data can either be streamed in chunks or retrieved from an existing resource.

If the data is streamed in chunks, the client must call the Close() method on the stream to indicate that it has finished.

Request: streaming SqlImportCSVRequest
Response: streaming SqlImportCSVResponse

SqlBulkUpdateRequest

FieldTypeDescription
database_idstring

The id of the database to update.

statementstring repeated

The SQL statements to execute. The statements will be executed within a transaction and will be committed if all statements succeed.

Bear in mind the maximum size limit of a single message is 64MB, and around 1MB seems to be optimal in terms of performance.

SqlBulkUpdateResponse

FieldTypeDescription
statustdx.volt_api.volt.v1.Status

Details of any error that occurred on the call.

SqlExecuteEnd

Ends the call.

FieldTypeDescription
commit_transactionbool

Set to commit the transaction. If not set, the transaction will be rolled back.

SqlExecuteNext

Intentionally empty.

SqlExecuteRequest

FieldTypeDescription
startSqlExecuteStart

Initialise the request with the database id and whether to execute within a transaction.

Also includes the SQL statement to execute.

nextSqlExecuteNext

To retrieve subsequent pages, send a `next` request.

endSqlExecuteEnd

To end the call, send an `end` request. Only really necessary for transaction-based calls, otherwise clients can just close the stream.

SqlExecuteResponse

One of the following fields will be present in any given message.

FieldTypeDescription
statustdx.volt_api.volt.v1.Status

A status will be sent on error.

headerRowHeader

The initial response for SELECT statements will be a header containing the column names and types.

rowVariantRow

Each row in the result set will be sent as a VariantRow.

affected_rowsuint32

NYI - For INSERT/UPDATE statements the number of affected rows will be sent.

SqlExecuteStart

FieldTypeDescription
database_idstring

The id of the database to execute on.

transactionbool

Set to start a transaction. If not set, each statement will be executed in its own transaction.

statementstring

The SQL statement to execute.

page_sizeuint32

This can be used to limit the number of rows returned by `SELECT` statements to avoid overloading a client. It is similar to using 'LIMIT/OFFSET' clauses on the 'SELECT' statement, but this method is easier to manage and the entire result set will be prepared on the Volt, and the client can then page through it by sending successive messages.

can_cancelbool

Set to indicate that the query will be cancelled if the client disconnects.

This is useful for long running queries, where it might be desirable for the client to be able to cancel the request before all the data is received. However this requires a worker thread to be allocated to the query until it completes, which may affect performance and limit the number of concurrent queries that can be executed due to file handle limitations.

Only applicable to `SELECT` statements, ignored otherwise.

parameterSqlExecuteStart.ParameterEntry repeated

The values to set for each parameter defined in a database view.

This field is only relevant to 'query' databases, i.e. those with kind `tdx:sqlite-view`.

The values in the map should be keyed by parameter name.

A query may have no parameters defined, in which case leave this field empty.

SqlExecuteStart.ParameterEntry

FieldTypeDescription
keystring

valuetdx.volt_api.volt.v1.AttributeValue

SqlImportCSVConfiguration

FieldTypeDescription
database_idstring

The target database resource id, which must already exist, and the authenticated account must have write access to the resource.

table_namestring

The target table name.

create_tablebool

Not yet implemented - flag indicating that data is to be inserted into an existing table.

source_resource_idstring

Optional - when not sending the data via this RPC, this should contain the id of a resource that contains the CSV data. If set, the authenticated account must have read access to the resource.

progress_intervaluint32

Optional - the interval to receive progress updates, in number of rows. E.g. set to 1000 to receive progress updates every 1000 rows. Set to 0 to disable progress updates.

schema_scan_limituint32

The number of rows scanned to infer the schema. Set to 0 to scan the entire file.

SqlImportCSVRequest

Each message must contain one and only one of the following fields.

FieldTypeDescription
configurationSqlImportCSVConfiguration

The initial request must contain the configuration parameters for the import.

upload_completebool

Set to indicate that the upload is complete.

blockbytes

Subsequent requests may contain the data to be imported, unless importing from an existing resource that contains the CSV data. It is recommended that the block size is less than 1MB.

abortbool

Set to abort the import.

SqlImportCSVResponse

FieldTypeDescription
statustdx.volt_api.volt.v1.Status

The status will contain any error info.

row_countint64

The number of rows processed - this will be sent after every `progress_interval` rows.

total_rowsint64

The total number of rows to be imported.

Status

FieldTypeDescription
codeint32

A simple error code that can be easily handled by the client.

Mirrors the grpc StatusCode enum, 0 => OK

messagestring

A developer-facing human-readable error message in English. It should both explain the error and offer an actionable resolution to it.

descriptionstring

Long form error description.

Column

FieldTypeDescription
namestring

descriptionstring

typeDataType

RowHeader

FieldTypeDescription
columnColumn repeated

Schema

FieldTypeDescription
namestring

descriptionstring

columnColumn repeated

Variant

FieldTypeDescription
textstring

integerint64

realdouble

blobbytes

nullbool

VariantRow

FieldTypeDescription
columnVariant repeated

DataType

Just reflect SQLite types for now.

NameNumberDescription
DATA_TYPE_UNKNOWN0

DATA_TYPE_TEXT1

DATA_TYPE_INTEGER2

DATA_TYPE_REAL3

DATA_TYPE_BLOB4

DATA_TYPE_NULL5

Access

FieldTypeDescription
idstring

resource_idstring

The resource being accessed.

resource_namestring

A human-readable short identifier of the resource.

resource_ownerstring

The identity that owns the resource.

resource_kindstring repeated

The kind of resource.

identity_didstring

The identity attempting access.

credential_lookupstring

The JSON path array for looking up verifiable credentials.

identity_namestring

A human-readable short identifier of the subject.

identity_kindstring repeated

The kind of identity.

issuer_idstring

issuer_namestring

issuer_kindstring repeated

accessstring

Requested access.

decisionPolicyDecision

Assigned decision.

recursivebool

request_timeint64

Time at which the request was made.

decision_timeint64

Time at which the decision was taken.

request_countuint32

Counter of number times this access was requested.

AttributeValue

Attribute value will be one of the following fields, depending on the data type.

FieldTypeDescription
stringstring

integerint64

realdouble

booleanbool

bytesbytes

Identity

A Volt identity encompasses a Resource and a set of identity aliases.

FieldTypeDescription
resourceResource

aliasIdentityAlias repeated

IdentityAlias

FieldTypeDescription
iduint32

The alias id.

identity_didstring

The corresponding identity id.

aliasstring

The actual alias, e.g. a common name or key fingerprint.

public_keystring

This will only be populated if alias_type == tdx:public-key

private_keystring

This will only be populated if alias_type == tdx:public-key, and the key is stored in the Volt.

alias_typestring

The alias type, for example public key, email, phone number etc.

issuer_idstring

The identity that issued this alias.

authenticatePolicyDecision

Indicates if this alias has an authenticate policy decision assigned.

descriptionstring

Optional description of this alias.

MethodDescription

Internal use only.

FieldTypeDescription
pathstring

client_streamingbool

server_streamingbool

ProtoFile

Describes a single protobuf file for use in ServiceDescription.

FieldTypeDescription
file_pathstring

The path name of the proto file, relative to the 'root' of the namespace, e.g. "tdx/volt_api/volt/v1/volt.proto".

protobufstring

The actual protobuf file contents.

service_namestring repeated

Optional - the service(s) contained in this protobuf file, if omitted here they will be loaded dynamically from the protobuf.

ProxyConnection

Represents an outbound connection from a Volt to a remote service that will act as a proxy for that Volt.

This enables Volts to bypass firewall and NATs.

Example - connection from a Volt to a Relay Volt running on the public internet, such as tdxvolt.com

FieldTypeDescription
idstring

Unique connection id.

namestring

A human-readable name for the connection.

addressstring

The remote address of the proxy service.

ca_pemstring

The certificate authority of the proxy service.

enabledbool

Indicates this connection is enabled.

connectedbool

Indicates this connection is currently in use.

enable_http_proxybool

Indicates that this connection will handle HTTP proxying as well as GRPC.

disable_volt_apibool

Set to indicate the Volt API itself is not automatically exposed to the connection.

challengestring

Optional challenge that can be presented in the authentication request.

target_idstring

The id of the target Volt that this connection is bound to.

sync_did_registrybool

Indicates that this connection hosts a DID registry that we should synchronise with.

did_registry_sync_iduint64

The id of the last DID registry operation that was synchronised.

sync_vc_registrybool

Indicates that this connection hosts a DID registry that we should synchronise with.

vc_registry_sync_timestampuint64

The timestamp of the last VC registry operation that was synchronised.

session_idstring

certificatestring

Resource

The core Resource metadata schema.

FieldTypeDescription
idstring

The globally unique resource id.

descriptionstring

Optional description.

namestring

Human-readable resource name.

share_modeShareMode

Not in use.

volt_idstring

The id of the Volt that hosts this resource.

service_descriptionServiceDescription

Optional description of any services exposed by this resource.

attributeResourceAttribute repeated

Attributes assigned to the resource.

platform_versionVersion

The version of the platform.

versionuint64

The resource version.

ownerstring

The identity of the resource owner.

createduint64

Creation timestamp, milliseconds since epoch.

modifieduint64

Last modification timestamp, milliseconds since epoch.

statusResourceStatus

Not in use.

kindstring repeated

The taxonomy of the resource.

online_statusOnlineStatus

The online status.

For most kinds of resource this indicates that the server hosting the resource is online, the exception being identity resources, in which case the status reflects whether or not the identity has a live connection.

All built-in resources are hosted by the Volt itself and are therefore always online when the Volt is running.

Resources hosted by external servers are online if the server itself is online and has registered the resource as online using `setServiceStatus`.

sizeuint64

The size of the resource store in bytes.

storestring

The path to the resource store.

aliasstring repeated

Alias(es) that can be used to refer to the resource rather than the id.

Each alias must be unique to the Volt, this is enforced by the API.

No format restrictions are currently applied to alias, but this may change in future, for the time being it makes sense to stick to alphanumeric characters and '_' or '-'.

content_hashstring

The hash of the resource content contained in the store.

childResource repeated

Not yet supported.

ResourceAttribute

A resource attribute enables storing arbitrary data associated with a resource.

FieldTypeDescription
iduint32

attribute_idstring

resource_idstring

data_typeAttributeDataType

valueAttributeValue repeated

ServiceDescription

Describes a Volt service.

FieldTypeDescription
host_typeServiceHostType

The configuration used by the host of this service.

host_client_idstring

The identity of the client that is exposing the service.

For example, if a third party is exposing a database service via a Volt, it will first authenticate and obtain a client DID and credentials in order to be able to create service resource(s).

Any resources that are owned by this client will be marked as online if the client itself is online, i.e. has a live connection to the Volt.

This will be empty if the service is a built-in Volt service.

host_service_idstring

The id of the resource that holds the protobuf definition for this resource.

For example, if a third party is exposing a database service via a Volt, it will create a service resource that holds details of the protobuf methods exposed by the service.

For built-in services, i.e. those hosted by the Volt, this will set to the Volt id.

host_addressstring

The address of the grpc server hosting this service.

Only relevant to grpc-hosted services.

host_ca_pemstring

The certificate authority (chain) that signed the service server certificate.

This is only relevant to grpc-hosted services.

host_public_keystring

The public key of the service host, which is used to encrypt payloads.

This may change as the service comes and goes online.

host_connection_idstring

The connection id currently used to host this service.

host_session_idstring

Internal use only.

discoverableDiscoveryMode

The discovery mode.

ping_timestampint64

The ping timestamp of the server hosting this service.

proto_fileProtoFile repeated

The protobuf definitions of the APIs exposed by this service.

service_apistring repeated

The fully qualified names of the protobuf services, for example tdx.volt_api.webcam.v1.WebcamControlAPI.

methodMethodDescription repeated

Internal use only.

Session

FieldTypeDescription
idstring

identity_didstring

identity_namestring

ipstring

createduint64

modifieduint64

expiresuint64

credentialSessionCredential repeated

originstring

statusSessionStatus

SessionCredential

FieldTypeDescription
iduint32

The alias id.

session_idstring

The corresponding session id.

credential_typestring

The credential type, for example public key, verifiable credential, challenge etc.

descriptionstring

Optional description of this credential.

vc_idstring

The id of the verifiable credential, if the credential type is volt:vc-claim.

vc_jsonstring

The verifiable credential in JSON format, if the credential type is volt:vc-claim.

vc_subject_idstring

The subject id extracted from the `vc_json` field.

vc_issuer_idstring

The issuer id extracted from the `vc_json` field.

vc_typestring

The comma-separated type(s) extracted from the `vc_json` field.

challengestring

The challenge string, if the credential type is volt:challenge.

key_fingerprintstring

The key fingerprint, if the credential type is volt:public-key.

public_keystring

The PEM-encoded public key, if the credential type is volt:public-key.

private_keystring

Optional PEM-encoded private key, if the credential type is volt:public-key. Only used for ephemeral REST-base sessions created dynamically after OTP authentication.

extrastring

Type-specific extra data stored with the credential.

extra_2string

More type-specific data stored with the credential.

Version

Using `major` and `minor` here upsets the GNU C Library, so we add a `version_` prefix.

FieldTypeDescription
version_majoruint32

version_minoruint32

version_patchuint32

VoltEndpoint

FieldTypeDescription
idstring

The globally unique Volt id.

display_namestring

Human-readable name of the Volt.

local_addressstring

The actual host/ip the volt is physically running on (might be a local ip if behind firewall).

http_addressstring

The address of the endpoint HTTP server.

relay_addressstring

The global (Relay) address of the volt. Any given volt may be advertising on more than one Relay instance. The value given here will depend on the Relay instance that handled the endpoint query response.

relay_ca_pemstring

The root certificate of the Relay instance referred to in `relay_address`.

ca_pemstring

The self-signed certificate used by the volt to sign client certificates.

public_keystring

The Volt public key in PEM format.

fingerprintstring

The base58 fingerprint of the Volt public key.

online_statusOnlineStatus

The online status of the Volt.

has_relaybool

Set to indicate that this Volt acts as a Relay.

api_versionVersion

descriptionstring

VoltParameters

Encapsulates the various Volt parameters that are configurable by the Volt owner.

FieldTypeDescription
idstring

namestring

The name of the Volt.

descriptionstring

Human-readable description of the Volt.

db_driverstring

The database driver in use.

locationstring

The local file path location of the Volt storage.

key_strategystring

The key strategy in use, this determines how the root key is stored.

key_idstring

The identifier for the key, the semantics depend on the key strategy in use.

ca_pemstring

The Volt certificate authority.

cert_pemstring

The Volt API server certificate.

fixed_hoststring

Optional hostname of the Volt if using DNS or a static IP address, e.g. tdxvolt.com

grpc_portint32

Port to use for hosting the Volt management service.

http_portint32

Port to use for hosting the Volt grpc service.

http_key_pathstring

The Volt http server key file path.

http_cert_pathstring

The Volt http server certificate file path.

http_ca_pathstring

The Volt http server certificate authority chain file path.

discoverablebool

Indicates the Volt will be discoverable by clients using the discovery api.

authenticate_challengestring

Optional challenge code that can be used aid in the process of authenticating clients.

require_authenticate_challengebool

Indicates that clients must present the correct challenge code in order to be able to authenticate.

confirm_stopbool

Internal use only.

auto_startbool

Internal use only.

enable_messagingbool

Internal use only.

has_relaybool

Set to indicate this Volt acts as a Relay.

This means this Volt can act as a proxy for other Volts (or in fact any client) that connect to it.

relay_openbool

Set to run the Relay open to any client, i.e. clients can utilise the Relay without first authenticating.

enable_http_serverbool

Determines if the Volt HTTP server is enabled.

http_server_securebool

Determines whether the HTTP server employs TLS.

enable_http_forwardingbool

Determines whether the HTTP server supports forwarding.

enable_http_apibool

Determines if the Volt REST API is exposed via the HTTP server.

enable_websocket_apibool

Determines if the Volt Websocket API is exposed via the HTTP server.

addressstring

The hostname:port at which the Volt API is currently running.

encrypt_file_storebool

Set to indicate the Volt file store is encrypted.

connection_idstring

This is a unique connection id.

Indicates that these parameters refer to a connection to a remote Volt rather than a local Volt.

relay_ca_pemstring

The certificate authority of the Relay if this is a remote connection via a Relay.

http_address_overridestring

Optional override of the http address, rather than using the default of fixed_host:http_port.

This is useful if the Volt is behind a firewall or NAT, and the http server is listening on a different port

from 80 or 443 but this is hidden by the proxy. For example, if the `fixed_host` is `coreid.com` and http server is

listening on 2115, but the proxy is forwarding 443 to 2115, then the http_address_override would be set to

`https://coreid.com`.

aliasstring

An optional alias that can be used to refer to the Volt rather than the `id` field.

This alias must be unique within the scope of the Battery in which the Volt is stored.

versionVersion

The runtime version this Volt is running.

approve_on_challengebool

If set, indicates that any client that provides the correct challenge during authentication will automatically be approved to access the Volt.

approve_on_didbool

If set, indicates that any client that proves ownership of a DID known to the Volt will automatically be approved to access the Volt.

enable_did_registrybool

If set, indicates that clients can register DIDs with this Volt.

did_registrystring repeated

Zero or more URLs of trusted peer DID registries.

enable_outbound_smtpbool

If set, enables outbound SMTP.

outbound_smtp_hoststring

The SMTP host to use for sending emails.

outbound_smtp_portuint32

The SMTP port to use for sending emails.

outbound_smtp_userstring

The SMTP username to use for sending emails.

outbound_smtp_passwordstring

The SMTP password to use for sending emails.

enable_anonymous_createbool

If set, enables sessions that authenticate using credentials rather than a DID to create resources in the 'anonymous' system folder.

catch_all_auth_decisionPolicyDecision

The decision to apply to all authentication requests that do not match any other policy.

The default is PROMPT.

enable_policy_cachebool

If set, enables caching of policy decisions.

enable_terminalbool

If set, enables the terminal API.

AttributeDataType

Attribute data types.

NameNumberDescription
ATTRIBUTE_DATA_TYPE_UNKNOWN0

ATTRIBUTE_DATA_TYPE_STRING1

ATTRIBUTE_DATA_TYPE_INTEGER2

ATTRIBUTE_DATA_TYPE_REAL3

ATTRIBUTE_DATA_TYPE_BOOLEAN4

ATTRIBUTE_DATA_TYPE_BYTES5

ATTRIBUTE_DATA_TYPE_IDENTITY100

ATTRIBUTE_DATA_TYPE_RESOURCE101

DiscoveryMode

NameNumberDescription
DISCOVERY_MODE_UNKNOWN0

DISCOVERY_MODE_TRUSTED1

Only local identities with explicit policy PERMIT can discover.

DISCOVERY_MODE_PUBLIC2

Any bound local identity can discover.

DISCOVERY_MODE_TRUSTED_GLOBAL3

Only identities with explicit policy PERMIT can discover, and the service will be available to local and non-local (Relayed) clients.

DISCOVERY_MODE_PUBLIC_GLOBAL4

Any bound identity can discover, and the service will be available to local and non-local (Relayed) clients.

OnlineStatus

NameNumberDescription
ONLINE_STATUS_UNKNOWN0

ONLINE_STATUS_ONLINE1

ONLINE_STATUS_OFFLINE2

PolicyDecision

@todo currently this must align with AuthorisationDecision enum in policy library, but some of the values are irrelevant outside of the public API so we need a public-facing enum and some translation.

NameNumberDescription
POLICY_DECISION_UNKNOWN0

POLICY_DECISION_PROMPT1

POLICY_DECISION_PERMIT2

POLICY_DECISION_DENY3

POLICY_DECISION_INDETERMINATE4

POLICY_DECISION_NOT_APPLICABLE5

POLICY_DECISION_APPLICABLE6

POLICY_DECISION_PENDING7

ResourceStatus

Not used ATM.

NameNumberDescription
RESOURCE_STATUS_UNKNOWN0

RESOURCE_STATUS_LIVE1

RESOURCE_STATUS_INACTIVE2

RESOURCE_STATUS_DELETED999

SecureMode

NameNumberDescription
SECURE_MODE_UNKNOWN0

SECURE_MODE_INSECURE1

SECURE_MODE_TLS2

ServiceHostType

NameNumberDescription
SERVICE_HOST_TYPE_UNKNOWN0

SERVICE_HOST_TYPE_BUILTIN1

A built-in service hosted by the Volt.

SERVICE_HOST_TYPE_SERVER2

A service hosted by a grpc server other than the Volt.

SERVICE_HOST_TYPE_RELAYED3

A service hosted by a Volt client via a relay connection, i.e. the service is not exposed by a server as such, rather a Volt client implements the service and a Volt acts as a proxy, calling back to the client to implement the methods.

SessionStatus

NameNumberDescription
SESSION_STATUS_UNKNOWN0

SESSION_STATUS_PENDING1

SESSION_STATUS_LIVE2

SESSION_STATUS_EXPIRED3

SESSION_STATUS_REVOKED4

SESSION_STATUS_REJECTED5

ShareMode

Not used ATM.

NameNumberDescription
SHARE_MODE_UNKNOWN0

SHARE_MODE_TRUSTED1

SHARE_MODE_PUBLIC_READ2

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)