9d03dcd28e
We discard instances of `cql3::description` right after serializing them, so let's change the signature of the function to save some work.
97 lines
4.0 KiB
C++
97 lines
4.0 KiB
C++
/*
|
|
* Copyright (C) 2024-present ScyllaDB
|
|
*/
|
|
|
|
/*
|
|
* SPDX-License-Identifier: LicenseRef-ScyllaDB-Source-Available-1.0
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <seastar/core/sstring.hh>
|
|
#include <seastar/util/bool_class.hh>
|
|
|
|
#include "utils/managed_string.hh"
|
|
|
|
#include <optional>
|
|
#include <vector>
|
|
|
|
using namespace seastar;
|
|
|
|
namespace cql3 {
|
|
|
|
/// Tag indicating whether a describe function should return a `cql3::description`
|
|
/// with a `create_statement` or not.
|
|
using with_create_statement = bool_class<struct with_create_statement_tag>;
|
|
|
|
/// An option type that functions generating instances of `cql3::description`
|
|
/// can be parameterized with.
|
|
///
|
|
/// In some cases, the user doesn't need a create statement, so producing it
|
|
/// is a waste of time. An example of that could be `DESCRIBE TYPES`.
|
|
///
|
|
/// In some other cases, we may want to produce either a less, or a more detailed
|
|
/// create statement depending on the context. An example of that is
|
|
/// `DESCRIBE SCHEMA [WITH INTERNALS]` that may print additional details of tables
|
|
/// when the `WITH INTERNALS` option is used.
|
|
///
|
|
/// Some entities can generate `cql3::description`s parameterized by those two
|
|
/// characteristics and this type embodies the choice of the user.
|
|
enum class describe_option {
|
|
NO_STMTS, /// Describe an entity, but don't generate a create statement.
|
|
STMTS, /// Describe an entity and generate a create statement.
|
|
STMTS_AND_INTERNALS /// Describe an entity and generate a create statement,
|
|
/// including internal details.
|
|
};
|
|
|
|
/// Type representing an entity that can be restored by performing
|
|
/// a SINGLE CQL query. It can correspond to a tangible object such as
|
|
/// a keyspace, a table, or a role, as well as to a more abstract concept
|
|
/// like a role grant.
|
|
///
|
|
/// Instances of this type correspond to the output of `DESCRIBE` statements.
|
|
///
|
|
/// ! Important note: !
|
|
/// -------------------
|
|
/// `description` will wrap `keyspace` and `name` in double quotation marks
|
|
/// before serializing them if it's necessary. However, it does NOT apply
|
|
/// to `type`. That field is assumed not to need it. If the user uses the interface
|
|
/// in a context where that may be needed, they should format `name` on their own.
|
|
/// -------------------
|
|
///
|
|
/// See scylladb/scylladb#11106 and scylladb/scylladb#18750 for more context.
|
|
/// See also `docs/dev/describe_schema.md`.
|
|
struct description {
|
|
/// The name of the keyspace the entity belongs to.
|
|
/// Empty optional if and only if the entity does not belong to any keyspace.
|
|
std::optional<sstring> keyspace;
|
|
/// The name of the type of an entity, e.g. a role may be of type: role
|
|
sstring type;
|
|
/// The name of the entity itself, e.g. a keyspace of name `ks` will be of name: ks
|
|
sstring name;
|
|
/// Encoded CQL statement that can be used to restore the entity.
|
|
///
|
|
/// Technical note:
|
|
/// ---------------
|
|
/// This field could (and used to) be an optional of `sstring`.
|
|
/// The reason why we use `managed_string` instead is that some create statements
|
|
/// may be quite large and lead to oversized allocations if we use a contiguous
|
|
/// memory buffer. That's a rare occurrence (in my own experience), but it has
|
|
/// happened: see issue scylladb/scylladb#24018. That's why we need to use
|
|
/// `managed_string` right away: it's less convenient to handle, but this struct
|
|
/// is pretty much only used for serialization purposes, so it's a good trade-off.
|
|
std::optional<managed_string> create_statement;
|
|
|
|
/// Serialize the description to represent multiple UTF-8 columns.
|
|
/// The number of columns will be equal to 4 unless `serialize_create_statement`
|
|
/// is `false`, in which case that number will be equal to 3.
|
|
///
|
|
/// If `keyspace.has_value() == false`, a `null` will be printed in its place.
|
|
///
|
|
/// Precondition: if `serialize_create_statement` is true, then `create_statement.has_value()`
|
|
/// is also true.
|
|
std::vector<managed_bytes_opt> serialize(bool serialize_create_statement = true) &&;
|
|
};
|
|
|
|
} // namespace cql3
|