{{{ #!rst THIS TRANSLATION IS IN PROGRESS: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------------------------------------------------------------------+ | This is an **in progress** translation document, that means there is somebody working on it. | | For more information on translating documents please look at `TranslateDocumentation Wiki`_. | | Please **do not** edit this page. | | | | .. _TranslateDocumentation Wiki : http://code.djangoproject.com/wiki/TranslateDocumentation | +-------------------------------------------------------------------------------------------------+ .. ====================== Database API reference ====================== .. sidebar:: Referência da API de Banco de Dados :subtitle: tradução para o português. Documento original: `Django Database API`_ Tradução: mario `` Referente a revisão: 3896 .. _Django Database API: http://www.djangoproject.com/documentation/db_api/ .. contents:: **Conteúdos do capítulo** =================================== Referência da API de Banco de Dados =================================== Este documento cobre a versão 0.95 de Django e a versão do desenvolvimento. Docs anteriores: `0.90`_, `0.91`_ ---------------------------------------------------------------------------------------------------------------- .. _0.90: http://www.djangoproject.com/documentation/0_90/ .. _0.91: http://www.djangoproject.com/documentation/0_91/ Uma vez que você criou seus `data models`_, Django fornece automaticamente uma API de abstração de banco de dados para você criar, recuperar, atualizar e deletar objetos. Este documento descreve esta API . .. _`data models`: http://www.djangoproject.com/documentation/model_api/ Durante toda esta referência, iremos fazer referências aos modelos descritos abaixo, que compreenderiam uma aplicação de weblog. .. code-block:: python class Blog(models.Model): name = models.CharField(maxlength=100) tagline = models.TextField() def __str__(self): return self.name class Author(models.Model): name = models.CharField(maxlength=50) email = models.URLField() def __str__(self): return self.name class Entry(models.Model): blog = models.ForeignKey(Blog) headline = models.CharField(maxlength=255) body_text = models.TextField() pub_date = models.DateTimeField() authors = models.ManyToManyField(Author) [imperfeita] def __str__(self): return self.name Criando objetos ================ Para representar tabelas do banco de dados em objetos do Python, Django usa um sistema intuitivo: Uma classe modelo representa uma tabela da banco de dados, e uma instância dessa classe representa um registro particular na tabela do banco de dados Para criar um objeto, instancie-o usando argumentos da classe modelo, então chame ``save()`` para salva-lo no banco de dados. Você importa a classe modelo de onde quer que ela esteja dentro do Python path, como é de se esperar. (Nós destacamos isto aqui porque em versões anteriores do Django tinhamos importações de classes modelo conturbadas.) Assumindo que os modelos estejam em um arquivo ``mysite/blog/models.py``, segue o exemplo:: from mysite.blog.models import Blog b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.') b.save() Isto executa uma declaração SQL ``INSERT`` por baixo do panos. Django não conecta ao banco de dados até que você se chame explicitamente ``save()``. O método ``save()`` não retorna valor algum. Para criar um objeto e salvá-lo, tudo em um único passo veja o método `create`_ . .. _`create`: http://www.djangoproject.com/documentation/db_api/#create-kwargs Auto incrementando chaves primárias ----------------------------------- Se um modelo tiver um ``AutoField`` -- uma chave primária auto-increment -- então o valor auto incrementado será calculado e salvo como um atributo em seu objeto na primeira vez em que você chamar ``save()``. Exemplo:: b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.') b2.id # Returns None, because b doesn't have an ID yet. b2.save() b2.id # Returns the ID of your new object. Não há maneira alguma de dizer qual será o valor de seu ID antes de chamar ``save()``, pois o valor é obtido pelo do banco de dados, e não pelo Django. (Para conveniência, por padrão cada modelo tem um ``AutoField`` nomeado ``id`` , a menos que você especifique explicitamente ``primary_key=True`` em um campo. Veja a documentação `AutoField`_ .) .. _`AutoField` : http://www.djangoproject.com/documentation/model_api/#autofield Especificando explicitamente valores auto-primary-key ------------------------------------------------------ Caso tenha um modelo com um campo ``AutoField`` mas você queira definir o ID de um objeto explicitamente quando o salvar, é só defini-lo explicitamente antes de salvá-lo, ao invés de deixar a auto atribuição do ID. Exemplo:: b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.') b3.id # Returns 3. b3.save() b3.id # Returns 3. Se você atribuir valores de chave-primária (auto-primary-keys) manualmente, certifique-se de não usar um valor já existente de chave primária! Se você criar um novo objeto com um valor explícito da chave-primária que já exista no banco de dados, Django irá supor que você está mudando o registro existente ao invés de criar um novo. Dado o exemplo acima do blog ``'Cheddar Talk'`` , este exemplo substituiria o registro antigo do banco de dados:: b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.') b4.save() # Overrides the previous blog with ID=3! Veja _`Como Django decide entre UPDATE vs. INSERT` , logo abaixo abaixo, para saber porque que isto acontece. Especificar valores de chaves-primárias (auto-primary-keys) explicitamente é na maior parte útil para salvar grandes quantidades de objetos, uma vez que você está seguro que não terá conflitos de chaves-primárias Salvando alterações nos Objetos =================================== Para salvar alterações em um objeto que já exista no banco de dados, use ``save()``. Dado a instância ``b5`` do ``Blog``, que já tenha sido salva no banco de dados, demonstramos no exemplo abaixo, como alterar seu nome e atualizar tal registro no banco de dados:: b5.name = 'New name' b5.save() Isto executa uma declaração SQL ``INSERT`` por detrás das cenas. Django não conecta ao banco de dados até que você chame explicitamente ``save()``. O método ``save()`` não retorna valor algum. Como Django decide entre UPDATE vs. INSERT ---------------------------------------------------- Você deve ter notado que os objetos de banco de dados do Django utiliza o mesmo método ``save()`` para criar e alterar objetos. Django abstrai a necessidade de utilizar declarações SQL de ``INSERT`` ou ``UPDATE``. Especificamente, quando você chama ``save()``, Django segue este algorítimo: * Caso o atributo chave-primária (primary-key) do objeto receba um valor que não resulte em ``False`` (assim como ``None`` ou strings vazias), Django executa uma query ``SELECT`` para determinar se já existe um registro com a chave-primária fornecida. * Caso já exista um registro com a chave-primária forncida, Django executa uma query de ``UPDATE``. * Se o atributo do chave-primária (primary-key) do objeto *não* recebeu valor algum, ou recebeu um valor que não tenha registro, Django executa um ``INSERT``. A grande sacada aqui é que você deve ter cuidado para não especificar explicitamente um valor de chave-primária (primary-key) ao salvar novos objetos quando você não puder garantir que o valor da chave-primária (primary-key) não esteja sendo utilizado. Para mais sobre estes aspectos, ver "Especificando explicitamente valores auto-primary-key" , acima. }}}