1#![cfg(any(feature = "mysql", feature = "postgres"))]
8
9use super::TableQuery;
10use crate::action::builtin::add::ReturningTarget;
11use crate::database::AnyTransaction;
12use crate::error::BaseError;
13use crate::table::field_config::Audience;
14use serde_json::Value;
15
16fn record_into_columns(record: crate::table::Record) -> std::collections::HashMap<String, Value> {
21 #[cfg(feature = "mysql")]
22 {
23 record.into_columns()
24 }
25 #[cfg(not(feature = "mysql"))]
26 {
27 record.into_map().into_iter().collect()
28 }
29}
30
31fn json_to_u64(value: &Value) -> Option<u64> {
33 match value {
34 Value::Number(number) => number
35 .as_u64()
36 .or_else(|| number.as_i64().and_then(|value| u64::try_from(value).ok())),
37 Value::String(text) => text.parse().ok(),
38 _ => None,
39 }
40}
41
42#[cfg(feature = "mysql")]
47struct PreparedUpsertBatch {
48 rows: Vec<std::collections::HashMap<String, Value>>,
50 tail: Vec<String>,
52}
53
54#[cfg(feature = "postgres")]
59#[derive(Debug)]
60struct PreparedPgUpsert {
61 rows: Vec<std::collections::HashMap<String, Value>>,
62 provided_columns: std::collections::BTreeSet<String>,
63}
64
65impl TableQuery {
66 pub async fn insert(self, data: crate::table::Record) -> Result<u64, BaseError> {
79 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
81 match self.backend()? {
82 #[cfg(feature = "mysql")]
83 yang_db::BackendKind::MySql => {
84 self.compile_db_write_query()?
85 .insert(&data)
86 .await
87 .map_err(BaseError::DatabaseExecuteFailed)?;
88 }
89 #[cfg(feature = "postgres")]
90 yang_db::BackendKind::PostgreSql => {
91 let database = self.pg_database()?;
92 let query = self.register_pg_fields(
93 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
94 data.keys(),
95 )?;
96 query
99 .insert_batch(std::slice::from_ref(&data))
100 .await
101 .map_err(BaseError::DatabaseExecuteFailed)?;
102 }
103 other => {
104 return Err(BaseError::ConfigError(format!(
105 "TableQuery 不支持当前数据库后端: {other:?}"
106 )));
107 }
108 }
109 Ok(1)
110 }
111
112 pub async fn insert_in_tx(
117 self,
118 tx: &mut AnyTransaction,
119 data: crate::table::Record,
120 ) -> Result<u64, BaseError> {
121 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
122 match tx {
123 #[cfg(feature = "mysql")]
124 AnyTransaction::MySql(tx) => {
125 let query = tx.table(&self.table_config.table_ref);
126 self.apply_write_plan(query)?
127 .insert(&data)
128 .await
129 .map_err(BaseError::DatabaseExecuteFailed)?;
130 }
131 #[cfg(feature = "postgres")]
132 AnyTransaction::Postgres(tx) => {
133 let query = tx.table(&self.table_config.table_ref);
134 let query =
135 self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
136 query
137 .insert_batch(std::slice::from_ref(&data))
138 .await
139 .map_err(BaseError::DatabaseExecuteFailed)?;
140 }
141 }
142 Ok(1)
143 }
144
145 pub async fn insert_returning(
158 self,
159 data: crate::table::Record,
160 target: ReturningTarget<'_>,
161 ) -> Result<crate::table::Record, BaseError> {
162 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
163 match self.backend()? {
164 #[cfg(feature = "mysql")]
165 yang_db::BackendKind::MySql => {
166 let primary_key = self.table_config.primary_key.clone();
167 let allowed = match target {
168 ReturningTarget::Pk => true,
169 ReturningTarget::Columns(columns) => {
170 columns.len() == 1 && columns[0] == primary_key.as_str()
171 }
172 ReturningTarget::All => false,
173 };
174 if !allowed {
175 return Err(Self::mysql_returning_unsupported("非整型主键列或整行"));
176 }
177 let value = self.mysql_insert_returning_pk(&data).await?;
178 Ok(crate::table::Record::new().set(primary_key, value))
179 }
180 #[cfg(feature = "postgres")]
181 yang_db::BackendKind::PostgreSql => self.pg_insert_returning(&data, target).await,
182 other => Err(BaseError::ConfigError(format!(
183 "TableQuery 不支持当前数据库后端: {other:?}"
184 ))),
185 }
186 }
187
188 #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
196 pub async fn insert_batch_returning(
197 self,
198 data: &[crate::table::Record],
199 target: ReturningTarget<'_>,
200 ) -> Result<Vec<crate::table::Record>, BaseError> {
201 match self.backend()? {
202 #[cfg(feature = "mysql")]
203 yang_db::BackendKind::MySql => Err(Self::mysql_batch_returning_unsupported(
204 "insert_batch_returning",
205 )),
206 #[cfg(feature = "postgres")]
207 yang_db::BackendKind::PostgreSql => {
208 let Some(rows) = self.prepare_pg_insert_rows(data)? else {
209 return Ok(Vec::new());
210 };
211 let database = self.pg_database()?;
212 let query = self.register_pg_fields(
213 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
214 rows[0].keys(),
215 )?;
216 self.apply_pg_returning_target(query, target)?
217 .insert_batch_returning(&rows)
218 .await
219 .map_err(BaseError::DatabaseExecuteFailed)
220 }
221 other => Err(BaseError::ConfigError(format!(
222 "TableQuery 不支持当前数据库后端: {other:?}"
223 ))),
224 }
225 }
226
227 #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
232 pub async fn insert_batch_returning_in_tx(
233 self,
234 tx: &mut AnyTransaction,
235 data: &[crate::table::Record],
236 target: ReturningTarget<'_>,
237 ) -> Result<Vec<crate::table::Record>, BaseError> {
238 match tx {
239 #[cfg(feature = "mysql")]
240 AnyTransaction::MySql(_) => Err(Self::mysql_batch_returning_unsupported(
241 "insert_batch_returning_in_tx",
242 )),
243 #[cfg(feature = "postgres")]
244 AnyTransaction::Postgres(tx) => {
245 let Some(rows) = self.prepare_pg_insert_rows(data)? else {
246 return Ok(Vec::new());
247 };
248 let query = self.register_pg_fields(
249 self.apply_pg_write_plan(tx.table(&self.table_config.table_ref))?,
250 rows[0].keys(),
251 )?;
252 self.apply_pg_returning_target(query, target)?
253 .insert_batch_returning(&rows)
254 .await
255 .map_err(BaseError::DatabaseExecuteFailed)
256 }
257 }
258 }
259
260 #[cfg(feature = "postgres")]
264 fn prepare_pg_insert_rows(
265 &self,
266 records: &[crate::table::Record],
267 ) -> Result<Option<Vec<std::collections::HashMap<String, Value>>>, BaseError> {
268 let mut rows = Vec::with_capacity(records.len());
269 let mut base_keys: Option<std::collections::BTreeSet<String>> = None;
270 for (index, record) in records.iter().enumerate() {
271 let prepared = self.prepare_and_validate_insert(record_into_columns(record.clone()))?;
272 let keys: std::collections::BTreeSet<String> = prepared.keys().cloned().collect();
273 match &base_keys {
274 Some(base) if *base != keys => {
275 return Err(BaseError::ParamInvalid(
276 "data".to_string(),
277 format!(
278 "批量 insert 第 {} 条记录提供的列集与第 1 条不一致",
279 index + 1
280 ),
281 ));
282 }
283 None => base_keys = Some(keys),
284 _ => {}
285 }
286 rows.push(prepared);
287 }
288 Ok((!rows.is_empty()).then_some(rows))
289 }
290
291 pub async fn insert_returning_pk_value(
296 self,
297 data: crate::table::Record,
298 ) -> Result<(u64, Value), BaseError> {
299 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
300 match self.backend()? {
301 #[cfg(feature = "mysql")]
302 yang_db::BackendKind::MySql => {
303 let value = self.mysql_insert_returning_pk(&data).await?;
304 Ok((1, value))
305 }
306 #[cfg(feature = "postgres")]
307 yang_db::BackendKind::PostgreSql => {
308 let primary_key = self.table_config.primary_key.clone();
309 let record = self.pg_insert_returning(&data, ReturningTarget::Pk).await?;
310 let value = record.get(&primary_key).cloned().ok_or_else(|| {
311 BaseError::ConfigError(
312 "INSERT ... RETURNING 未返回主键列,无法回填主键".to_string(),
313 )
314 })?;
315 Ok((1, value))
316 }
317 other => Err(BaseError::ConfigError(format!(
318 "TableQuery 不支持当前数据库后端: {other:?}"
319 ))),
320 }
321 }
322
323 pub async fn insert_returning_id(
335 self,
336 data: crate::table::Record,
337 ) -> Result<(u64, u64), BaseError> {
338 self.ensure_integer_primary_key()?;
339 let (affected, value) = self.insert_returning_pk_value(data).await?;
340 let id = json_to_u64(&value).ok_or_else(|| {
341 BaseError::ParamInvalid(
342 "primary_key".to_string(),
343 format!(
344 "insert_returning_id 仅支持整型主键,当前主键值为 {value};\
345 请改用 insert_returning_pk_value() 或 insert_returning(ReturningTarget::Pk)"
346 ),
347 )
348 })?;
349 Ok((affected, id))
350 }
351
352 pub async fn insert_returning_id_in_tx(
357 self,
358 tx: &mut AnyTransaction,
359 data: crate::table::Record,
360 ) -> Result<(u64, u64), BaseError> {
361 self.ensure_integer_primary_key()?;
362 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
363 match tx {
364 #[cfg(feature = "mysql")]
365 AnyTransaction::MySql(tx) => {
366 let query = tx.table(&self.table_config.table_ref);
367 let id = self
368 .apply_write_plan(query)?
369 .insert(&data)
370 .await
371 .map_err(BaseError::DatabaseExecuteFailed)?;
372 Ok((1, id))
373 }
374 #[cfg(feature = "postgres")]
375 AnyTransaction::Postgres(tx) => {
376 let primary_key = self.field_ref(&self.table_config.primary_key)?;
377 let query = tx.table(&self.table_config.table_ref);
378 let query =
379 self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
380 let id = query
381 .returning(primary_key)
382 .insert(&data)
383 .await
384 .map_err(BaseError::DatabaseExecuteFailed)?;
385 Ok((1, id))
386 }
387 }
388 }
389
390 fn ensure_integer_primary_key(&self) -> Result<(), BaseError> {
392 let primary_key = &self.table_config.primary_key;
393 let config = self.table_config.get_field(primary_key).ok_or_else(|| {
394 BaseError::FieldNotFound(self.table_config.table_name.clone(), primary_key.clone())
395 })?;
396 if matches!(
397 config.field_type,
398 crate::table::FieldType::Integer | crate::table::FieldType::BigInt
399 ) {
400 return Ok(());
401 }
402 Err(BaseError::ParamInvalid(
403 "primary_key".to_string(),
404 format!(
405 "insert_returning_id 仅支持整型主键,当前主键 {}.{primary_key} 为 {:?};\
406 请改用 insert_returning_pk_value() / insert_returning(ReturningTarget::Pk) \
407 取回真实类型主键,或 insert() 并在插入后按业务键查询",
408 self.table_config.table_name, config.field_type
409 ),
410 ))
411 }
412
413 #[cfg(feature = "mysql")]
415 fn mysql_returning_unsupported(what: &str) -> BaseError {
416 BaseError::ConfigError(format!(
417 "MySQL 不支持 INSERT ... RETURNING(请求 {what}):只能取回整型主键;\
418 请改用 insert_returning(ReturningTarget::Pk) 或插入后按业务键查询"
419 ))
420 }
421
422 #[cfg(feature = "mysql")]
424 fn mysql_batch_returning_unsupported(entry: &str) -> BaseError {
425 BaseError::ConfigError(format!(
426 "{entry} 仅支持 PostgreSQL:MySQL 没有 RETURNING,批量写入无法按真实行回填;\
427 请改用 PostgreSQL,或逐条写入后按业务键查询"
428 ))
429 }
430
431 #[cfg(feature = "mysql")]
433 async fn mysql_insert_returning_pk(
434 &self,
435 data: &std::collections::HashMap<String, Value>,
436 ) -> Result<Value, BaseError> {
437 self.ensure_integer_primary_key()?;
438 let primary_key = &self.table_config.primary_key;
439 if let Some(value) = data.get(primary_key).filter(|value| !value.is_null()) {
440 if json_to_u64(value).is_none() {
441 return Err(Self::mysql_returning_unsupported("非整型主键值"));
442 }
443 return Ok(value.clone());
444 }
445 let id = self
446 .compile_db_write_query()?
447 .insert(data)
448 .await
449 .map_err(BaseError::DatabaseExecuteFailed)?;
450 Ok(Value::Number(id.into()))
451 }
452
453 #[cfg(feature = "postgres")]
455 fn apply_pg_returning_target<'a>(
456 &self,
457 query: yang_db::postgres::QueryBuilder<'a>,
458 target: ReturningTarget<'_>,
459 ) -> Result<yang_db::postgres::QueryBuilder<'a>, BaseError> {
460 match target {
461 ReturningTarget::Pk => {
462 Ok(query.returning(self.field_ref(&self.table_config.primary_key)?))
463 }
464 ReturningTarget::All => Ok(query.returning_all()),
465 ReturningTarget::Columns(columns) => {
466 if columns.is_empty() {
467 return Err(BaseError::ParamInvalid(
468 "columns".to_string(),
469 "ReturningTarget::Columns 至少需要一列".to_string(),
470 ));
471 }
472 for name in columns {
473 if !self.table_config.fields.contains_key(*name) {
474 return Err(BaseError::FieldNotFound(
475 self.table_config.table_name.clone(),
476 (*name).to_string(),
477 ));
478 }
479 }
480 let refs = self.pg_field_refs(columns)?;
481 Ok(query.returning_columns(&refs))
482 }
483 }
484 }
485
486 #[cfg(feature = "postgres")]
488 async fn pg_insert_returning(
489 &self,
490 data: &std::collections::HashMap<String, Value>,
491 target: ReturningTarget<'_>,
492 ) -> Result<crate::table::Record, BaseError> {
493 let database = self.pg_database()?;
494 let query = self.register_pg_fields(
495 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
496 data.keys(),
497 )?;
498 self.apply_pg_returning_target(query, target)?
499 .insert_returning(data)
500 .await
501 .map_err(BaseError::DatabaseExecuteFailed)
502 }
503
504 #[cfg(feature = "postgres")]
519 pub async fn upsert_batch(
520 self,
521 rows: Vec<crate::table::Record>,
522 conflict_columns: &[&str],
523 ) -> Result<u64, BaseError> {
524 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
525 return Ok(0);
526 };
527 self.execute_pg_upsert_batch(prepared, conflict_columns, None, None, false)
528 .await
529 }
530
531 #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
539 pub async fn upsert_batch_returning(
540 self,
541 rows: Vec<crate::table::Record>,
542 conflict_columns: &[&str],
543 target: ReturningTarget<'_>,
544 ) -> Result<Vec<crate::table::Record>, BaseError> {
545 match self.backend()? {
546 #[cfg(feature = "mysql")]
547 yang_db::BackendKind::MySql => Err(Self::mysql_batch_returning_unsupported(
548 "upsert_batch_returning",
549 )),
550 #[cfg(feature = "postgres")]
551 yang_db::BackendKind::PostgreSql => {
552 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
553 return Ok(Vec::new());
554 };
555 let database = self.pg_database()?;
556 let conflicts = self.pg_field_refs(conflict_columns)?;
557 let query = self.register_pg_fields(
558 database.table(&self.table_config.table_ref),
559 prepared.rows[0].keys(),
560 )?;
561 let columns = self.resolve_pg_update_columns(&prepared, conflict_columns, None)?;
562 let query = if columns.is_empty() {
563 query.do_nothing()
564 } else {
565 let names: Vec<&str> = columns.iter().map(String::as_str).collect();
566 query.update_columns(&self.pg_field_refs(&names)?)
567 };
568 self.apply_pg_returning_target(query, target)?
569 .upsert_batch_returning(&prepared.rows, &conflicts)
570 .await
571 .map_err(BaseError::DatabaseExecuteFailed)
572 }
573 other => Err(BaseError::ConfigError(format!(
574 "TableQuery 不支持当前数据库后端: {other:?}"
575 ))),
576 }
577 }
578
579 #[cfg(feature = "postgres")]
587 pub async fn upsert_batch_with_update_columns(
588 self,
589 rows: Vec<crate::table::Record>,
590 conflict_columns: &[&str],
591 update_columns: &[&str],
592 ) -> Result<u64, BaseError> {
593 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
594 return Ok(0);
595 };
596 self.execute_pg_upsert_batch(
597 prepared,
598 conflict_columns,
599 None,
600 Some(update_columns),
601 false,
602 )
603 .await
604 }
605
606 #[cfg(feature = "postgres")]
611 pub async fn upsert_batch_do_nothing(
612 self,
613 rows: Vec<crate::table::Record>,
614 conflict_columns: &[&str],
615 ) -> Result<u64, BaseError> {
616 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
617 return Ok(0);
618 };
619 self.execute_pg_upsert_batch(prepared, conflict_columns, None, None, true)
620 .await
621 }
622
623 #[cfg(feature = "postgres")]
633 pub async fn upsert_batch_with_conflict_predicate(
634 self,
635 rows: Vec<crate::table::Record>,
636 conflict_columns: &[&str],
637 predicate: Option<&str>,
638 ) -> Result<u64, BaseError> {
639 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
640 return Ok(0);
641 };
642 self.execute_pg_upsert_batch(prepared, conflict_columns, predicate, None, false)
643 .await
644 }
645
646 pub async fn upsert_batch_in_tx(
676 self,
677 tx: &mut AnyTransaction,
678 rows: Vec<crate::table::Record>,
679 columns: &[&str],
680 ) -> Result<u64, BaseError> {
681 match tx {
682 #[cfg(feature = "mysql")]
683 AnyTransaction::MySql(tx) => {
684 let Some(batch) = self.plan_upsert_batch(rows, columns)? else {
686 return Ok(0);
687 };
688 tx.table(&self.table_config.table_ref)
692 .upsert_batch(&batch.rows, &batch.tail)
693 .await
694 .map_err(BaseError::DatabaseExecuteFailed)
695 }
696 #[cfg(feature = "postgres")]
697 AnyTransaction::Postgres(tx) => {
698 let Some(prepared) = self.prepare_pg_upsert_rows(rows, columns)? else {
699 return Ok(0);
700 };
701 self.execute_pg_upsert_batch_in_tx(tx, &prepared, columns, None, None, false)
702 .await
703 }
704 }
705 }
706
707 #[cfg(feature = "postgres")]
712 pub async fn upsert_batch_in_tx_with_update_columns(
713 self,
714 tx: &mut AnyTransaction,
715 rows: Vec<crate::table::Record>,
716 conflict_columns: &[&str],
717 update_columns: &[&str],
718 ) -> Result<u64, BaseError> {
719 match tx {
720 AnyTransaction::Postgres(tx) => {
721 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
722 return Ok(0);
723 };
724 self.execute_pg_upsert_batch_in_tx(
725 tx,
726 &prepared,
727 conflict_columns,
728 None,
729 Some(update_columns),
730 false,
731 )
732 .await
733 }
734 #[cfg(feature = "mysql")]
735 AnyTransaction::MySql(_) => Err(BaseError::ConfigError(
736 "upsert_batch_in_tx_with_update_columns 仅支持 PostgreSQL;MySQL 请使用 upsert_batch_in_tx(rows, update_columns) 的 ON DUPLICATE KEY UPDATE 语义"
737 .to_string(),
738 )),
739 }
740 }
741
742 #[cfg(feature = "postgres")]
749 pub async fn upsert_batch_do_nothing_in_tx(
750 self,
751 tx: &mut AnyTransaction,
752 rows: Vec<crate::table::Record>,
753 conflict_columns: &[&str],
754 ) -> Result<u64, BaseError> {
755 match tx {
756 AnyTransaction::Postgres(tx) => {
757 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
758 return Ok(0);
759 };
760 self.execute_pg_upsert_batch_in_tx(tx, &prepared, conflict_columns, None, None, true)
761 .await
762 }
763 #[cfg(feature = "mysql")]
764 AnyTransaction::MySql(_) => Err(BaseError::ConfigError(
765 "upsert_batch_do_nothing_in_tx 仅支持 PostgreSQL;MySQL 请使用 upsert_batch_in_tx 的 ON DUPLICATE KEY UPDATE 语义"
766 .to_string(),
767 )),
768 }
769 }
770
771 pub async fn upsert_batch_in_tx_with_conflict_predicate(
783 self,
784 tx: &mut AnyTransaction,
785 rows: Vec<crate::table::Record>,
786 columns: &[&str],
787 predicate: Option<&str>,
788 ) -> Result<u64, BaseError> {
789 match tx {
790 #[cfg(feature = "mysql")]
791 AnyTransaction::MySql(tx) => {
792 if let Some(predicate) = predicate {
793 return Err(BaseError::ConfigError(format!(
794 "MySQL 不支持 ON DUPLICATE KEY UPDATE 的冲突谓词(收到 `{predicate}`);\
795 请改用 PostgreSQL,或去掉谓词后使用 upsert_batch_in_tx"
796 )));
797 }
798 let Some(batch) = self.plan_upsert_batch(rows, columns)? else {
799 return Ok(0);
800 };
801 tx.table(&self.table_config.table_ref)
802 .upsert_batch(&batch.rows, &batch.tail)
803 .await
804 .map_err(BaseError::DatabaseExecuteFailed)
805 }
806 #[cfg(feature = "postgres")]
807 AnyTransaction::Postgres(tx) => {
808 let Some(prepared) = self.prepare_pg_upsert_rows(rows, columns)? else {
809 return Ok(0);
810 };
811 self.execute_pg_upsert_batch_in_tx(tx, &prepared, columns, predicate, None, false)
812 .await
813 }
814 }
815 }
816
817 #[cfg(feature = "postgres")]
823 fn prepare_pg_upsert_rows(
824 &self,
825 rows: Vec<crate::table::Record>,
826 conflict_columns: &[&str],
827 ) -> Result<Option<PreparedPgUpsert>, BaseError> {
828 let total = rows.len();
829 if total == 0 {
830 return Ok(None);
831 }
832
833 if !self.query_params.where_conditions.is_empty() || !self.any_conditions.is_empty() {
838 return Err(BaseError::ParamInvalid(
839 "where".to_string(),
840 "批量 upsert 不支持 where / where_any 条件:ON CONFLICT 没有 WHERE,条件会被静默忽略"
841 .to_string(),
842 ));
843 }
844 if self.table_config.soft_delete_field.is_some() && !self.include_trashed {
845 return Err(BaseError::ParamInvalid(
846 "soft_delete_field".to_string(),
847 "该表配置了软删字段,而批量 upsert 无法表达软删守卫;要么改用 update_in_tx,要么先 with_trashed()"
848 .to_string(),
849 ));
850 }
851 if conflict_columns.is_empty() {
852 return Err(BaseError::ParamInvalid(
853 "conflict_columns".to_string(),
854 "PostgreSQL 批量 upsert 必须显式指定冲突列(ON CONFLICT 目标)".to_string(),
855 ));
856 }
857 for name in conflict_columns {
858 if !self.table_config.fields.contains_key(*name) {
859 return Err(BaseError::FieldNotFound(
860 self.table_config.table_name.clone(),
861 (*name).to_string(),
862 ));
863 }
864 }
865 if let Some(tenant_field) = self.tenant_key_field() {
868 if !conflict_columns.contains(&tenant_field) {
869 return Err(BaseError::ParamInvalid(
870 "conflict_columns".to_string(),
871 format!(
872 "表 {} 声明了租户字段 `{tenant_field}`,批量 upsert 的冲突列必须包含该字段,否则会跨租户改写",
873 self.table_config.table_name
874 ),
875 ));
876 }
877 }
878
879 let mut prepared_rows = Vec::with_capacity(total);
880 let mut base_keys: Option<std::collections::BTreeSet<String>> = None;
881 let mut provided_columns = std::collections::BTreeSet::new();
882 for (index, record) in rows.into_iter().enumerate() {
883 let provided: std::collections::BTreeSet<String> =
886 record.as_map().keys().cloned().collect();
887 if index == 0 {
888 provided_columns = provided.clone();
889 } else if provided != provided_columns {
890 return Err(BaseError::ParamInvalid(
891 "rows".to_string(),
892 format!(
893 "批量 upsert 第 {} 条记录提供的列集与第 1 条不一致",
894 index + 1
895 ),
896 ));
897 }
898
899 let prepared = self.prepare_and_validate_insert(record_into_columns(record))?;
900 let keys: std::collections::BTreeSet<String> = prepared.keys().cloned().collect();
901 match &base_keys {
902 Some(base) if *base != keys => {
903 return Err(BaseError::ParamInvalid(
904 "rows".to_string(),
905 format!(
906 "批量 upsert 第 {} 条记录提供的列集与第 1 条不一致",
907 index + 1
908 ),
909 ));
910 }
911 None => base_keys = Some(keys),
912 _ => {}
913 }
914 for name in conflict_columns {
915 if !prepared.contains_key(*name) {
916 return Err(BaseError::ParamInvalid(
917 "conflict_columns".to_string(),
918 format!("冲突列 `{name}` 不在第 {} 条待写记录里", index + 1),
919 ));
920 }
921 }
922 prepared_rows.push(prepared);
923 }
924
925 Ok(Some(PreparedPgUpsert {
926 rows: prepared_rows,
927 provided_columns,
928 }))
929 }
930
931 #[cfg(feature = "postgres")]
933 fn pg_field_refs(&self, columns: &[&str]) -> Result<Vec<&yang_db::FieldRef>, BaseError> {
934 columns.iter().map(|name| self.field_ref(name)).collect()
935 }
936
937 #[cfg(feature = "postgres")]
939 fn tenant_key_field(&self) -> Option<&str> {
940 self.table_config
941 .fields
942 .iter()
943 .find_map(|(name, field)| field.tenant_key.then_some(name.as_str()))
944 }
945
946 fn is_framework_owned_column(&self, name: &str) -> bool {
948 if name == self.table_config.primary_key {
949 return true;
950 }
951 if let Some((tenant_field, _)) = &self.tenant_scope {
952 if tenant_field == name {
953 return true;
954 }
955 }
956 if self
957 .table_config
958 .get_field(name)
959 .is_some_and(|field| field.tenant_key || field.auto_increment)
960 {
961 return true;
962 }
963 if let Some(ts) = &self.table_config.timestamp_fields {
964 if ts.created_at.as_deref() == Some(name) || ts.deleted_at.as_deref() == Some(name) {
965 return true;
966 }
967 }
968 matches!(name, "created_at" | "tenant_id")
969 }
970
971 #[cfg(feature = "postgres")]
973 fn is_default_upsert_excluded_column(&self, name: &str) -> bool {
974 self.is_framework_owned_column(name) || matches!(name, "source_file" | "company")
975 }
976
977 #[cfg(feature = "postgres")]
982 fn default_pg_update_columns(
983 &self,
984 insert_columns: &[String],
985 conflict_columns: &[&str],
986 ) -> Vec<String> {
987 insert_columns
988 .iter()
989 .filter(|name| !conflict_columns.contains(&name.as_str()))
990 .filter(|name| !self.is_default_upsert_excluded_column(name))
991 .cloned()
992 .collect()
993 }
994
995 #[cfg(feature = "postgres")]
997 fn validate_pg_update_columns(
998 &self,
999 provided_columns: &std::collections::BTreeSet<String>,
1000 conflict_columns: &[&str],
1001 update_columns: &[&str],
1002 ) -> Result<Vec<String>, BaseError> {
1003 if update_columns.is_empty() {
1004 return Err(BaseError::ParamInvalid(
1005 "update_columns".to_string(),
1006 "批量 upsert 至少需要一个可更新列".to_string(),
1007 ));
1008 }
1009 let mut columns = Vec::with_capacity(update_columns.len());
1010 for name in update_columns {
1011 if !self.table_config.fields.contains_key(*name) {
1012 return Err(BaseError::FieldNotFound(
1013 self.table_config.table_name.clone(),
1014 (*name).to_string(),
1015 ));
1016 }
1017 if conflict_columns.contains(name) {
1018 return Err(BaseError::ParamInvalid(
1019 "update_columns".to_string(),
1020 format!("更新列 `{name}` 是冲突列,不能出现在 DO UPDATE SET 里"),
1021 ));
1022 }
1023 if !provided_columns.contains(*name) {
1024 return Err(BaseError::ParamInvalid(
1025 "update_columns".to_string(),
1026 format!("更新列 `{name}` 不在调用方提供的待写列里"),
1027 ));
1028 }
1029 if self.is_framework_owned_column(name) {
1030 return Err(BaseError::ParamInvalid(
1031 "update_columns".to_string(),
1032 format!("更新列 `{name}` 是主键/租户/创建时间等框架保护列,不能被 upsert 覆盖"),
1033 ));
1034 }
1035 if !columns.iter().any(|existing| existing == name) {
1036 columns.push((*name).to_string());
1037 }
1038 }
1039 if let Some(updated_at) = self
1041 .table_config
1042 .timestamp_fields
1043 .as_ref()
1044 .and_then(|fields| fields.updated_at.as_ref())
1045 .filter(|name| self.table_config.fields.contains_key(*name))
1046 {
1047 if !columns.iter().any(|existing| existing == updated_at) {
1048 columns.push(updated_at.clone());
1049 }
1050 }
1051 Ok(columns)
1052 }
1053
1054 #[cfg(feature = "postgres")]
1056 fn resolve_pg_update_columns(
1057 &self,
1058 prepared: &PreparedPgUpsert,
1059 conflict_columns: &[&str],
1060 update_columns: Option<&[&str]>,
1061 ) -> Result<Vec<String>, BaseError> {
1062 match update_columns {
1063 Some(explicit) => self.validate_pg_update_columns(
1064 &prepared.provided_columns,
1065 conflict_columns,
1066 explicit,
1067 ),
1068 None => {
1069 let insert_columns: Vec<String> = prepared.rows[0].keys().cloned().collect();
1070 Ok(self.default_pg_update_columns(&insert_columns, conflict_columns))
1071 }
1072 }
1073 }
1074
1075 #[cfg(feature = "postgres")]
1077 async fn execute_pg_upsert_batch(
1078 self,
1079 prepared: PreparedPgUpsert,
1080 conflict_columns: &[&str],
1081 conflict_predicate: Option<&str>,
1082 update_columns: Option<&[&str]>,
1083 do_nothing: bool,
1084 ) -> Result<u64, BaseError> {
1085 let database = self.pg_database()?;
1086 let conflicts = self.pg_field_refs(conflict_columns)?;
1087 let query = self.register_pg_fields(
1088 database.table(&self.table_config.table_ref),
1089 prepared.rows[0].keys(),
1090 )?;
1091 let query = match conflict_predicate {
1092 Some(predicate) => query.on_conflict_with_predicate(&conflicts, predicate),
1093 None => query,
1094 };
1095 let query = if do_nothing {
1096 query.do_nothing()
1097 } else {
1098 let columns =
1099 self.resolve_pg_update_columns(&prepared, conflict_columns, update_columns)?;
1100 if columns.is_empty() {
1101 query.do_nothing()
1103 } else {
1104 let names: Vec<&str> = columns.iter().map(String::as_str).collect();
1105 let refs = self.pg_field_refs(&names)?;
1106 query.update_columns(&refs)
1107 }
1108 };
1109 query
1110 .upsert_batch(&prepared.rows, &conflicts)
1111 .await
1112 .map_err(BaseError::DatabaseExecuteFailed)
1113 }
1114
1115 #[cfg(feature = "postgres")]
1117 async fn execute_pg_upsert_batch_in_tx(
1118 &self,
1119 tx: &mut yang_db::postgres::Transaction,
1120 prepared: &PreparedPgUpsert,
1121 conflict_columns: &[&str],
1122 conflict_predicate: Option<&str>,
1123 update_columns: Option<&[&str]>,
1124 do_nothing: bool,
1125 ) -> Result<u64, BaseError> {
1126 let conflicts = self.pg_field_refs(conflict_columns)?;
1127 let query = self.register_pg_fields(
1128 tx.table(&self.table_config.table_ref),
1129 prepared.rows[0].keys(),
1130 )?;
1131 let query = match conflict_predicate {
1132 Some(predicate) => query.on_conflict_with_predicate(&conflicts, predicate),
1133 None => query,
1134 };
1135 let query = if do_nothing {
1136 query.do_nothing()
1137 } else {
1138 let columns =
1139 self.resolve_pg_update_columns(prepared, conflict_columns, update_columns)?;
1140 if columns.is_empty() {
1141 query.do_nothing()
1142 } else {
1143 let names: Vec<&str> = columns.iter().map(String::as_str).collect();
1144 let refs = self.pg_field_refs(&names)?;
1145 query.update_columns(&refs)
1146 }
1147 };
1148 query
1149 .upsert_batch(&prepared.rows, &conflicts)
1150 .await
1151 .map_err(BaseError::DatabaseExecuteFailed)
1152 }
1153
1154 #[cfg(feature = "mysql")]
1159 fn plan_upsert_batch(
1160 &self,
1161 rows: Vec<crate::table::Record>,
1162 update_columns: &[&str],
1163 ) -> Result<Option<PreparedUpsertBatch>, BaseError> {
1164 let total = rows.len();
1165 let mut records = rows.into_iter();
1166 let Some(first) = records.next() else {
1168 return Ok(None);
1169 };
1170
1171 if !self.query_params.where_conditions.is_empty() {
1173 return Err(BaseError::ParamInvalid(
1174 "where".to_string(),
1175 "批量 upsert 不支持 where 条件:ON DUPLICATE KEY UPDATE 没有 WHERE,条件会被静默忽略"
1176 .to_string(),
1177 ));
1178 }
1179 if self.table_config.soft_delete_field.is_some() && !self.include_trashed {
1182 return Err(BaseError::ParamInvalid(
1183 "soft_delete_field".to_string(),
1184 "该表配置了软删字段,而批量 upsert 无法表达软删守卫;要么改用 update_in_tx,要么先 with_trashed()"
1185 .to_string(),
1186 ));
1187 }
1188
1189 let first_provided: std::collections::BTreeSet<String> =
1193 first.as_map().keys().cloned().collect();
1194 let first_prepared = self.prepare_and_validate_insert(record_into_columns(first))?;
1195 let first_prepared_keys: std::collections::BTreeSet<String> =
1196 first_prepared.keys().cloned().collect();
1197
1198 let mut prepared_rows = Vec::with_capacity(total);
1199 prepared_rows.push(first_prepared);
1200 for (offset, record) in records.enumerate() {
1201 let provided: std::collections::BTreeSet<String> =
1202 record.as_map().keys().cloned().collect();
1203 let prepared = self.prepare_and_validate_insert(record_into_columns(record))?;
1204 let prepared_keys: std::collections::BTreeSet<String> =
1205 prepared.keys().cloned().collect();
1206 let row_number = offset + 2;
1208 if provided != first_provided {
1211 return Err(BaseError::ParamInvalid(
1212 "rows".to_string(),
1213 format!("批量 upsert 第 {row_number} 条记录提供的列集与第 1 条不一致"),
1214 ));
1215 }
1216 if prepared_keys != first_prepared_keys {
1218 return Err(BaseError::ParamInvalid(
1219 "rows".to_string(),
1220 format!("批量 upsert 第 {row_number} 条记录提供的列集与第 1 条不一致"),
1221 ));
1222 }
1223 prepared_rows.push(prepared);
1224 }
1225
1226 if update_columns.is_empty() {
1227 return Err(BaseError::ParamInvalid(
1228 "update_columns".to_string(),
1229 "批量 upsert 至少需要一个可更新列(ON DUPLICATE KEY UPDATE 的赋值列)".to_string(),
1230 ));
1231 }
1232 for name in update_columns {
1233 if !first_provided.contains(*name) {
1238 return Err(BaseError::ParamInvalid(
1239 "update_columns".to_string(),
1240 format!(
1241 "赋值列 `{name}` 不在调用方提供的列里(框架补出来的默认值与 created_at 不能当赋值列)"
1242 ),
1243 ));
1244 }
1245 if self
1246 .table_config
1247 .get_field(name)
1248 .is_some_and(|field| field.auto_increment)
1249 {
1250 return Err(BaseError::ParamInvalid(
1251 "update_columns".to_string(),
1252 format!("赋值列 `{name}` 是自增列,不能出现在 ON DUPLICATE KEY UPDATE 里"),
1253 ));
1254 }
1255 }
1256 for name in update_columns {
1259 if self.is_framework_owned_column(name) {
1260 return Err(BaseError::ParamInvalid(
1261 "update_columns".to_string(),
1262 format!("赋值列 `{name}` 是主键/租户/创建时间等框架保护列,不能被 upsert 覆盖"),
1263 ));
1264 }
1265 }
1266
1267 let mut tail: Vec<String> = Vec::with_capacity(update_columns.len() + 1);
1270 for name in update_columns {
1271 if !tail.iter().any(|existing| existing.as_str() == *name) {
1272 tail.push((*name).to_string());
1273 }
1274 }
1275 if let Some(updated_at) = self
1276 .table_config
1277 .timestamp_fields
1278 .as_ref()
1279 .and_then(|fields| fields.updated_at.as_ref())
1280 .filter(|name| self.table_config.fields.contains_key(*name))
1281 {
1282 if !tail.iter().any(|existing| existing == updated_at) {
1283 tail.push(updated_at.clone());
1284 }
1285 }
1286
1287 Ok(Some(PreparedUpsertBatch {
1288 rows: prepared_rows,
1289 tail,
1290 }))
1291 }
1292
1293 pub(crate) fn prepare_and_validate_insert(
1302 &self,
1303 data: std::collections::HashMap<String, Value>,
1304 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1305 let mut prepared = data;
1306
1307 if let Some((field, value)) = &self.tenant_scope {
1309 if prepared.contains_key(field) {
1310 return Err(BaseError::PermissionDenied(format!(
1311 "禁止显式写入租户字段: {field}"
1312 )));
1313 }
1314 prepared.insert(field.clone(), value.clone());
1315 }
1316
1317 for (field_name, value) in &prepared {
1320 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
1321 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
1322 })?;
1323 let omitted_auto_increment = field_config.auto_increment && value.is_null();
1324 let injected_tenant = self
1325 .tenant_scope
1326 .as_ref()
1327 .is_some_and(|(tenant_field, _)| tenant_field == field_name);
1328 if !injected_tenant
1329 && !omitted_auto_increment
1330 && !field_config.permissions.can_write(&self.user_roles_set)
1331 {
1332 return Err(BaseError::FieldPermissionDenied(
1333 self.table_config.table_name.clone(),
1334 field_name.clone(),
1335 "用户无写入权限".to_string(),
1336 ));
1337 }
1338 }
1339
1340 for (field_name, field_config) in &self.table_config.fields {
1342 if field_config.auto_increment
1343 && prepared
1344 .get(field_name)
1345 .map(serde_json::Value::is_null)
1346 .unwrap_or(true)
1347 {
1348 prepared.remove(field_name);
1349 }
1350 }
1351
1352 for (field_name, field_config) in &self.table_config.fields {
1354 if field_config.auto_increment {
1355 continue;
1356 }
1357 if let Some(default) = &field_config.default_value {
1358 if !prepared.contains_key(field_name) {
1359 prepared.insert(field_name.clone(), default.clone());
1360 }
1361 }
1362 }
1363
1364 if let Some(ts) = &self.table_config.timestamp_fields {
1366 let now = chrono::Utc::now().timestamp();
1367 for ts_field in [&ts.created_at, &ts.updated_at].into_iter().flatten() {
1368 if self.table_config.fields.contains_key(ts_field) {
1369 let missing = prepared.get(ts_field).map(|v| v.is_null()).unwrap_or(true);
1370 if missing {
1371 prepared.insert(ts_field.clone(), Value::Number(now.into()));
1372 }
1373 }
1374 }
1375 }
1376
1377 for (field_name, field_config) in &self.table_config.fields {
1379 if !field_config.permissions.can_write(&self.user_roles_set) {
1380 continue;
1381 }
1382 if field_config.auto_increment && !prepared.contains_key(field_name) {
1383 continue;
1384 }
1385 let value = prepared.get(field_name).unwrap_or(&Value::Null);
1386 field_config.validate(value, &self.regex_cache)?;
1387 }
1388
1389 Ok(prepared)
1390 }
1391
1392 fn ensure_soft_delete_write_has_where(&self, op: &str) -> Result<(), BaseError> {
1412 if self.include_trashed || self.table_config.soft_delete_field.is_none() {
1413 return Ok(());
1414 }
1415 if self.query_params.where_conditions.is_empty() && self.any_conditions.is_empty() {
1416 return Err(BaseError::MissingWhereClause(op.to_string()));
1417 }
1418 Ok(())
1419 }
1420
1421 pub async fn update(self, data: crate::table::Record) -> Result<u64, BaseError> {
1430 let data = self.prepare_update_data(record_into_columns(data))?;
1431 self.ensure_soft_delete_write_has_where("UPDATE")?;
1434 match self.backend()? {
1435 #[cfg(feature = "mysql")]
1436 yang_db::BackendKind::MySql => self
1437 .compile_db_write_query()?
1438 .update(&data)
1439 .await
1440 .map_err(BaseError::DatabaseExecuteFailed),
1441 #[cfg(feature = "postgres")]
1442 yang_db::BackendKind::PostgreSql => {
1443 let database = self.pg_database()?;
1444 let query = self.register_pg_fields(
1445 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
1446 data.keys(),
1447 )?;
1448 query
1449 .update(&data)
1450 .await
1451 .map_err(BaseError::DatabaseExecuteFailed)
1452 }
1453 other => Err(BaseError::ConfigError(format!(
1454 "TableQuery 不支持当前数据库后端: {other:?}"
1455 ))),
1456 }
1457 }
1458
1459 pub async fn update_in_tx(
1464 self,
1465 tx: &mut AnyTransaction,
1466 data: crate::table::Record,
1467 ) -> Result<u64, BaseError> {
1468 let data = self.prepare_update_data(record_into_columns(data))?;
1469 self.ensure_soft_delete_write_has_where("UPDATE")?;
1470 match tx {
1471 #[cfg(feature = "mysql")]
1472 AnyTransaction::MySql(tx) => {
1473 let query = tx.table(&self.table_config.table_ref);
1474 self.apply_write_plan(query)?
1475 .update(&data)
1476 .await
1477 .map_err(BaseError::DatabaseExecuteFailed)
1478 }
1479 #[cfg(feature = "postgres")]
1480 AnyTransaction::Postgres(tx) => {
1481 let query = tx.table(&self.table_config.table_ref);
1482 let query =
1483 self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
1484 query
1485 .update(&data)
1486 .await
1487 .map_err(BaseError::DatabaseExecuteFailed)
1488 }
1489 }
1490 }
1491
1492 fn prepare_update_data(
1493 &self,
1494 data: std::collections::HashMap<String, Value>,
1495 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1496 self.validate_update_data(&data)?;
1497 self.with_updated_timestamp(data)
1498 }
1499
1500 fn with_updated_timestamp(
1501 &self,
1502 mut data: std::collections::HashMap<String, Value>,
1503 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1504 if data.is_empty() {
1505 return Err(BaseError::ParamInvalid(
1506 "data".to_string(),
1507 "无可更新字段".to_string(),
1508 ));
1509 }
1510 if let Some(updated_at) = self
1511 .table_config
1512 .timestamp_fields
1513 .as_ref()
1514 .and_then(|fields| fields.updated_at.as_ref())
1515 .filter(|name| self.table_config.fields.contains_key(*name))
1516 {
1517 data.insert(
1518 updated_at.clone(),
1519 Value::Number(chrono::Utc::now().timestamp().into()),
1520 );
1521 }
1522 Ok(data)
1523 }
1524
1525 #[cfg(test)]
1527 pub fn validate_update_data(
1528 &self,
1529 data: &std::collections::HashMap<String, Value>,
1530 ) -> Result<(), BaseError> {
1531 self.validate_update_data_impl(data)
1532 }
1533
1534 #[cfg(not(test))]
1536 fn validate_update_data(
1537 &self,
1538 data: &std::collections::HashMap<String, Value>,
1539 ) -> Result<(), BaseError> {
1540 self.validate_update_data_impl(data)
1541 }
1542
1543 fn validate_update_data_impl(
1545 &self,
1546 data: &std::collections::HashMap<String, Value>,
1547 ) -> Result<(), BaseError> {
1548 if data.is_empty() {
1549 return Err(BaseError::ParamInvalid(
1550 "data".to_string(),
1551 "至少需要一个更新字段".to_string(),
1552 ));
1553 }
1554 self.validate_update_fields(data, None)
1555 }
1556
1557 fn validate_update_fields(
1559 &self,
1560 data: &std::collections::HashMap<String, Value>,
1561 skip: Option<&str>,
1562 ) -> Result<(), BaseError> {
1563 for (field_name, value) in data {
1565 if skip.is_some_and(|name| name == field_name) {
1566 continue;
1567 }
1568 if self
1569 .tenant_scope
1570 .as_ref()
1571 .is_some_and(|(tenant_field, _)| tenant_field == field_name)
1572 {
1573 return Err(BaseError::PermissionDenied(format!(
1574 "禁止修改租户字段: {field_name}"
1575 )));
1576 }
1577 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
1579 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
1580 })?;
1581
1582 if !field_config.permissions.can_write(&self.user_roles_set) {
1584 return Err(BaseError::FieldPermissionDenied(
1585 self.table_config.table_name.clone(),
1586 field_name.clone(),
1587 "用户无写入权限".to_string(),
1588 ));
1589 }
1590
1591 field_config.validate(value, &self.regex_cache)?;
1594 }
1595
1596 Ok(())
1597 }
1598
1599 fn prepare_soft_delete_data(
1605 &self,
1606 data: std::collections::HashMap<String, Value>,
1607 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1608 let framework_managed = self.table_config.soft_delete_field.as_ref().filter(|name| {
1609 self.table_config
1610 .get_field(name)
1611 .is_some_and(|field| matches!(field.permissions.writable, Audience::Nobody))
1612 });
1613 self.validate_update_fields(&data, framework_managed.map(String::as_str))?;
1614 self.with_updated_timestamp(data)
1615 }
1616
1617 #[allow(clippy::type_complexity)]
1623 #[cfg(all(test, feature = "mysql"))]
1624 pub fn upsert_batch_plan_for_test(
1625 &self,
1626 rows: Vec<crate::table::Record>,
1627 update_columns: &[&str],
1628 ) -> Result<Option<(Vec<std::collections::HashMap<String, Value>>, Vec<String>)>, BaseError>
1629 {
1630 Ok(self
1631 .plan_upsert_batch(rows, update_columns)?
1632 .map(|batch| (batch.rows, batch.tail)))
1633 }
1634
1635 pub async fn delete(self) -> Result<u64, BaseError> {
1642 if let Some(soft_delete_field) = self.table_config.soft_delete_field.clone() {
1643 let data = self.prepare_soft_delete_data(std::collections::HashMap::from([(
1644 soft_delete_field,
1645 Value::Number(chrono::Utc::now().timestamp().into()),
1646 )]))?;
1647 self.ensure_soft_delete_write_has_where("DELETE")?;
1650 return self.execute_soft_delete(data).await;
1651 }
1652 self.execute_physical_delete().await
1653 }
1654
1655 async fn execute_soft_delete(
1657 self,
1658 data: std::collections::HashMap<String, Value>,
1659 ) -> Result<u64, BaseError> {
1660 match self.backend()? {
1661 #[cfg(feature = "mysql")]
1662 yang_db::BackendKind::MySql => self
1663 .compile_db_write_query()?
1664 .update(&data)
1665 .await
1666 .map_err(BaseError::DatabaseExecuteFailed),
1667 #[cfg(feature = "postgres")]
1668 yang_db::BackendKind::PostgreSql => {
1669 let database = self.pg_database()?;
1670 let query = self.register_pg_fields(
1671 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
1672 data.keys(),
1673 )?;
1674 query
1675 .update(&data)
1676 .await
1677 .map_err(BaseError::DatabaseExecuteFailed)
1678 }
1679 other => Err(BaseError::ConfigError(format!(
1680 "TableQuery 不支持当前数据库后端: {other:?}"
1681 ))),
1682 }
1683 }
1684
1685 async fn execute_physical_delete(self) -> Result<u64, BaseError> {
1687 match self.backend()? {
1688 #[cfg(feature = "mysql")]
1689 yang_db::BackendKind::MySql => self
1690 .compile_db_write_query()?
1691 .delete()
1692 .await
1693 .map_err(BaseError::DatabaseExecuteFailed),
1694 #[cfg(feature = "postgres")]
1695 yang_db::BackendKind::PostgreSql => {
1696 let database = self.pg_database()?;
1697 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?
1698 .delete()
1699 .await
1700 .map_err(BaseError::DatabaseExecuteFailed)
1701 }
1702 other => Err(BaseError::ConfigError(format!(
1703 "TableQuery 不支持当前数据库后端: {other:?}"
1704 ))),
1705 }
1706 }
1707
1708 pub async fn delete_in_tx(self, tx: &mut AnyTransaction) -> Result<u64, BaseError> {
1713 let soft_delete_data = self
1715 .table_config
1716 .soft_delete_field
1717 .clone()
1718 .map(|field| {
1719 self.prepare_soft_delete_data(std::collections::HashMap::from([(
1720 field,
1721 Value::Number(chrono::Utc::now().timestamp().into()),
1722 )]))
1723 })
1724 .transpose()?;
1725 self.ensure_soft_delete_write_has_where("DELETE")?;
1727 match tx {
1728 #[cfg(feature = "mysql")]
1729 AnyTransaction::MySql(tx) => {
1730 let query = tx.table(&self.table_config.table_ref);
1731 if let Some(data) = soft_delete_data {
1732 return self
1733 .apply_write_plan(query)?
1734 .update(&data)
1735 .await
1736 .map_err(BaseError::DatabaseExecuteFailed);
1737 }
1738 self.apply_write_plan(query)?
1739 .delete()
1740 .await
1741 .map_err(BaseError::DatabaseExecuteFailed)
1742 }
1743 #[cfg(feature = "postgres")]
1744 AnyTransaction::Postgres(tx) => {
1745 let query = tx.table(&self.table_config.table_ref);
1746 if let Some(data) = soft_delete_data {
1747 let query =
1748 self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
1749 return query
1750 .update(&data)
1751 .await
1752 .map_err(BaseError::DatabaseExecuteFailed);
1753 }
1754 self.apply_pg_write_plan(query)?
1755 .delete()
1756 .await
1757 .map_err(BaseError::DatabaseExecuteFailed)
1758 }
1759 }
1760 }
1761}
1762
1763#[cfg(all(test, feature = "postgres"))]
1764mod pg_tests {
1765 use super::*;
1766 use crate::table::{Field, Record, Table};
1767 use std::sync::Arc;
1768
1769 fn lazy_query(table: Table) -> TableQuery {
1770 let definition = table.build().expect("测试表定义应有效");
1771 TableQuery::new(
1772 definition.shared_config(),
1773 Arc::from(Vec::<String>::new()),
1774 None,
1775 )
1776 }
1777
1778 #[test]
1782 fn pg_upsert_rejects_where_any_conditions() {
1783 let mut query = lazy_query(Table::new("pg_upsert_where_any").fields([
1784 Field::id("id"),
1785 Field::string("option_key", 64).required(),
1786 Field::string("label", 64).required(),
1787 ]));
1788 query
1789 .any_conditions
1790 .push(("option_key".to_string(), vec![serde_json::json!("opt_a")]));
1791 let rows = vec![Record::new().set("option_key", "opt_a").set("label", "x")];
1792
1793 let error = query
1794 .prepare_pg_upsert_rows(rows, &["option_key"])
1795 .expect_err("where_any 条件不得在批量 upsert 中被静默忽略");
1796 match error {
1797 BaseError::ParamInvalid(field, message) => {
1798 assert_eq!(field, "where");
1799 assert!(
1800 message.contains("where_any"),
1801 "错误信息应点名 where_any: {message}"
1802 );
1803 }
1804 other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1805 }
1806 }
1807
1808 #[test]
1811 fn insert_returning_id_rejects_non_integer_primary_key() {
1812 let query = lazy_query(Table::new("pg_string_pk").fields([
1813 Field::string("code", 32).primary_key().required(),
1814 Field::string("name", 32).required(),
1815 ]));
1816
1817 let error = query
1818 .ensure_integer_primary_key()
1819 .expect_err("字符串主键必须被拒绝");
1820 match error {
1821 BaseError::ParamInvalid(field, message) => {
1822 assert_eq!(field, "primary_key");
1823 assert!(
1824 message.contains("insert_returning_id"),
1825 "错误信息应指引到 insert_returning_id: {message}"
1826 );
1827 assert!(
1828 message.contains("insert()"),
1829 "错误信息应给出替代入口: {message}"
1830 );
1831 }
1832 other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1833 }
1834 }
1835
1836 #[test]
1838 fn insert_returning_id_accepts_integer_primary_key() {
1839 let query = lazy_query(
1840 Table::new("pg_int_pk").fields([Field::id("id"), Field::string("name", 32).required()]),
1841 );
1842
1843 query.ensure_integer_primary_key().expect("整型主键应放行");
1844 }
1845
1846 #[test]
1849 fn pg_upsert_requires_tenant_key_in_conflict_columns() {
1850 let query = lazy_query(Table::new("pg_upsert_tenant_conflict").fields([
1851 Field::id("id"),
1852 Field::bigint("tenant_id").tenant_key(),
1853 Field::string("option_key", 64).required(),
1854 Field::string("label", 64).required(),
1855 ]));
1856 let rows = vec![Record::new()
1857 .set("tenant_id", 1_i64)
1858 .set("option_key", "opt_a")
1859 .set("label", "x")];
1860
1861 let error = query
1862 .prepare_pg_upsert_rows(rows, &["option_key"])
1863 .expect_err("缺少租户冲突列必须拒绝");
1864 match error {
1865 BaseError::ParamInvalid(field, message) => {
1866 assert_eq!(field, "conflict_columns");
1867 assert!(
1868 message.contains("tenant_id"),
1869 "错误信息应点名租户字段: {message}"
1870 );
1871 }
1872 other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1873 }
1874 }
1875
1876 #[test]
1878 fn pg_default_update_columns_exclude_tenant_key() {
1879 let query = lazy_query(Table::new("pg_upsert_tenant_whitelist").fields([
1880 Field::id("id"),
1881 Field::bigint("tenant_id").tenant_key(),
1882 Field::string("option_key", 64).required(),
1883 Field::string("label", 64).required(),
1884 ]));
1885 let rows = vec![Record::new()
1886 .set("tenant_id", 1_i64)
1887 .set("option_key", "opt_a")
1888 .set("label", "x")];
1889 let prepared = query
1890 .prepare_pg_upsert_rows(rows, &["tenant_id", "option_key"])
1891 .expect("含租户冲突列应通过校验")
1892 .expect("非空批应产出计划");
1893 let insert_columns: Vec<String> = prepared.rows[0].keys().cloned().collect();
1894 let update_columns =
1895 query.default_pg_update_columns(&insert_columns, &["tenant_id", "option_key"]);
1896
1897 assert!(
1898 !update_columns.contains(&"tenant_id".to_string()),
1899 "默认白名单不得包含租户列: {update_columns:?}"
1900 );
1901 assert!(
1902 update_columns.contains(&"label".to_string()),
1903 "非保护业务列应在默认白名单内: {update_columns:?}"
1904 );
1905 }
1906}
1907
1908#[cfg(all(test, feature = "mysql"))]
1909mod batch_returning_mysql_tests {
1910 use super::*;
1911 use crate::database::AnyPool;
1912 use crate::table::{Field, Record, Table};
1913 use std::sync::Arc;
1914
1915 fn lazy_mysql_query(table: Table) -> TableQuery {
1916 let definition = table.build().expect("测试表定义应有效");
1917 let pool = sqlx::mysql::MySqlPoolOptions::new()
1918 .connect_lazy("mysql://root@127.0.0.1:3306/test")
1919 .expect("懒连接池构造不应触发网络连接");
1920 TableQuery::new(
1921 definition.shared_config(),
1922 Arc::from(Vec::<String>::new()),
1923 Some(AnyPool::MySql(Arc::new(pool))),
1924 )
1925 }
1926
1927 #[tokio::test]
1930 async fn insert_batch_returning_rejects_mysql() {
1931 let query = lazy_mysql_query(
1932 Table::new("tq_batch_returning_mysql")
1933 .fields([Field::id("id"), Field::string("label", 32).required()]),
1934 );
1935
1936 let error = query
1937 .insert_batch_returning(&[Record::new().set("label", "x")], ReturningTarget::Pk)
1938 .await
1939 .expect_err("MySQL 批量 RETURNING 必须被拒绝");
1940 assert!(
1941 matches!(
1942 error,
1943 BaseError::ConfigError(ref message) if message.contains("insert_batch_returning")
1944 ),
1945 "应返回 ConfigError 并点名入口,实际: {error:?}"
1946 );
1947 }
1948
1949 #[tokio::test]
1951 async fn upsert_batch_returning_rejects_mysql() {
1952 let query = lazy_mysql_query(Table::new("tq_batch_upsert_returning_mysql").fields([
1953 Field::id("id"),
1954 Field::string("option_key", 32).required(),
1955 Field::string("label", 32).required(),
1956 ]));
1957
1958 let error = query
1959 .upsert_batch_returning(
1960 vec![Record::new().set("option_key", "k").set("label", "x")],
1961 &["option_key"],
1962 ReturningTarget::Pk,
1963 )
1964 .await
1965 .expect_err("MySQL 批量 upsert RETURNING 必须被拒绝");
1966 assert!(
1967 matches!(
1968 error,
1969 BaseError::ConfigError(ref message) if message.contains("upsert_batch_returning")
1970 ),
1971 "应返回 ConfigError 并点名入口,实际: {error:?}"
1972 );
1973 }
1974}
1975
1976#[cfg(test)]
1977mod delete_permission_tests {
1978 use super::*;
1979 use crate::table::{Field, Record, Table};
1980 use std::sync::Arc;
1981
1982 fn query_for(table: Table, roles: &[&str]) -> TableQuery {
1983 let definition = table.build().expect("测试表定义应有效");
1984 TableQuery::new(
1985 definition.shared_config(),
1986 Arc::from(
1987 roles
1988 .iter()
1989 .map(|role| (*role).to_string())
1990 .collect::<Vec<String>>(),
1991 ),
1992 None,
1993 )
1994 }
1995
1996 #[tokio::test]
1999 async fn soft_delete_respects_explicit_soft_delete_write_audience() {
2000 let query = query_for(
2001 Table::new("tq_soft_delete_guard").fields([
2002 Field::id("id"),
2003 Field::soft_delete("deleted_at").writable_by(["admin"]),
2004 ]),
2005 &["user"],
2006 );
2007
2008 let error = query
2009 .delete()
2010 .await
2011 .expect_err("无写权限的软删列必须被拒绝");
2012 assert!(
2013 matches!(
2014 error,
2015 BaseError::FieldPermissionDenied(_, ref field, _) if field == "deleted_at"
2016 ),
2017 "应返回 deleted_at 的 FieldPermissionDenied,实际: {error:?}"
2018 );
2019 }
2020
2021 #[tokio::test]
2025 async fn framework_managed_soft_delete_passes_field_permission_guard() {
2026 let query = query_for(
2027 Table::new("tq_soft_delete_framework")
2028 .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2029 &["user"],
2030 )
2031 .where_eq("id", serde_json::json!(1))
2032 .expect("主键条件应有效");
2033
2034 let error = query
2035 .delete()
2036 .await
2037 .expect_err("无连接池应在守卫通过后才报错");
2038 assert!(
2039 matches!(error, BaseError::DatabaseNotInitialized),
2040 "默认软删列不应触发字段权限错误,实际: {error:?}"
2041 );
2042 }
2043
2044 #[tokio::test]
2051 async fn soft_delete_update_without_where_is_rejected() {
2052 let query = query_for(
2053 Table::new("tq_soft_delete_zero_where_update").fields([
2054 Field::id("id"),
2055 Field::string("name", 32),
2056 Field::soft_delete("deleted_at"),
2057 ]),
2058 &["admin"],
2059 );
2060
2061 let error = query
2062 .update(Record::new().set("name", "x"))
2063 .await
2064 .expect_err("软删表零 WHERE 更新必须被拒绝");
2065 assert!(
2066 matches!(error, BaseError::MissingWhereClause(ref op) if op == "UPDATE"),
2067 "应返回 UPDATE 的 MissingWhereClause,实际: {error:?}"
2068 );
2069 }
2070
2071 #[tokio::test]
2073 async fn soft_delete_delete_without_where_is_rejected() {
2074 let query = query_for(
2075 Table::new("tq_soft_delete_zero_where_delete").fields([
2076 Field::id("id"),
2077 Field::string("name", 32),
2078 Field::soft_delete("deleted_at"),
2079 ]),
2080 &["user"],
2081 );
2082
2083 let error = query
2084 .delete()
2085 .await
2086 .expect_err("软删表零 WHERE 删除必须被拒绝");
2087 assert!(
2088 matches!(error, BaseError::MissingWhereClause(ref op) if op == "DELETE"),
2089 "应返回 DELETE 的 MissingWhereClause,实际: {error:?}"
2090 );
2091 }
2092
2093 #[test]
2097 fn soft_delete_zero_where_guard_scope() {
2098 let query = query_for(
2100 Table::new("tq_zero_where_plain").fields([Field::id("id")]),
2101 &["user"],
2102 );
2103 query
2104 .ensure_soft_delete_write_has_where("UPDATE")
2105 .expect("非软删表不应触发守卫");
2106
2107 let query = query_for(
2109 Table::new("tq_zero_where_trashed")
2110 .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2111 &["user"],
2112 )
2113 .with_trashed();
2114 query
2115 .ensure_soft_delete_write_has_where("UPDATE")
2116 .expect("with_trashed 不应触发守卫");
2117
2118 let mut query = query_for(
2120 Table::new("tq_zero_where_any")
2121 .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2122 &["user"],
2123 );
2124 query
2125 .any_conditions
2126 .push(("id".to_string(), vec![serde_json::json!(1)]));
2127 query
2128 .ensure_soft_delete_write_has_where("DELETE")
2129 .expect("where_any 条件应被视为已有 WHERE");
2130
2131 let query = query_for(
2133 Table::new("tq_zero_where_tenant").fields([
2134 Field::id("id"),
2135 Field::bigint("tenant_id").tenant_key(),
2136 Field::soft_delete("deleted_at"),
2137 ]),
2138 &["user"],
2139 )
2140 .scope_tenant("tenant_id", serde_json::json!(7))
2141 .expect("租户条件注入应成功");
2142 query
2143 .ensure_soft_delete_write_has_where("UPDATE")
2144 .expect("租户注入条件应被视为已有 WHERE");
2145 }
2146}