1#![cfg(any(feature = "mysql", feature = "postgres"))]
8
9use super::TableQuery;
10use crate::action::builtin::add::ReturningTarget;
11use crate::database::{AnyTransaction, AnyTransactionKind};
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 self.ensure_same_source(tx)?;
122 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
123 match tx.kind_mut() {
124 #[cfg(feature = "mysql")]
125 AnyTransactionKind::MySql(tx) => {
126 let query = tx.table(&self.table_config.table_ref);
127 self.apply_write_plan(query)?
128 .insert(&data)
129 .await
130 .map_err(BaseError::DatabaseExecuteFailed)?;
131 }
132 #[cfg(feature = "postgres")]
133 AnyTransactionKind::Postgres(tx) => {
134 let query = tx.table(&self.table_config.table_ref);
135 let query =
136 self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
137 query
138 .insert_batch(std::slice::from_ref(&data))
139 .await
140 .map_err(BaseError::DatabaseExecuteFailed)?;
141 }
142 }
143 Ok(1)
144 }
145
146 pub async fn insert_returning(
159 self,
160 data: crate::table::Record,
161 target: ReturningTarget<'_>,
162 ) -> Result<crate::table::Record, BaseError> {
163 if matches!(target, ReturningTarget::Pk) {
164 self.ensure_single_primary_key("insert_returning(ReturningTarget::Pk)")?;
165 }
166 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
167 match self.backend()? {
168 #[cfg(feature = "mysql")]
169 yang_db::BackendKind::MySql => {
170 let primary_key = self.table_config.primary_key.clone();
171 let allowed = match target {
172 ReturningTarget::Pk => true,
173 ReturningTarget::Columns(columns) => {
174 columns.len() == 1 && columns[0] == primary_key.as_str()
175 }
176 ReturningTarget::All => false,
177 };
178 if !allowed {
179 return Err(Self::mysql_returning_unsupported("非整型主键列或整行"));
180 }
181 let value = self.mysql_insert_returning_pk(&data).await?;
182 Ok(crate::table::Record::new().set(primary_key, value))
183 }
184 #[cfg(feature = "postgres")]
185 yang_db::BackendKind::PostgreSql => self.pg_insert_returning(&data, target).await,
186 other => Err(BaseError::ConfigError(format!(
187 "TableQuery 不支持当前数据库后端: {other:?}"
188 ))),
189 }
190 }
191
192 #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
200 pub async fn insert_batch_returning(
201 self,
202 data: &[crate::table::Record],
203 target: ReturningTarget<'_>,
204 ) -> Result<Vec<crate::table::Record>, BaseError> {
205 match self.backend()? {
206 #[cfg(feature = "mysql")]
207 yang_db::BackendKind::MySql => Err(Self::mysql_batch_returning_unsupported(
208 "insert_batch_returning",
209 )),
210 #[cfg(feature = "postgres")]
211 yang_db::BackendKind::PostgreSql => {
212 let Some(rows) = self.prepare_pg_insert_rows(data)? else {
213 return Ok(Vec::new());
214 };
215 let database = self.pg_database()?;
216 let query = self.register_pg_fields(
217 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
218 rows[0].keys(),
219 )?;
220 self.apply_pg_returning_target(query, target)?
221 .insert_batch_returning(&rows)
222 .await
223 .map_err(BaseError::DatabaseExecuteFailed)
224 }
225 other => Err(BaseError::ConfigError(format!(
226 "TableQuery 不支持当前数据库后端: {other:?}"
227 ))),
228 }
229 }
230
231 #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
236 pub async fn insert_batch_returning_in_tx(
237 self,
238 tx: &mut AnyTransaction,
239 data: &[crate::table::Record],
240 target: ReturningTarget<'_>,
241 ) -> Result<Vec<crate::table::Record>, BaseError> {
242 self.ensure_same_source(tx)?;
243 match tx.kind_mut() {
244 #[cfg(feature = "mysql")]
245 AnyTransactionKind::MySql(_) => Err(Self::mysql_batch_returning_unsupported(
246 "insert_batch_returning_in_tx",
247 )),
248 #[cfg(feature = "postgres")]
249 AnyTransactionKind::Postgres(tx) => {
250 let Some(rows) = self.prepare_pg_insert_rows(data)? else {
251 return Ok(Vec::new());
252 };
253 let query = self.register_pg_fields(
254 self.apply_pg_write_plan(tx.table(&self.table_config.table_ref))?,
255 rows[0].keys(),
256 )?;
257 self.apply_pg_returning_target(query, target)?
258 .insert_batch_returning(&rows)
259 .await
260 .map_err(BaseError::DatabaseExecuteFailed)
261 }
262 }
263 }
264
265 #[cfg(feature = "postgres")]
269 fn prepare_pg_insert_rows(
270 &self,
271 records: &[crate::table::Record],
272 ) -> Result<Option<Vec<std::collections::HashMap<String, Value>>>, BaseError> {
273 let mut rows = Vec::with_capacity(records.len());
274 let mut base_keys: Option<std::collections::BTreeSet<String>> = None;
275 for (index, record) in records.iter().enumerate() {
276 let prepared = self.prepare_and_validate_insert(record_into_columns(record.clone()))?;
277 let keys: std::collections::BTreeSet<String> = prepared.keys().cloned().collect();
278 match &base_keys {
279 Some(base) if *base != keys => {
280 return Err(BaseError::ParamInvalid(
281 "data".to_string(),
282 format!(
283 "批量 insert 第 {} 条记录提供的列集与第 1 条不一致",
284 index + 1
285 ),
286 ));
287 }
288 None => base_keys = Some(keys),
289 _ => {}
290 }
291 rows.push(prepared);
292 }
293 Ok((!rows.is_empty()).then_some(rows))
294 }
295
296 pub async fn insert_returning_pk_value(
301 self,
302 data: crate::table::Record,
303 ) -> Result<(u64, Value), BaseError> {
304 self.ensure_single_primary_key("insert_returning_pk_value")?;
305 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
306 match self.backend()? {
307 #[cfg(feature = "mysql")]
308 yang_db::BackendKind::MySql => {
309 let value = self.mysql_insert_returning_pk(&data).await?;
310 Ok((1, value))
311 }
312 #[cfg(feature = "postgres")]
313 yang_db::BackendKind::PostgreSql => {
314 let primary_key = self.table_config.primary_key.clone();
315 let record = self.pg_insert_returning(&data, ReturningTarget::Pk).await?;
316 let value = record.get(&primary_key).cloned().ok_or_else(|| {
317 BaseError::ConfigError(
318 "INSERT ... RETURNING 未返回主键列,无法回填主键".to_string(),
319 )
320 })?;
321 Ok((1, value))
322 }
323 other => Err(BaseError::ConfigError(format!(
324 "TableQuery 不支持当前数据库后端: {other:?}"
325 ))),
326 }
327 }
328
329 pub async fn insert_returning_id(
341 self,
342 data: crate::table::Record,
343 ) -> Result<(u64, u64), BaseError> {
344 self.ensure_integer_primary_key()?;
345 let (affected, value) = self.insert_returning_pk_value(data).await?;
346 let id = json_to_u64(&value).ok_or_else(|| {
347 BaseError::ParamInvalid(
348 "primary_key".to_string(),
349 format!(
350 "insert_returning_id 仅支持整型主键,当前主键值为 {value};\
351 请改用 insert_returning_pk_value() 或 insert_returning(ReturningTarget::Pk)"
352 ),
353 )
354 })?;
355 Ok((affected, id))
356 }
357
358 pub async fn insert_returning_id_in_tx(
363 self,
364 tx: &mut AnyTransaction,
365 data: crate::table::Record,
366 ) -> Result<(u64, u64), BaseError> {
367 self.ensure_same_source(tx)?;
368 self.ensure_integer_primary_key()?;
369 let data = self.prepare_and_validate_insert(record_into_columns(data))?;
370 match tx.kind_mut() {
371 #[cfg(feature = "mysql")]
372 AnyTransactionKind::MySql(tx) => {
373 let query = tx.table(&self.table_config.table_ref);
374 let id = self
375 .apply_write_plan(query)?
376 .insert(&data)
377 .await
378 .map_err(BaseError::DatabaseExecuteFailed)?;
379 Ok((1, id))
380 }
381 #[cfg(feature = "postgres")]
382 AnyTransactionKind::Postgres(tx) => {
383 let primary_key = self.field_ref(&self.table_config.primary_key)?;
384 let query = tx.table(&self.table_config.table_ref);
385 let query =
386 self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
387 let id = query
388 .returning(primary_key)
389 .insert(&data)
390 .await
391 .map_err(BaseError::DatabaseExecuteFailed)?;
392 Ok((1, id))
393 }
394 }
395 }
396
397 fn ensure_integer_primary_key(&self) -> Result<(), BaseError> {
399 let primary_key = self.ensure_single_primary_key("insert_returning_id")?;
400 let config = self.table_config.get_field(primary_key).ok_or_else(|| {
401 BaseError::FieldNotFound(
402 self.table_config.table_name.clone(),
403 primary_key.to_string(),
404 )
405 })?;
406 if matches!(
407 config.field_type,
408 crate::table::FieldType::Integer | crate::table::FieldType::BigInt
409 ) {
410 return Ok(());
411 }
412 Err(BaseError::ParamInvalid(
413 "primary_key".to_string(),
414 format!(
415 "insert_returning_id 仅支持整型主键,当前主键 {}.{primary_key} 为 {:?};\
416 请改用 insert_returning_pk_value() / insert_returning(ReturningTarget::Pk) \
417 取回真实类型主键,或 insert() 并在插入后按业务键查询",
418 self.table_config.table_name, config.field_type
419 ),
420 ))
421 }
422
423 fn ensure_single_primary_key(&self, operation: &str) -> Result<&str, BaseError> {
425 if self.table_config.primary_keys.len() != 1 {
426 return Err(BaseError::ConfigError(format!(
427 "{operation} 仅支持单主键表;表 {} 的主键为 {:?}",
428 self.table_config.table_name, self.table_config.primary_keys
429 )));
430 }
431 Ok(&self.table_config.primary_key)
432 }
433
434 #[cfg(feature = "mysql")]
436 fn mysql_returning_unsupported(what: &str) -> BaseError {
437 BaseError::ConfigError(format!(
438 "MySQL 不支持 INSERT ... RETURNING(请求 {what}):只能取回整型主键;\
439 请改用 insert_returning(ReturningTarget::Pk) 或插入后按业务键查询"
440 ))
441 }
442
443 #[cfg(feature = "mysql")]
445 fn mysql_batch_returning_unsupported(entry: &str) -> BaseError {
446 BaseError::ConfigError(format!(
447 "{entry} 仅支持 PostgreSQL:MySQL 没有 RETURNING,批量写入无法按真实行回填;\
448 请改用 PostgreSQL,或逐条写入后按业务键查询"
449 ))
450 }
451
452 #[cfg(feature = "mysql")]
454 async fn mysql_insert_returning_pk(
455 &self,
456 data: &std::collections::HashMap<String, Value>,
457 ) -> Result<Value, BaseError> {
458 self.ensure_integer_primary_key()?;
459 let primary_key = &self.table_config.primary_key;
460 if let Some(value) = data.get(primary_key).filter(|value| !value.is_null()) {
461 if json_to_u64(value).is_none() {
462 return Err(Self::mysql_returning_unsupported("非整型主键值"));
463 }
464 return Ok(value.clone());
465 }
466 let id = self
467 .compile_db_write_query()?
468 .insert(data)
469 .await
470 .map_err(BaseError::DatabaseExecuteFailed)?;
471 Ok(Value::Number(id.into()))
472 }
473
474 #[cfg(feature = "postgres")]
476 fn apply_pg_returning_target<'a>(
477 &self,
478 query: yang_db::postgres::QueryBuilder<'a>,
479 target: ReturningTarget<'_>,
480 ) -> Result<yang_db::postgres::QueryBuilder<'a>, BaseError> {
481 match target {
482 ReturningTarget::Pk => {
483 self.ensure_single_primary_key("ReturningTarget::Pk")?;
484 Ok(query.returning(self.field_ref(&self.table_config.primary_key)?))
485 }
486 ReturningTarget::All => Ok(query.returning_all()),
487 ReturningTarget::Columns(columns) => {
488 if columns.is_empty() {
489 return Err(BaseError::ParamInvalid(
490 "columns".to_string(),
491 "ReturningTarget::Columns 至少需要一列".to_string(),
492 ));
493 }
494 for name in columns {
495 if !self.table_config.fields.contains_key(*name) {
496 return Err(BaseError::FieldNotFound(
497 self.table_config.table_name.clone(),
498 (*name).to_string(),
499 ));
500 }
501 }
502 let refs = self.pg_field_refs(columns)?;
503 Ok(query.returning_columns(&refs))
504 }
505 }
506 }
507
508 #[cfg(feature = "postgres")]
510 async fn pg_insert_returning(
511 &self,
512 data: &std::collections::HashMap<String, Value>,
513 target: ReturningTarget<'_>,
514 ) -> Result<crate::table::Record, BaseError> {
515 let database = self.pg_database()?;
516 let query = self.register_pg_fields(
517 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
518 data.keys(),
519 )?;
520 self.apply_pg_returning_target(query, target)?
521 .insert_returning(data)
522 .await
523 .map_err(BaseError::DatabaseExecuteFailed)
524 }
525
526 #[cfg(feature = "postgres")]
541 pub async fn upsert_batch(
542 self,
543 rows: Vec<crate::table::Record>,
544 conflict_columns: &[&str],
545 ) -> Result<u64, BaseError> {
546 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
547 return Ok(0);
548 };
549 self.execute_pg_upsert_batch(prepared, conflict_columns, None, None, false)
550 .await
551 }
552
553 #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
561 pub async fn upsert_batch_returning(
562 self,
563 rows: Vec<crate::table::Record>,
564 conflict_columns: &[&str],
565 target: ReturningTarget<'_>,
566 ) -> Result<Vec<crate::table::Record>, BaseError> {
567 match self.backend()? {
568 #[cfg(feature = "mysql")]
569 yang_db::BackendKind::MySql => Err(Self::mysql_batch_returning_unsupported(
570 "upsert_batch_returning",
571 )),
572 #[cfg(feature = "postgres")]
573 yang_db::BackendKind::PostgreSql => {
574 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
575 return Ok(Vec::new());
576 };
577 let database = self.pg_database()?;
578 let conflicts = self.pg_field_refs(conflict_columns)?;
579 let query = self.register_pg_fields(
580 database.table(&self.table_config.table_ref),
581 prepared.rows[0].keys(),
582 )?;
583 let columns = self.resolve_pg_update_columns(&prepared, conflict_columns, None)?;
584 let query = if columns.is_empty() {
585 query.do_nothing()
586 } else {
587 let names: Vec<&str> = columns.iter().map(String::as_str).collect();
588 query.update_columns(&self.pg_field_refs(&names)?)
589 };
590 self.apply_pg_returning_target(query, target)?
591 .upsert_batch_returning(&prepared.rows, &conflicts)
592 .await
593 .map_err(BaseError::DatabaseExecuteFailed)
594 }
595 other => Err(BaseError::ConfigError(format!(
596 "TableQuery 不支持当前数据库后端: {other:?}"
597 ))),
598 }
599 }
600
601 #[cfg(feature = "postgres")]
609 pub async fn upsert_batch_with_update_columns(
610 self,
611 rows: Vec<crate::table::Record>,
612 conflict_columns: &[&str],
613 update_columns: &[&str],
614 ) -> Result<u64, BaseError> {
615 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
616 return Ok(0);
617 };
618 self.execute_pg_upsert_batch(
619 prepared,
620 conflict_columns,
621 None,
622 Some(update_columns),
623 false,
624 )
625 .await
626 }
627
628 #[cfg(feature = "postgres")]
633 pub async fn upsert_batch_do_nothing(
634 self,
635 rows: Vec<crate::table::Record>,
636 conflict_columns: &[&str],
637 ) -> Result<u64, BaseError> {
638 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
639 return Ok(0);
640 };
641 self.execute_pg_upsert_batch(prepared, conflict_columns, None, None, true)
642 .await
643 }
644
645 #[cfg(feature = "postgres")]
655 pub async fn upsert_batch_with_conflict_predicate(
656 self,
657 rows: Vec<crate::table::Record>,
658 conflict_columns: &[&str],
659 predicate: Option<&str>,
660 ) -> Result<u64, BaseError> {
661 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
662 return Ok(0);
663 };
664 self.execute_pg_upsert_batch(prepared, conflict_columns, predicate, None, false)
665 .await
666 }
667
668 pub async fn upsert_batch_in_tx(
698 self,
699 tx: &mut AnyTransaction,
700 rows: Vec<crate::table::Record>,
701 columns: &[&str],
702 ) -> Result<u64, BaseError> {
703 self.ensure_same_source(tx)?;
704 match tx.kind_mut() {
705 #[cfg(feature = "mysql")]
706 AnyTransactionKind::MySql(tx) => {
707 let Some(batch) = self.plan_upsert_batch(rows, columns)? else {
709 return Ok(0);
710 };
711 tx.table(&self.table_config.table_ref)
715 .upsert_batch(&batch.rows, &batch.tail)
716 .await
717 .map_err(BaseError::DatabaseExecuteFailed)
718 }
719 #[cfg(feature = "postgres")]
720 AnyTransactionKind::Postgres(tx) => {
721 let Some(prepared) = self.prepare_pg_upsert_rows(rows, columns)? else {
722 return Ok(0);
723 };
724 self.execute_pg_upsert_batch_in_tx(tx, &prepared, columns, None, None, false)
725 .await
726 }
727 }
728 }
729
730 #[cfg(feature = "postgres")]
735 pub async fn upsert_batch_in_tx_with_update_columns(
736 self,
737 tx: &mut AnyTransaction,
738 rows: Vec<crate::table::Record>,
739 conflict_columns: &[&str],
740 update_columns: &[&str],
741 ) -> Result<u64, BaseError> {
742 self.ensure_same_source(tx)?;
743 match tx.kind_mut() {
744 AnyTransactionKind::Postgres(tx) => {
745 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
746 return Ok(0);
747 };
748 self.execute_pg_upsert_batch_in_tx(
749 tx,
750 &prepared,
751 conflict_columns,
752 None,
753 Some(update_columns),
754 false,
755 )
756 .await
757 }
758 #[cfg(feature = "mysql")]
759 AnyTransactionKind::MySql(_) => Err(BaseError::ConfigError(
760 "upsert_batch_in_tx_with_update_columns 仅支持 PostgreSQL;MySQL 请使用 upsert_batch_in_tx(rows, update_columns) 的 ON DUPLICATE KEY UPDATE 语义"
761 .to_string(),
762 )),
763 }
764 }
765
766 #[cfg(feature = "postgres")]
773 pub async fn upsert_batch_do_nothing_in_tx(
774 self,
775 tx: &mut AnyTransaction,
776 rows: Vec<crate::table::Record>,
777 conflict_columns: &[&str],
778 ) -> Result<u64, BaseError> {
779 self.ensure_same_source(tx)?;
780 match tx.kind_mut() {
781 AnyTransactionKind::Postgres(tx) => {
782 let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
783 return Ok(0);
784 };
785 self.execute_pg_upsert_batch_in_tx(tx, &prepared, conflict_columns, None, None, true)
786 .await
787 }
788 #[cfg(feature = "mysql")]
789 AnyTransactionKind::MySql(_) => Err(BaseError::ConfigError(
790 "upsert_batch_do_nothing_in_tx 仅支持 PostgreSQL;MySQL 请使用 upsert_batch_in_tx 的 ON DUPLICATE KEY UPDATE 语义"
791 .to_string(),
792 )),
793 }
794 }
795
796 pub async fn upsert_batch_in_tx_with_conflict_predicate(
808 self,
809 tx: &mut AnyTransaction,
810 rows: Vec<crate::table::Record>,
811 columns: &[&str],
812 predicate: Option<&str>,
813 ) -> Result<u64, BaseError> {
814 self.ensure_same_source(tx)?;
815 match tx.kind_mut() {
816 #[cfg(feature = "mysql")]
817 AnyTransactionKind::MySql(tx) => {
818 if let Some(predicate) = predicate {
819 return Err(BaseError::ConfigError(format!(
820 "MySQL 不支持 ON DUPLICATE KEY UPDATE 的冲突谓词(收到 `{predicate}`);\
821 请改用 PostgreSQL,或去掉谓词后使用 upsert_batch_in_tx"
822 )));
823 }
824 let Some(batch) = self.plan_upsert_batch(rows, columns)? else {
825 return Ok(0);
826 };
827 tx.table(&self.table_config.table_ref)
828 .upsert_batch(&batch.rows, &batch.tail)
829 .await
830 .map_err(BaseError::DatabaseExecuteFailed)
831 }
832 #[cfg(feature = "postgres")]
833 AnyTransactionKind::Postgres(tx) => {
834 let Some(prepared) = self.prepare_pg_upsert_rows(rows, columns)? else {
835 return Ok(0);
836 };
837 self.execute_pg_upsert_batch_in_tx(tx, &prepared, columns, predicate, None, false)
838 .await
839 }
840 }
841 }
842
843 #[cfg(feature = "postgres")]
849 fn prepare_pg_upsert_rows(
850 &self,
851 rows: Vec<crate::table::Record>,
852 conflict_columns: &[&str],
853 ) -> Result<Option<PreparedPgUpsert>, BaseError> {
854 let total = rows.len();
855 if total == 0 {
856 return Ok(None);
857 }
858
859 if !self.query_params.where_conditions.is_empty() || !self.any_conditions.is_empty() {
864 return Err(BaseError::ParamInvalid(
865 "where".to_string(),
866 "批量 upsert 不支持 where / where_any 条件:ON CONFLICT 没有 WHERE,条件会被静默忽略"
867 .to_string(),
868 ));
869 }
870 if self.table_config.soft_delete_field.is_some() && !self.include_trashed {
871 return Err(BaseError::ParamInvalid(
872 "soft_delete_field".to_string(),
873 "该表配置了软删字段,而批量 upsert 无法表达软删守卫;要么改用 update_in_tx,要么先 with_trashed()"
874 .to_string(),
875 ));
876 }
877 if conflict_columns.is_empty() {
878 return Err(BaseError::ParamInvalid(
879 "conflict_columns".to_string(),
880 "PostgreSQL 批量 upsert 必须显式指定冲突列(ON CONFLICT 目标)".to_string(),
881 ));
882 }
883 for name in conflict_columns {
884 if !self.table_config.fields.contains_key(*name) {
885 return Err(BaseError::FieldNotFound(
886 self.table_config.table_name.clone(),
887 (*name).to_string(),
888 ));
889 }
890 }
891 if let Some(tenant_field) = self.tenant_key_field() {
894 if !conflict_columns.contains(&tenant_field) {
895 return Err(BaseError::ParamInvalid(
896 "conflict_columns".to_string(),
897 format!(
898 "表 {} 声明了租户字段 `{tenant_field}`,批量 upsert 的冲突列必须包含该字段,否则会跨租户改写",
899 self.table_config.table_name
900 ),
901 ));
902 }
903 }
904
905 let mut prepared_rows = Vec::with_capacity(total);
906 let mut base_keys: Option<std::collections::BTreeSet<String>> = None;
907 let mut provided_columns = std::collections::BTreeSet::new();
908 for (index, record) in rows.into_iter().enumerate() {
909 let provided: std::collections::BTreeSet<String> =
912 record.as_map().keys().cloned().collect();
913 if index == 0 {
914 provided_columns = provided.clone();
915 } else if provided != provided_columns {
916 return Err(BaseError::ParamInvalid(
917 "rows".to_string(),
918 format!(
919 "批量 upsert 第 {} 条记录提供的列集与第 1 条不一致",
920 index + 1
921 ),
922 ));
923 }
924
925 let prepared = self.prepare_and_validate_insert(record_into_columns(record))?;
926 let keys: std::collections::BTreeSet<String> = prepared.keys().cloned().collect();
927 match &base_keys {
928 Some(base) if *base != keys => {
929 return Err(BaseError::ParamInvalid(
930 "rows".to_string(),
931 format!(
932 "批量 upsert 第 {} 条记录提供的列集与第 1 条不一致",
933 index + 1
934 ),
935 ));
936 }
937 None => base_keys = Some(keys),
938 _ => {}
939 }
940 for name in conflict_columns {
941 if !prepared.contains_key(*name) {
942 return Err(BaseError::ParamInvalid(
943 "conflict_columns".to_string(),
944 format!("冲突列 `{name}` 不在第 {} 条待写记录里", index + 1),
945 ));
946 }
947 }
948 prepared_rows.push(prepared);
949 }
950
951 Ok(Some(PreparedPgUpsert {
952 rows: prepared_rows,
953 provided_columns,
954 }))
955 }
956
957 #[cfg(feature = "postgres")]
959 fn pg_field_refs(&self, columns: &[&str]) -> Result<Vec<&yang_db::FieldRef>, BaseError> {
960 columns.iter().map(|name| self.field_ref(name)).collect()
961 }
962
963 #[cfg(feature = "postgres")]
965 fn tenant_key_field(&self) -> Option<&str> {
966 self.table_config
967 .fields
968 .iter()
969 .find_map(|(name, field)| field.tenant_key.then_some(name.as_str()))
970 }
971
972 fn is_framework_owned_column(&self, name: &str) -> bool {
974 if self
975 .table_config
976 .primary_keys
977 .iter()
978 .any(|primary| primary == name)
979 {
980 return true;
981 }
982 if let Some((tenant_field, _)) = &self.tenant_scope {
983 if tenant_field == name {
984 return true;
985 }
986 }
987 if self
988 .table_config
989 .get_field(name)
990 .is_some_and(|field| field.tenant_key || field.auto_increment)
991 {
992 return true;
993 }
994 if let Some(ts) = &self.table_config.timestamp_fields {
995 if ts.created_at.as_deref() == Some(name) || ts.deleted_at.as_deref() == Some(name) {
996 return true;
997 }
998 }
999 matches!(name, "created_at" | "tenant_id")
1000 }
1001
1002 #[cfg(feature = "postgres")]
1004 fn is_default_upsert_excluded_column(&self, name: &str) -> bool {
1005 self.is_framework_owned_column(name) || matches!(name, "source_file" | "company")
1006 }
1007
1008 #[cfg(feature = "postgres")]
1013 fn default_pg_update_columns(
1014 &self,
1015 insert_columns: &[String],
1016 conflict_columns: &[&str],
1017 ) -> Vec<String> {
1018 insert_columns
1019 .iter()
1020 .filter(|name| !conflict_columns.contains(&name.as_str()))
1021 .filter(|name| !self.is_default_upsert_excluded_column(name))
1022 .cloned()
1023 .collect()
1024 }
1025
1026 #[cfg(feature = "postgres")]
1028 fn validate_pg_update_columns(
1029 &self,
1030 provided_columns: &std::collections::BTreeSet<String>,
1031 conflict_columns: &[&str],
1032 update_columns: &[&str],
1033 ) -> Result<Vec<String>, BaseError> {
1034 if update_columns.is_empty() {
1035 return Err(BaseError::ParamInvalid(
1036 "update_columns".to_string(),
1037 "批量 upsert 至少需要一个可更新列".to_string(),
1038 ));
1039 }
1040 let mut columns = Vec::with_capacity(update_columns.len());
1041 for name in update_columns {
1042 if !self.table_config.fields.contains_key(*name) {
1043 return Err(BaseError::FieldNotFound(
1044 self.table_config.table_name.clone(),
1045 (*name).to_string(),
1046 ));
1047 }
1048 if conflict_columns.contains(name) {
1049 return Err(BaseError::ParamInvalid(
1050 "update_columns".to_string(),
1051 format!("更新列 `{name}` 是冲突列,不能出现在 DO UPDATE SET 里"),
1052 ));
1053 }
1054 if !provided_columns.contains(*name) {
1055 return Err(BaseError::ParamInvalid(
1056 "update_columns".to_string(),
1057 format!("更新列 `{name}` 不在调用方提供的待写列里"),
1058 ));
1059 }
1060 if self.is_framework_owned_column(name) {
1061 return Err(BaseError::ParamInvalid(
1062 "update_columns".to_string(),
1063 format!("更新列 `{name}` 是主键/租户/创建时间等框架保护列,不能被 upsert 覆盖"),
1064 ));
1065 }
1066 if !columns.iter().any(|existing| existing == name) {
1067 columns.push((*name).to_string());
1068 }
1069 }
1070 if let Some(updated_at) = self
1072 .table_config
1073 .timestamp_fields
1074 .as_ref()
1075 .and_then(|fields| fields.updated_at.as_ref())
1076 .filter(|name| self.table_config.fields.contains_key(*name))
1077 {
1078 if !columns.iter().any(|existing| existing == updated_at) {
1079 columns.push(updated_at.clone());
1080 }
1081 }
1082 Ok(columns)
1083 }
1084
1085 #[cfg(feature = "postgres")]
1087 fn resolve_pg_update_columns(
1088 &self,
1089 prepared: &PreparedPgUpsert,
1090 conflict_columns: &[&str],
1091 update_columns: Option<&[&str]>,
1092 ) -> Result<Vec<String>, BaseError> {
1093 match update_columns {
1094 Some(explicit) => self.validate_pg_update_columns(
1095 &prepared.provided_columns,
1096 conflict_columns,
1097 explicit,
1098 ),
1099 None => {
1100 let insert_columns: Vec<String> = prepared.rows[0].keys().cloned().collect();
1101 Ok(self.default_pg_update_columns(&insert_columns, conflict_columns))
1102 }
1103 }
1104 }
1105
1106 #[cfg(feature = "postgres")]
1108 async fn execute_pg_upsert_batch(
1109 self,
1110 prepared: PreparedPgUpsert,
1111 conflict_columns: &[&str],
1112 conflict_predicate: Option<&str>,
1113 update_columns: Option<&[&str]>,
1114 do_nothing: bool,
1115 ) -> Result<u64, BaseError> {
1116 let database = self.pg_database()?;
1117 let conflicts = self.pg_field_refs(conflict_columns)?;
1118 let query = self.register_pg_fields(
1119 database.table(&self.table_config.table_ref),
1120 prepared.rows[0].keys(),
1121 )?;
1122 let query = match conflict_predicate {
1123 Some(predicate) => query.on_conflict_with_predicate(&conflicts, predicate),
1124 None => query,
1125 };
1126 let query = if do_nothing {
1127 query.do_nothing()
1128 } else {
1129 let columns =
1130 self.resolve_pg_update_columns(&prepared, conflict_columns, update_columns)?;
1131 if columns.is_empty() {
1132 query.do_nothing()
1134 } else {
1135 let names: Vec<&str> = columns.iter().map(String::as_str).collect();
1136 let refs = self.pg_field_refs(&names)?;
1137 query.update_columns(&refs)
1138 }
1139 };
1140 query
1141 .upsert_batch(&prepared.rows, &conflicts)
1142 .await
1143 .map_err(BaseError::DatabaseExecuteFailed)
1144 }
1145
1146 #[cfg(feature = "postgres")]
1148 async fn execute_pg_upsert_batch_in_tx(
1149 &self,
1150 tx: &mut yang_db::postgres::Transaction,
1151 prepared: &PreparedPgUpsert,
1152 conflict_columns: &[&str],
1153 conflict_predicate: Option<&str>,
1154 update_columns: Option<&[&str]>,
1155 do_nothing: bool,
1156 ) -> Result<u64, BaseError> {
1157 let conflicts = self.pg_field_refs(conflict_columns)?;
1158 let query = self.register_pg_fields(
1159 tx.table(&self.table_config.table_ref),
1160 prepared.rows[0].keys(),
1161 )?;
1162 let query = match conflict_predicate {
1163 Some(predicate) => query.on_conflict_with_predicate(&conflicts, predicate),
1164 None => query,
1165 };
1166 let query = if do_nothing {
1167 query.do_nothing()
1168 } else {
1169 let columns =
1170 self.resolve_pg_update_columns(prepared, conflict_columns, update_columns)?;
1171 if columns.is_empty() {
1172 query.do_nothing()
1173 } else {
1174 let names: Vec<&str> = columns.iter().map(String::as_str).collect();
1175 let refs = self.pg_field_refs(&names)?;
1176 query.update_columns(&refs)
1177 }
1178 };
1179 query
1180 .upsert_batch(&prepared.rows, &conflicts)
1181 .await
1182 .map_err(BaseError::DatabaseExecuteFailed)
1183 }
1184
1185 #[cfg(feature = "mysql")]
1190 fn plan_upsert_batch(
1191 &self,
1192 rows: Vec<crate::table::Record>,
1193 update_columns: &[&str],
1194 ) -> Result<Option<PreparedUpsertBatch>, BaseError> {
1195 let total = rows.len();
1196 let mut records = rows.into_iter();
1197 let Some(first) = records.next() else {
1199 return Ok(None);
1200 };
1201
1202 if !self.query_params.where_conditions.is_empty() {
1204 return Err(BaseError::ParamInvalid(
1205 "where".to_string(),
1206 "批量 upsert 不支持 where 条件:ON DUPLICATE KEY UPDATE 没有 WHERE,条件会被静默忽略"
1207 .to_string(),
1208 ));
1209 }
1210 if self.table_config.soft_delete_field.is_some() && !self.include_trashed {
1213 return Err(BaseError::ParamInvalid(
1214 "soft_delete_field".to_string(),
1215 "该表配置了软删字段,而批量 upsert 无法表达软删守卫;要么改用 update_in_tx,要么先 with_trashed()"
1216 .to_string(),
1217 ));
1218 }
1219
1220 let first_provided: std::collections::BTreeSet<String> =
1224 first.as_map().keys().cloned().collect();
1225 let first_prepared = self.prepare_and_validate_insert(record_into_columns(first))?;
1226 let first_prepared_keys: std::collections::BTreeSet<String> =
1227 first_prepared.keys().cloned().collect();
1228
1229 let mut prepared_rows = Vec::with_capacity(total);
1230 prepared_rows.push(first_prepared);
1231 for (offset, record) in records.enumerate() {
1232 let provided: std::collections::BTreeSet<String> =
1233 record.as_map().keys().cloned().collect();
1234 let prepared = self.prepare_and_validate_insert(record_into_columns(record))?;
1235 let prepared_keys: std::collections::BTreeSet<String> =
1236 prepared.keys().cloned().collect();
1237 let row_number = offset + 2;
1239 if provided != first_provided {
1242 return Err(BaseError::ParamInvalid(
1243 "rows".to_string(),
1244 format!("批量 upsert 第 {row_number} 条记录提供的列集与第 1 条不一致"),
1245 ));
1246 }
1247 if prepared_keys != first_prepared_keys {
1249 return Err(BaseError::ParamInvalid(
1250 "rows".to_string(),
1251 format!("批量 upsert 第 {row_number} 条记录提供的列集与第 1 条不一致"),
1252 ));
1253 }
1254 prepared_rows.push(prepared);
1255 }
1256
1257 if update_columns.is_empty() {
1258 return Err(BaseError::ParamInvalid(
1259 "update_columns".to_string(),
1260 "批量 upsert 至少需要一个可更新列(ON DUPLICATE KEY UPDATE 的赋值列)".to_string(),
1261 ));
1262 }
1263 for name in update_columns {
1264 if !first_provided.contains(*name) {
1269 return Err(BaseError::ParamInvalid(
1270 "update_columns".to_string(),
1271 format!(
1272 "赋值列 `{name}` 不在调用方提供的列里(框架补出来的默认值与 created_at 不能当赋值列)"
1273 ),
1274 ));
1275 }
1276 if self
1277 .table_config
1278 .get_field(name)
1279 .is_some_and(|field| field.auto_increment)
1280 {
1281 return Err(BaseError::ParamInvalid(
1282 "update_columns".to_string(),
1283 format!("赋值列 `{name}` 是自增列,不能出现在 ON DUPLICATE KEY UPDATE 里"),
1284 ));
1285 }
1286 }
1287 for name in update_columns {
1290 if self.is_framework_owned_column(name) {
1291 return Err(BaseError::ParamInvalid(
1292 "update_columns".to_string(),
1293 format!("赋值列 `{name}` 是主键/租户/创建时间等框架保护列,不能被 upsert 覆盖"),
1294 ));
1295 }
1296 }
1297
1298 let mut tail: Vec<String> = Vec::with_capacity(update_columns.len() + 1);
1301 for name in update_columns {
1302 if !tail.iter().any(|existing| existing.as_str() == *name) {
1303 tail.push((*name).to_string());
1304 }
1305 }
1306 if let Some(updated_at) = self
1307 .table_config
1308 .timestamp_fields
1309 .as_ref()
1310 .and_then(|fields| fields.updated_at.as_ref())
1311 .filter(|name| self.table_config.fields.contains_key(*name))
1312 {
1313 if !tail.iter().any(|existing| existing == updated_at) {
1314 tail.push(updated_at.clone());
1315 }
1316 }
1317
1318 Ok(Some(PreparedUpsertBatch {
1319 rows: prepared_rows,
1320 tail,
1321 }))
1322 }
1323
1324 pub(crate) fn prepare_and_validate_insert(
1333 &self,
1334 data: std::collections::HashMap<String, Value>,
1335 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1336 let mut prepared = data;
1337
1338 if let Some((field, value)) = &self.tenant_scope {
1340 if prepared.contains_key(field) {
1341 return Err(BaseError::PermissionDenied(format!(
1342 "禁止显式写入租户字段: {field}"
1343 )));
1344 }
1345 prepared.insert(field.clone(), value.clone());
1346 }
1347
1348 for (field_name, value) in &prepared {
1351 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
1352 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
1353 })?;
1354 let omitted_auto_increment = field_config.auto_increment && value.is_null();
1355 let injected_tenant = self
1356 .tenant_scope
1357 .as_ref()
1358 .is_some_and(|(tenant_field, _)| tenant_field == field_name);
1359 if !injected_tenant
1360 && !omitted_auto_increment
1361 && !field_config.permissions.can_write(&self.user_roles_set)
1362 {
1363 return Err(BaseError::FieldPermissionDenied(
1364 self.table_config.table_name.clone(),
1365 field_name.clone(),
1366 "用户无写入权限".to_string(),
1367 ));
1368 }
1369 }
1370
1371 for (field_name, field_config) in &self.table_config.fields {
1373 if field_config.auto_increment
1374 && prepared
1375 .get(field_name)
1376 .map(serde_json::Value::is_null)
1377 .unwrap_or(true)
1378 {
1379 prepared.remove(field_name);
1380 }
1381 }
1382
1383 for (field_name, field_config) in &self.table_config.fields {
1385 if field_config.auto_increment {
1386 continue;
1387 }
1388 if let Some(default) = &field_config.default_value {
1389 if !prepared.contains_key(field_name) {
1390 prepared.insert(field_name.clone(), default.clone());
1391 }
1392 }
1393 }
1394
1395 if let Some(ts) = &self.table_config.timestamp_fields {
1397 let now = chrono::Utc::now().timestamp();
1398 for ts_field in [&ts.created_at, &ts.updated_at].into_iter().flatten() {
1399 if self.table_config.fields.contains_key(ts_field) {
1400 let missing = prepared.get(ts_field).map(|v| v.is_null()).unwrap_or(true);
1401 if missing {
1402 prepared.insert(ts_field.clone(), Value::Number(now.into()));
1403 }
1404 }
1405 }
1406 }
1407
1408 for (field_name, field_config) in &self.table_config.fields {
1410 if !field_config.permissions.can_write(&self.user_roles_set) {
1411 continue;
1412 }
1413 if field_config.auto_increment && !prepared.contains_key(field_name) {
1414 continue;
1415 }
1416 let value = prepared.get(field_name).unwrap_or(&Value::Null);
1417 field_config.validate(value, &self.regex_cache)?;
1418 }
1419
1420 Ok(prepared)
1421 }
1422
1423 fn ensure_soft_delete_write_has_where(&self, op: &str) -> Result<(), BaseError> {
1443 if self.include_trashed || self.table_config.soft_delete_field.is_none() {
1444 return Ok(());
1445 }
1446 if self.query_params.where_conditions.is_empty() && self.any_conditions.is_empty() {
1447 return Err(BaseError::MissingWhereClause(op.to_string()));
1448 }
1449 Ok(())
1450 }
1451
1452 pub async fn update(self, data: crate::table::Record) -> Result<u64, BaseError> {
1461 let data = self.prepare_update_data(record_into_columns(data))?;
1462 self.ensure_soft_delete_write_has_where("UPDATE")?;
1465 match self.backend()? {
1466 #[cfg(feature = "mysql")]
1467 yang_db::BackendKind::MySql => self
1468 .compile_db_write_query()?
1469 .update(&data)
1470 .await
1471 .map_err(BaseError::DatabaseExecuteFailed),
1472 #[cfg(feature = "postgres")]
1473 yang_db::BackendKind::PostgreSql => {
1474 let database = self.pg_database()?;
1475 let query = self.register_pg_fields(
1476 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
1477 data.keys(),
1478 )?;
1479 query
1480 .update(&data)
1481 .await
1482 .map_err(BaseError::DatabaseExecuteFailed)
1483 }
1484 other => Err(BaseError::ConfigError(format!(
1485 "TableQuery 不支持当前数据库后端: {other:?}"
1486 ))),
1487 }
1488 }
1489
1490 pub async fn update_in_tx(
1495 self,
1496 tx: &mut AnyTransaction,
1497 data: crate::table::Record,
1498 ) -> Result<u64, BaseError> {
1499 self.ensure_same_source(tx)?;
1500 let data = self.prepare_update_data(record_into_columns(data))?;
1501 self.ensure_soft_delete_write_has_where("UPDATE")?;
1502 match tx.kind_mut() {
1503 #[cfg(feature = "mysql")]
1504 AnyTransactionKind::MySql(tx) => {
1505 let query = tx.table(&self.table_config.table_ref);
1506 self.apply_write_plan(query)?
1507 .update(&data)
1508 .await
1509 .map_err(BaseError::DatabaseExecuteFailed)
1510 }
1511 #[cfg(feature = "postgres")]
1512 AnyTransactionKind::Postgres(tx) => {
1513 let query = tx.table(&self.table_config.table_ref);
1514 let query =
1515 self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
1516 query
1517 .update(&data)
1518 .await
1519 .map_err(BaseError::DatabaseExecuteFailed)
1520 }
1521 }
1522 }
1523
1524 fn prepare_update_data(
1525 &self,
1526 data: std::collections::HashMap<String, Value>,
1527 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1528 self.validate_update_data(&data)?;
1529 self.with_updated_timestamp(data)
1530 }
1531
1532 fn with_updated_timestamp(
1533 &self,
1534 mut data: std::collections::HashMap<String, Value>,
1535 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1536 if data.is_empty() {
1537 return Err(BaseError::ParamInvalid(
1538 "data".to_string(),
1539 "无可更新字段".to_string(),
1540 ));
1541 }
1542 if let Some(updated_at) = self
1543 .table_config
1544 .timestamp_fields
1545 .as_ref()
1546 .and_then(|fields| fields.updated_at.as_ref())
1547 .filter(|name| self.table_config.fields.contains_key(*name))
1548 {
1549 data.insert(
1550 updated_at.clone(),
1551 Value::Number(chrono::Utc::now().timestamp().into()),
1552 );
1553 }
1554 Ok(data)
1555 }
1556
1557 #[cfg(test)]
1559 pub fn validate_update_data(
1560 &self,
1561 data: &std::collections::HashMap<String, Value>,
1562 ) -> Result<(), BaseError> {
1563 self.validate_update_data_impl(data)
1564 }
1565
1566 #[cfg(not(test))]
1568 fn validate_update_data(
1569 &self,
1570 data: &std::collections::HashMap<String, Value>,
1571 ) -> Result<(), BaseError> {
1572 self.validate_update_data_impl(data)
1573 }
1574
1575 fn validate_update_data_impl(
1577 &self,
1578 data: &std::collections::HashMap<String, Value>,
1579 ) -> Result<(), BaseError> {
1580 if data.is_empty() {
1581 return Err(BaseError::ParamInvalid(
1582 "data".to_string(),
1583 "至少需要一个更新字段".to_string(),
1584 ));
1585 }
1586 self.validate_update_fields(data, None)
1587 }
1588
1589 fn validate_update_fields(
1591 &self,
1592 data: &std::collections::HashMap<String, Value>,
1593 skip: Option<&str>,
1594 ) -> Result<(), BaseError> {
1595 for (field_name, value) in data {
1597 if skip.is_some_and(|name| name == field_name) {
1598 continue;
1599 }
1600 if self
1601 .tenant_scope
1602 .as_ref()
1603 .is_some_and(|(tenant_field, _)| tenant_field == field_name)
1604 {
1605 return Err(BaseError::PermissionDenied(format!(
1606 "禁止修改租户字段: {field_name}"
1607 )));
1608 }
1609 let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
1611 BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
1612 })?;
1613
1614 if !field_config.permissions.can_write(&self.user_roles_set) {
1616 return Err(BaseError::FieldPermissionDenied(
1617 self.table_config.table_name.clone(),
1618 field_name.clone(),
1619 "用户无写入权限".to_string(),
1620 ));
1621 }
1622
1623 field_config.validate(value, &self.regex_cache)?;
1626 }
1627
1628 Ok(())
1629 }
1630
1631 fn prepare_soft_delete_data(
1637 &self,
1638 data: std::collections::HashMap<String, Value>,
1639 ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1640 let framework_managed = self.table_config.soft_delete_field.as_ref().filter(|name| {
1641 self.table_config
1642 .get_field(name)
1643 .is_some_and(|field| matches!(field.permissions.writable, Audience::Nobody))
1644 });
1645 self.validate_update_fields(&data, framework_managed.map(String::as_str))?;
1646 self.with_updated_timestamp(data)
1647 }
1648
1649 #[allow(clippy::type_complexity)]
1655 #[cfg(all(test, feature = "mysql"))]
1656 pub fn upsert_batch_plan_for_test(
1657 &self,
1658 rows: Vec<crate::table::Record>,
1659 update_columns: &[&str],
1660 ) -> Result<Option<(Vec<std::collections::HashMap<String, Value>>, Vec<String>)>, BaseError>
1661 {
1662 Ok(self
1663 .plan_upsert_batch(rows, update_columns)?
1664 .map(|batch| (batch.rows, batch.tail)))
1665 }
1666
1667 pub async fn delete(self) -> Result<u64, BaseError> {
1674 if let Some(soft_delete_field) = self.table_config.soft_delete_field.clone() {
1675 let data = self.prepare_soft_delete_data(std::collections::HashMap::from([(
1676 soft_delete_field,
1677 Value::Number(chrono::Utc::now().timestamp().into()),
1678 )]))?;
1679 self.ensure_soft_delete_write_has_where("DELETE")?;
1682 return self.execute_soft_delete(data).await;
1683 }
1684 self.execute_physical_delete().await
1685 }
1686
1687 async fn execute_soft_delete(
1689 self,
1690 data: std::collections::HashMap<String, Value>,
1691 ) -> Result<u64, BaseError> {
1692 match self.backend()? {
1693 #[cfg(feature = "mysql")]
1694 yang_db::BackendKind::MySql => self
1695 .compile_db_write_query()?
1696 .update(&data)
1697 .await
1698 .map_err(BaseError::DatabaseExecuteFailed),
1699 #[cfg(feature = "postgres")]
1700 yang_db::BackendKind::PostgreSql => {
1701 let database = self.pg_database()?;
1702 let query = self.register_pg_fields(
1703 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
1704 data.keys(),
1705 )?;
1706 query
1707 .update(&data)
1708 .await
1709 .map_err(BaseError::DatabaseExecuteFailed)
1710 }
1711 other => Err(BaseError::ConfigError(format!(
1712 "TableQuery 不支持当前数据库后端: {other:?}"
1713 ))),
1714 }
1715 }
1716
1717 async fn execute_physical_delete(self) -> Result<u64, BaseError> {
1719 match self.backend()? {
1720 #[cfg(feature = "mysql")]
1721 yang_db::BackendKind::MySql => self
1722 .compile_db_write_query()?
1723 .delete()
1724 .await
1725 .map_err(BaseError::DatabaseExecuteFailed),
1726 #[cfg(feature = "postgres")]
1727 yang_db::BackendKind::PostgreSql => {
1728 let database = self.pg_database()?;
1729 self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?
1730 .delete()
1731 .await
1732 .map_err(BaseError::DatabaseExecuteFailed)
1733 }
1734 other => Err(BaseError::ConfigError(format!(
1735 "TableQuery 不支持当前数据库后端: {other:?}"
1736 ))),
1737 }
1738 }
1739
1740 pub async fn delete_in_tx(self, tx: &mut AnyTransaction) -> Result<u64, BaseError> {
1745 self.ensure_same_source(tx)?;
1746 let soft_delete_data = self
1748 .table_config
1749 .soft_delete_field
1750 .clone()
1751 .map(|field| {
1752 self.prepare_soft_delete_data(std::collections::HashMap::from([(
1753 field,
1754 Value::Number(chrono::Utc::now().timestamp().into()),
1755 )]))
1756 })
1757 .transpose()?;
1758 self.ensure_soft_delete_write_has_where("DELETE")?;
1760 match tx.kind_mut() {
1761 #[cfg(feature = "mysql")]
1762 AnyTransactionKind::MySql(tx) => {
1763 let query = tx.table(&self.table_config.table_ref);
1764 if let Some(data) = soft_delete_data {
1765 return self
1766 .apply_write_plan(query)?
1767 .update(&data)
1768 .await
1769 .map_err(BaseError::DatabaseExecuteFailed);
1770 }
1771 self.apply_write_plan(query)?
1772 .delete()
1773 .await
1774 .map_err(BaseError::DatabaseExecuteFailed)
1775 }
1776 #[cfg(feature = "postgres")]
1777 AnyTransactionKind::Postgres(tx) => {
1778 let query = tx.table(&self.table_config.table_ref);
1779 if let Some(data) = soft_delete_data {
1780 let query =
1781 self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
1782 return query
1783 .update(&data)
1784 .await
1785 .map_err(BaseError::DatabaseExecuteFailed);
1786 }
1787 self.apply_pg_write_plan(query)?
1788 .delete()
1789 .await
1790 .map_err(BaseError::DatabaseExecuteFailed)
1791 }
1792 }
1793 }
1794}
1795
1796#[cfg(all(test, feature = "postgres"))]
1797mod pg_tests {
1798 use super::*;
1799 use crate::table::{Field, Record, Table};
1800 use std::sync::Arc;
1801
1802 fn lazy_query(table: Table) -> TableQuery {
1803 let definition = table.build().expect("测试表定义应有效");
1804 TableQuery::new(
1805 definition.shared_config(),
1806 Arc::from(Vec::<String>::new()),
1807 None,
1808 )
1809 }
1810
1811 #[test]
1815 fn pg_upsert_rejects_where_any_conditions() {
1816 let mut query = lazy_query(Table::new("pg_upsert_where_any").fields([
1817 Field::id("id"),
1818 Field::string("option_key", 64).required(),
1819 Field::string("label", 64).required(),
1820 ]));
1821 query
1822 .any_conditions
1823 .push(("option_key".to_string(), vec![serde_json::json!("opt_a")]));
1824 let rows = vec![Record::new().set("option_key", "opt_a").set("label", "x")];
1825
1826 let error = query
1827 .prepare_pg_upsert_rows(rows, &["option_key"])
1828 .expect_err("where_any 条件不得在批量 upsert 中被静默忽略");
1829 match error {
1830 BaseError::ParamInvalid(field, message) => {
1831 assert_eq!(field, "where");
1832 assert!(
1833 message.contains("where_any"),
1834 "错误信息应点名 where_any: {message}"
1835 );
1836 }
1837 other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1838 }
1839 }
1840
1841 #[test]
1844 fn insert_returning_id_rejects_non_integer_primary_key() {
1845 let query = lazy_query(Table::new("pg_string_pk").fields([
1846 Field::string("code", 32).primary_key().required(),
1847 Field::string("name", 32).required(),
1848 ]));
1849
1850 let error = query
1851 .ensure_integer_primary_key()
1852 .expect_err("字符串主键必须被拒绝");
1853 match error {
1854 BaseError::ParamInvalid(field, message) => {
1855 assert_eq!(field, "primary_key");
1856 assert!(
1857 message.contains("insert_returning_id"),
1858 "错误信息应指引到 insert_returning_id: {message}"
1859 );
1860 assert!(
1861 message.contains("insert()"),
1862 "错误信息应给出替代入口: {message}"
1863 );
1864 }
1865 other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1866 }
1867 }
1868
1869 #[test]
1871 fn insert_returning_id_accepts_integer_primary_key() {
1872 let query = lazy_query(
1873 Table::new("pg_int_pk").fields([Field::id("id"), Field::string("name", 32).required()]),
1874 );
1875
1876 query.ensure_integer_primary_key().expect("整型主键应放行");
1877 }
1878
1879 #[test]
1882 fn pg_upsert_requires_tenant_key_in_conflict_columns() {
1883 let query = lazy_query(Table::new("pg_upsert_tenant_conflict").fields([
1884 Field::id("id"),
1885 Field::bigint("tenant_id").tenant_key(),
1886 Field::string("option_key", 64).required(),
1887 Field::string("label", 64).required(),
1888 ]));
1889 let rows = vec![Record::new()
1890 .set("tenant_id", 1_i64)
1891 .set("option_key", "opt_a")
1892 .set("label", "x")];
1893
1894 let error = query
1895 .prepare_pg_upsert_rows(rows, &["option_key"])
1896 .expect_err("缺少租户冲突列必须拒绝");
1897 match error {
1898 BaseError::ParamInvalid(field, message) => {
1899 assert_eq!(field, "conflict_columns");
1900 assert!(
1901 message.contains("tenant_id"),
1902 "错误信息应点名租户字段: {message}"
1903 );
1904 }
1905 other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1906 }
1907 }
1908
1909 #[test]
1911 fn pg_default_update_columns_exclude_tenant_key() {
1912 let query = lazy_query(Table::new("pg_upsert_tenant_whitelist").fields([
1913 Field::id("id"),
1914 Field::bigint("tenant_id").tenant_key(),
1915 Field::string("option_key", 64).required(),
1916 Field::string("label", 64).required(),
1917 ]));
1918 let rows = vec![Record::new()
1919 .set("tenant_id", 1_i64)
1920 .set("option_key", "opt_a")
1921 .set("label", "x")];
1922 let prepared = query
1923 .prepare_pg_upsert_rows(rows, &["tenant_id", "option_key"])
1924 .expect("含租户冲突列应通过校验")
1925 .expect("非空批应产出计划");
1926 let insert_columns: Vec<String> = prepared.rows[0].keys().cloned().collect();
1927 let update_columns =
1928 query.default_pg_update_columns(&insert_columns, &["tenant_id", "option_key"]);
1929
1930 assert!(
1931 !update_columns.contains(&"tenant_id".to_string()),
1932 "默认白名单不得包含租户列: {update_columns:?}"
1933 );
1934 assert!(
1935 update_columns.contains(&"label".to_string()),
1936 "非保护业务列应在默认白名单内: {update_columns:?}"
1937 );
1938 }
1939}
1940
1941#[cfg(all(test, feature = "mysql"))]
1942mod batch_returning_mysql_tests {
1943 use super::*;
1944 use crate::database::AnyPool;
1945 use crate::table::{Field, Record, Table};
1946 use std::sync::Arc;
1947
1948 fn lazy_mysql_query(table: Table) -> TableQuery {
1949 let definition = table.build().expect("测试表定义应有效");
1950 let pool = sqlx::mysql::MySqlPoolOptions::new()
1951 .connect_lazy("mysql://root@127.0.0.1:3306/test")
1952 .expect("懒连接池构造不应触发网络连接");
1953 TableQuery::new(
1954 definition.shared_config(),
1955 Arc::from(Vec::<String>::new()),
1956 Some(AnyPool::MySql(Arc::new(pool))),
1957 )
1958 }
1959
1960 #[tokio::test]
1963 async fn insert_batch_returning_rejects_mysql() {
1964 let query = lazy_mysql_query(
1965 Table::new("tq_batch_returning_mysql")
1966 .fields([Field::id("id"), Field::string("label", 32).required()]),
1967 );
1968
1969 let error = query
1970 .insert_batch_returning(&[Record::new().set("label", "x")], ReturningTarget::Pk)
1971 .await
1972 .expect_err("MySQL 批量 RETURNING 必须被拒绝");
1973 assert!(
1974 matches!(
1975 error,
1976 BaseError::ConfigError(ref message) if message.contains("insert_batch_returning")
1977 ),
1978 "应返回 ConfigError 并点名入口,实际: {error:?}"
1979 );
1980 }
1981
1982 #[tokio::test]
1984 async fn upsert_batch_returning_rejects_mysql() {
1985 let query = lazy_mysql_query(Table::new("tq_batch_upsert_returning_mysql").fields([
1986 Field::id("id"),
1987 Field::string("option_key", 32).required(),
1988 Field::string("label", 32).required(),
1989 ]));
1990
1991 let error = query
1992 .upsert_batch_returning(
1993 vec![Record::new().set("option_key", "k").set("label", "x")],
1994 &["option_key"],
1995 ReturningTarget::Pk,
1996 )
1997 .await
1998 .expect_err("MySQL 批量 upsert RETURNING 必须被拒绝");
1999 assert!(
2000 matches!(
2001 error,
2002 BaseError::ConfigError(ref message) if message.contains("upsert_batch_returning")
2003 ),
2004 "应返回 ConfigError 并点名入口,实际: {error:?}"
2005 );
2006 }
2007}
2008
2009#[cfg(test)]
2010mod delete_permission_tests {
2011 use super::*;
2012 use crate::table::{Field, Record, Table};
2013 use std::sync::Arc;
2014
2015 fn query_for(table: Table, roles: &[&str]) -> TableQuery {
2016 let definition = table.build().expect("测试表定义应有效");
2017 TableQuery::new(
2018 definition.shared_config(),
2019 Arc::from(
2020 roles
2021 .iter()
2022 .map(|role| (*role).to_string())
2023 .collect::<Vec<String>>(),
2024 ),
2025 None,
2026 )
2027 }
2028
2029 #[tokio::test]
2032 async fn soft_delete_respects_explicit_soft_delete_write_audience() {
2033 let query = query_for(
2034 Table::new("tq_soft_delete_guard").fields([
2035 Field::id("id"),
2036 Field::soft_delete("deleted_at").writable_by(["admin"]),
2037 ]),
2038 &["user"],
2039 );
2040
2041 let error = query
2042 .delete()
2043 .await
2044 .expect_err("无写权限的软删列必须被拒绝");
2045 assert!(
2046 matches!(
2047 error,
2048 BaseError::FieldPermissionDenied(_, ref field, _) if field == "deleted_at"
2049 ),
2050 "应返回 deleted_at 的 FieldPermissionDenied,实际: {error:?}"
2051 );
2052 }
2053
2054 #[tokio::test]
2058 async fn framework_managed_soft_delete_passes_field_permission_guard() {
2059 let query = query_for(
2060 Table::new("tq_soft_delete_framework")
2061 .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2062 &["user"],
2063 )
2064 .where_eq("id", serde_json::json!(1))
2065 .expect("主键条件应有效");
2066
2067 let error = query
2068 .delete()
2069 .await
2070 .expect_err("无连接池应在守卫通过后才报错");
2071 assert!(
2072 matches!(error, BaseError::DatabaseNotInitialized),
2073 "默认软删列不应触发字段权限错误,实际: {error:?}"
2074 );
2075 }
2076
2077 #[tokio::test]
2084 async fn soft_delete_update_without_where_is_rejected() {
2085 let query = query_for(
2086 Table::new("tq_soft_delete_zero_where_update").fields([
2087 Field::id("id"),
2088 Field::string("name", 32),
2089 Field::soft_delete("deleted_at"),
2090 ]),
2091 &["admin"],
2092 );
2093
2094 let error = query
2095 .update(Record::new().set("name", "x"))
2096 .await
2097 .expect_err("软删表零 WHERE 更新必须被拒绝");
2098 assert!(
2099 matches!(error, BaseError::MissingWhereClause(ref op) if op == "UPDATE"),
2100 "应返回 UPDATE 的 MissingWhereClause,实际: {error:?}"
2101 );
2102 }
2103
2104 #[tokio::test]
2106 async fn soft_delete_delete_without_where_is_rejected() {
2107 let query = query_for(
2108 Table::new("tq_soft_delete_zero_where_delete").fields([
2109 Field::id("id"),
2110 Field::string("name", 32),
2111 Field::soft_delete("deleted_at"),
2112 ]),
2113 &["user"],
2114 );
2115
2116 let error = query
2117 .delete()
2118 .await
2119 .expect_err("软删表零 WHERE 删除必须被拒绝");
2120 assert!(
2121 matches!(error, BaseError::MissingWhereClause(ref op) if op == "DELETE"),
2122 "应返回 DELETE 的 MissingWhereClause,实际: {error:?}"
2123 );
2124 }
2125
2126 #[test]
2130 fn soft_delete_zero_where_guard_scope() {
2131 let query = query_for(
2133 Table::new("tq_zero_where_plain").fields([Field::id("id")]),
2134 &["user"],
2135 );
2136 query
2137 .ensure_soft_delete_write_has_where("UPDATE")
2138 .expect("非软删表不应触发守卫");
2139
2140 let query = query_for(
2142 Table::new("tq_zero_where_trashed")
2143 .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2144 &["user"],
2145 )
2146 .with_trashed();
2147 query
2148 .ensure_soft_delete_write_has_where("UPDATE")
2149 .expect("with_trashed 不应触发守卫");
2150
2151 let mut query = query_for(
2153 Table::new("tq_zero_where_any")
2154 .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2155 &["user"],
2156 );
2157 query
2158 .any_conditions
2159 .push(("id".to_string(), vec![serde_json::json!(1)]));
2160 query
2161 .ensure_soft_delete_write_has_where("DELETE")
2162 .expect("where_any 条件应被视为已有 WHERE");
2163
2164 let query = query_for(
2166 Table::new("tq_zero_where_tenant").fields([
2167 Field::id("id"),
2168 Field::bigint("tenant_id").tenant_key(),
2169 Field::soft_delete("deleted_at"),
2170 ]),
2171 &["user"],
2172 )
2173 .scope_tenant("tenant_id", serde_json::json!(7))
2174 .expect("租户条件注入应成功");
2175 query
2176 .ensure_soft_delete_write_has_where("UPDATE")
2177 .expect("租户注入条件应被视为已有 WHERE");
2178 }
2179}