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.
- rakko/__init__.py +613 -0
- rakko/__main__.py +10 -0
- rakko/apps.py +356 -0
- rakko/backends/__init__.py +4 -0
- rakko/backends/asyncpg/__init__.py +7 -0
- rakko/backends/asyncpg/client.py +223 -0
- rakko/backends/asyncpg/executor.py +20 -0
- rakko/backends/asyncpg/schema_generator.py +17 -0
- rakko/backends/base/__init__.py +4 -0
- rakko/backends/base/client.py +438 -0
- rakko/backends/base/config_generator.py +249 -0
- rakko/backends/base/executor.py +764 -0
- rakko/backends/base/schema_generator.py +580 -0
- rakko/backends/base_postgres/__init__.py +4 -0
- rakko/backends/base_postgres/client.py +170 -0
- rakko/backends/base_postgres/executor.py +149 -0
- rakko/backends/base_postgres/schema_generator.py +84 -0
- rakko/backends/mssql/__init__.py +7 -0
- rakko/backends/mssql/client.py +127 -0
- rakko/backends/mssql/executor.py +17 -0
- rakko/backends/mssql/schema_generator.py +125 -0
- rakko/backends/mysql/__init__.py +7 -0
- rakko/backends/mysql/client.py +312 -0
- rakko/backends/mysql/executor.py +154 -0
- rakko/backends/mysql/schema_generator.py +101 -0
- rakko/backends/odbc/__init__.py +4 -0
- rakko/backends/odbc/client.py +221 -0
- rakko/backends/odbc/executor.py +20 -0
- rakko/backends/oracle/__init__.py +7 -0
- rakko/backends/oracle/client.py +136 -0
- rakko/backends/oracle/executor.py +27 -0
- rakko/backends/oracle/schema_generator.py +120 -0
- rakko/backends/psycopg/__init__.py +7 -0
- rakko/backends/psycopg/client.py +288 -0
- rakko/backends/psycopg/executor.py +14 -0
- rakko/backends/psycopg/schema_generator.py +17 -0
- rakko/backends/sqlite/__init__.py +14 -0
- rakko/backends/sqlite/client.py +299 -0
- rakko/backends/sqlite/executor.py +88 -0
- rakko/backends/sqlite/schema_generator.py +32 -0
- rakko/cli/__init__.py +13 -0
- rakko/cli/cli.py +878 -0
- rakko/cli/utils.py +181 -0
- rakko/config.py +315 -0
- rakko/connection.py +345 -0
- rakko/context.py +571 -0
- rakko/contrib/__init__.py +4 -0
- rakko/contrib/aiohttp/__init__.py +99 -0
- rakko/contrib/blacksheep/__init__.py +121 -0
- rakko/contrib/fastapi/__init__.py +301 -0
- rakko/contrib/mysql/__init__.py +4 -0
- rakko/contrib/mysql/fields.py +63 -0
- rakko/contrib/mysql/functions.py +19 -0
- rakko/contrib/mysql/indexes.py +28 -0
- rakko/contrib/mysql/json_functions.py +80 -0
- rakko/contrib/mysql/search.py +49 -0
- rakko/contrib/postgres/__init__.py +4 -0
- rakko/contrib/postgres/array_functions.py +35 -0
- rakko/contrib/postgres/fields.py +105 -0
- rakko/contrib/postgres/functions.py +43 -0
- rakko/contrib/postgres/indexes.py +33 -0
- rakko/contrib/postgres/json_functions.py +113 -0
- rakko/contrib/postgres/regex.py +31 -0
- rakko/contrib/postgres/search.py +483 -0
- rakko/contrib/pydantic/__init__.py +16 -0
- rakko/contrib/pydantic/base.py +147 -0
- rakko/contrib/pydantic/creator.py +681 -0
- rakko/contrib/pydantic/descriptions.py +207 -0
- rakko/contrib/pydantic/utils.py +38 -0
- rakko/contrib/pylint/__init__.py +158 -0
- rakko/contrib/quart/__init__.py +117 -0
- rakko/contrib/sanic/__init__.py +116 -0
- rakko/contrib/sqlite/__init__.py +4 -0
- rakko/contrib/sqlite/functions.py +16 -0
- rakko/contrib/sqlite/regex.py +46 -0
- rakko/contrib/starlette/__init__.py +180 -0
- rakko/contrib/test/__init__.py +336 -0
- rakko/contrib/test/condition.py +42 -0
- rakko/converters.py +160 -0
- rakko/exceptions.py +130 -0
- rakko/expressions.py +962 -0
- rakko/fields/__init__.py +111 -0
- rakko/fields/base.py +685 -0
- rakko/fields/data.py +1308 -0
- rakko/fields/db_defaults.py +105 -0
- rakko/fields/relational.py +703 -0
- rakko/filters.py +639 -0
- rakko/functions.py +142 -0
- rakko/indexes.py +165 -0
- rakko/log.py +8 -0
- rakko/manager.py +29 -0
- rakko/migrations/__init__.py +41 -0
- rakko/migrations/api/__init__.py +16 -0
- rakko/migrations/api/migrate.py +77 -0
- rakko/migrations/api/plan.py +76 -0
- rakko/migrations/api/sqlmigrate.py +69 -0
- rakko/migrations/autodetector.py +203 -0
- rakko/migrations/constraints.py +31 -0
- rakko/migrations/exceptions.py +10 -0
- rakko/migrations/executor.py +368 -0
- rakko/migrations/expressions.py +13 -0
- rakko/migrations/graph.py +158 -0
- rakko/migrations/loader.py +127 -0
- rakko/migrations/migration.py +189 -0
- rakko/migrations/operations.py +1288 -0
- rakko/migrations/recorder.py +104 -0
- rakko/migrations/schema_editor/__init__.py +25 -0
- rakko/migrations/schema_editor/asyncpg.py +11 -0
- rakko/migrations/schema_editor/base.py +945 -0
- rakko/migrations/schema_editor/base_postgres.py +171 -0
- rakko/migrations/schema_editor/data.py +18 -0
- rakko/migrations/schema_editor/mssql.py +339 -0
- rakko/migrations/schema_editor/mysql.py +408 -0
- rakko/migrations/schema_editor/oracle.py +259 -0
- rakko/migrations/schema_editor/psycopg.py +11 -0
- rakko/migrations/schema_editor/sqlite.py +424 -0
- rakko/migrations/schema_generator/__init__.py +5 -0
- rakko/migrations/schema_generator/operation_generator.py +163 -0
- rakko/migrations/schema_generator/state.py +224 -0
- rakko/migrations/schema_generator/state_apps.py +165 -0
- rakko/migrations/schema_generator/state_diff.py +419 -0
- rakko/migrations/writer.py +515 -0
- rakko/models.py +1854 -0
- rakko/py.typed +0 -0
- rakko/query_api.py +134 -0
- rakko/query_utils.py +238 -0
- rakko/queryset.py +2743 -0
- rakko/relations.py +85 -0
- rakko/router.py +55 -0
- rakko/schema_quoting.py +62 -0
- rakko/signals.py +73 -0
- rakko/timezone.py +173 -0
- rakko/transactions.py +69 -0
- rakko/utils.py +50 -0
- rakko/validators.py +412 -0
- rakko/warnings.py +22 -0
- rakko_orm-1.0.0a0.dist-info/METADATA +114 -0
- rakko_orm-1.0.0a0.dist-info/RECORD +143 -0
- rakko_orm-1.0.0a0.dist-info/WHEEL +4 -0
- rakko_orm-1.0.0a0.dist-info/entry_points.txt +5 -0
- rakko_orm-1.0.0a0.dist-info/licenses/CONTRIBUTORS.rst +86 -0
- rakko_orm-1.0.0a0.dist-info/licenses/LICENSE.txt +201 -0
- 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
|
+
}
|