OPT: Make Database an owned handle, keep the global as an optional default #28
Labels
No labels
area:core
area:database
area:migrations
area:model
area:relations
area:schema
area:tests
breaking-change
size:M
size:S
tracking
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
NoctisWolfshadow/tessera-orm#28
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Databaseis currently a stateless handle over a process-widestatic BACKEND: OnceLock<Backend>. Everything goes through the global, so the ORM cannot be used with more than one database per process, tests cannot get isolated in-memory databases, andset_configcan only ever succeed once.Proposal: make
Databasea real value that owns its backend, make the ORM generic over anExecutortrait, and keep a global default on top for convenience. Both usage styles are supported:Motivation
&mut conn,&pool,&db).OnceLockallows exactly one config per process, so in-memory tests share state or fight over initialization.Databasemethod insideDatabase::transactiondeadlocks on in-memory databases (non-reentrantMutex) and opens a competing connection on file-backed ones. Today this is only documented, not prevented.User::find(1). So the global stays, but as a layer on top of the explicit API, not the foundation.Proposed design
1.
Databaseowns its backendDatabaseisSend + Syncas long asConfigis, so it can be shared as&DatabaseorArc<Database>.2.
Executortrait: ORM code works with aDatabaseor aTransactionModel methods take
&impl Executor:Models stay plain data (
Clone,Debug, serializable). Persistence lives on the executor side, e.g.user.save(&db).3. Global default on top
Usage examples
Application startup with the global
Explicit handle
Multiple databases in one process
Transactions (same model code,
txinstead ofdb)Isolated tests
Functions that don't care which one they get
Caveats
Executoris not object-safe (generic method), so&dyn Executoris not possible. Use generics (&impl Executor).&dbor&Globalis its own transaction (autocommit). Usetransactionto group calls.set_default/Globalmust live in a dedicated integration test file (separate binary), becauseOnceLockcannot be reset.Tasks
Database::new(Config)and moveconninto the structconnection,transaction,execute,execute_batchto take&selfExecutortrait with impls forDatabaseandTransactionDatabase::set_default,Database::global, and keepset_configas a shimGlobalexecutor and itsexecute/execute_batch/transactionhelpers&impl ExecutorDatabasemethods inside the closure" rule with theGlobalcaveat aboveDatabase::new(Config::memory())set_default/Global/ConfigAlreadySetOpen questions
Globalget sugar on models too (e.g.User::find_global(1)), or isUser::find(&Global, 1)enough?Database::global()have a panicking variant for application code, or stayResult-only?Config: Send + Syncguaranteed?Databaseneeds it to be usable from astaticand across threads.