From 3a930a8f790cd9c683e207553565675c5d081f5f Mon Sep 17 00:00:00 2001 From: shuiyisong Date: Mon, 20 Jul 2026 21:06:44 +0800 Subject: [PATCH] chore: add comments Signed-off-by: shuiyisong --- src/common/meta/src/ddl/create_database.rs | 23 ++++++++++++++++++++++ src/meta-srv/src/service/procedure.rs | 9 +++++++-- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/src/common/meta/src/ddl/create_database.rs b/src/common/meta/src/ddl/create_database.rs index 751f8e508f0..7e1be4a2a05 100644 --- a/src/common/meta/src/ddl/create_database.rs +++ b/src/common/meta/src/ddl/create_database.rs @@ -32,21 +32,34 @@ use crate::key::schema_name::{SchemaNameKey, SchemaNameValue}; use crate::lock_key::{CatalogLock, SchemaLock}; use crate::rpc::ddl::CreatorGrantIntent; +/// Describes the creator-access result of an atomic create. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum AtomicCreateAccess { + /// Added an exact `ALL` ACL entry for the new database. AddedExactAll, + /// The creator already had effective `ALL` access, so their ACL was unchanged. AlreadyEffectiveAll, } +/// Outcome of atomically creating database metadata and ensuring creator access. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum AtomicCreateOutcome { + /// This attempt created the database with the given access result. Created(AtomicCreateAccess), + /// The same create procedure committed during an earlier attempt. AlreadyCommitted, + /// The creator row changed concurrently and the operation should be retried. UserChanged, + /// The creator is missing or no longer identifies the same account generation. UserMissing, + /// A different value already exists for the database metadata. SchemaConflict, } +/// Commits database metadata and any required creator access atomically. +/// +/// Implementations classify conditional-write failures with [`AtomicCreateOutcome`] so the +/// procedure can retry without overwriting concurrent user changes. #[async_trait] pub trait CreateDatabaseMetadataCommitter: Send + Sync { async fn commit( @@ -58,8 +71,10 @@ pub trait CreateDatabaseMetadataCommitter: Send + Sync { ) -> std::result::Result; } +/// Shared [`CreateDatabaseMetadataCommitter`]. pub type CreateDatabaseMetadataCommitterRef = Arc; +/// Procedure that creates a database and optionally ensures its creator has access. pub struct CreateDatabaseProcedure { pub context: DdlContext, pub data: CreateDatabaseData, @@ -123,6 +138,7 @@ impl CreateDatabaseProcedure { let mut value: SchemaNameValue = (&self.data.options).try_into()?; if let Some(creator) = self.data.creator.as_ref() { + // Distinguishes a replay of this procedure from a competing create. value.create_procedure_id = Some(procedure_id.to_string()); let Some(committer) = self.context.create_database_metadata_committer.as_ref() else { return error::UnexpectedSnafu { @@ -182,6 +198,7 @@ impl CreateDatabaseProcedure { } } + // The durable transaction is complete; retry cache invalidation separately. self.data.state = CreateDatabaseState::InvalidateCreatorCache; return Ok(Status::executing(true)); } @@ -258,13 +275,18 @@ impl Procedure for CreateDatabaseProcedure { } } +/// Persistent states of [`CreateDatabaseProcedure`]. #[derive(Debug, Clone, Serialize, Deserialize, AsRefStr)] pub enum CreateDatabaseState { + /// Checks whether the database already exists. Prepare, + /// Creates metadata and, when supplied, ensures the creator has access atomically. CreateMetadata, + /// Invalidates the creator's cached user data after the durable commit. InvalidateCreatorCache, } +/// Persistent data of [`CreateDatabaseProcedure`]. #[serde_as] #[derive(Debug, Serialize, Deserialize)] pub struct CreateDatabaseData { @@ -274,6 +296,7 @@ pub struct CreateDatabaseData { pub create_if_not_exists: bool, #[serde_as(deserialize_as = "DefaultOnNull")] pub options: HashMap, + /// Authenticated creator whose access is ensured, absent for legacy schema-only requests. #[serde(default)] pub creator: Option, } diff --git a/src/meta-srv/src/service/procedure.rs b/src/meta-srv/src/service/procedure.rs index 1e73beaf1d8..87ec36def3e 100644 --- a/src/meta-srv/src/service/procedure.rs +++ b/src/meta-srv/src/service/procedure.rs @@ -309,14 +309,19 @@ impl procedure_service_server::ProcedureService for Metasrv { } } +/// Restores the authenticated creator omitted from the protobuf create-database task. +/// +/// The frontend sends the serialized [`CreatorGrantIntent`] in both a reserved query-context +/// extension and internal gRPC metadata. This function removes the extension, requires both +/// copies to match on a frontend create-database request, and writes the decoded intent into the +/// task. Missing both preserves legacy and admin behavior; missing or mismatched copies fail +/// closed. fn restore_create_database_creator( metadata: &MetadataMap, role: i32, task: &mut DdlTask, query_context: &mut QueryContext, ) -> Result<(), Status> { - // The body copy makes metadata loss fail closed; old frontends provide no matching - // internal metadata and cannot turn public hints into trusted creator context. let forwarded = query_context .extensions .remove(CREATE_DATABASE_CREATOR_EXTENSION_KEY);