{{{
#!rst

..
  ======================
  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 `<mario.caseiro at gmail.com>`
  
  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 um modelo tenha um campo ``AutoField``, porém 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.




=======================
D E A R  F R I E N D S:
=======================
 I have already translate more on this document, but didn't have more time to do all rST formating.
 I hope to finish the tranlating this week, since that happens i'll update this page.



}}}