Apesar de não ser uma tarefa tão comum para muitos projetos em Drupal, algumas customizações podem precisar de soluções nas quais seja necessário o uso de novas tabelas para registrarmos dados que não se enquadram como nodes, taxonomias, usuários e etc. O uso de tabelas próprias não se restringe a módulos personalizados, criados especificamente para um determinado projeto. É muito comum encontrarmos casos como estes em módulos contribuídos no drupal.org.

Para facilitar estas tarefas de manipulação de dados, o Drupal nos provê algumas funções muito úteis, como a função drupal_write_record(), por exemplo.

Um caso muito comum de uso de tabelas próprias é quando utilizamos de entidades personalizadas, que possuem suas próprias tabelas para armazenar o valor de suas propriedades. Neste caso, entretanto, temos maneiras mais fáceis de manipular a estrutura de dados, como a API de Entidades, o módulo Entity API, ou o ECK (Entity Construction Kit). O ECK vai mais longe e toma conta da criação do schema das entidades criadas pela sua API. No caso de entidades personalizadas, o uso da função drupal_write_record() não se faz necessário. Não vou me aprofundar nisso agora, mas vamos tratar deste tema em artigos futuros.

Sendo assim, partindo do ponto de que vamos precisar de uma tabela própria para guardar informações específicas, que não seriam tratadas como entidades, fields ou variáveis. O mais indicado para trabalhar diretamente com o banco de dados é sempre fazer uso da API de Abstração de Banco de Dados do Drupal para manipular os registros de maneira prática e segura.

Dessa maneira, evitamos o uso de SQL, o que torna a manipulação dos dados mais elegante, além de fazer a aplicação mais agnóstica com relação ao armazenamento destes dados. Assim, não precisamos nos preocupar com qual base de dados será utilizada, ou seja, para a nossa aplicação não fará diferença se será utilizado MySQL, PostgreSQL, MongoDB etc.

Como usar o drupal_write_record()?

Segundo a documentação, você deverá usar essa função de acordo com o descrito abaixo:

drupal_write_record($table, &$record, $primary_keys = array());

• $table: é o nome da tabela onde os dados serão inseridos ou atualizados;
• $record: é um objeto ou array que representa os dados que serão inseridos ou atualizados;
• $primary_keys: é usado para indicar que os dados inseridos são uma atualização. Este argumento especifica os nomes de campos de chaves primárias.

Para fins de esclarecimento, partiremos do seguinte problema proposto: precisamos elaborar um módulo de notificações que exibe aleatoriamente uma mensagem de boas vindas para todos os usuários que acessam o sistema. O módulo deverá armazenar todas as mensagens disponíveis e possibilitar a edição de uma mensagem já cadastrada, assim como a manipulação do status das mensagens (zero ou um) para controlar quais mensagens podem ser exibidas.

Neste caso, precisamos de um insert para adicionar uma nova mensagem na lista, e um update para atualização do corpo ou do status das mensagens já cadastradas.

Podemos alcançar este resultado da seguinte forma:

Como inserir um registro no banco de dados?

$table = 'welcome_messages';

$data = array(
'status' => 1,
'message' => 'Bem vindo, camarada!',
);

drupal_write_record($table, $data);

Como atualizar um registro no banco de dados?

$table = 'welcome_messages';
 
$data = array(
'id' => 2;
'status' => 1,
'message' => 'É ótimo vê-la novamente!',
);
 
drupal_write_record($table, $data, 'id');

Para ver na prática o uso do drupal_write_record() você pode acessar o artigo Como criar um módulo (parte 3) – Drupal 7.

Importante!

De acordo com a API, a função drupal_write_record() não deve ser utilizada dentro de funções de update, ou seja, implementações do hook_update_N() – uma vez que o esquema de banco de dados não pode ser invocado quando um usuário está executando atualizações em série*. Nestes casos, usedb_insert() ou db_update() para salvar o registro. Iremos ver estas funções em detalhe nos próximos artigos.

*Atualizações em série são as atualizações de banco de dados que são executadas no momento em que é executato o arquivo update.php ou o comando drush updb.

Para mais detalhes veja a documentação.