summaryrefslogtreecommitdiff
path: root/doc/build/orm/tutorial.rst
Commit message (Collapse)AuthorAgeFilesLines
* further 2.0 modernizationsMike Bayer2022-10-131-1/+1
| | | | | | | biggest change here is the old tutorials were removed from the TOC and some additional links to them have been corrected. Change-Id: I79b878a946422eac24ed2449b440fc5d556576c4
* pass through docs for 2.0 styleMike Bayer2021-11-111-0/+12
| | | | | | | | | | | this change restores the orm/tutorial.rst and core/tutorial.rst files, hidden from the index with an update on the new tutorial. Also started noting Query is legacy, as we will have lots of docs to update for 2.0 style. Change-Id: I4f98eeaaa0fd6e03b9976320b568975fe6d06ade
* initial 2.0 setupMike Bayer2021-10-301-2257/+0
| | | | | | | Adapted from 55e64f857daeb6057b85ff67297a774b when we previously started a 2.0 branch. Change-Id: Ib5af75df94b23104eebe0e918adcf979d798ea3b
* Merge "Modernize tests - session_query_get" into mainmike bayer2021-10-291-1/+1
|\
| * Modernize tests - session_query_getGord Thompson2021-10-281-1/+1
| | | | | | | | | | Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com> Change-Id: I92013aad471baf32df1b51b756e86d95449b5cfd
* | warnings: cascade_backrefsMike Bayer2021-10-281-0/+4
|/ | | | | | | this one is a little different in that the thing changing is the detection of a behavior, not an explicit API. Change-Id: Id142943a2b901b39fe9053d0120c1e820dc1a6d0
* turn off deduping for col expressionsMike Bayer2021-09-041-2/+4
| | | | | | | | | | | | | Fixed ORM issue where column expressions passed to ``query()`` or ORM-enabled ``select()`` would be deduplicated on the identity of the object, such as a phrase like ``select(A.id, null(), null())`` would produce only one "NULL" expression, which previously was not the case in 1.3. However, the change also allows for ORM expressions to render as given as well, such as ``select(A.data, A.data)`` will produce a result row with two columns. Fixes: #6979 Change-Id: I4dd59d4c7b1baa711b686379eb959f87c44841c4
* standardizing docs #6821jonathan vanasco2021-08-231-3/+3
| | | | | | | | | | | | | | | | | | | | | | | | | (redo of 2999/I5609025feee8cfdecc09b55bfbf1bd13fa2e6602) This PR is designed to bring more clarity within the docs by renaming object instances that may be consfusingly similar to class, method, and attribute names. For example, instances of the class `MetaData` are available on some objects as `.metadata` property, and had appeared within the docs as both `meta` and `metadata` which has confused some users in the past. By this PR, the docs now utilize the following naming convention: * MetaData - SQLAlchemy class * .metadata - SQLAlchemy API attributes * metadata_obj - developer instantiated metadata objects or references Detailed Changes: * standardized `meta` and `metadata` instances to `metadata_obj`. note: the docs were evenly split between 'meta' and 'metadata'. * standardized 'cursor' to 'cursor_obj' to avoid confusion with the method. * standardized a 'scalar_subquery = ' to 'scalar_subq' to avoid confusion with the method. * standardized a 'cte = ' to 'cte_obj' to avoid confusion with the method Change-Id: I79c98aee16c5fc6649289b2dd7d6dfc368222fb4
* Replace all http:// links to https://Federico Caselli2021-07-041-2/+2
| | | | | | Also replace http://pypi.python.org/pypi with https://pypi.org/project Change-Id: I84b5005c39969a82140706472989f2a30b0c7685
* As of 1.1, there are five object statesJohn Whitlock2021-02-241-2/+2
|
* Create explicit GC ordering between ConnectionFairy/ConnectionRecordMike Bayer2021-01-151-0/+6
| | | | | | | | | | | | | | Fixed issue where connection pool would not return connections to the pool or otherwise be finalized upon garbage collection under pypy if the checked out connection fell out of scope without being closed. This is a long standing issue due to pypy's difference in GC behavior that does not call weakref finalizers if they are relative to another object that is also being garbage collected. A strong reference to the related record is now maintained so that the weakref has a strong-referenced "base" to trigger off of. Fixes: #5842 Change-Id: Id5448fdacb6cceaac1ea40b2fbc851f052ed8e86
* tutorial 2.0 WIPreview/mike_bayer/tutorial20Mike Bayer2020-10-311-13/+30
| | | | | | | | | | | | | | Add SelectBase.exists() method as it seems strange this is not available already. The Exists construct itself does not provide full SELECT-building capabilities so it makes sense this should be used more like a scalar_subquery. Make sure stream_results is getting set up when yield_per is used, for 2.0 style statements as well. this was hardcoded inside of Query.yield_per() and is now moved to take place within QueryContext. Change-Id: Icafcd4fd9b708772343d56edf40995c9e8f835d6
* new docs WIPMike Bayer2020-09-241-3/+3
| | | | | | | | | | | | | | | This WIP is part of the final push for 1.4's docs to fully "2.0-ize" what we can, and have it all ready. So far this includes a rewrite of the 2.0 migration, set up for the 1.4 /2.0 docs style, and a total redesign of the index page using a new flex layout in zzzeeksphinx. It also reworks some of the API reference sections to have more subheaders. zzzeeksphinx is also enhanced to provide automatic summaries for all api doc section. Change-Id: I01d360cb9c8749520246b96ee6496143c6037918
* Rename Core expression isnot, not_in_jonathan vanasco2020-09-141-3/+3
| | | | | | | | | | | | | | | | | | | Several operators are renamed to achieve more consistent naming across SQLAlchemy. The operator changes are: * `isnot` is now `is_not` * `not_in_` is now `not_in` Because these are core operators, the internal migration strategy for this change is to support legacy terms for an extended period of time -- if not indefinitely -- but update all documentation, tutorials, and internal usage to the new terms. The new terms are used to define the functions, and the legacy terms have been deprecated into aliases of the new terms. Fixes: #5429 Change-Id: Ia1e66e7a50ac35d3f6260d8bf6ba3ce8087cbad2
* Build out new declarative systems; deprecate mapper()Mike Bayer2020-09-101-1/+1
| | | | | | | | | | | | | The ORM Declarative system is now unified into the ORM itself, with new import spaces under ``sqlalchemy.orm`` and new kinds of mappings. Support for decorator-based mappings without using a base class, support for classical style-mapper() calls that have access to the declarative class registry for relationships, and full integration of Declarative with 3rd party class attribute systems like ``dataclasses`` and ``attrs`` is now supported. Fixes: #5508 Change-Id: I130b2b6edff6450bfe8a3e6baa099ff04b5471ff
* Emit v2.0 deprecation warning for "implicit autocommit"Gord Thompson2020-08-281-10/+18
| | | | | | | | | | | | | | | | | | | | | | | | | "Implicit autocommit", which is the COMMIT that occurs when a DML or DDL statement is emitted on a connection, is deprecated and won't be part of SQLAlchemy 2.0. A 2.0-style warning is emitted when autocommit takes effect, so that the calling code may be adjusted to use an explicit transaction. As part of this change, DDL methods such as :meth:`_schema.MetaData.create_all` when used against a :class:`_engine.Engine` or :class:`_engine.Connection` will run the operation in a BEGIN block if one is not started already. The MySQL and MariaDB dialects now query from the information_schema.tables system view in order to determine if a particular table exists or not. Previously, the "DESCRIBE" command was used with an exception catch to detect non-existent, which would have the undesirable effect of emitting a ROLLBACK on the connection. There appeared to be legacy encoding issues which prevented the use of "SHOW TABLES", for this, but as MySQL support is now at 5.0.2 or above due to :ticket:`4189`, the information_schema tables are now available in all cases. Fixes: #4846 Change-Id: I733a7e0e17477a63607fb9931c87c393bbd7ac57
* Documentation updates for 1.4Mike Bayer2020-08-051-3/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * major additions to 1.4 migration doc; removed additional verbosity regarding caching methodology and reorganized the doc to present itself more as a "what's changed" guide * as we now have a path for asyncio, update that doc so that we aren't spreading obsolete information * updates to the 2.0 migration guide with latest info, however this is still an architecture doc and not a migration guide yet, will need further rework. * start really talking about 1.x vs. 2.0 style everywhere. Querying is most of the docs so this is going to be a prominent theme, start getting it to fit in * Add introductory documentation for ORM example sections as these are too sparse * new documentation for do_orm_execute(), many separate sections, adding deprecation notes to before_compile() and similar * new example suites to illustrate do_orm_execute(), with_loader_criteria() * modernized horizontal sharding examples and added a separate example to distinguish between multiple databases and single database w/ multiple tables use case * introducing DEEP ALCHEMY, will use zzzeeksphinx 1.1.6 * no name for the alchemist yet however the dragon's name is Flambé Change-Id: Id6b5c03b1ce9ddb7b280f66792212a0ef0a1c541
* Fix a wide variety of typos and broken linksaplatkouski2020-06-251-11/+11
| | | | | | | | | | | | Note the PR has a few remaining doc linking issues listed in the comment that must be addressed separately. Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com> Closes: #5371 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/5371 Pull-request-sha: 7e7d233cf3a0c66980c27db0fcdb3c7d93bc2510 Change-Id: I9c36e8d8804483950db4b42c38ee456e384c59e3
* Turn on caching everywhere, add loggingMike Bayer2020-06-101-78/+78
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | A variety of caching issues found by running all tests with statement caching turned on. The cache system now has a more conservative approach where any subclass of a SQL element will by default invalidate the cache key unless it adds the flag inherit_cache=True at the class level, or if it implements its own caching. Add working caching to a few elements that were omitted previously; fix some caching implementations to suit lesser used edge cases such as json casts and array slices. Refine the way BaseCursorResult and CursorMetaData interact with caching; to suit cases like Alembic modifying table structures, don't cache the cursor metadata if it were created against a cursor.description using non-positional matching, e.g. "select *". if a table re-ordered its columns or added/removed, now that data is obsolete. Additionally we have to adapt the cursor metadata _keymap regardless of if we just processed cursor.description, because if we ran against a cached SQLCompiler we won't have the right columns in _keymap. Other refinements to how and when we do this adaption as some weird cases were exposed in the Postgresql dialect, a text() construct that names just one column that is not actually in the statement. Fixed that also as it looks like a cut-and-paste artifact that doesn't actually affect anything. Various issues with re-use of compiled result maps and cursor metadata in conjunction with tables being changed, such as change in order of columns. mappers can be cleared but the class remains, meaning a mapper has to use itself as the cache key not the class. lots of bound parameter / literal issues, due to Alembic creating a straight subclass of bindparam that renders inline directly. While we can update Alembic to not do this, we have to assume other people might be doing this, so bindparam() implements the inherit_cache=True logic as well that was a bit involved. turn on cache stats in logging. Includes a fix to subqueryloader which moves all setup to the create_row_processor() phase and elminates any storage within the compiled context. This includes some changes to create_row_processor() signature and a revising of the technique used to determine if the loader can participate in polymorphic queries, which is also applied to selectinloading. DML update.values() and ordered_values() now coerces the keys as we have tests that pass an arbitrary class here which only includes __clause_element__(), so the key can't be cached unless it is coerced. this in turn changed how composite attributes support bulk update to use the standard approach of ClauseElement with annotations that are parsed in the ORM context. memory profiling successfully caught that the Session from Query was getting passed into _statement_20() so that was a big win for that test suite. Apparently Compiler had .execute() and .scalar() methods stuck on it, these date back to version 0.4 and there was a single test in the PostgreSQL dialect tests that exercised it for no apparent reason. Removed these methods as well as the concept of a Compiler holding onto a "bind". Fixes: #5386 Change-Id: I990b43aab96b42665af1b2187ad6020bee778784
* Disable "check unicode returns" under Python 3Mike Bayer2020-05-191-1/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | Disabled the "unicode returns" check that runs on dialect startup when running under Python 3, which for many years has occurred in order to test the current DBAPI's behavior for whether or not it returns Python Unicode or Py2K strings for the VARCHAR and NVARCHAR datatypes. The check still occurs by default under Python 2, however the mechanism to test the behavior will be removed in SQLAlchemy 2.0 when Python 2 support is also removed. This logic was very effective when it was needed, however now that Python 3 is standard, all DBAPIs are expected to return Python 3 strings for character datatypes. In the unlikely case that a third party DBAPI does not support this, the conversion logic within :class:`.String` is still available and the third party dialect may specify this in its upfront dialect flags by setting the dialect level flag ``returns_unicode_strings`` to one of :attr:`.String.RETURNS_CONDITIONAL` or :attr:`.String.RETURNS_BYTES`, both of which will enable Unicode conversion even under Python 3. As part of this change, disabling testing of the doctest tutorials under Python 2. Fixes: #5315 Change-Id: I1260e894611409d3b7fe1a92bd90c52043bbcf19
* Consider aliased=True, from_joinpoint as legacyMike Bayer2020-05-041-7/+16
| | | | | | | | | | | | | | | | For a 1.4 / 1.3 merge, rewrite the documentation for Query.join() to indicate calling forms that are now considered legacy, including the use of strings in join(), sending a series of join paths in one call, and using the aliased=True flag. update the elementtree examples as well to use aliased() (they are much simpler to understand this way too) and update other links. Also improve docs for aliased() and some other ORM targets such as PropComparator. Change-Id: I636e3a9130dc5509e51c2cf60a52f38fcadffbc6 References: #4705
* Set up absolute references for create_engine and relatedMike Bayer2020-04-141-3/+3
| | | | | | | includes more replacements for create_engine(), Connection, disambiguation of Result from future/baked Change-Id: Icb60a79ee7a6c45ea9056c211ffd1be110da3b5e
* Run search and replace of symbolic module namesMike Bayer2020-04-141-85/+85
| | | | | | | | Replaces a wide array of Sphinx-relative doc references with an abbreviated absolute form now supported by zzzeeksphinx. Change-Id: I94bffcc3f37885ffdde6238767224296339698a2
* Add missing definitions to glossaryMike Bayer2020-04-131-1/+1
| | | | | | improve formatting Change-Id: Iea3b72187d7c8020e18babb72a53c39c5aeec68c
* Remove ORDER BY pk from subqueryload, selectinloadMike Bayer2020-03-301-1/+1
| | | | | | | | | | | | | | | | | | | | Modified the queries used by subqueryload and selectinload to no longer ORDER BY the primary key of the parent entity; this ordering was there to allow the rows as they come in to be copied into lists directly with a minimal level of Python-side collation. However, these ORDER BY clauses can negatively impact the performance of the query as in many scenarios these columns are derived from a subquery or are otherwise not actual primary key columns such that SQL planners cannot make use of indexes. The Python-side collation uses the native itertools.group_by() to collate the incoming rows, and has been modified to allow multiple row-groups-per-parent to be assembled together using list.extend(), which should still allow for relatively fast Python-side performance. There will still be an ORDER BY present for a relationship that includes an explicit order_by parameter, however this is the only ORDER BY that will be added to the query for both kinds of loading. Fixes: #5162 Change-Id: I8befd1303c1af7cc24cbf005f39bc01c8b2745f3
* Result initial introductionMike Bayer2020-02-211-23/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This builds on cc718cccc0bf8a01abdf4068c7ea4f3 which moved RowProxy to Row, allowing Row to be more like a named tuple. - KeyedTuple in ORM is replaced with Row - ResultSetMetaData broken out into "simple" and "cursor" versions for ORM and Core, as well as LegacyCursor version. - Row now has _mapping attribute that supplies full mapping behavior. Row and SimpleRow both have named tuple behavior otherwise. LegacyRow has some mapping features on the tuple which emit deprecation warnings (e.g. keys(), values(), etc). the biggest change for mapping->tuple is the behavior of __contains__ which moves from testing of "key in row" to "value in row". - ResultProxy breaks into ResultProxy and FutureResult (interim), the latter has the newer APIs. Made available to dialects using execution options. - internal reflection methods and most tests move off of implicit Row mapping behavior and move to row._mapping, result.mappings() method using future result - a new strategy system for cursor handling replaces the various subclasses of RowProxy - some execution context adjustments. We will leave EC in but refined things like get_result_proxy() and out parameter handling. Dialects for 1.4 will need to adjust from get_result_proxy() to get_result_cursor_strategy(), if they are using this method - out parameter handling now accommodated by get_out_parameter_values() EC method. Oracle changes for this. external dialect for DB2 for example will also need to adjust for this. - deprecate case_insensitive flag for engine / result, this feature is not used mapping-methods on Row are deprecated, and replaced with Row._mapping.<meth>, including: row.keys() -> use row._mapping.keys() row.items() -> use row._mapping.items() row.values() -> use row._mapping.values() key in row -> use key in row._mapping int in row -> use int < len(row) Fixes: #4710 Fixes: #4878 Change-Id: Ieb9085e9bcff564359095b754da9ae0af55679f0
* Add note on the use of tuple_() for the IN operator in the docsStepland2019-09-161-0/+7
| | | | | | | | Closes: #4861 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/4861 Pull-request-sha: c7379d390752d0c10d6488872b163b06ee30d952 Change-Id: I223008f720fe64951e2a0bf95aab955ece22516b
* Document Query deduplicationMike Bayer2019-09-051-0/+17
| | | | | | | | | | Users are frequently confused why count() does not return the same number as the number of objects returned by all(). While we continue to want to find a better solution to this problem, in the meantime this has never been clearly documented. Add an FAQ section with links from .count() , .all(), ORM tutorial. Change-Id: I6eff36b686ff6cdd55489036fc48a981bc47d5ee
* Always include a schema name in SQLite PRAGMAMike Bayer2019-08-021-1/+3
| | | | | | | | | | | | | | Fixed bug where usage of "PRAGMA table_info" in SQLite dialect meant that reflection features to detect for table existence, list of table columns, and list of foreign keys, would default to any table in any attached database, when no schema name was given and the table did not exist in the base schema. The fix explicitly runs PRAGMA for the 'main' schema and then the 'temp' schema if the 'main' returned no rows, to maintain the behavior of tables + temp tables in the "no schema" namespace, attached tables only in the "schema" namespace. Fixes: #4793 Change-Id: I75bc03ef42581c46b98987510d2d2e701df07412
* - continued 1.4 setup, somehow the commit didn't workMike Bayer2019-04-271-2/+2
| | | | | Fixes: #4631 Change-Id: I400e388a704aa6ee7722a89687a033083ce22550
* Remove all occurrences of the word "password" from all examples and tutorialsMike Bayer2019-02-051-107/+107
| | | | | Fixes: #4484 Change-Id: I97e8cbd9f4906332ac0a4fe9c8496a0147fc9a9b
* selectinload omit joinJayson Reis2018-10-101-26/+20
| | | | | | | | | | | | | | | | | | | | | | The "selectin" loader strategy now omits the JOIN in the case of a simple one-to-many load, where it instead relies upon the foreign key columns of the related table in order to match up to primary keys in the parent table. This optimization can be disabled by setting the :paramref:`.relationship.omit_join` flag to False. Many thanks to Jayson Reis for the efforts on this. As part of this change, horizontal shard no longer relies upon the _mapper_zero() method to get the query-bound mapper, instead using the more generalized _bind_mapper() (which will use mapper_zero if no explicit FROM is present). A short check for the particular recursive condition is added to BundleEntity and it no longer assigns itself as the "namespace" to its ColumnEntity objects which creates a reference cycle. Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com> Fixes: #4340 Change-Id: I649587e1c07b684ecd63f7d10054cd165891baf4 Pull-request: https://bitbucket.org/zzzeek/sqlalchemy/pull-requests/7
* Setup master as 1.3Mike Bayer2018-03-021-2/+2
| | | | Change-Id: I1e8240d19f891cb6575f10d93524b551d74864ea
* Make flush logic slightly clearer in tutorial.Feanil Patel2017-07-231-1/+1
| | | Improve the wording of how sessions commit changes.
* Replace Session class with session instanceTom Sitter2017-07-121-1/+1
| | | The Session class was used instead of the session instance which resulted in an attribute error.
* Repair formatting throughout documentationKataev Denis2017-05-221-5/+5
| | | | | | | | | | | 1. Section decorators to [one style](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections): without inset at both side and with same length as text. 2. Fix broken [reference](http://docs.sqlalchemy.org/en/latest/core/type_basics.html#generic-types). 3. Convert tabs to space in some small files. 4. Some python code snippets have python+sql syntax hint. Change-Id: I39a7a41ef0b0591c6bf1e610748e2b5c19fc5379 Pull-request: https://github.com/zzzeek/sqlalchemy/pull/361
* - bump minimum python version to 2.7Mike Bayer2017-03-101-2/+2
| | | | | | - add placeholder 1.2 release documentation, update intro numbers Change-Id: I9f9969cbb9e95c2f750a5c16798e92c35a5ef6cf
* - correctly document LIKE / ILIKE, fixes #3890Mike Bayer2017-01-161-1/+14
| | | | Change-Id: Ie59e61f53d7c59a4777ab9e6e75a43c71d67523b
* Fix a minor grammatical error in the ORM tutorial.Randy Barlow2016-10-131-2/+2
| | | | Change-Id: I50daaee2645dd8aa2ee7217f4065589492ed0b7d
* spelling: Postgresql -> PostgreSQLVille Skyttä2016-10-081-1/+1
|
* Fix typopr/249Benjamin Dopplinger2016-03-161-1/+1
|
* - clarify the "Adding" section also illustrates updates, fixes #2942Mike Bayer2016-01-201-3/+6
|
* - illustrate these using the newer exception doctest format.Mike Bayer2016-01-141-26/+8
| | | | | unfortunately we can't show the SQL unless we filtered it out from doctest...not worth it
* - A deep improvement to the recently added :meth:`.TextClause.columns`Mike Bayer2016-01-141-15/+30
| | | | | | | | | | | | | | | | | | | method, and its interaction with result-row processing, now allows the columns passed to the method to be positionally matched with the result columns in the statement, rather than matching on name alone. The advantage to this includes that when linking a textual SQL statement to an ORM or Core table model, no system of labeling or de-duping of common column names needs to occur, which also means there's no need to worry about how label names match to ORM columns and so-forth. In addition, the :class:`.ResultProxy` has been further enhanced to map column and string keys to a row with greater precision in some cases. fixes #3501 - reorganize the initialization of ResultMetaData for readability and complexity; use the name "cursor_description", define the task of "merging" cursor_description with compiled column information as its own function, and also define "name extraction" as a separate task. - fully change the name we use in the "ambiguous column" error to be the actual name that was ambiguous, modify the C ext also
* - convert ORM tutorial and basic_relationships to favorMike Bayer2015-12-101-24/+41
| | | | | back_populates while still maintaining great familiarity w/ backref so as not to confuse people. fixes #3390
* - The ORM and Core tutorials, which have always been in doctest format,Mike Bayer2015-12-101-110/+99
| | | | | | | | | | | are now exercised within the normal unit test suite in both Python 2 and Python 3. - remove the old testdocs.py runner and replace with test/base/test_tutorials.py - use pytest's unicode fixer so that we can test for unicode strings in both py2k/3k - use py3k format overall for prints, exceptions - add other fixers to guarantee deterministic results - add skips and ellipses to outputs that aren't worth matching
* - add an additional note regarding select_from, fixes #3546Mike Bayer2015-10-021-0/+10
|
* - remove ambiguous use of the phrase "joined together by AND" as thisMike Bayer2015-10-011-0/+6
| | | | | | | may be construed as the Python "and" keyword - add notes to ORM tutorial for beginners that Python "and" keyword is not to be used fixes #3545
* Add Query.one_or_none()pr/201Eric Siegerman2015-09-241-1/+6
|
* - update moved link, fixes #3351Mike Bayer2015-09-031-1/+1
|
View Lorry Controller Status