Executa instruções no formato de comandos na linguagem SQL. Este bloco utiliza recursos do Apache Cordova, para mais informações de configuração e funcionamento deste recurso, verifique a documentação oficial do Cordova.

Figura 1 - Bloco Executar Comando SQL

Compatibilidade

• Bloco cliente (mobile): cronapi.cordova.database.executeSql()

Retorno

O retorno do bloco irá depender do comando SQL executado. Em geral, apenas os comandos de consulta ao banco de dados, como o SELECT, retornam um objeto contendo os dados da consulta realizada.

Parâmetros

Nome do Banco

Nome do banco de dados no qual serão executados os comandos SQL. O nome informado nesse parâmetro deve corresponder ao mesmo nome utilizado no bloco Criar banco de dados, durante a criação do banco de dados.

• Posição: 1
• Inglês: Database Name
• Tipo: Texto / String
• Exemplo: "contatos"

SQL

Comando SQL a ser executado no banco de dados informado anteriormente.

• Posição: 2
• Inglês: SQL
• Tipo: Texto / String
• Exemplo: "CREATE TABLE PESSOA (idPessoa integer PRIMARY KEY, nome);"

Lista de parâmetros

Lista de parâmetros a ser adicionada ao comando. Neste parâmetro, para criar a lista, pode ser utilizado o bloco criar lista com.

• Posição: 3
• Inglês: List of parameters
• Tipo: Objeto / Object
• Exemplo: Uso do bloco criar lista com.

Características do bloco

O bloco Executar Comandos SQL utiliza os comandos da linguagem SQL. Esses comandos são agrupados em 4 categorias, sendo DDL e DML as duas principais:

• Linguagem de Definição de Dados (DDL): Comandos desse tipo são utilizados pra criar, modificar e apagar a estrutura dos objetos de um banco de dados. Os comandos são: CREATE, ALTER, DROP, RENAME e TRUNCATE.

• Linguagem de Manipulação de Dados (DML): Comandos desse tipo são utilizados para armazenar, obter, modificar e apagar os dados. Os comandos são: INSERT, SELECT, UPDATE e DELETE.

Consultas dinâmicas

O bloco Executar Comandos SQL além de aceitar consultas estáticas, onde os parâmetros são passados na própria consulta, também aceita consultas dinâmicas. As consultas SQL dinâmicas são úteis quando os argumentos a serem utilizados na consulta são obtidos durante a execução do programa, sendo frequentemente recuperados através da interação do usuário com o sistema.

Nesse tipo de consulta, os parâmetros são passados de forma dinâmica, de acordo com o exemplo abaixo, onde o símbolo (?) significa o valor a ser obtido e agregado ao comando SQL a ser executado. Além disso, é necessário fornecer uma lista contendo esses valores, ordenados de acordo com os campos da consulta, no parâmetro Lista de parâmetros.

INSERT INTO nomeTabela VALUES (?,?,?);

Exemplo

Os tópicos a seguir apresentam exemplos de uso do bloco Executar Comando SQL, demostrando os principais comandos SQL utilizados. O banco de dados utilizado nos exemplos é o mesmo que foi criado na documentação do bloco Criar banco de dados, consulte-a para mais detalhes.

Criando tabelas

Na função da Figura 2, estamos criando duas tabelas, PESSOA e TELEFONE, no banco de dados "contatos" em um dispositivo móvel. Para esta ação, inserimos dois comandos CREATE, descritos no bloco de código abaixo, no parâmetro SQL do bloco. 

CREATE TABLE PESSOA (idPessoa integer PRIMARY KEY, nome);
CREATE TABLE TELEFONE (idTel integer PRIMARY KEY, num, idPessoa, CONSTRAINT fk_PesTel FOREIGN KEY (idPessoa) REFERENCES PESSOA (idPessoa));

Neste exemplo, a tabela PESSOA é composta por duas colunas, "idPessoa" (chave primária) e "nome", enquanto a tabela TELEFONE possui as colunas "idTel" (chave primária), "num" e "idPessoa". Observe também que essas tabelas mantêm um relacionamento de chave estrangeira, o que significa que cada registro na tabela TELEFONE deve estar associado a um registro na tabela PESSOA.

Figura 2 - Criando tabelas utilizando o comando 'create'

Inserindo registros

Na função da Figura 2.1, estamos inserindo registros nas tabelas criadas utilizando os comandos do tipo INSERT. No bloco Executar Comando SQL da variável "pessoa", estamos utilizando uma consulta dinâmica, descrita no bloco de código abaixo. Por isso, no parâmetro Lista de parâmetros adicionamos um bloco criar lista com e o valor "Ana".

INSERT INTO PESSOA (nome) VALUES (?);

Figura 2.1 - Inserindo registros nas tabelas utilizando o comando 'insert'

No bloco Executar Comando SQL da variável "telefone", utilizamos uma consulta estática para inserir dois registros na tabela TELEFONE. Os comandos passados estão no bloco de código abaixo.

INSERT INTO TELEFONE (idPessoa, num) VALUES (1,'(63) 99097-6578');
INSERT INTO TELEFONE (idPessoa, num) VALUES (1,'(51) 98764-3200');

Consultando registros

Na função da Figura 2.2, será realizada uma consulta na tabela TELEFONE utilizando o comando SELECT. Neste exemplo, iremos retornar os registros que possuem "idPessoa" igual a 1, para isso configuramos o bloco Executar Comando SQL na variável "objeto", e, no parâmetro SQL do bloco, inserimos o comando SQL descrito no código abaixo. 

SELECT * FROM TELEFONE WHERE idPessoa=1;

Após realizar os passos acima, precisamos configurar um laço de repetição para percorrer todos os itens retornados na variável "objeto". Para isso, utilizamos o bloco para cada item na lista e, nele, inserimos a variável "objeto". Em seguida, na variável "item", adicionamos o bloco Obter Propriedade, para obter a propriedade "num", que corresponde ao número de telefone de cada registro consultado.

É importante destacar, que na variável "objeto", além dos itens da consulta, também são retornadas as propriedades length e prototype. Por isso, utilizamos o bloco condicional se faça para encerrar o laço caso a variável "item" seja nula. Posteriormente, definimos a variável "item" para armazenar cada registro obtido. Por fim, no bloco Alterar valor do campo, inserimos no parâmetro Campo a variável "lista" contendo o resultado obtido, que será exibido em um componente área de texto, como mostra a Figura 2.3.

Figura 2.2 - Consultando registros utilizando o comando 'select'

A imagem abaixo mostra o resultado de execução da função da Figura 2.2, nela visualizamos os registros da consulta realizada.

Figura 2.3 - Resultado de execução da função da Figura 2.2

Atualizando um registro

Na função da Figura 2.4, iremos atualizar um registro na tabela PESSOA utilizando o comando UPDATE. Neste exemplo, no parâmetro SQL do bloco Executar Comando SQL, inserimos o comando descrito no bloco de código abaixo, o qual é responsável por atualizar o registro que possui "idPessoa" igual a 1." Observe que no tópico Criando tabelas, esse registro foi criado com o campo "nome" preenchido como "Ana", e agora vamos atualizá-lo para "Ana Paula". Para visualizar o registro atualizado, pode-se utilizar o comando de consulta SELECT, abordado no tópico Consultando registros.

UPDATE PESSOA SET nome=? WHERE idPessoa=1;

Figura 2.4 - Atualizando um registro utilizando o comando 'update'

Excluindo um registro

Na função da Figura 2.5, iremos excluir um registro da tabela TELEFONE utilizando o comando DELETE. Neste exemplo, excluir o registro que possui "idTel" igual a 1. Para visualizar se o registro foi de fato excluído, pode-se utilizar o comando SELECT, abordado no tópico Consultando registros.

DELETE FROM TELEFONE WHERE idTel=?

Figura 2.5 - Excluindo um registro utilizando o comando 'delete'