Databaser¶
Django har officiellt stöd för följande databaser:
Det finns ocksÄ ett antal databasbackends som tillhandahÄlls av tredje part.
Django försöker att stödja sÄ mÄnga funktioner som möjligt pÄ alla databasbackends. Alla databasbackends Àr dock inte likadana, och vi har varit tvungna att fatta designbeslut om vilka funktioner som ska stödjas och vilka antaganden vi kan göra pÄ ett sÀkert sÀtt.
Den hÀr filen beskriver nÄgra av de funktioner som kan vara relevanta för Django-anvÀndning. Den Àr inte avsedd att ersÀtta serverspecifik dokumentation eller referenshandböcker.
AllmÀnna anteckningar¶
BestÀndiga anslutningar¶
Med bestÀndiga anslutningar undviks omkostnaderna för att ÄterupprÀtta en anslutning till databasen vid varje HTTP-begÀran. De styrs av parametern CONN_MAX_AGE som definierar den maximala livslÀngden för en anslutning. Den kan stÀllas in oberoende för varje databas.
StandardvÀrdet Àr 0, vilket bevarar det historiska beteendet att stÀnga databasanslutningen i slutet av varje begÀran. För att aktivera lÄngvariga anslutningar, stÀll in CONN_MAX_AGE till ett positivt heltal av sekunder. För obegrÀnsade lÄngvariga anslutningar, stÀll in den pÄ None.
NÀr ASGI anvÀnds bör permanenta anslutningar inaktiveras. AnvÀnd istÀllet databasens inbyggda anslutningspoolning om den finns tillgÀnglig, eller undersök ett alternativ för anslutningspoolning frÄn tredje part om det behövs.
Hantering av anslutningar¶
Django öppnar en anslutning till databasen nÀr den först gör en databasförfrÄgan. Den hÄller denna anslutning öppen och ÄteranvÀnder den i efterföljande förfrÄgningar. Django stÀnger anslutningen nÀr den överskrider den maximala Älder som definieras av CONN_MAX_AGE eller nÀr den inte lÀngre kan anvÀndas.
I detalj öppnar Django automatiskt en anslutning till databasen nÀr den behöver en och inte redan har en - antingen för att detta Àr den första anslutningen eller för att den tidigare anslutningen stÀngdes.
I början av varje begÀran stÀnger Django anslutningen om den har nÄtt sin maximala Älder. Om din databas avslutar inaktiva anslutningar efter en viss tid bör du stÀlla in CONN_MAX_AGE till ett lÀgre vÀrde, sÄ att Django inte försöker anvÀnda en anslutning som har avslutats av databasservern. (Detta problem kan endast pÄverka webbplatser med mycket lÄg trafik)
I slutet av varje begÀran stÀnger Django anslutningen om den har nÄtt sin maximala Älder eller om den befinner sig i ett feltillstÄnd som inte kan ÄterstÀllas. Om nÄgra databasfel har intrÀffat under behandlingen av begÀrandena kontrollerar Django om anslutningen fortfarande fungerar och stÀnger den om den inte gör det. Databasfel pÄverkar sÄledes högst en begÀran per varje applikations arbetstrÄd; om anslutningen blir oanvÀndbar fÄr nÀsta begÀran en ny anslutning.
Om du sÀtter CONN_HEALTH_CHECKS till True kan du förbÀttra robustheten för ÄteranvÀndning av anslutningar och förhindra fel nÀr en anslutning har stÀngts av databasservern som nu Àr redo att ta emot och hantera nya anslutningar, t.ex. efter omstart av databasservern. HÀlsokontrollen utförs endast en gÄng per begÀran och endast om databasen nÄs under hanteringen av begÀran.
FörbehÄll¶
Eftersom varje trÄd upprÀtthÄller sin egen anslutning mÄste din databas stödja minst lika mÄnga samtidiga anslutningar som du har arbetstrÄdar.
Ibland kommer majoriteten av dina vyer inte Ät en databas, t.ex. för att det Àr databasen för ett externt system eller tack vare cachning. I sÄdana fall bör du stÀlla in CONN_MAX_AGE till ett lÄgt vÀrde eller till och med 0, eftersom det inte Àr meningsfullt att upprÀtthÄlla en anslutning som sannolikt inte kommer att ÄteranvÀndas. Detta bidrar till att hÄlla nere antalet samtidiga anslutningar till databasen.
Utvecklingsservern skapar en ny trÄd för varje begÀran som den hanterar, vilket upphÀver effekten av bestÀndiga anslutningar. Aktivera dem inte under utveckling.
NÀr Django upprÀttar en anslutning till databasen stÀller den in lÀmpliga parametrar, beroende pÄ vilken backend som anvÀnds. Om du aktiverar bestÀndiga anslutningar upprepas inte lÀngre denna instÀllning vid varje begÀran. Om du Àndrar parametrar som anslutningens isoleringsnivÄ eller tidszon, bör du antingen ÄterstÀlla Djangos standardvÀrden i slutet av varje begÀran, tvinga fram ett lÀmpligt vÀrde i början av varje begÀran eller inaktivera bestÀndiga anslutningar.
Om en anslutning skapas i en lÄngvarig process, utanför Djangos request-response-cykel, kommer anslutningen att förbli öppen tills den uttryckligen stÀngs eller timeout intrÀffar. Du kan anvÀnda django.db.close_old_connections() för att stÀnga alla gamla eller oanvÀndbara anslutningar.
Avkodning¶
Django förutsĂ€tter att alla databaser anvĂ€nder UTF-8-kodning. Om du anvĂ€nder andra kodningar kan det leda till ovĂ€ntat beteende, till exempel âvĂ€rdet Ă€r för lĂ„ngtâ-fel frĂ„n din databas för data som Ă€r giltiga i Django. Se de databasspecifika anmĂ€rkningarna nedan för information om hur du konfigurerar din databas korrekt.
PostgreSQL anteckningar¶
Django stöder PostgreSQL 14 och högre. psycopg 3.1.8+ eller psycopg2 2.8.4+ krÀvs, men den senaste psycopg 3.1.8+ rekommenderas.
Observera
Stöd för psycopg2 kommer sannolikt att bli förÄldrat och tas bort nÄgon gÄng i framtiden.
PostgreSQL-anslutningsinstÀllningar¶
Se HOST för mer information.
Om du vill ansluta med ett servicenamn frÄn connection service file och ett lösenord frÄn password file mÄste du ange dem i OPTIONS-delen av din databaskonfiguration i DATABASES:
settings.py¶DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"OPTIONS": {
"service": "my_service",
"passfile": ".my_pgpass",
},
}
}
.pg_service.conf¶[my_service]
host=localhost
user=USER
dbname=NAME
port=5432
.my_pgpass¶localhost:5432:NAME:USER:PASSWORD
PostgreSQL-backend skickar innehÄllet i OPTIONS som nyckelordsargument till anslutningskonstruktören, vilket möjliggör mer avancerad kontroll av drivrutinsbeteendet. Alla tillgÀngliga parametrar beskrivs i detalj i PostgreSQL-dokumentationen.
Varning
Att anvÀnda ett servicenamn för testÀndamÄl stöds inte. Denna kan komma att implementeras senare.
Optimera PostgreSQL: s konfiguration¶
Django behöver följande parametrar för sina databasanslutningar:
client_encoding:'UTF8',default_transaction_isolation:'read committed'som standard, eller det vÀrde som anges i anslutningsalternativen (se nedan),
Om dessa parametrar redan har rÀtt vÀrden kommer Django inte att stÀlla in dem för varje ny anslutning, vilket förbÀttrar prestandan nÄgot. Du kan konfigurera dem direkt i postgresql.conf eller mer bekvÀmt per databasanvÀndare med ALTER ROLE.
Django fungerar bra utan denna optimering, men varje ny anslutning kommer att göra nÄgra ytterligare frÄgor för att stÀlla in dessa parametrar.
IsolationsnivĶ
Liksom PostgreSQL sjÀlv, Àr Django standard för READ COMMITTED isoleringsnivÄ`_. Om du behöver en högre isoleringsnivÄ, till exempel ``REPEATABLE READ eller SERIALIZABLE, stÀller du in den i OPTIONS-delen av din databaskonfiguration i DATABASES:
from django.db.backends.postgresql.psycopg_any import IsolationLevel
DATABASES = {
# ...
"OPTIONS": {
"isolation_level": IsolationLevel.SERIALIZABLE,
},
}
Observera
Vid högre isoleringsnivÄer bör ditt program vara förberett pÄ att hantera undantag som uppstÄr vid serialiseringsfel. Det hÀr alternativet Àr avsett för avancerad anvÀndning.
Roll¶
Om du behöver anvÀnda en annan roll för databasanslutningar Àn den roll som anvÀnds för att upprÀtta anslutningen, anger du den i OPTIONS-delen av din databaskonfiguration i DATABASES:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
# ...
"OPTIONS": {
"assume_role": "my_application_role",
},
},
}
Anslutningspool¶
För att anvÀnda en anslutningspool med psycopg kan du antingen stÀlla in "pool" i OPTIONS-delen av din databaskonfiguration i DATABASER till att vara en dict som ska skickas till ConnectionPool, eller till True för att anvÀnda ConnectionPool-standardvÀrdena:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
# ...
"OPTIONS": {
"pool": True,
},
},
}
Detta alternativ krÀver att psycopg[pool] eller psycopg-pool Àr installerat och ignoreras med psycopg2.
Bindning av parametrar pÄ serversidan¶
Med psycopg 3.1.8+ anvÀnder Django som standard client-side binding cursors. Om du vill anvÀnda server-side binding stÀll in det i OPTIONS-delen av din databaskonfiguration i DATABASES:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
# ...
"OPTIONS": {
"server_side_binding": True,
},
},
}
Detta alternativ ignoreras med psycopg2.
Index för kolumnerna varchar och text¶
NÀr du anger db_index=True pÄ dina modellfÀlt, skriver Django vanligtvis ut ett enda CREATE INDEX-uttalande. Men om databastypen för fÀltet Àr antingen varchar eller text (t.ex. anvÀnds av CharField, FileField och TextField), kommer Django att skapa ett extra index som anvÀnder en lÀmplig PostgreSQL-operatörsklass för kolumnen. Det extra indexet Àr nödvÀndigt för att korrekt utföra uppslagningar som anvÀnder operatören LIKE i sin SQL, vilket görs med uppslagningstyperna contains och startswith.
Migrationsoperation för att lÀgga till tillÀgg¶
Om du behöver lÀgga till en PostgreSQL-förlÀngning (som hstore, postgis, etc.) med hjÀlp av en migrering, anvÀnd CreateExtension operation.
Markörer pÄ serversidan¶
NÀr du anvÀnder QuerySet.iterator() öppnar Django en server-side cursor. Som standard antar PostgreSQL att endast de första 10% of resultaten av markörfrÄgor kommer att hÀmtas. FrÄgeplaneraren spenderar mindre tid pÄ att planera frÄgan och börjar returnera resultat snabbare, men detta kan minska prestandan om mer Àn 10% of resultaten hÀmtas. PostgreSQL: s antaganden om antalet rader som hÀmtas för en markörfrÄga styrs med alternativet cursor_tuple_fraction.
Transaktionspoolning och cursorer pÄ serversidan¶
Om du anvÀnder en anslutningspooler i transaktionspoolningslÀge (t.ex. PgBouncer) mÄste du inaktivera markörer pÄ serversidan för den anslutningen.
Markörer pÄ serversidan Àr lokala för en anslutning och förblir öppna i slutet av en transaktion nÀr AUTOCOMMIT Àr True. En efterföljande transaktion kan försöka hÀmta fler resultat frÄn en markör pÄ serversidan. I transaktionspoolningslÀget finns det ingen garanti för att efterföljande transaktioner kommer att anvÀnda samma anslutning. Om en annan anslutning anvÀnds uppstÄr ett fel nÀr transaktionen refererar till markören pÄ serversidan, eftersom markörer pÄ serversidan endast Àr tillgÀngliga i den anslutning dÀr de skapades.
En lösning Àr att inaktivera markörer pÄ serversidan för en anslutning i DATABASER genom att stÀlla in DISABLE_SERVER_SIDE_CURSORS till True.
Om du vill dra nytta av markörer pÄ serversidan i transaktionspoolningslÀge kan du konfigurera en annan anslutning till databasen för att utföra frÄgor som anvÀnder markörer pÄ serversidan. Den hÀr anslutningen mÄste antingen vara direkt till databasen eller till en anslutningspooler i sessionspoolningslÀge.
Ett annat alternativ Àr att linda in varje QuerySet som anvÀnder markörer pÄ serversidan i ett atomic()-block, eftersom det inaktiverar autocommit under transaktionens varaktighet. PÄ sÄ sÀtt kommer markören pÄ serversidan bara att leva under transaktionens varaktighet.
Manuellt specificerade vÀrden för primÀrnycklar med automatisk inkrementering¶
Django anvÀnder PostgreSQLs identitetskolumner för att lagra automatiskt ökande primÀrnycklar. En identitetskolumn fylls med vÀrden frÄn en sekvens som hÄller reda pÄ nÀsta tillgÀngliga vÀrde. Att manuellt tilldela ett vÀrde till ett fÀlt med automatisk ökning uppdaterar inte fÀltets sekvens, vilket senare kan orsaka en konflikt. Ett exempel:
>>> from django.contrib.auth.models import User
>>> User.objects.create(username="alice", pk=1)
<User: alice>
>>> # The sequence hasn't been updated; its next value is 1.
>>> User.objects.create(username="bob")
IntegrityError: duplicate key value violates unique constraint
"auth_user_pkey" DETAIL: Key (id)=(1) already exists.
Om du behöver ange sÄdana vÀrden ska du ÄterstÀlla sekvensen efterÄt för att undvika att ÄteranvÀnda ett vÀrde som redan finns i tabellen. Hanteringskommandot sqlsequencereset genererar SQL-satserna för att göra detta.
Test av databasmallar¶
Du kan anvÀnda instÀllningen TEST['TEMPLATE'] för att ange en template (t.ex. 'template0') frÄn vilken en testdatabas ska skapas.
Snabbare testkörning med icke-durabla instÀllningar¶
Du kan pÄskynda testkörningstiderna genom att konfigurera PostgreSQL för att vara icke-durable.
Varning
Detta Àr farligt: det gör din databas mer mottaglig för dataförlust eller korruption i hÀndelse av en serverkrasch eller strömavbrott. AnvÀnd detta endast pÄ en utvecklingsmaskin dÀr du enkelt kan ÄterstÀlla hela innehÄllet i alla databaser i klustret.
MariaDB anteckningar¶
Django stöder MariaDB 10.5 och senare.
För att anvÀnda MariaDB, anvÀnd MySQL-backend, som delas mellan de tvÄ. Se MySQL notes för mer information.
Anteckningar om MySQL¶
Stöd för version¶
Django stöder MySQL 8.0.11 och senare.
Djangos funktion inspectdb anvÀnder databasen information_schema, som innehÄller detaljerade uppgifter om alla databasscheman.
Django förvÀntar sig att databasen stöder Unicode (UTF-8-kodning) och delegerar till den uppgiften att upprÀtthÄlla transaktioner och referensintegritet. Det Àr viktigt att vara medveten om det faktum att de tvÄ sistnÀmnda faktiskt inte upprÀtthÄlls av MySQL nÀr MyISAM-lagringsmotorn anvÀnds, se nÀsta avsnitt.
Lagringsmotorer¶
MySQL har flera lagringsmotorer. Du kan Àndra standardlagringsmotorn i serverkonfigurationen.
MySQL:s standardlagringsmotor Ă€r InnoDB. Denna motor Ă€r helt transaktionell och stöder utlĂ€ndska nyckelreferenser. Det Ă€r det rekommenderade valet. InnoDB:s autoincrement-rĂ€knare gĂ„r dock förlorad vid en MySQL-omstart eftersom den inte kommer ihĂ„g vĂ€rdet AUTO_INCREMENT, utan istĂ€llet Ă„terskapar det som âmax(id)+1â. Detta kan resultera i en oavsiktlig Ă„teranvĂ€ndning av AutoField-vĂ€rden.
De största nackdelarna med MyISAM Àr att den inte stöder transaktioner eller upprÀtthÄller begrÀnsningar för utlÀndska nycklar.
MySQL DB API-drivrutiner¶
MySQL har ett par drivrutiner som implementerar Python Database API som beskrivs i PEP 249:
mysqlclient Àr en inbyggd drivrutin. Det Àr det rekommenderade valet.
MySQL Connector/Python Àr en ren Python-drivrutin frÄn Oracle som inte krÀver MySQL-klientbiblioteket eller nÄgra Python-moduler utanför standardbiblioteket.
Förutom en DB API-drivrutin behöver Django en adapter för att komma Ät databasdrivrutinerna frÄn sin ORM. Django tillhandahÄller en adapter för mysqlclient medan MySQL Connector/Python innehÄller sin egen.
mysqlclient¶
Django krÀver mysqlclient 1.4.3 eller senare.
MySQL Connector/Python¶
MySQL Connector/Python Àr tillgÀnglig frÄn nedladdningssidan. Django-adaptern Àr tillgÀnglig i version 1.1.X och senare. Den kanske inte stöder de senaste versionerna av Django.
Definitioner av tidszoner¶
Om du planerar att anvÀnda Djangos tidszonsstöd, anvÀnd mysql_tzinfo_to_sql för att ladda tidszonstabeller i MySQL-databasen. Detta behöver bara göras en gÄng för din MySQL-server, inte per databas.
Skapa din databas¶
Du kan skapa din databas med hjÀlp av kommandoradsverktygen och denna SQL:
CREATE DATABASE <dbname> CHARACTER SET utf8mb4;
Detta sÀkerstÀller att alla tabeller och kolumner anvÀnder UTF-8 som standard.
InstÀllningar för sortering¶
KollationsinstÀllningen för en kolumn styr den ordning i vilken data sorteras samt vilka strÀngar som jÀmförs som lika. Du kan ange parametern db_collation för att stÀlla in kolumnens kollationsnamn för CharField och TextField.
Kollationen kan ocksÄ stÀllas in pÄ en databasomfattande nivÄ och per tabell. Detta Àr dokumenterat grundligt i MySQL-dokumentationen. I sÄdana fall mÄste du stÀlla in sorteringen genom att direkt manipulera databasinstÀllningarna eller tabellerna. Django tillhandahÄller inte ett API för att Àndra dem.
Som standard, med en UTF-8-databas, kommer MySQL att anvÀnda kollationen utf8mb4_0900_ai_ci. Detta resulterar i att alla jÀmförelser av strÀnglikhet görs pÄ ett case-insensitive sÀtt. Det innebÀr att "Fred" och "freD" betraktas som lika pÄ databasnivÄ. Om du har en unik begrÀnsning pÄ ett fÀlt skulle det vara olagligt att försöka infoga bÄde "aa" och "AA" i samma kolumn, eftersom de jÀmförs som lika (och dÀrmed icke-unika) med standardkollationen. Om du vill ha jÀmförelser med skiftlÀgeskÀnslighet i en viss kolumn eller tabell, Àndrar du kolumnen eller tabellen sÄ att den anvÀnder sorteringen utf8mb4_0900_as_cs.
Observera att enligt MySQL Unicode Character Sets Àr jÀmförelser för `` utf8mb4_general_ci`` kollation snabbare, men nÄgot mindre korrekta Àn jÀmförelser för `` utf8mb4_unicode_ci``. Om detta Àr acceptabelt för ditt program bör du anvÀnda utf8mb4_general_ci eftersom det Àr snabbare. Om detta inte Àr acceptabelt (t.ex. om du behöver tysk ordboksordning), anvÀnd utf8mb4_unicode_ci eftersom det Àr mer exakt.
Varning
ModellformulÀren validerar unika fÀlt pÄ ett skiftlÀgeskÀnsligt sÀtt. Om man anvÀnder en kollationering som inte tar hÀnsyn till versaler kommer en formulÀruppsÀttning med unika fÀltvÀrden som endast skiljer sig Ät genom versaler att klara valideringen, men nÀr man anropar save() kommer ett IntegrityError att uppstÄ.
Anslutning till databasen¶
Se instÀllningsdokumentation.
AnslutningsinstÀllningarna anvÀnds i denna ordning:
Med andra ord, om du anger namnet pÄ databasen i OPTIONS, kommer detta att ha företrÀde framför NAME, som skulle ÄsidosÀtta allt i en MySQL-alternativfil.
HÀr Àr ett exempel pÄ en konfiguration som anvÀnder en MySQL-alternativfil:
# settings.py
DATABASES = {
"default": {
"ENGINE": "django.db.backends.mysql",
"OPTIONS": {
"read_default_file": "/path/to/my.cnf",
},
}
}
# my.cnf
[client]
database = NAME
user = USER
password = PASSWORD
default-character-set = utf8mb4
Flera andra MySQLdb-anslutningsalternativ kan vara anvÀndbara, till exempel ssl, init_command och sql_mode.
StÀlla in sql_mode¶
StandardvÀrdet för alternativet sql_mode innehÄller STRICT_TRANS_TABLES. Det alternativet eskalerar varningar till fel nÀr data trunkeras vid infogning, sÄ Django rekommenderar starkt att du aktiverar ett strikt lÀge för MySQL för att förhindra dataförlust (antingen STRICT_TRANS_TABLES eller STRICT_ALL_TABLES).
Om du behöver anpassa SQL-lÀget kan du stÀlla in variabeln sql_mode som andra MySQL-alternativ: antingen i en konfigurationsfil eller med posten 'init_command': "SET sql_mode='STRICT_TRANS_TABLES'" i OPTIONS-delen av din databaskonfiguration i DATABASER.
IsolationsnivĶ
NÀr samtidiga belastningar körs kan databastransaktioner frÄn olika sessioner (t.ex. separata trÄdar som hanterar olika förfrÄgningar) interagera med varandra. Dessa interaktioner pÄverkas av varje sessions transaktionsisoleringsnivÄ. Du kan ange en anslutnings isoleringsnivÄ med en 'isolation_level'-post i OPTIONS-delen av din databaskonfiguration i DATABASER. Giltiga vÀrden för den hÀr posten Àr de fyra standardisoleringsnivÄerna:
'lĂ€sa utan Ă„tagande''read committed'âupprepningsbar lĂ€sning
'serializable'
eller None för att anvÀnda serverns konfigurerade isoleringsnivÄ. Django fungerar dock bÀst med och anvÀnder som standard read committed i stÀllet för MySQL:s standard, repeatable read. Dataförlust Àr möjlig med repeterbar lÀsning. I synnerhet kan du se fall dÀr get_or_create() kommer att ge upphov till ett IntegrityError men objektet kommer inte att visas i ett efterföljande get()-anrop.
Skapa dina tabeller¶
NÀr Django genererar schemat anges ingen lagringsmotor, sÄ tabeller kommer att skapas med den standardlagringsmotor som din databasserver Àr konfigurerad för. Den enklaste lösningen Àr att stÀlla in din databasservers standardlagringsmotor till den önskade motorn.
Om du anvÀnder en vÀrdtjÀnst och inte kan Àndra serverns standardlagringsmotor har du ett par alternativ.
NÀr tabellerna har skapats kan du köra en
ALTER TABLE-sats för att konvertera en tabell till en ny lagringsmotor (t.ex. InnoDB):ALTER TABLE <tablename> ENGINE=INNODB;
Detta kan vara trÄkigt om du har mÄnga tabeller.
Ett annat alternativ Àr att anvÀnda alternativet
init_commandför MySQLdb innan du skapar dina tabeller:"OPTIONS": { "init_command": "SET default_storage_engine=INNODB", }
Detta anger standardlagringsmotorn vid anslutning till databasen. NÀr tabellerna har skapats bör du ta bort det hÀr alternativet eftersom det lÀgger till en frÄga som bara behövs nÀr tabellerna skapas i varje databasanslutning.
Tabellnamn¶
Det finns kÀnda problem Àven i de senaste versionerna av MySQL som kan leda till att versalerna i ett tabellnamn Àndras nÀr vissa SQL-satser körs under vissa förhÄllanden. Det rekommenderas att du anvÀnder smÄ bokstÀver i tabellnamn, om möjligt, för att undvika problem som kan uppstÄ pÄ grund av detta beteende. Django anvÀnder smÄ bokstÀver i tabellnamn nÀr det automatiskt genererar tabellnamn frÄn modeller, sÄ detta Àr frÀmst ett övervÀgande om du ÄsidosÀtter tabellnamnet via db_table-parametern.
Spara poÀng¶
BÄde Django ORM och MySQL (nÀr de anvÀnder InnoDB storage engine) stöder databas savepoints.
Om du anvÀnder MyISAM-lagringsmotorn bör du vara medveten om att du kommer att fÄ databasgenererade fel om du försöker anvÀnda savepoint-relaterade metoder i transaktions-API:n. Anledningen till detta Àr att det Àr en dyr operation att upptÀcka lagringsmotorn för en MySQL-databas/tabell, sÄ det beslutades att det inte Àr vÀrt att dynamiskt konvertera dessa metoder till no-op baserat pÄ resultaten av sÄdan upptÀckt.
Anteckningar om specifika omrÄden¶
TeckenfÀlt¶
Alla fÀlt som lagras med kolumntyperna VARCHAR kan ha sin max_length begrÀnsad till 255 tecken om du anvÀnder unique=True för fÀltet. Detta pÄverkar CharField, SlugField. Se MySQL-dokumentationen för mer information.
begrÀnsningar för TextField¶
MySQL kan endast indexera de första N tecknen i en BLOB eller TEXT-kolumn. Eftersom TextField inte har en definierad lĂ€ngd kan du inte markera den som unique=True. MySQL kommer att rapportera: âBLOB/TEXT-kolumn â<db_column>â anvĂ€nds i nyckelspecifikation utan en nyckellĂ€ngdâ.
Stöd för brÄkdelar av sekunder för Time- och DateTime-fÀlt¶
MySQL kan lagra brÄkdelar av sekunder, förutsatt att kolumndefinitionen innehÄller en brÄkdelsindikation (t.ex. DATETIME(6)).
Django kommer inte att uppgradera befintliga kolumner för att inkludera brÄkdelar av sekunder om databasservern stöder det. Om du vill aktivera dem i en befintlig databas Àr det upp till dig att antingen manuellt uppdatera kolumnen i mÄldatabasen genom att köra ett kommando som:
ALTER TABLE `your_table` MODIFY `your_datetime_column` DATETIME(6)
eller anvÀnda en RunSQL operation i en datamigrering.
TIMESTAMP kolumner¶
Om du anvÀnder en Àldre databas som innehÄller TIMESTAMP-kolumner mÄste du stÀlla in USE_TZ = False för att undvika datakorruption. inspectdb mappar dessa kolumner till DateTimeField och om du aktiverar tidszonsstöd kommer bÄde MySQL och Django att försöka konvertera vÀrdena frÄn UTC till lokal tid.
RadlÄsning med QuerySet.select_for_update()¶
MySQL och MariaDB stöder inte vissa alternativ till SELECT ... FOR UPDATE-satsen. Om select_for_update() anvÀnds med ett alternativ som inte stöds, kommer ett NotSupportedError att uppstÄ.
Alternativ |
MariaDB |
MySQL |
|---|---|---|
|
X (â„10.6) |
X |
|
X |
X |
|
X |
|
|
NÀr du anvÀnder select_for_update() pÄ MySQL, se till att du filtrerar en frÄgeuppsÀttning mot Ätminstone en uppsÀttning fÀlt som ingÄr i unika begrÀnsningar eller endast mot fÀlt som tÀcks av index. Annars kommer ett exklusivt skrivlÄs att förvÀrvas över hela tabellen under hela transaktionens varaktighet.
Automatisk typcasting kan leda till ovÀntade resultat¶
NÀr du utför en frÄga pÄ en strÀngtyp, men med ett heltalsvÀrde, kommer MySQL att tvinga typerna för alla vÀrden i tabellen till ett heltal innan jÀmförelsen utförs. Om din tabell innehÄller vÀrdena 'abc', 'def' och du frÄgar efter WHERE mycolumn=0, kommer bÄda raderna att matcha. PÄ samma sÀtt kommer WHERE mycolumn=1 att matcha vÀrdet 'abc1'. DÀrför kommer fÀlt av strÀngtyp som ingÄr i Django alltid att kasta vÀrdet till en strÀng innan det anvÀnds i en frÄga.
Om du implementerar anpassade modellfÀlt som Àrver frÄn Field direkt, ÄsidosÀtter get_prep_value() eller anvÀnder RawSQL, extra(), eller raw(), bör du se till att du utför lÀmplig typecasting.
Anteckningar om SQLite¶
Django stöder SQLite 3.31.0 och senare.
SQLite Àr ett utmÀrkt utvecklingsalternativ för applikationer som huvudsakligen Àr skrivskyddade eller som krÀver en mindre installation. Som med alla databasservrar finns det dock vissa skillnader som Àr specifika för SQLite som du bör vara medveten om.
Matchning av substrÀngar och skiftlÀgeskÀnslighet¶
För alla SQLite-versioner finns det ett nÄgot kontraintuitivt beteende nÀr man försöker matcha vissa typer av strÀngar. Dessa utlöses nÀr man anvÀnder filtren iexact eller contains i frÄgeuppsÀttningar. Beteendet delas upp i tvÄ fall:
1. For substring matching, all matches are done case-insensitively. That is a
filter such as filter(name__contains="aa") will match a name of "Aabb".
2. For strings containing characters outside the ASCII range, all exact string
matches are performed case-sensitively, even when the case-insensitive options
are passed into the query. So the iexact filter will behave exactly
the same as the exact filter in these cases.
NÄgra möjliga lösningar för detta finns dokumenterade pÄ sqlite.org, men de anvÀnds inte av standard SQLite-backend i Django, eftersom det skulle vara ganska svÄrt att göra dem robusta. SÄledes exponerar Django standard SQLite-beteendet och du bör vara medveten om detta nÀr du gör skiftlÀgeskÀnslig eller delstrÀngsfiltrering.
Decimalhantering¶
SQLite har ingen riktig decimal intern typ. DecimalvÀrden konverteras internt till datatypen REAL (8-byte IEEE flyttalsnummer), vilket förklaras i SQLite datatypes documentation, sÄ de stöder inte korrekt avrundad decimal flyttalsaritmetik.
felmeddelandet âDatabasen Ă€r lĂ„stâ¶
SQLite Àr tÀnkt att vara en lÀttviktig databas och kan dÀrför inte stödja en hög nivÄ av samtidighet. OperationalError: database is locked-fel indikerar att din applikation upplever mer samtidighet Àn vad sqlite kan hantera i standardkonfigurationen. Det hÀr felet innebÀr att en trÄd eller process har ett exklusivt lÄs pÄ databasanslutningen och att en annan trÄd tidsavbröts i vÀntan pÄ att lÄset skulle frigöras.
Pythons SQLite-wrapper har ett standardvÀrde för timeout som avgör hur lÀnge den andra trÄden fÄr vÀnta pÄ lÄset innan det tar slut och felet OperationalError: database is locked uppstÄr.
Om du fÄr det hÀr felet kan du lösa det genom att:
Byta till en annan databasbackend. Vid en viss punkt blir SQLite för âliteâ för verkliga applikationer, och den hĂ€r typen av samtidighetsfel indikerar att du har nĂ„tt den punkten.
Skriva om din kod för att minska samtidighet och sÀkerstÀlla att databastransaktioner Àr kortlivade.
Ăka standardvĂ€rdet för timeout genom att stĂ€lla in databasalternativet
timeout:"OPTIONS": { # ... "timeout": 20, # ... }
Detta gör att SQLite vĂ€ntar lite lĂ€ngre innan den ger felmeddelandet âdatabasen Ă€r lĂ„stâ, men det gör egentligen ingenting för att lösa dem.
Transaktionsbeteende¶
SQLite stöder tre transaktionslÀgen: DEFERRED, IMMEDIATE och EXCLUSIVE.
StandardvÀrdet Àr DEFERRED. Om du behöver anvÀnda ett annat lÀge anger du det i OPTIONS-delen av din databaskonfiguration i DATABASER, till exempel:
"OPTIONS": {
# ...
"transaction_mode": "IMMEDIATE",
# ...
}
Om du vill vara sĂ€ker pĂ„ att dina transaktioner vĂ€ntar till timeout innan du meddelar âDatabasen Ă€r lĂ„stâ, Ă€ndrar du transaktionslĂ€get till IMMEDIATE.
För bÀsta prestanda med IMMEDIATE och EXCLUSIVE bör transaktionerna vara sÄ korta som möjligt. Detta kan vara svÄrt att garantera för alla dina vyer, sÄ anvÀndningen av ATOMIC_REQUESTS avrÄds i detta fall.
För mer information se Transaktioner i SQLite.
QuerySet.select_for_update() stöds inte¶
SQLite har inte stöd för syntaxen SELECT ... FOR UPDATE. Att anropa den kommer inte att ha nÄgon effekt.
Isolering vid anvÀndning av QuerySet.iterator()¶
Det finns sÀrskilda övervÀganden som beskrivs i Isolation In SQLite nÀr man Àndrar en tabell medan man itererar över den med QuerySet.iterator(). Om en rad lÀggs till, Àndras eller tas bort inom loopen kan den raden visas eller inte visas, eller visas tvÄ gÄnger, i efterföljande resultat som hÀmtas frÄn iteratorn. Din kod mÄste hantera detta.
Aktivera JSON1-tillÀgget pÄ SQLite¶
För att anvÀnda JSONField pÄ SQLite mÄste du aktivera JSON1-tillÀgget pÄ Pythons sqlite3-bibliotek. Om tillÀgget inte Àr aktiverat i din installation kommer ett systemfel (fields.E180) att uppstÄ.
För att aktivera JSON1-tillÀgget kan du följa instruktionerna pÄ wikisidan.
Observera
JSON1-tillÀgget Àr aktiverat som standard i SQLite 3.38+.
StÀlla in pragma-alternativ¶
Pragma options kan stÀllas in vid anslutning med hjÀlp av init_command i OPTIONS-delen av din databaskonfiguration i DATABASES. I exemplet nedan visas hur man aktiverar extra hÄllbarhet för synkrona skrivningar och Àndrar cache_size:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.sqlite3",
# ...
"OPTIONS": {
"init_command": "PRAGMA synchronous=3; PRAGMA cache_size=2000;",
},
}
}
Oracle anteckningar¶
Django stöder Oracle Database Server version 19c och senare. Version 2.3.0 eller högre av Python-drivrutinen oracledb krÀvs.
Deprecated since version 5.0: Stöd för cx_Oracle Àr borttaget.
För att kommandot python manage.py migrate ska fungera mÄste din Oracle-databasanvÀndare ha behörighet att köra följande kommandon:
SKAPA TABELL
SKAPA SEKVENS
SKAPA PROCEDUR
SKAPA TRIGGER
För att köra ett projekts testsvit behöver anvÀndaren vanligtvis dessa ytterligare behörigheter:
SKAPA ANVĂNDARE
ĂNDRAR ANVĂNDARE
DROP ANVĂNDARE
SKAPA TABLESPACE
SLĂPP TABLESPACE
SKAPA SESSION MED ADMINISTRATĂRSALTERNATIV
SKAPA TABELL MED ADMINISTRATĂRSALTERNATIV
SKAPA SEKVENS MED ADMINISTRATĂRSALTERNATIV
SKAPA PROCEDUR MED ADMINISTRATĂRSALTERNATIV
SKAPA TRIGGER MED ADMINISTRATĂRSALTERNATIV
Ăven om rollen RESOURCE har de nödvĂ€ndiga behörigheterna CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE och CREATE TRIGGER och en anvĂ€ndare som tilldelats RESOURCE WITH ADMIN OPTION kan tilldela RESOURCE, kan en sĂ„dan anvĂ€ndare inte tilldela de enskilda behörigheterna (t.ex.t.ex. CREATE TABLE), och dĂ€rför Ă€r RESOURCE WITH ADMIN OPTION vanligtvis inte tillrĂ€ckligt för att köra tester.
Vissa testsviter skapar ocksÄ vyer eller materialiserade vyer; för att köra dessa behöver anvÀndaren ocksÄ behörigheterna CREATE VIEW WITH ADMIN OPTION och CREATE MATERIALIZED VIEW WITH ADMIN OPTION. I synnerhet behövs detta för Djangos egen testsvit.
Alla dessa behörigheter ingÄr i DBA-rollen, som Àr lÀmplig att anvÀnda i en privat utvecklares databas.
Oracle-databasens backend anvÀnder paketen SYS.DBMS_LOB och SYS.DBMS_RANDOM, sÄ din anvÀndare kommer att behöva exekveringsbehörighet för det. Det Àr normalt tillgÀngligt för alla anvÀndare som standard, men om det inte Àr det mÄste du ge behörigheter pÄ följande sÀtt:
GRANT EXECUTE ON SYS.DBMS_LOB TO user;
GRANT EXECUTE ON SYS.DBMS_RANDOM TO user;
Anslutning till databasen¶
Om du vill ansluta med hjÀlp av servicenamnet för din Oracle-databas ska filen settings.py se ut ungefÀr sÄ hÀr:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.oracle",
"NAME": "xe",
"USER": "a_user",
"PASSWORD": "a_password",
"HOST": "",
"PORT": "",
}
}
I det hĂ€r fallet bör du lĂ€mna bĂ„de HOST och PORT tomma. Om du dĂ€remot inte anvĂ€nder filen tnsnames.ora eller nĂ„gon liknande namngivningsmetod och vill ansluta med hjĂ€lp av SID (âxeâ i det hĂ€r exemplet), fyller du i bĂ„de HOST och PORT pĂ„ följande sĂ€tt:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.oracle",
"NAME": "xe",
"USER": "a_user",
"PASSWORD": "a_password",
"HOST": "dbprod01ned.mycompany.com",
"PORT": "1540",
}
}
Du bör antingen ange bÄde HOST och PORT, eller lÀmna bÄda som tomma strÀngar. Django kommer att anvÀnda en annan connect descriptor beroende pÄ detta val.
FullstÀndig DSN och Easy Connect¶
En fullstÀndig DSN- eller Easy Connect-strÀng kan anvÀndas i NAME om bÄde HOST och PORT Àr tomma. Det hÀr formatet krÀvs nÀr du anvÀnder RAC eller pluggbara databaser utan tnsnames.ora, till exempel.
Exempel pÄ en Easy Connect-strÀng:
"NAME": "localhost:1521/orclpdb1"
Exempel pÄ en fullstÀndig DSN-strÀng:
"NAME": (
"(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))"
"(CONNECT_DATA=(SERVICE_NAME=orclpdb1)))"
)
Anslutningspool¶
För att anvÀnda en anslutningspool med oracledb, sÀtt "pool" till True i OPTIONS-delen av din databaskonfiguration. Detta anvÀnder drivrutinens create_pool() standardvÀrden:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.oracle",
# ...
"OPTIONS": {
"pool": True,
},
},
}
För att skicka anpassade parametrar till drivrutinens funktion create_pool() kan du alternativt ange att "pool" ska vara en dict:
DATABASES = {
"default": {
"ENGINE": "django.db.backends.oracle",
# ...
"OPTIONS": {
"pool": {
"min": 1,
"max": 10,
# ...
}
},
},
}
GÀngat alternativ¶
Om du planerar att köra Django i en flertrÄdad miljö (t.ex. Apache med standardmodulen MPM pÄ alla moderna operativsystem), mÄste du ** stÀlla in alternativet threaded i din Oracle-databas konfiguration till True:
"OPTIONS": {
"threaded": True,
}
Om du inte gör detta kan det leda till krascher och andra konstiga beteenden.
INFOGA ⊠à TERVĂNDANDE TILL¶
Som standard anvĂ€nder Oracle backend en âRETURNING INTOâ-klausul för att effektivt hĂ€mta vĂ€rdet pĂ„ en âAutoFieldâ nĂ€r nya rader infogas. Detta beteende kan resultera i ett DatabaseError i vissa ovanliga konfigurationer, t.ex. nĂ€r du infogar i en fjĂ€rrtabell eller i en vy med en INSTEAD OF-trigger. Klausulen RETURNING INTO kan inaktiveras genom att alternativet use_returning_into i databaskonfigurationen sĂ€tts till False:
"OPTIONS": {
"use_returning_into": False,
}
I det hÀr fallet kommer Oracle-backend att anvÀnda en separat SELECT-frÄga för att hÀmta AutoField-vÀrden.
Problem med namngivning¶
Oracle har en begrÀnsning pÄ 30 tecken för namnlÀngden. För att tillgodose detta trunkerar backend databasidentifierare sÄ att de passar och ersÀtter de sista fyra tecknen i det trunkerade namnet med ett upprepningsbart MD5-hashvÀrde. Dessutom Àndrar backend databasidentifierare till enbart versaler.
För att förhindra dessa omvandlingar (detta krÀvs vanligtvis endast nÀr man arbetar med Àldre databaser eller har Ätkomst till tabeller som tillhör andra anvÀndare), anvÀnd ett citerat namn som vÀrde för db_table:
class LegacyModel(models.Model):
class Meta:
db_table = '"name_left_in_lowercase"'
class ForeignModel(models.Model):
class Meta:
db_table = '"OTHER_USER"."NAME_ONLY_SEEMS_OVER_30"'
Citerade namn kan ocksÄ anvÀndas med Djangos andra stödda databasbackends; med undantag för Oracle har citaten dock ingen effekt.
NÀr man kör migrate kan felet ORA-06552 uppstÄ om vissa Oracle-nyckelord anvÀnds som namn pÄ ett modellfÀlt eller som vÀrde pÄ ett db_column-alternativ. Django citerar alla identifierare som anvÀnds i frÄgor för att förhindra de flesta sÄdana problem, men det hÀr felet kan fortfarande uppstÄ nÀr en Oracle-datatyp anvÀnds som ett kolumnnamn. Var sÀrskilt noga med att undvika att anvÀnda namnen date, timestamp, number eller float som fÀltnamn.
NULL och tomma strÀngar¶
Django föredrar i allmÀnhet att anvÀnda den tomma strÀngen ('') i stÀllet för NULL, men Oracle behandlar bÄda identiskt. För att komma runt detta ignorerar Oracle-backend ett explicit null-alternativ pÄ fÀlt som har den tomma strÀngen som ett möjligt vÀrde och genererar DDL som om null=True. Vid hÀmtning frÄn databasen antas det att ett NULL-vÀrde i ett av dessa fÀlt verkligen betyder den tomma strÀngen, och data konverteras tyst för att Äterspegla detta antagande.
begrÀnsningar för TextField¶
Oracles backend lagrar varje TextField som en NCLOB-kolumn. Oracle inför vissa begrÀnsningar för anvÀndningen av sÄdana LOB-kolumner i allmÀnhet:
LOB-kolumner fÄr inte anvÀndas som primÀrnycklar.
LOB-kolumner fÄr inte anvÀndas i index.
LOB-kolumner fÄr inte anvÀndas i en
SELECT DISTINCT-lista. Detta innebÀr att försök att anvÀnda metodenQuerySet.distinctpÄ en modell som innehÄllerTextField-kolumner kommer att resultera i ettORA-00932-fel nÀr den körs mot Oracle. Som en lösning kan du anvÀnda metodenQuerySet.defertillsammans meddistinct()för att förhindra attTextField-kolumner inkluderas i listanSELECT DISTINCT.
Underklassning av de inbyggda databasbackends¶
Django levereras med inbyggda databasbackends. Du kan underklassa en befintlig databasbackend för att Àndra dess beteende, funktioner eller konfiguration.
TÀnk dig till exempel att du behöver Àndra en enda databasfunktion. Först mÄste du skapa en ny katalog med en base-modul i den. Ett exempel:
mysite/
...
mydbengine/
__init__.py
base.py
Modulen base.py mÄste innehÄlla en klass med namnet DatabaseWrapper som underklassar en befintlig motor frÄn modulen django.db.backends. HÀr Àr ett exempel pÄ underklassning av PostgreSQL-motorn för att Àndra en funktionsklass allows_group_by_selected_pks_on_model:
mysite/mydbengine/base.py¶from django.db.backends.postgresql import base, features
class DatabaseFeatures(features.DatabaseFeatures):
def allows_group_by_selected_pks_on_model(self, model):
return True
class DatabaseWrapper(base.DatabaseWrapper):
features_class = DatabaseFeatures
Slutligen mÄste du ange en DATABASE-ENGINE i din settings.py-fil:
DATABASES = {
"default": {
"ENGINE": "mydbengine",
# ...
},
}
Du kan se den aktuella listan över databasmotorer genom att titta i django/db/backends.
AnvÀnda en databasbackend frÄn tredje part¶
Förutom de databaser som stöds officiellt finns det backends som tillhandahÄlls av tredje part som gör att du kan anvÀnda andra databaser med Django:
De Django-versioner och ORM-funktioner som stöds av dessa inofficiella backends varierar avsevÀrt. FrÄgor om de specifika funktionerna i dessa inofficiella backends, tillsammans med eventuella supportfrÄgor, bör riktas till de supportkanaler som tillhandahÄlls av varje tredjepartsprojekt.