package page_api

Get desktop application:
View/edit binary Protocol Buffers messages

NB: unlike libpq, there is no CheckRelExists in gRPC, at the compute team's request. Instead, use GetRelSize with allow_missing=true to check existence.

• rpc GetBaseBackup (GetBaseBackupRequest, stream GetBaseBackupResponseChunk)

  page_service.proto:45

  Fetches a base backup.

  message GetBaseBackupRequest

  page_service.proto:101

  Requests a base backup.

  • uint64 lsn = 1

    The LSN to fetch the base backup at. 0 or absent means the latest LSN known to the Pageserver.

  • bool replica = 2

    If true, logical replication slots will not be created.

  • bool full = 3

    If true, include relation files in the base backup. Mainly for debugging and tests.

  • BaseBackupCompression compression = 4

    Compression algorithm to use. Base backups send a compressed payload instead of using gRPC compression, so that we can cache compressed backups on the server.

  message GetBaseBackupResponseChunk

  page_service.proto:124

  Base backup response chunk, returned as an ordered stream.

  • bytes chunk = 1

    A basebackup data chunk. The size is undefined, but bounded by the 4 MB gRPC message size limit.

• rpc GetDbSize (GetDbSizeRequest, GetDbSizeResponse)

  page_service.proto:48

  Returns the total size of a database, as # of bytes.

  message GetDbSizeRequest

  page_service.proto:132

  Requests the size of a database, as # of bytes. Only valid on shard 0, other shards will error.

  • optional ReadLsn read_lsn = 1

  • uint32 db_oid = 2

  message GetDbSizeResponse

  page_service.proto:137

  • uint64 num_bytes = 1

• rpc GetPages (stream GetPageRequest, stream GetPageResponse)

  page_service.proto:62

  Fetches pages. This is implemented as a bidirectional streaming RPC for performance. Unary requests incur costs for e.g. HTTP/2 stream setup, header parsing, authentication, and so on -- with streaming, we only pay these costs during the initial stream setup. This ~doubles throughput in benchmarks. Other RPCs use regular unary requests, since they are not as frequent and performance-critical, and this simplifies implementation. NB: a gRPC status response (e.g. errors) will terminate the stream. The stream may be shared by multiple Postgres backends, so we avoid this by sending them as GetPageResponse.status_code instead.

  message GetPageRequest

  page_service.proto:142

  Requests one or more pages.

  • optional RequestID request_id = 1

    A request ID. Will be included in the response. Should be unique for in-flight requests on the stream.

  • GetPageClass request_class = 2

    The request class.

  • optional ReadLsn read_lsn = 3

    The LSN to read at.

  • optional RelTag rel = 4

    The relation to read from.

  • repeated uint32 block_number = 5

    Page numbers to read. Must belong to the remote shard. Multiple pages will be executed as a single batch by the Pageserver, amortizing layer access costs and parallelizing them. This may increase the latency of any individual request, but improves the overall latency and throughput of the batch as a whole. TODO: this causes an allocation in the common single-block case. The sender can use a SmallVec to stack-allocate it, but Prost will always deserialize into a heap-allocated Vec. Consider optimizing this. TODO: we might be able to avoid a sort or something if we mandate that these are always in order. But we can't currenly rely on this on the server, because of compatibility with the libpq protocol handler.

  message GetPageResponse

  page_service.proto:197

  A GetPage response. A batch response will contain all of the requested pages. We could eagerly emit individual pages as soon as they are ready, but on a readv() Postgres holds buffer pool locks on all pages in the batch and we'll only return once the entire batch is ready, so no one can make use of the individual pages.

  • optional RequestID request_id = 1

    The original request's ID.

  • GetPageStatusCode status_code = 2

    The response status code. If not OK, the rel and page fields will be empty.

  • string reason = 3

    A string describing the status, if any.

  • optional RelTag rel = 4

    The relation that the pages belong to.

  • repeated Page page = 5

    The page(s), in the same order as the request.

• rpc GetRelSize (GetRelSizeRequest, GetRelSizeResponse)

  page_service.proto:65

  Returns the size of a relation, as # of blocks.

  message GetRelSizeRequest

  page_service.proto:249

  Fetches the size of a relation at a given LSN, as # of blocks. Only valid on shard 0, other shards will error.

  • optional ReadLsn read_lsn = 1

  • optional RelTag rel = 2

  • bool allow_missing = 3

    If true, return missing=true for missing relations instead of a NotFound error.

  message GetRelSizeResponse

  page_service.proto:256

  • uint32 num_blocks = 1

    The number of blocks in the relation.

  • bool missing = 2

    If allow_missing=true, this is true for missing relations.

• rpc GetSlruSegment (GetSlruSegmentRequest, GetSlruSegmentResponse)

  page_service.proto:68

  Fetches an SLRU segment.

  message GetSlruSegmentRequest

  page_service.proto:264

  Requests an SLRU segment. Only valid on shard 0, other shards will error.

  • optional ReadLsn read_lsn = 1

  • uint32 kind = 2

  • uint32 segno = 3

  message GetSlruSegmentResponse

  page_service.proto:273

  Returns an SLRU segment. These are up 32 pages (256 KB), so we can send them as a single response.

  • bytes segment = 1

• rpc LeaseLsn (LeaseLsnRequest, LeaseLsnResponse)

  page_service.proto:72

  Acquires or extends a lease on the given LSN. This guarantees that the Pageserver won't garbage collect the LSN until the lease expires. Must be acquired on all relevant shards.

  message LeaseLsnRequest

  page_service.proto:279

  Acquires or extends a lease on the given LSN. This guarantees that the Pageserver won't garbage collect the LSN until the lease expires. Must be acquired on all relevant shards.

  • uint64 lsn = 1

    The LSN to lease. Can't be 0 or below the current GC cutoff.

  message LeaseLsnResponse

  page_service.proto:286

  Lease acquisition response. If the lease could not be granted because the LSN has already been garbage collected, a FailedPrecondition status will be returned instead.

  • optional google.protobuf.Timestamp expires = 1

    The lease expiration time.

Base backup compression algorithms.

Used in: GetBaseBackupRequest

• BASE_BACKUP_COMPRESSION_UNKNOWN = 0

  Unknown algorithm. Used when clients send an unsupported algorithm.

• BASE_BACKUP_COMPRESSION_NONE = 1

  No compression.

• BASE_BACKUP_COMPRESSION_GZIP = 2

  GZIP compression.

A GetPageRequest class. Primarily intended for observability, but may also be used for prioritization in the future.

Used in: GetPageRequest

• GET_PAGE_CLASS_UNKNOWN = 0

  Unknown class. For backwards compatibility: used when an older client version sends a class that a newer server version has removed.

• GET_PAGE_CLASS_NORMAL = 1

  A normal request. This is the default.

• GET_PAGE_CLASS_PREFETCH = 2

  A prefetch request. NB: can only be classified on pg < 18.

• GET_PAGE_CLASS_BACKGROUND = 3

  A background request (e.g. vacuum).

A GetPageResponse status code. These are effectively equivalent to gRPC statuses. However, we use a bidirectional stream (potentially shared by many backends), and a gRPC status response would terminate the stream so we send GetPageResponse messages with these codes instead.

Used in: GetPageResponse

• GET_PAGE_STATUS_CODE_UNKNOWN = 0

  Unknown status. For forwards compatibility: used when an older client version receives a new status code from a newer server version.

• GET_PAGE_STATUS_CODE_OK = 1

  The request was successful.

• GET_PAGE_STATUS_CODE_NOT_FOUND = 2

  The page did not exist. The tenant/timeline/shard has already been validated during stream setup.

• GET_PAGE_STATUS_CODE_INVALID_REQUEST = 3

  The request was invalid.

• GET_PAGE_STATUS_CODE_INTERNAL_ERROR = 4

  The request failed due to an internal server error.

• GET_PAGE_STATUS_CODE_SLOW_DOWN = 5

  The tenant is rate limited. Slow down and retry later.

  NB: shutdown errors are emitted as a gRPC Unavailable status. TODO: consider adding a GET_PAGE_STATUS_CODE_LAYER_DOWNLOAD in the case of a layer download. This could free up the server task to process other requests while the download is in progress.

A page. TODO: it would be slightly more efficient (but less convenient) to have separate arrays of block numbers and images, but given the 8KB page size it's probably negligible. Benchmark it anyway.

Used in: GetPageResponse

• uint32 block_number = 1

  The page number.

• bytes image = 2

  The materialized page image, as an 8KB byte vector.

The LSN a request should read at.

Used in: GetDbSizeRequest, GetPageRequest, GetRelSizeRequest, GetSlruSegmentRequest

• uint64 request_lsn = 1

  The request's read LSN. Required.

• uint64 not_modified_since_lsn = 2

  If given, the caller guarantees that the page has not been modified since this LSN. Must be smaller than or equal to request_lsn. This allows the Pageserver to serve an old page without waiting for the request LSN to arrive. Valid for all request types. It is undefined behaviour to make a request such that the page was, in fact, modified between request_lsn and not_modified_since_lsn. The Pageserver might detect it and return an error, or it might return the old page version or the new page version. Setting not_modified_since_lsn equal to request_lsn is always safe, but can lead to unnecessary waiting.

A relation identifier.

Used in: GetPageRequest, GetPageResponse, GetRelSizeRequest

• uint32 spc_oid = 1

• uint32 db_oid = 2

• uint32 rel_number = 3

• uint32 fork_number = 4

A Request ID. Should be unique for in-flight requests on a stream. Included in the response.

Used in: GetPageRequest, GetPageResponse

• uint64 id = 1

  The base request ID.

• uint32 attempt = 2

  The request attempt. Starts at 0, incremented on each retry.