Construtor de Consultas ======================= O Construtor de Consultas do Yii fornece uam abordagem orientada a objeto para escrever comandos SQL. Ele permite que desenvolvedores usem métodos de e propriedades para especificar partes individuais de um comando SQL. Então ele monta estas partes para formar um comando SQL válido que pode ser executado ao chamar os métodos DAO como descrito em [Data Access Objects](/doc/guide/database.dao). A seguir é mostrado um uso típico do Construtor de Consultas para construir um comando SQL SELECT: ~~~ [php] $user = Yii::app()->db->createCommand() ->select('id, username, profile') ->from('tbl_user u') ->join('tbl_profile p', 'u.id=p.user_id') ->where('id=:id', array(':id'=>$id)) ->queryRow(); ~~~ O Construtor de Consultas é melhor usado quando você precisa montar um comando SQL de maneira procedural, ou baseado em alguma lógica condicional na sua aplicação. Os principais benefícios de usar o Construtor de Consultas incluem: * Ele permite a construção programática de comandos SQL complexos. * Ele automaticamente adiciona aspas aos nomes de tabelas e colunas para evitar conflitos com palavras reservadas do SQL e caracteres especiais. * Ele também adiciona aspas aos valores dos parâmetros e usa parâmetros vinculados quando possível, o que ajuda a reduzir os riscos de ataques de injeção de SQL. * Ele oferece um certon nível de abstração do banco de dados, o que simplifica a migração entre diferentes plataformas de bancos de dados. O uso do Construtor de Consultas não é obrigatório. Se as suas consultas são simples, é de fato mais fácil e rápido escrever os comandos SQL diretamente. > Note|Nota: O Construtor de Consultas não pode ser usado para modificar uma consulta existente especificada > como um comando SQL. Por exemplo, o código a seguite não iria funcionar: > > ~~~ > [php] > $command = Yii::app()->db->createCommand('SELECT * FROM tbl_user'); > // the following line will NOT append WHERE clause to the above SQL > $command->where('id=:id', array(':id'=>$id)); > ~~~ > > Em outras palavras, não misture o uso de comandos SQL em texto com o Construtor de Consultas. Preparando o Construtor de Consultas ------------------------------------ O Construtor de Consultas do Yii é fornecido na classe [CDbCommand], a principal classe para lidar com consultas ao banco de dados descrita em [Data Access Objects](/doc/guide/database.dao). Para começar a usar o Construtor de Consultas, nós criamos uma nova instância de [CDbCommand] como a seguir, ~~~ [php] $command = Yii::app()->db->createCommand(); ~~~ Ou seja, nós usamos `Yii::app()->db` para obter a conexão ao banco de dados, e então chamamos [CDbConnection::createCommand()] para criar a instância do comando. Note que ao invés de passar um comando completo para a chamada de `createCommand()` como fazemos em [Data Access Objects](/doc/guide/database.dao), nós o deixamos vazio. Fazemos isto porque nós vamos construir as partes individuais do comando SQL usando os métodos do Construtor de Consultas explicados a seguir. Construindo Consultas para Obtenção de Dados -------------------------------------------- Consultas de obtenção de dados referem-se aos comando SQL SELECT. O Construtor de Consultas fornece um conjunto de métodos para construir as partes individuais de um comando SELECT. Como todos estes métodos retornam uma instância de [CDbCommand], nós podemos usá-los de maneira encadeada, como mostrado no exemplo do início desta seção. * [select()|CDbCommand::select() ]: especifica a parte SELECT da consulta * [selectDistinct()|CDbCommand::selectDistinct]: especifica a parte SELECT da consulta e ativa a opção DISTINCT * [from()|CDbCommand::from() ]: especifica a parte FROM da consulta * [where()|CDbCommand::where() ]: especifica a parte WHERE da consulta * [andWhere()|CDbCommand::andWhere() ]: adiciona uma condição à cláusula WHERE da consulta com o operador `AND` * [orWhere()|CDbCommand::orWhere() ]: adiciona uma condição à cláusula WHERE da consulta com o operador `OR` * [join()|CDbCommand::join() ]: adiciona um fragmento de consulta INNER JOIN * [leftJoin()|CDbCommand::leftJoin]: adiciona um fragmento de consulta LEFT OUTER JOIN * [rightJoin()|CDbCommand::rightJoin]: adiciona um fragmento de consulta RIGHT OUTER JOIN * [crossJoin()|CDbCommand::crossJoin]: adiciona um fragmento de consulta CROSS JOIN * [naturalJoin()|CDbCommand::naturalJoin]: adiciona um fragmento de consulta NATURAL JOIN * [group()|CDbCommand::group() ]: especifica a parte GROUP BY da consulta * [having()|CDbCommand::having() ]: especifica a parte HAVING da consulta * [order()|CDbCommand::order() ]: especifica a parte ORDER BY da consulta * [limit()|CDbCommand::limit() ]: especifica a parte LIMIT da consulta * [offset()|CDbCommand::offset() ]: especifica a parte OFFSET da consulta * [union()|CDbCommand::union() ]: adiciona um fragmento de consulta UNION A seguir, nós explicamos como usar estes métodos do construtor de consultas. Para simplificar, nós assumimos que o banco de dados usado é o MySQL. Note que se você estiver usando outro SGBD, as aspas das tabelas, colunas e valores mostrados nos exemplos podem ser diferentes. ### select() ~~~ [php] function select($columns='*') ~~~ O método [select()|CDbCommand::select() especifica a parte `SELECT` da consulta. O parâmetro `$columns` especifica as colunas a serem selecionadas, que pode ser uma string representando nomes de colunas separados por vírgulas ou um array de nomes de colunas. Nomes de colunas podem conter o prefixo da tabela e/ou "apelidos" (aliases) das colunas. O método vai adicionar automaticamente as aspas aos nomes das colunas, a menos que o nome tenha parênteses (o que significa que a coluan informada é, na verdade, uma expressão do banco de dados). Alguns exemplos abaixo: ~~~ [php] // SELECT * select() // SELECT `id`, `username` select('id, username') // SELECT `tbl_user`.`id`, `username` AS `name` select('tbl_user.id, username as name') // SELECT `id`, `username` select(array('id', 'username')) // SELECT `id`, count(*) as num select(array('id', 'count(*) as num')) ~~~ ### selectDistinct() ~~~ [php] function selectDistinct($columns) ~~~ O método [selectDistinct()|CDbCommand::selectDistinct] ésimilar a [select()|CDbCommand::select() ] porém ele ativa a opção `DISTINCT`. Por exemplo, `selectDistinct('id, username')` iria gerar o seguinte SQL: ~~~ SELECT DISTINCT `id`, `username` ~~~ ### from() ~~~ [php] function from($tables) ~~~ O método [from()|CDbCommand::from() ] especifica a parte `FROM` da consulta. O parâmetro `$tables` especifica de quais tabelas a seleção erá feita. Ele pode ser uma string representando nomes de tabelas separados por vírgulas ou uma array de nomes de tabelas. Os nomes das tabelas podem conter prefixos de esquema (por exemplo `public.tbl_user`) e/ou "apelidos" da tabela (e.g. `tbl_user u`). O método vai adicionar aspas automaticamente ao nome da tabela, a menos que o nome contenha parênteses (o que significa que o nome da tabela é na verdade uma subconsulta ou uma expressão do banco de dados). Alguns exemplos abaixo: ~~~ [php] // FROM `tbl_user` from('tbl_user') // FROM `tbl_user` `u`, `public`.`tbl_profile` `p` from('tbl_user u, public.tbl_profile p') // FROM `tbl_user`, `tbl_profile` from(array('tbl_user', 'tbl_profile')) // FROM `tbl_user`, (select * from tbl_profile) p from(array('tbl_user', '(select * from tbl_profile) p')) ~~~ ### where() ~~~ [php] function where($conditions, $params=array()) ~~~ O método [where()|CDbCommand::where()] especifica a parte `WHERE` da consulta. O parâmetro `$conditions` especifica as condições da consulta enquanto o parâmetro `$params` especifica os parâmetros para serem vinculados à consulta. O parâmetro `$conditions` pode ser uma string (por exemplo `id=1`) ou um array no seguinte formato: ~~~ [php] array(operator, operand1, operand2, ...) ~~~ onde `operator` pode ser um dos seguintes: * `and`: os operandos (operand1, operand2 etc) devem ser concatenados usandoo `AND`. Por exemplo, `array('and', 'id=1', 'id=2')` vai gerar `id=1 AND id=2`. Se um operando é um array, ele serrá convertido em uma string usando as mesmas regras descritas aqui. Por exemplo, `array('and', 'type=1', array('or', 'id=1', 'id=2'))` iria gerar `type=1 AND (id=1 OR id=2)`. O método não irá adicionar aspas ou fazer qualquer sanitização nos caracteres. * `or`: similar ao operador `and` exceto que os operandos são concatenados usando OR. * `in`: o operando 1 deve ser uma coluna ou expressão do banco de dados e o operando 2 ser um array representando o intervalo de valores no qual a coluna ou a expressão deve estar. Por exemplo, `array('in', 'id', array(1,2,3))` vai gerar `id IN (1,2,3)`. O método vai adicionar aspas apropriadamente ao nome da coluna e sanitizar os valores no intervalo. * `not in`: similar ao operador `in` exceto que `IN` é substituído por `NOT IN` na condição gerada. * `like`: o operando 1 deve ser uam coluna ou expressão do banco de dados e o operando 2 deve ser uma string ou um array representando o intervalo de valores o qual a coluna ou a expressão devem ser semelhantes. Por exemplo, `array('like', 'name', '%tester%')` vai gerar `name LIKE '%tester%'`. Quando o intervalo de valores é fornecido comom um array, múltiplos predicados `LIKE` serão gerados e concatenados usando `AND`. Por exemplo, `array('like', 'name', array('%test%', '%sample%'))` vai gerar `name LIKE '%test%' AND name LIKE '%sample%'`. O método vai adicionar aspas ao nome da coluna e sanitizar os valores no intervalo. * `not like`: similar ao operador `like` exceto que `LIKE` é substituído por `NOT LIKE` na condição gerada. * `or like`: similar ao operador `like` exceto que `OR` é usado para concatenar múltiplos predicados `LIKE`. * `or not like`: similar ao operador `not like` exceto que `OR` é usado para concatenar múltiplos predicados `NOT LIKE`. Abaixo estão alguns exemplos do uso de `where`: ~~~ [php] // WHERE id=1 or id=2 where('id=1 or id=2') // WHERE id=:id1 or id=:id2 where('id=:id1 or id=:id2', array(':id1'=>1, ':id2'=>2)) // WHERE id=1 OR id=2 where(array('or', 'id=1', 'id=2')) // WHERE id=1 AND (type=2 OR type=3) where(array('and', 'id=1', array('or', 'type=2', 'type=3'))) // WHERE `id` IN (1, 2) where(array('in', 'id', array(1, 2)) // WHERE `id` NOT IN (1, 2) where(array('not in', 'id', array(1,2))) // WHERE `name` LIKE '%Qiang%' where(array('like', 'name', '%Qiang%')) // WHERE `name` LIKE '%Qiang' AND `name` LIKE '%Xue' where(array('like', 'name', array('%Qiang', '%Xue'))) // WHERE `name` LIKE '%Qiang' OR `name` LIKE '%Xue' where(array('or like', 'name', array('%Qiang', '%Xue'))) // WHERE `name` NOT LIKE '%Qiang%' where(array('not like', 'name', '%Qiang%')) // WHERE `name` NOT LIKE '%Qiang%' OR `name` NOT LIKE '%Xue%' where(array('or not like', 'name', array('%Qiang%', '%Xue%'))) ~~~ Por favor note que quando o operador contém `like`, nós temos que especificar explicitamente o caracter curinga (como `%` e `_`) nos padrões. Se os padrões vêm de dados enviados pelo usuário, nós devemos tambpem usar o código a seguir para sanitizar os caracteres especiais para prevenir que eles sejam tratados como caracteres selvagens: ~~~ [php] $keyword=$_GET['q']; // escape % and _ characters $keyword=strtr($keyword, array('%'=>'\%', '_'=>'\_')); $command->where(array('like', 'title', '%'.$keyword.'%')); ~~~ ### andWhere() ~~~ [php] function andWhere($conditions, $params=array()) ~~~ O método [addWhere()|CDbCommand::addWhere() ] adiciona a condição especificada à parte `WHERE` de uma consulta com o operador `AND`. O comportamento deste método é similar ao de [where()|CDbCommand::where() ] exceto que ele adiciona uma condição e não a substitui. Veja a documentação de [where()|CDbCommand::where() ] para mais informações sobre o parâmetros deste método. ### orWhere() ~~~ [php] function orWhere($conditions, $params=array()) ~~~ O método [orWhere()|CDbCommand::orWhere() ] adiciona a condição especificada à parte `WHERE` de uma consulta com o operador `OR`. O comportamento deste método é similar ao de [where()|CDbCommand::where() ] exceto que ele adiciona uma condição e não a substitui. Veja a documentação de [where()|CDbCommand::where() ] Para mais informações sobre os parâmetros deste método. ### order() ~~~ [php] function order($columns) ~~~ O método [order()|CDbCommand::order() ] especifica a parte `ORDER BY` de uma consulta. O parâmetro `$columns` especifica as colunas pelas quais a ordenação será feita e pode conter uma string representando nomes de colunas separados por vírgulas e o sentido da ordenação (`ASC` ou `DESC`), ou um array de nomes de colunas e sentidos de ordenação. Nomes de colunas podem conter prefixos de tabelas. O método vai adicionar automaticamente aspas aos nomes das colunas, a menos que o nome contenha parênteses (o que significa que o nome é uma expressão do banco de dados). Alguns exemplos a seguir: ~~~ [php] // ORDER BY `name`, `id` DESC order('name, id desc') // ORDER BY `tbl_profile`.`name`, `id` DESC order(array('tbl_profile.name', 'id desc')) ~~~ ### limit() and offset() ~~~ [php] function limit($limit, $offset=null) function offset($offset) ~~~ Os métodos [limit()|CDbCommand::limit() ] e [offset()|CDbCommand::offset() ] especificam as partes `LIMIT` e `OFFSET` de uma consulta. Note que alguns SGBD podem não suportar a sintaxe `LIMIT` e `OFFSET`. Neste caso, o Construtor de Consultas vai sobrescrever todo o comando SQL para simular a função esperada. Alguns exemplos abaixo: ~~~ [php] // LIMIT 10 limit(10) // LIMIT 10 OFFSET 20 limit(10, 20) // OFFSET 20 offset(20) ~~~ ### join() e suas variações ~~~ [php] function join($table, $conditions, $params=array()) function leftJoin($table, $conditions, $params=array()) function rightJoin($table, $conditions, $params=array()) function crossJoin($table) function naturalJoin($table) ~~~ O método [join()|CDbCommand::join() ] e as suas variações especificam como outras tabelas devem ser consultadas adicionalmete usando `INNER JOIN`, `LEFT OUTER JOIN`, `RIGHT OUTER JOIN`, `CROSS JOIN`, or `NATURAL JOIN`. O parâmetro `$table` especifica quais tabelas devem ser incluídas. O nome da tabela pode contar o prefixo do esquema e/ou um apelido. O método irá adicionar aspas ao nome a menos que ele contenha parênteses, o que significa que ele é uma expressão do banco de dados ou uma subconsulta. O parâmetro `$conditions` especifica a condição da inclusão. A sua sintaxe é a mesma que a de [where()|CDbCommand::where() ]. E `$params` especifica os parâmetros a serem vinculados à consulta. Note que, diferentemente dos outros métodos do Construtor de Consultas, cada chamada a este método irá adicionar o código gerado ao resultado das chamadas anteriores. Alguns exemplos abaixo: ~~~ [php] // JOIN `tbl_profile` ON user_id=id join('tbl_profile', 'user_id=id') // LEFT JOIN `pub`.`tbl_profile` `p` ON p.user_id=id AND type=1 leftJoin('pub.tbl_profile p', 'p.user_id=id AND type=:type', array(':type'=>1)) ~~~ ### group() ~~~ [php] function group($columns) ~~~ O método [group()|CDbCommand::group() ] especifica a parte `GROUP BY` de uma consulta. O parâmetro `$columns` especifica as colunas a serem agrupadas, que pode ser uma string representando nomes de colunas separados por vírgulas ou um array de nomes de colunas. Os nomes das colunas podem conter prefixos de tabela. O método irá adicionar aspas automaticamente ao nome da coluna, a menos que ele contenha parênteses (o que significa que ele é uma expressão do banco de dados). Alguns exemplos abaixo: ~~~ [php] // GROUP BY `name`, `id` group('name, id') // GROUP BY `tbl_profile`.`name`, `id` group(array('tbl_profile.name', 'id')) ~~~ ### having() ~~~ [php] function having($conditions, $params=array()) ~~~ O método [having()|CDbCommand::having() ] especifica a parte `HAVING` de uma consulta. O seu uso é similar ao de [where()|CDbCommand::where() ]. Alguns exemplos abaixo: ~~~ [php] // HAVING id=1 or id=2 having('id=1 or id=2') // HAVING id=1 OR id=2 having(array('or', 'id=1', 'id=2')) ~~~ ### union() ~~~ [php] function union($sql) ~~~ O método [union()|CDbCommand::union() ] especifica a parte `UNION` de uma consulta. Ele adiciona `$sql` à consulta existente usando o operador `UNION`. Chamar `union()` múltiplas vezes irá adicionar múltiplos SQLs ao SQL existente. Alguns exemplos abaixo: ~~~ [php] // UNION (select * from tbl_profile) union('select * from tbl_profile') ~~~ ### Executando Consultas Depos de chamar os métodos do Construtor de Consultas acima para construir uma consulta, nós podemos chamar os métodos DAO como descrito em [Data Access Objects](/doc/guide/database.dao) para executar a consulta. Por exemplo, nós podemos chamar [CDbCommand::queryRow()] para obter uma linha de um resultado, ou [CDbCommand::queryAll()] para obter todas as linhas de uma vez. Example: ~~~ [php] $users = Yii::app()->db->createCommand() ->select('*') ->from('tbl_user') ->queryAll(); ~~~ ### Obtendo SQLs Além de executar a consutla construída pelo Construtor de Consultas, nós podemos também obter o comando SQL correspondente. Isto pode ser feito chamando [CDbCommand::getText()]. ~~~ [php] $sql = Yii::app()->db->createCommand() ->select('*') ->from('tbl_user') ->text; ~~~ Se há parâmetros para serem vinculados a uma consulta, eles podem ser obtidos através da propriedade [CDbCommand::params]. ### Sintaxe Alternativa para a Construção de Consultas Algumas vezes, usar o encadeamento de métodos para construir uma query pode não ser a melhor escolha. O Construtor de Consultas do Yii permite que uma consulta seja construída usando simples atribuições de propriedades. Em particular, para cada método do Construtor de Consultas, há também uma propriedade correspondente com o mesmo nome. Atribuir um valor a uma destas propriedades é o mesmo que chamar o método correspondente. Por exemplo, os dois comandos a seguir são equivalentes, assumindo que `$command` representa um objeto [CDbCommand]: ~~~ [php] $command->select(array('id', 'username')); $command->select = array('id', 'username'); ~~~ Além disso, o método [CDbConnection::createCommand()] pode receber um array como parâmetro. Os pares nome-valor do array serão usado para inicializar as propriedades da instância de [CDbCommand]. Isto significa que nós podemos usar o código abaixo para construir uma consulta: ~~~ [php] $row = Yii::app()->db->createCommand(array( 'select' => array('id', 'username'), 'from' => 'tbl_user', 'where' => 'id=:id', 'params' => array(':id'=>1), ))->queryRow(); ~~~ ### Construindo Múltiplas Consultas Uma instância de [CDbCommand] pode ser reutilizada múltiplas vezes para construir várias consultas. Antes de construir uma nova consulta, o método [CDbCommand::reset()] deve ser chamado para limpar a consulta anterior. Por exemplo: ~~~ [php] $command = Yii::app()->db->createCommand(); $users = $command->select('*')->from('tbl_users')->queryAll(); $command->reset(); // clean up the previous query $posts = $command->select('*')->from('tbl_posts')->queryAll(); ~~~ Construindo Consultas de Manipulação de Dados --------------------------------------------- Consultas de manipulação de dados referem-se a comandos SQL para a inserção, atualização e remoção de dados em uma tabela do banco de dados. Para cada uma destas consultas, o Construtor de Consultas possui os métodos `insert`, `update` and `delete`, respectivamente. Diferentemente dos métodos de consulta SELECT descritos acima,cada um destes métodos de manipulação de dados vai construir um comando SQL completo e executá-lo imediatamente. * [insert()|CDbCommand::insert]: insere uma linha em uma tabela * [update()|CDbCommand::update]: atualiza dados em uma tabela * [delete()|CDbCommand::delete]: remove dados de uma tabela Nós descrevemos abaixo estes métodos de manipulação de dados. ### insert() ~~~ [php] function insert($table, $columns) ~~~ O método [insert()|CDbCommand::insert] constrói e executa um comando SQL `INSERT`. O parâmetro `$table` especifica em qual tabela a inserção é feita, enquanto `$columns` é um array de pares nome-valos especificando os valores das colunas a inserir. O método va adicionar aspas ao nome da tabela e vai vincular os parâmetros para os valores a serem inseridos. Um exemplo abaixo: ~~~ [php] // build and execute the following SQL: // INSERT INTO `tbl_user` (`name`, `email`) VALUES (:name, :email) $command->insert('tbl_user', array( 'name'=>'Tester', 'email'=>'tester@example.com', )); ~~~ ### update() ~~~ [php] function update($table, $columns, $conditions='', $params=array()) ~~~ O método [update()|CDbCommand::update] constrói e executa um comando SQL `UPDATE`. O parâmetro `$table` especifica qual tabela será atualizada; `$columns` é um array de pares nome-valor especificando os valores a serem atualizados; `$conditions` e `$params` são como em [where()|CDbCommand::where() ], os quais especificam a cláusula `WHERE` no comando `UPDATE`. o método vai adicionar aspas ao nome da tabela e vai vincular os parâmetros para os valores a serem atualizados. Um exemplo abaixo: ~~~ [php] // build and execute the following SQL: // UPDATE `tbl_user` SET `name`=:name WHERE id=:id $command->update('tbl_user', array( 'name'=>'Tester', ), 'id=:id', array(':id'=>1)); ~~~ ### delete() ~~~ [php] function delete($table, $conditions='', $params=array()) ~~~ O método [delete()|CDbCommand::delete] constrói e executa um comando SQL `DELETE`. O parâmetro `$table` especifica de qual tabela a remoção é feita; `$conditions` e `$params` são como em [where()|CDbCommand::where() ], que especificam a cláusula `WHERE` no comando `DELETE`. O método vai adicionar aspas ao nome da tabela. Um exemplo abaixo: ~~~ [php] // build and execute the following SQL: // DELETE FROM `tbl_user` WHERE id=:id $command->delete('tbl_user', 'id=:id', array(':id'=>1)); ~~~ Construindo Consultas de Manipulação do Esquema ----------------------------------------------- Além dos métodos para construção de consultas para a obtenção normal e a manipulação de dados, o Construtor de Consultas também oferece um conjunto de métodos para a construção e execução de consultas SQL que podem manipular o esquema de um banco de dados. Em particular, ele suporta as consultas a seguir: * [createTable()|CDbCommand::createTable]: cria uma tabela * [renameTable()|CDbCommand::renameTable]: renomeia uma tabela * [dropTable()|CDbCommand::dropTable]: remove (drop) uma tabela * [truncateTable()|CDbCommand::truncateTable]: limpa (truncate) uma tabela * [addColumn()|CDbCommand::addColumn]: adiciona uma coluna a uma tabela * [renameColumn()|CDbCommand::renameColumn]: renomeia uma coluna de uma tabela * [alterColumn()|CDbCommand::alterColumn]: altera a coluna de uma tabela * [dropColumn()|CDbCommand::dropColumn]: remove (drop) a coluna de uma tabela * [createIndex()|CDbCommand::createIndex]: cria um índice * [dropIndex()|CDbCommand::dropIndex]: remove (drop) um índice > Info|Informação: Apesar de os comandos SQL reais para a manipulação do esquema dos bancos de dados variar bastante nos diferentes SGBD, o Construtor de Consultas tenta fornecer uma interface uniforme para a construção destas consultas. Isto simplifica a tarefa de migrar o banco de dados de um SGBD para outro. ###Tipos de Dados Abstratos O Construtor de Consultas introduz um conjunto de tipos de dados abstratos que podem ser usados para definir as colunas das tabelas. Deferentemente dos tipos de dados físicos que são específicos de cada SGBD e que são bem diferentes entre eles, os tipos de dados abstratos são independentes dos SGBD. Quando os tipos de dados abstratos são usados para definir as colunas das tabelas, o Construtor de Consultas vai convertê-los para o tipo de dados físico correspondente. Os tipos de dados abstrados a seguir são suportados pelo Construtor de Consultas. * `pk`: um tipo genérico de chave primária, que será convertido para `int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY` para o MySQL; * `string`: tipo de texto, que será convertido para `varchar(255)` para o MySQL; * `text`: tipo de texto (long string), que será convertido para `text` para o MySQL; * `integer`: tipo de inteiro, que será convertido para `int(11)` para o MySQL; * `float`: tipo de número de ponto flutuante, que será convertido para `float` para o MySQL; * `decimal`: tipo de número decimal, que será convertido para `decimal` para o MySQL; * `datetime`: tipo de data e hora, que será convertido para `datetime` para o MySQL; * `timestamp`: tipo de carimbo de tempo, que será convertido para `timestamp` para o MySQL; * `time`: tipo de tempo, que será convertido para `time` para o MySQL; * `date`: tipo de data, que será convertido para `date` para o MySQL; * `binary`: tipo binário, que será convertido para `blob` para o MySQL; * `boolean`: tipo boolean, que será convertido para `tinyint(1)` para o MySQL; * `money`: tipo de dinheiro/moeda, que será convertido para `decimal(19,4)` para o MySQL. Este tipo está disponível desde a versão 1.1.8. ###createTable() ~~~ [php] function createTable($table, $columns, $options=null) ~~~ O método [createTable()|CDbCommand::createTable] constrói e executa uma consulta SQL para a criação de uma tabela. O parâmetro `$table` especifica o nome da tabela a ser criada. O parâmetro `$columns` especifica as colunas da nova tabela. Elas devem ser fornecidas como pares nome-definição (por exemplo `'username'=>'string'`). O parâmetro `$options` especifica qualquer fragmento SQL extra que deve ser adicionado ao SQL gerado. O Construtor de Consultas vai adicionar aspas aos nomes da tabela e das colunas. Ao especificar a definição das colunas, é possível usar os tipos de dados abstratos descritos acima. O Construtor de Consultas vai converter os tipos de dados abstratos para os tipos de dados físicos correspondente, de acordo com o SGBD em uso. Por exemplo, `string` será convertido para `varchar(255)` para o MySQL. Uma definição de coluna pode também conter tipos de dados não-abstratos ou especificações. Eles serão adicionados ao SQL gerado sem nenhuma alteração. Por exemplo, `point` não é um tipo de dados abstrato, e se for usado em uma definição de coluna, irá aparecer como especificado no SQL resultante; e `string NOT NULL` será convertido para `varchar(255) NOT NULL` (por exemplo, apenas o tipo abstrato `string` é convertido). Abaixo está um exemplo mostrando como criar uma tabela: ~~~ [php] // CREATE TABLE `tbl_user` ( // `id` int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, // `username` varchar(255) NOT NULL, // `location` point // ) ENGINE=InnoDB createTable('tbl_user', array( 'id' => 'pk', 'username' => 'string NOT NULL', 'location' => 'point', ), 'ENGINE=InnoDB') ~~~ ###renameTable() ~~~ [php] function renameTable($table, $newName) ~~~ O método [renameTable()|CDbCommand::renameTable] constrói e executa um comando SQL para renomear uma tabela. O parâmetro `$table` especifica o nome da tabela a ser renomeada. O parâmetro `$newName` especifica o novo nome da tabela. O Construtor de Consultas vai adicionar aspas aos nomes. Abaixo está um exemplo de como renomear uma tabela: ~~~ [php] // RENAME TABLE `tbl_users` TO `tbl_user` renameTable('tbl_users', 'tbl_user') ~~~ ###dropTable() ~~~ [php] function dropTable($table) ~~~ O método [dropTable()|CDbCommand::dropTable] constrói e executa um comando SQL para remover uma tabela. O parâmetro `$table` especifica o nome da tabela a ser removida. O Construtor de Consultas vai adicionar aspas ao nome da tabela. Abaixo está um exemplo de como remover uma tabela. ~~~ [php] // DROP TABLE `tbl_user` dropTable('tbl_user') ~~~ ###truncateTable() ~~~ [php] function truncateTable($table) ~~~ O método [truncateTable()|CDbCommand::truncateTable] constrói e executa um comando SQL para limpar uma tabela. O parâmetro `$table` espeficica o nome da tabela a ser limpa. O Construtor de Consultas vai adicionar aspas ao nome da tabela. Abaixo está um exemplo de como limpar uma tabela: ~~~ [php] // TRUNCATE TABLE `tbl_user` truncateTable('tbl_user') ~~~ ###addColumn() ~~~ [php] function addColumn($table, $column, $type) ~~~ O método [addColumn()|CDbCommand::addColumn] constrói e executa um comando SQL para adicionar uma nova coluna a uma tabela. O parâmetro `$table` especifica o nome da tabela à qual a nova coluna será adicionada. O parâmetro `$column` especifica o nome da nova coluna. E `$type` especifica a definição da nova coluna. A definição da coluna pode conter tipos de dados abstrados, como descrito na subseção de "createTable". O Construtor de Consultas vai adicionar aspas aos nomes da tabela e das colunas. Abaixo está um exemplo de como adicionar uma coluna a uma tabela: ~~~ [php] // ALTER TABLE `tbl_user` ADD `email` varchar(255) NOT NULL addColumn('tbl_user', 'email', 'string NOT NULL') ~~~ ###dropColumn() ~~~ [php] function dropColumn($table, $column) ~~~ O método [dropColumn()|CDbCommand::dropColumn] constrói e executa um comando SQL para remover uma coluna de uma tabela. O parâmetro `$table` especifica o nome da tabela da qual a coluna será removida. O parâmetro `$column` especifica o nome da coluna a ser removida. O Construtor de Consultas vai adicionar aspas aos nomes da tabela e da coluna. Abaixo está um exemplo de como remover uma coluna de uma tabela: ~~~ [php] // ALTER TABLE `tbl_user` DROP COLUMN `location` dropColumn('tbl_user', 'location') ~~~ ###renameColumn() ~~~ [php] function renameColumn($table, $name, $newName) ~~~ O método [renameColumn()|CDbCommand::renameColumn] constrói e executa um comando SQL para renomear a coluna de uma tabela. O parâmetro `$table` especifica o nome da tabela cuja coluna será renomeada. O parâmetro `$name` especifica o nome velho (atual) da coluna. E `$newName` especifica o novo nome da coluna. O Construtor de Consultas vai adicionar aspas aos nomes da tabela e da coluna. Abaixo está um exemplo de como renomear uma coluna de uma tabela: ~~~ [php] // ALTER TABLE `tbl_users` CHANGE `name` `username` varchar(255) NOT NULL renameColumn('tbl_user', 'name', 'username') ~~~ ###alterColumn() ~~~ [php] function alterColumn($table, $column, $type) ~~~ O método [alterColumn()|CDbCommand::alterColumn] constrói e executa um comando SQL para alterar uma coluna de uma tabela. O parâmetro `$table` especifica o nome da tabela cuja coluna será alterada. O parâmetro `$column` especifica o nome da coluna a ser alterada. E `$type` especifica a nova definição da coluna. A definição da coluna pode contar tipos de dados abstratos, como descrito na subseção de "createTable". O Construtor de Consultas vai adicionar aspas aos nomes da tabela e da coluna. Abaixo está um exemplo de como alterar a coluna de uma tabela. ~~~ [php] // ALTER TABLE `tbl_user` CHANGE `username` `username` varchar(255) NOT NULL alterColumn('tbl_user', 'username', 'string NOT NULL') ~~~ ###addForeignKey() ~~~ [php] function addForeignKey($name, $table, $columns, $refTable, $refColumns, $delete=null, $update=null) ~~~ O método [addForeignKey()|CDbCommand::addForeignKey] constrói e executa um comando SQL para adicionar um constraint de chave estrangeira a uma tabela. O parâmetro `$name` especifica o nome da chave estrangeira. Os parâmetros `$table` e `$columns` especificam o nome da tabela e a coluna sobre os quais é a chave estrangeira. Se há múltiplas colunas, elas devem ser separadas por vírgulas. Os parâmetros `$refTable` e `$refColumns` especificam o nome da tabela e da coluna os quais a chave estrangeira referencia. Os parâmetros `$delete` e `$update` especificam as opções `ON DELETE` e `ON UPDATE` do comando SQL, respectivamente. A maior parte dos SGBD suporta estas opções: `RESTRICT`, `CASCADE`, `NO ACTION`, `SET DEFAULT`, `SET NULL`. O Construtor de Consultas vai adicionar aspas aos nomes da tabela, índice e colunas. Abaixo está um exemplo de como adicionar um constraint de chave estrangeira: ~~~ [php] // ALTER TABLE `tbl_profile` ADD CONSTRAINT `fk_profile_user_id` // FOREIGN KEY (`user_id`) REFERENCES `tbl_user` (`id`) // ON DELETE CASCADE ON UPDATE CASCADE addForeignKey('fk_profile_user_id', 'tbl_profile', 'user_id', 'tbl_user', 'id', 'CASCADE', 'CASCADE') ~~~ ###dropForeignKey() ~~~ [php] function dropForeignKey($name, $table) ~~~ O método [dropForeignKey()|CDbCommand::dropForeignKey] constrói e executa um comando SQL para remover um constraint de chave estrangeira. O parâmetro `$name` especifica o nome do constraint de chave estrangeira a ser removido. O parâmetro `$table` especifica o nome da tabela onde a chave está. O Construtor de Consultas vai adicionar aspas aos nomes da tabela e do constraint. Abaixo está um exemplo de como remover um constraint de chave estrangeira de uma tabela: ~~~ [php] // ALTER TABLE `tbl_profile` DROP FOREIGN KEY `fk_profile_user_id` dropForeignKey('fk_profile_user_id', 'tbl_profile') ~~~ ###createIndex() ~~~ [php] function createIndex($name, $table, $column, $unique=false) ~~~ O método [createIndex()|CDbCommand::createIndex] constrói e executa um comando SQL para criar um índica. O parâmetro `$name` especifica o nome do índica a ser criado. O parâmetro `$table` especifica o nome da tabela onde está o índice. O parâmetro `$column` especifica o nome da coluna a ser indexada. E o parâmetro `$unique` especifica se um índica único deve ser criado. Se o índica consiste de múltiplas colunas, elas devem ser separadas por vírgulas. O Construtor de Consultas vai adicionar aspas aos nomes da tabela, índice e colunas. Abaixo está um exemplo de como criar um índice: ~~~ [php] // CREATE INDEX `idx_username` ON `tbl_user` (`username`) createIndex('idx_username', 'tbl_user', 'username') ~~~ ###dropIndex() ~~~ [php] function dropIndex($name, $table) ~~~ O método [dropIndex()|CDbCommand::dropIndex] constrói e executa um comando SQL para remover um índice. O parâmetro `$name` especifica o nome do índice a ser removido. O parâmetro `$table` especifica o nome da tabela onde está o índice. O Construtor de Consultas vai adicionar aspas aos nomes da tabela e do índice. Abaixo está um exemplo mostrando como remover um índice: ~~~ [php] // DROP INDEX `idx_username` ON `tbl_user` dropIndex('idx_username', 'tbl_user') ~~~
$Id$