rakko-orm 1.0.0a0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. rakko/__init__.py +613 -0
  2. rakko/__main__.py +10 -0
  3. rakko/apps.py +356 -0
  4. rakko/backends/__init__.py +4 -0
  5. rakko/backends/asyncpg/__init__.py +7 -0
  6. rakko/backends/asyncpg/client.py +223 -0
  7. rakko/backends/asyncpg/executor.py +20 -0
  8. rakko/backends/asyncpg/schema_generator.py +17 -0
  9. rakko/backends/base/__init__.py +4 -0
  10. rakko/backends/base/client.py +438 -0
  11. rakko/backends/base/config_generator.py +249 -0
  12. rakko/backends/base/executor.py +764 -0
  13. rakko/backends/base/schema_generator.py +580 -0
  14. rakko/backends/base_postgres/__init__.py +4 -0
  15. rakko/backends/base_postgres/client.py +170 -0
  16. rakko/backends/base_postgres/executor.py +149 -0
  17. rakko/backends/base_postgres/schema_generator.py +84 -0
  18. rakko/backends/mssql/__init__.py +7 -0
  19. rakko/backends/mssql/client.py +127 -0
  20. rakko/backends/mssql/executor.py +17 -0
  21. rakko/backends/mssql/schema_generator.py +125 -0
  22. rakko/backends/mysql/__init__.py +7 -0
  23. rakko/backends/mysql/client.py +312 -0
  24. rakko/backends/mysql/executor.py +154 -0
  25. rakko/backends/mysql/schema_generator.py +101 -0
  26. rakko/backends/odbc/__init__.py +4 -0
  27. rakko/backends/odbc/client.py +221 -0
  28. rakko/backends/odbc/executor.py +20 -0
  29. rakko/backends/oracle/__init__.py +7 -0
  30. rakko/backends/oracle/client.py +136 -0
  31. rakko/backends/oracle/executor.py +27 -0
  32. rakko/backends/oracle/schema_generator.py +120 -0
  33. rakko/backends/psycopg/__init__.py +7 -0
  34. rakko/backends/psycopg/client.py +288 -0
  35. rakko/backends/psycopg/executor.py +14 -0
  36. rakko/backends/psycopg/schema_generator.py +17 -0
  37. rakko/backends/sqlite/__init__.py +14 -0
  38. rakko/backends/sqlite/client.py +299 -0
  39. rakko/backends/sqlite/executor.py +88 -0
  40. rakko/backends/sqlite/schema_generator.py +32 -0
  41. rakko/cli/__init__.py +13 -0
  42. rakko/cli/cli.py +878 -0
  43. rakko/cli/utils.py +181 -0
  44. rakko/config.py +315 -0
  45. rakko/connection.py +345 -0
  46. rakko/context.py +571 -0
  47. rakko/contrib/__init__.py +4 -0
  48. rakko/contrib/aiohttp/__init__.py +99 -0
  49. rakko/contrib/blacksheep/__init__.py +121 -0
  50. rakko/contrib/fastapi/__init__.py +301 -0
  51. rakko/contrib/mysql/__init__.py +4 -0
  52. rakko/contrib/mysql/fields.py +63 -0
  53. rakko/contrib/mysql/functions.py +19 -0
  54. rakko/contrib/mysql/indexes.py +28 -0
  55. rakko/contrib/mysql/json_functions.py +80 -0
  56. rakko/contrib/mysql/search.py +49 -0
  57. rakko/contrib/postgres/__init__.py +4 -0
  58. rakko/contrib/postgres/array_functions.py +35 -0
  59. rakko/contrib/postgres/fields.py +105 -0
  60. rakko/contrib/postgres/functions.py +43 -0
  61. rakko/contrib/postgres/indexes.py +33 -0
  62. rakko/contrib/postgres/json_functions.py +113 -0
  63. rakko/contrib/postgres/regex.py +31 -0
  64. rakko/contrib/postgres/search.py +483 -0
  65. rakko/contrib/pydantic/__init__.py +16 -0
  66. rakko/contrib/pydantic/base.py +147 -0
  67. rakko/contrib/pydantic/creator.py +681 -0
  68. rakko/contrib/pydantic/descriptions.py +207 -0
  69. rakko/contrib/pydantic/utils.py +38 -0
  70. rakko/contrib/pylint/__init__.py +158 -0
  71. rakko/contrib/quart/__init__.py +117 -0
  72. rakko/contrib/sanic/__init__.py +116 -0
  73. rakko/contrib/sqlite/__init__.py +4 -0
  74. rakko/contrib/sqlite/functions.py +16 -0
  75. rakko/contrib/sqlite/regex.py +46 -0
  76. rakko/contrib/starlette/__init__.py +180 -0
  77. rakko/contrib/test/__init__.py +336 -0
  78. rakko/contrib/test/condition.py +42 -0
  79. rakko/converters.py +160 -0
  80. rakko/exceptions.py +130 -0
  81. rakko/expressions.py +962 -0
  82. rakko/fields/__init__.py +111 -0
  83. rakko/fields/base.py +685 -0
  84. rakko/fields/data.py +1308 -0
  85. rakko/fields/db_defaults.py +105 -0
  86. rakko/fields/relational.py +703 -0
  87. rakko/filters.py +639 -0
  88. rakko/functions.py +142 -0
  89. rakko/indexes.py +165 -0
  90. rakko/log.py +8 -0
  91. rakko/manager.py +29 -0
  92. rakko/migrations/__init__.py +41 -0
  93. rakko/migrations/api/__init__.py +16 -0
  94. rakko/migrations/api/migrate.py +77 -0
  95. rakko/migrations/api/plan.py +76 -0
  96. rakko/migrations/api/sqlmigrate.py +69 -0
  97. rakko/migrations/autodetector.py +203 -0
  98. rakko/migrations/constraints.py +31 -0
  99. rakko/migrations/exceptions.py +10 -0
  100. rakko/migrations/executor.py +368 -0
  101. rakko/migrations/expressions.py +13 -0
  102. rakko/migrations/graph.py +158 -0
  103. rakko/migrations/loader.py +127 -0
  104. rakko/migrations/migration.py +189 -0
  105. rakko/migrations/operations.py +1288 -0
  106. rakko/migrations/recorder.py +104 -0
  107. rakko/migrations/schema_editor/__init__.py +25 -0
  108. rakko/migrations/schema_editor/asyncpg.py +11 -0
  109. rakko/migrations/schema_editor/base.py +945 -0
  110. rakko/migrations/schema_editor/base_postgres.py +171 -0
  111. rakko/migrations/schema_editor/data.py +18 -0
  112. rakko/migrations/schema_editor/mssql.py +339 -0
  113. rakko/migrations/schema_editor/mysql.py +408 -0
  114. rakko/migrations/schema_editor/oracle.py +259 -0
  115. rakko/migrations/schema_editor/psycopg.py +11 -0
  116. rakko/migrations/schema_editor/sqlite.py +424 -0
  117. rakko/migrations/schema_generator/__init__.py +5 -0
  118. rakko/migrations/schema_generator/operation_generator.py +163 -0
  119. rakko/migrations/schema_generator/state.py +224 -0
  120. rakko/migrations/schema_generator/state_apps.py +165 -0
  121. rakko/migrations/schema_generator/state_diff.py +419 -0
  122. rakko/migrations/writer.py +515 -0
  123. rakko/models.py +1854 -0
  124. rakko/py.typed +0 -0
  125. rakko/query_api.py +134 -0
  126. rakko/query_utils.py +238 -0
  127. rakko/queryset.py +2743 -0
  128. rakko/relations.py +85 -0
  129. rakko/router.py +55 -0
  130. rakko/schema_quoting.py +62 -0
  131. rakko/signals.py +73 -0
  132. rakko/timezone.py +173 -0
  133. rakko/transactions.py +69 -0
  134. rakko/utils.py +50 -0
  135. rakko/validators.py +412 -0
  136. rakko/warnings.py +22 -0
  137. rakko_orm-1.0.0a0.dist-info/METADATA +114 -0
  138. rakko_orm-1.0.0a0.dist-info/RECORD +143 -0
  139. rakko_orm-1.0.0a0.dist-info/WHEEL +4 -0
  140. rakko_orm-1.0.0a0.dist-info/entry_points.txt +5 -0
  141. rakko_orm-1.0.0a0.dist-info/licenses/CONTRIBUTORS.rst +86 -0
  142. rakko_orm-1.0.0a0.dist-info/licenses/LICENSE.txt +201 -0
  143. rakko_orm-1.0.0a0.dist-info/licenses/NOTICE.txt +22 -0
@@ -0,0 +1,438 @@
1
+ # Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
2
+ # Derived from Tortoise ORM; maintained and modified for Rakko ORM.
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ from __future__ import annotations
6
+
7
+ import abc
8
+ import asyncio
9
+ import inspect
10
+ from collections.abc import Awaitable, Callable, Sequence
11
+ from typing import Any, Generic, TypeAlias, TypeVar, cast
12
+
13
+ from pypika_tortoise import Query
14
+
15
+ from rakko.backends.base.executor import BaseExecutor
16
+ from rakko.backends.base.schema_generator import BaseSchemaGenerator
17
+ from rakko.connection import get_connections
18
+ from rakko.exceptions import TransactionManagementError
19
+ from rakko.log import db_client_logger
20
+
21
+ T_conn = TypeVar("T_conn") # Instance of client connection, such as: asyncpg.Connection()
22
+
23
+ #: A callable returning a password, awaited first if it returns an awaitable.
24
+ PasswordFactory: TypeAlias = Callable[[], "str | Awaitable[str]"]
25
+ PasswordType: TypeAlias = "str | PasswordFactory | None"
26
+
27
+
28
+ async def resolve_password(password: PasswordType) -> str | None:
29
+ """
30
+ Resolve a password that may be supplied as a plain string or as a callable.
31
+
32
+ Callables are invoked once per connection attempt, which allows short-lived
33
+ credentials (AWS RDS IAM tokens, Azure Entra ID tokens, Vault leases, ...) to be
34
+ refreshed transparently without recreating the client.
35
+
36
+ :param password: A string, ``None``, or a sync/async callable returning a string.
37
+ """
38
+ if callable(password):
39
+ resolved = password()
40
+ if inspect.isawaitable(resolved):
41
+ resolved = await resolved
42
+ return resolved
43
+ return password
44
+
45
+
46
+ class Capabilities:
47
+ """
48
+ DB Client Capabilities indicates the supported feature-set,
49
+ and is also used to note common workarounds to deficiencies.
50
+
51
+ Defaults are set with the following standard:
52
+
53
+ * Deficiencies: assume it is working right.
54
+ * Features: assume it doesn't have it.
55
+
56
+ :param dialect: Dialect name of the DB Client driver.
57
+ :param daemon: Is the DB an external Daemon we connect to?
58
+ :param requires_limit: Indicates that this DB requires a ``LIMIT`` statement for
59
+ an ``OFFSET`` statement to work.
60
+ :param inline_comment: Indicates that comments should be rendered in line with the
61
+ DDL statement, and not as a separate statement.
62
+ :param supports_transactions: Indicates that this DB supports transactions.
63
+ :param support_for_update: Indicates that this DB supports SELECT ... FOR UPDATE SQL statement.
64
+ :param support_for_update_no_key: Indicates that this DB supports SELECT ... FOR NO KEY UPDATE SQL statement.
65
+ :param support_index_hint: Support force index or use index.
66
+ :param support_update_limit_order_by: support update/delete with limit and order by.
67
+ :param support_for_posix_regex_queries: indicated if the db supports posix regex queries
68
+ :param support_json_attributes: indicated if the db supports accessing json attributes
69
+ :param can_rollback_ddl: Whether the database supports transactional DDL.
70
+ Used to determine if migrations can be run atomically.
71
+ :param support_returning: Indicates that this DB supports INSERT ... RETURNING.
72
+ """
73
+
74
+ def __init__(
75
+ self,
76
+ dialect: str,
77
+ *,
78
+ # Is the connection a Daemon?
79
+ daemon: bool = True,
80
+ # Deficiencies to work around:
81
+ requires_limit: bool = False,
82
+ inline_comment: bool = False,
83
+ supports_transactions: bool = True,
84
+ support_for_update: bool = True,
85
+ support_for_no_key_update: bool = False,
86
+ # Support force index or use index?
87
+ support_index_hint: bool = False,
88
+ # support update/delete with limit and order by
89
+ support_update_limit_order_by: bool = True,
90
+ support_for_posix_regex_queries: bool = False,
91
+ support_json_attributes: bool = False,
92
+ can_rollback_ddl: bool = False,
93
+ support_returning: bool = False,
94
+ ) -> None:
95
+ super().__setattr__("_mutable", True)
96
+
97
+ self.dialect = dialect
98
+ self.daemon = daemon
99
+ self.requires_limit = requires_limit
100
+ self.inline_comment = inline_comment
101
+ self.supports_transactions = supports_transactions
102
+ self.support_for_update = support_for_update
103
+ self.support_for_no_key_update = support_for_no_key_update
104
+ self.support_index_hint = support_index_hint
105
+ self.support_update_limit_order_by = support_update_limit_order_by
106
+ self.support_for_posix_regex_queries = support_for_posix_regex_queries
107
+ self.support_json_attributes = support_json_attributes
108
+ self.can_rollback_ddl = can_rollback_ddl
109
+ self.support_returning = support_returning
110
+ super().__setattr__("_mutable", False)
111
+
112
+ def __setattr__(self, attr: str, value: Any) -> None:
113
+ if not getattr(self, "_mutable", False):
114
+ raise AttributeError(attr)
115
+ super().__setattr__(attr, value)
116
+
117
+ def __str__(self) -> str:
118
+ return str(self.__dict__)
119
+
120
+
121
+ class BaseDBAsyncClient(abc.ABC):
122
+ """
123
+ Base class for containing a DB connection.
124
+
125
+ Parameters get passed as kwargs, and is mostly driver specific.
126
+
127
+ .. attribute:: query_class
128
+ :annotation: type[pypika_tortoise.Query]
129
+
130
+ The PyPika Query dialect (low level dialect)
131
+
132
+ .. attribute:: executor_class
133
+ :annotation: type[BaseExecutor]
134
+
135
+ The executor dialect class (high level dialect)
136
+
137
+ .. attribute:: schema_generator
138
+ :annotation: type[BaseSchemaGenerator]
139
+
140
+ The DDL schema generator
141
+
142
+ .. attribute:: capabilities
143
+ :annotation: Capabilities
144
+
145
+ Contains the connection capabilities
146
+ """
147
+
148
+ _connection: Any
149
+ _parent: BaseDBAsyncClient
150
+ _pool: Any
151
+ _bound_loop: asyncio.AbstractEventLoop | None = None
152
+ connection_name: str
153
+ query_class: type[Query] = Query
154
+ executor_class: type[BaseExecutor] = BaseExecutor
155
+ schema_generator: type[BaseSchemaGenerator] = BaseSchemaGenerator
156
+ capabilities: Capabilities = Capabilities("")
157
+
158
+ def __init__(self, connection_name: str, fetch_inserted: bool = True, **kwargs: Any) -> None:
159
+ self.log = db_client_logger
160
+ self.connection_name = connection_name
161
+ self.fetch_inserted = fetch_inserted
162
+
163
+ def _check_loop(self) -> bool:
164
+ """Check if the current event loop matches the one this client was created on."""
165
+ try:
166
+ current = asyncio.get_running_loop()
167
+ except RuntimeError:
168
+ return True # No running loop — can't validate
169
+ if self._bound_loop is None:
170
+ return True # Not yet bound (pool not created yet)
171
+ return self._bound_loop is current
172
+
173
+ async def _post_connect(self) -> None:
174
+ """Called after pool/connection is created. Records the bound loop."""
175
+ self._bound_loop = asyncio.get_running_loop()
176
+
177
+ async def create_connection(self, with_db: bool) -> None:
178
+ """
179
+ Establish a DB connection.
180
+
181
+ :param with_db: If True, then select the DB to use, else use default.
182
+ Use case for this is to create/drop a database.
183
+ """
184
+ raise NotImplementedError() # pragma: nocoverage
185
+
186
+ async def close(self) -> None:
187
+ """
188
+ Closes the DB connection.
189
+ """
190
+ raise NotImplementedError() # pragma: nocoverage
191
+
192
+ async def db_create(self) -> None:
193
+ """
194
+ Created the database in the server. Typically only called by the test runner.
195
+
196
+ Need to have called ``create_connection()``` with parameter ``with_db=False`` set to
197
+ use the default connection instead of the configured one, else you would get errors
198
+ indicating the database doesn't exist.
199
+ """
200
+ raise NotImplementedError() # pragma: nocoverage
201
+
202
+ async def db_delete(self) -> None:
203
+ """
204
+ Delete the database from the Server. Typically only called by the test runner.
205
+
206
+ Need to have called ``create_connection()``` with parameter ``with_db=False`` set to
207
+ use the default connection instead of the configured one, else you would get errors
208
+ indicating the database is in use.
209
+ """
210
+ raise NotImplementedError() # pragma: nocoverage
211
+
212
+ def acquire_connection(self) -> ConnectionWrapper | PoolConnectionWrapper:
213
+ """
214
+ Acquires a connection from the pool.
215
+ Will return the current context connection if already in a transaction.
216
+ """
217
+ raise NotImplementedError() # pragma: nocoverage
218
+
219
+ def _in_transaction(self) -> TransactionContext:
220
+ raise NotImplementedError() # pragma: nocoverage
221
+
222
+ async def execute_insert(self, query: str, values: list) -> Any:
223
+ """
224
+ Executes a RAW SQL insert statement, with provided parameters.
225
+
226
+ :param query: The SQL string, pre-parametrized for the target DB dialect.
227
+ :param values: A sequence of positional DB parameters.
228
+ :return: The primary key if it is generated by the DB.
229
+ (Currently only integer autonumber PK's)
230
+ """
231
+ raise NotImplementedError() # pragma: nocoverage
232
+
233
+ async def execute_query(
234
+ self, query: str, values: list | None = None
235
+ ) -> tuple[int, Sequence[dict]]:
236
+ """
237
+ Executes a RAW SQL query statement, and returns the resultset.
238
+
239
+ :param query: The SQL string, pre-parametrized for the target DB dialect.
240
+ :param values: A sequence of positional DB parameters.
241
+ :return: A tuple of: (The number of rows affected, The resultset)
242
+ """
243
+ raise NotImplementedError() # pragma: nocoverage
244
+
245
+ async def execute_script(self, query: str) -> None:
246
+ """
247
+ Executes a RAW SQL script with multiple statements, and returns nothing.
248
+
249
+ :param query: The SQL string, which will be passed on verbatim.
250
+ Semicolons is supported here.
251
+ """
252
+ raise NotImplementedError() # pragma: nocoverage
253
+
254
+ async def execute_many(self, query: str, values: list[list]) -> None:
255
+ """
256
+ Executes a RAW bulk insert statement, like execute_insert, but returns no data.
257
+
258
+ :param query: The SQL string, pre-parametrized for the target DB dialect.
259
+ :param values: A sequence of positional DB parameters.
260
+ """
261
+ raise NotImplementedError() # pragma: nocoverage
262
+
263
+ async def execute_query_dict(self, query: str, values: list | None = None) -> list[dict]:
264
+ """
265
+ Executes a RAW SQL query statement, and returns the resultset as a list of dicts.
266
+
267
+ :param query: The SQL string, pre-parametrized for the target DB dialect.
268
+ :param values: A sequence of positional DB parameters.
269
+ """
270
+ return (await self.execute_query_dict_with_affected(query, values))[0]
271
+
272
+ async def execute_query_dict_with_affected(
273
+ self, query: str, values: list | None = None
274
+ ) -> tuple[list[dict], int]:
275
+ """
276
+ Executes a RAW SQL query statement, and returns the resultset as a list of dicts
277
+ along with the rows affected if available.
278
+
279
+ :param query: The SQL string, pre-parametrized for the target DB dialect.
280
+ :param values: A sequence of positional DB parameters.
281
+ """
282
+ rowcount, rows = await self.execute_query(query, values)
283
+ normalized = [dict(row) for row in rows]
284
+ return normalized, rowcount
285
+
286
+
287
+ class TransactionalDBClient(BaseDBAsyncClient, abc.ABC):
288
+ """An interface of the DB client that supports transactions."""
289
+
290
+ _finalized: bool = False
291
+
292
+ @abc.abstractmethod
293
+ async def begin(self) -> None: ...
294
+
295
+ @abc.abstractmethod
296
+ async def savepoint(self) -> None: ...
297
+
298
+ @abc.abstractmethod
299
+ async def rollback(self) -> None: ...
300
+
301
+ @abc.abstractmethod
302
+ async def savepoint_rollback(self) -> None: ...
303
+
304
+ @abc.abstractmethod
305
+ async def commit(self) -> None: ...
306
+
307
+ @abc.abstractmethod
308
+ async def release_savepoint(self) -> None: ...
309
+
310
+
311
+ class ConnectionWrapper(Generic[T_conn]):
312
+ """Wraps the connections with a lock to facilitate safe concurrent access when using
313
+ asyncio.gather, TaskGroup, or similar."""
314
+
315
+ __slots__ = ("connection", "_lock", "client")
316
+
317
+ def __init__(self, lock: asyncio.Lock, client: BaseDBAsyncClient) -> None:
318
+ self._lock: asyncio.Lock = lock
319
+ self.client = client
320
+ self.connection: T_conn = client._connection
321
+
322
+ async def ensure_connection(self) -> None:
323
+ if not self.connection:
324
+ await self.client.create_connection(with_db=True)
325
+ self.connection = self.client._connection
326
+
327
+ async def __aenter__(self) -> T_conn:
328
+ await self._lock.acquire()
329
+ await self.ensure_connection()
330
+ return self.connection
331
+
332
+ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
333
+ self._lock.release()
334
+
335
+
336
+ class TransactionContext:
337
+ """A context manager interface for transactions. It is returned from in_transaction
338
+ and _in_transaction."""
339
+
340
+ client: TransactionalDBClient
341
+
342
+ @abc.abstractmethod
343
+ async def __aenter__(self) -> TransactionalDBClient: ...
344
+
345
+ @abc.abstractmethod
346
+ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None: ...
347
+
348
+
349
+ class TransactionContextPooled(TransactionContext):
350
+ "A version of TransactionContext that uses a pool to acquire connections."
351
+
352
+ __slots__ = ("client", "connection_name", "token", "_pool_init_lock")
353
+
354
+ def __init__(self, client: TransactionalDBClient, pool_init_lock: asyncio.Lock) -> None:
355
+ self.client = client
356
+ self.connection_name = client.connection_name
357
+ self._pool_init_lock = pool_init_lock
358
+
359
+ async def ensure_connection(self) -> None:
360
+ if not self.client._parent._pool:
361
+ # a safeguard against multiple concurrent tasks trying to initialize the pool
362
+ async with self._pool_init_lock:
363
+ if not self.client._parent._pool:
364
+ await self.client._parent.create_connection(with_db=True)
365
+
366
+ async def __aenter__(self) -> TransactionalDBClient:
367
+ await self.ensure_connection()
368
+ # Acquire connection first to avoid race condition where concurrent tasks
369
+ # see the wrapper via the context before it has a connection.
370
+ self.client._connection = await self.client._parent._pool.acquire()
371
+ # Set the context variable so the current task is always seeing a
372
+ # TransactionWrapper connection.
373
+ self.token = get_connections().set(self.connection_name, self.client)
374
+ await self.client.begin()
375
+ return self.client
376
+
377
+ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
378
+ try:
379
+ if not self.client._finalized:
380
+ if exc_type:
381
+ # Can't rollback a transaction that already failed.
382
+ if exc_type is not TransactionManagementError:
383
+ await self.client.rollback()
384
+ else:
385
+ await self.client.commit()
386
+ finally:
387
+ if self.client._parent._pool:
388
+ await self.client._parent._pool.release(self.client._connection)
389
+ get_connections().reset(self.token)
390
+
391
+
392
+ class NestedTransactionContext(TransactionContext):
393
+ __slots__ = ("client", "connection_name")
394
+
395
+ def __init__(self, client: TransactionalDBClient) -> None:
396
+ self.client = client
397
+ self.connection_name = client.connection_name
398
+
399
+ async def __aenter__(self) -> TransactionalDBClient:
400
+ await self.client.savepoint()
401
+ return self.client
402
+
403
+ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
404
+ if not self.client._finalized:
405
+ if exc_type:
406
+ # Can't rollback a transaction that already failed.
407
+ if exc_type is not TransactionManagementError:
408
+ await self.client.savepoint_rollback()
409
+ else:
410
+ await self.client.release_savepoint()
411
+
412
+
413
+ class PoolConnectionWrapper(Generic[T_conn]):
414
+ """Class to manage acquiring from and releasing connections to a pool."""
415
+
416
+ __slots__ = ("client", "connection", "_pool_init_lock")
417
+
418
+ def __init__(self, client: BaseDBAsyncClient, pool_init_lock: asyncio.Lock) -> None:
419
+ self.client = client
420
+ self.connection: T_conn | None = None
421
+ self._pool_init_lock = pool_init_lock
422
+
423
+ async def ensure_connection(self) -> None:
424
+ if not self.client._pool:
425
+ # a safeguard against multiple concurrent tasks trying to initialize the pool
426
+ async with self._pool_init_lock:
427
+ if not self.client._pool:
428
+ await self.client.create_connection(with_db=True)
429
+
430
+ async def __aenter__(self) -> T_conn:
431
+ await self.ensure_connection()
432
+ # get first available connection. If none available, wait until one is released
433
+ self.connection = await self.client._pool.acquire()
434
+ return cast(T_conn, self.connection)
435
+
436
+ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
437
+ # release the connection back to the pool
438
+ await self.client._pool.release(self.connection)
@@ -0,0 +1,249 @@
1
+ # Copyright (c) 2026 ropmyung (Rakko ORM modifications and additions).
2
+ # Derived from Tortoise ORM; maintained and modified for Rakko ORM.
3
+ # SPDX-License-Identifier: Apache-2.0
4
+
5
+ from __future__ import annotations
6
+
7
+ import urllib.parse as urlparse
8
+ import uuid
9
+ from collections.abc import Iterable
10
+ from types import ModuleType
11
+ from typing import Any
12
+
13
+ from rakko.exceptions import ConfigurationError
14
+
15
+ urlparse.uses_netloc.append("postgres")
16
+ urlparse.uses_netloc.append("postgresql")
17
+ urlparse.uses_netloc.append("asyncpg")
18
+ urlparse.uses_netloc.append("psycopg")
19
+ urlparse.uses_netloc.append("sqlite")
20
+ urlparse.uses_netloc.append("mysql")
21
+ urlparse.uses_netloc.append("oracle")
22
+ urlparse.uses_netloc.append("mssql")
23
+ DB_LOOKUP: dict[str, dict[str, Any]] = {
24
+ "psycopg": {
25
+ "engine": "rakko.backends.psycopg",
26
+ "vmap": {
27
+ "path": "database",
28
+ "hostname": "host",
29
+ "port": "port",
30
+ "username": "user",
31
+ "password": "password", # nosec:B105
32
+ },
33
+ "defaults": {"port": 5432},
34
+ "cast": {
35
+ "min_size": int,
36
+ "max_size": int,
37
+ "max_queries": int,
38
+ "max_inactive_connection_lifetime": float,
39
+ "timeout": int,
40
+ "statement_cache_size": int,
41
+ "max_cached_statement_lifetime": int,
42
+ "max_cacheable_statement_size": int,
43
+ "ssl": bool,
44
+ },
45
+ },
46
+ "asyncpg": {
47
+ "engine": "rakko.backends.asyncpg",
48
+ "vmap": {
49
+ "path": "database",
50
+ "hostname": "host",
51
+ "port": "port",
52
+ "username": "user",
53
+ "password": "password", # nosec:B105
54
+ },
55
+ "defaults": {"port": 5432},
56
+ "cast": {
57
+ "min_size": int,
58
+ "max_size": int,
59
+ "max_queries": int,
60
+ "max_inactive_connection_lifetime": float,
61
+ "timeout": int,
62
+ "statement_cache_size": int,
63
+ "max_cached_statement_lifetime": int,
64
+ "max_cacheable_statement_size": int,
65
+ "ssl": bool,
66
+ },
67
+ },
68
+ "sqlite": {
69
+ "engine": "rakko.backends.sqlite",
70
+ "skip_first_char": False,
71
+ "vmap": {"path": "file_path"},
72
+ "defaults": {"journal_mode": "WAL", "journal_size_limit": 16384},
73
+ "cast": {
74
+ "journal_size_limit": int,
75
+ "install_regexp_functions": bool,
76
+ },
77
+ },
78
+ "mysql": {
79
+ "engine": "rakko.backends.mysql",
80
+ "vmap": {
81
+ "path": "database",
82
+ "hostname": "host",
83
+ "port": "port",
84
+ "username": "user",
85
+ "password": "password", # nosec:B105
86
+ },
87
+ "defaults": {"port": 3306, "charset": "utf8mb4", "sql_mode": "STRICT_TRANS_TABLES"},
88
+ "cast": {
89
+ "minsize": int,
90
+ "maxsize": int,
91
+ "connect_timeout": float,
92
+ "echo": bool,
93
+ "use_unicode": bool,
94
+ "pool_recycle": int,
95
+ "ssl": bool,
96
+ },
97
+ },
98
+ "mssql": {
99
+ "engine": "rakko.backends.mssql",
100
+ "vmap": {
101
+ "path": "database",
102
+ "hostname": "host",
103
+ "port": "port",
104
+ "username": "user",
105
+ "password": "password", # nosec:B105
106
+ },
107
+ "defaults": {"port": 1433},
108
+ "cast": {
109
+ "minsize": int,
110
+ "maxsize": int,
111
+ "echo": bool,
112
+ "pool_recycle": int,
113
+ },
114
+ },
115
+ "oracle": {
116
+ "engine": "rakko.backends.oracle",
117
+ "vmap": {
118
+ "path": "database",
119
+ "hostname": "host",
120
+ "port": "port",
121
+ "username": "user",
122
+ "password": "password", # nosec:B105
123
+ },
124
+ "defaults": {"port": 1521},
125
+ "cast": {
126
+ "minsize": int,
127
+ "maxsize": int,
128
+ "echo": bool,
129
+ "pool_recycle": int,
130
+ },
131
+ },
132
+ }
133
+ # Create an alias for backwards compatibility
134
+ DB_LOOKUP["postgres"] = DB_LOOKUP["asyncpg"]
135
+ # "postgresql" is the scheme accepted by libpq and pydantic's PostgresDsn
136
+ DB_LOOKUP["postgresql"] = DB_LOOKUP["asyncpg"]
137
+
138
+
139
+ def _quote_url_userinfo(db_url: str) -> str:
140
+ """Encode characters in the userinfo section that break urlparse.
141
+
142
+ Specifically, '[' and ']' cause urlparse to fail with a ValueError because
143
+ it interprets them as IPv6 address brackets. This encodes only those characters,
144
+ leaving everything else (including '%') untouched.
145
+ """
146
+ scheme_end = db_url.find("://")
147
+ if scheme_end == -1:
148
+ return db_url
149
+
150
+ scheme = db_url[: scheme_end + 3]
151
+ rest = db_url[scheme_end + 3 :]
152
+
153
+ at_pos = rest.find("@")
154
+ if at_pos == -1:
155
+ return db_url
156
+
157
+ userinfo = rest[:at_pos]
158
+ after_userinfo = rest[at_pos:]
159
+
160
+ colon_pos = userinfo.find(":")
161
+ if colon_pos == -1:
162
+ username = userinfo.replace("[", "%5B").replace("]", "%5D")
163
+ return scheme + username + after_userinfo
164
+
165
+ username = userinfo[:colon_pos]
166
+ password = userinfo[colon_pos + 1 :]
167
+ username_quoted = username.replace("[", "%5B").replace("]", "%5D")
168
+ password_quoted = password.replace("[", "%5B").replace("]", "%5D")
169
+ return scheme + username_quoted + ":" + password_quoted + after_userinfo
170
+
171
+
172
+ def expand_db_url(db_url: str, testing: bool = False) -> dict:
173
+ # Quote special characters in userinfo to avoid parsing errors
174
+ db_url = _quote_url_userinfo(db_url)
175
+ url = urlparse.urlparse(db_url)
176
+ if url.scheme not in DB_LOOKUP:
177
+ raise ConfigurationError(f"Unknown DB scheme: {url.scheme}")
178
+
179
+ db_backend = url.scheme
180
+ db = DB_LOOKUP[db_backend]
181
+ if db.get("skip_first_char", True):
182
+ path: str | None = url.path[1:]
183
+ else:
184
+ path = url.netloc + url.path
185
+
186
+ if not path:
187
+ if db_backend == "sqlite":
188
+ raise ConfigurationError("No path specified for DB_URL")
189
+ # Other database backend accepts database name being None (but not empty string).
190
+ path = None
191
+
192
+ params: dict = {}
193
+ for key, val in db["defaults"].items():
194
+ params[key] = val
195
+ for key, val in urlparse.parse_qs(url.query).items():
196
+ cast = db["cast"].get(key, str)
197
+ last_value = val[-1]
198
+ if cast is bool:
199
+ params[key] = last_value.lower() in ("true", "1", "yes", "on")
200
+ else:
201
+ params[key] = cast(last_value)
202
+
203
+ if testing and path:
204
+ path = path.replace("\\{", "{").replace("\\}", "}")
205
+ path = path.format(uuid.uuid4().hex)
206
+
207
+ vmap: dict = {}
208
+ vmap.update(db["vmap"])
209
+ params[vmap["path"]] = path
210
+ if host_key := vmap.get("hostname"):
211
+ if url.hostname:
212
+ params[host_key] = url.hostname
213
+ elif host_key not in params:
214
+ # Keep a host given in the query string (e.g. a unix socket directory)
215
+ params[host_key] = None
216
+ try:
217
+ if vmap.get("port") and url.port:
218
+ params[vmap["port"]] = int(url.port)
219
+ except ValueError as e:
220
+ raise ConfigurationError("Port is not an integer") from e
221
+ if vmap.get("username") and (url.username or vmap["username"] not in params):
222
+ # Pass username as None, instead of empty string,
223
+ # to let asyncpg retrieve username from environment variable or OS user
224
+ params[vmap["username"]] = urlparse.unquote(url.username) if url.username else None
225
+ if vmap.get("password") and (url.password or vmap["password"] not in params):
226
+ # asyncpg accepts None for password, but aiomysql not
227
+ params[vmap["password"]] = (
228
+ None
229
+ if (not url.password and db_backend in {"postgres", "postgresql", "asyncpg", "psycopg"})
230
+ else urlparse.unquote(url.password or "")
231
+ )
232
+
233
+ return {"engine": db["engine"], "credentials": params}
234
+
235
+
236
+ def generate_config(
237
+ db_url: str,
238
+ app_modules: dict[str, Iterable[str | ModuleType]],
239
+ connection_label: str | None = None,
240
+ testing: bool = False,
241
+ ) -> dict:
242
+ _connection_label = connection_label or "default"
243
+ return {
244
+ "connections": {_connection_label: expand_db_url(db_url, testing)},
245
+ "apps": {
246
+ app_label: {"models": modules, "default_connection": _connection_label}
247
+ for app_label, modules in app_modules.items()
248
+ },
249
+ }