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.

Referência da API de Banco de Dados

tradução para o português.

Documento original: Django Database API

Tradução: mario <mario.caseiro at gmail.com>

Referente a revisão: 3896

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
    • Criando objetos
  • Auto incrementando chaves primárias
  • Especificando explicitamente valores auto-primary-key
    • Salvando alterações nos Objetos

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

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 .

Durante toda esta referência, iremos fazer referências aos modelos descritos abaixo, que compreenderiam uma aplicação de weblog.

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 .

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 .)

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 salver alterações em um objeto que já exista no banco de dados, use save().

Dado a instância b5 do Blog, que já fora salvo no banco de dados, este exemplo altera seu nome e atualiza seu 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.