Manual do PHP
Anterior |  | Próxima

# C. MySQL Melhorada

# Introdução

A extensão mysqli permite a você acessar a funcionalidade provida pelo MySQL 4.1 e posterior. Maiores informações sobre o servidor de banco de dados MySQL podem ser encontradas em http://www.mysql.com/

Documentação para o MySQL pode ser encontrada em http://dev.mysql.com/doc/.

Partes desta documentação foram incluídas do manual do MySQL com a permissão de MySQL AB.

# Dependências

Para ter esta funções disponíveis, você deverá compilar o PHP com suporte para a extensão mysqli.

> Nota: A extensão mysqli foi criada para funcionar com a versão 4.1.2 ou posterior do MySQL. Para versões anteriores, por favor vejaa documentação da extensão MySQL.

# Instalação

Para instalar a extensão mysqli para o PHP, use a opção de configuração `--with-mysqli=mysql_config_path/mysql_config` aonde `mysql_config_path` representa a localização do programa `mysql_config` que vem com versões do MySQL maiores do que 4.1.

Se você quiser instalar a extensão mysql junto com a extensão mysqli você tem que usar a mesma biblioteca de cliente para previnir quaisquer conflitos.

# Configurações em execução

O comportamento dessas funções podem ser modificado pelas configurações do `php.ini`.

Tabela 1. Opções de configuração do MySQLi

Nome | Padrão | Modificável
--- | --- | ---
mysqli.max_links | "-1" | PHP_INI_SYSTEM
mysqli.default_port | NULL | PHP_INI_ALL
mysqli.default_socket | NULL | PHP_INI_ALL
mysqli.default_host | NULL | PHP_INI_ALL
mysqli.default_user | NULL | PHP_INI_ALL
mysqli.default_pw | NULL | PHP_INI_ALL

Para maiores detalhes e definições das constantes PHP_INI_* acima, veja o capitulo sobre mudanças de configuração.

Breve descrição das diretivas de configuração.

`mysqli.max_links` integer

  O número máximo de conexões MySQL por processo.

`mysqli.default_port` string

  O número da porta TCP padrão para usar ao conectar ao servidor de banco de dados se não for especificada outra porta. Se não for especificado um padrão, então a porta será obtida da variável de ambiênte `MYSQL_TCP_PORT`, a entrada `mysql-tcp` em `/etc/services` ou a constante em tempo de compilação `MYSQL_PORT`, nesta ordem. Em Win32 será usada apenas a constante `MYSQL_PORT`.

`mysqli.default_socket` string

  O nome padrão do socket para usar ao conectar com um servidor de banco de dados local, se não for especificado outro nome de socket.

`mysqli.default_host` string

  O servidor padrão para usar ao conectar com o servidor de banco de dados se não for especificado um servidor. Não se aplica em safe mode.

`mysqli.default_user` string

  O nome de usuário padrão para usar ao conectar com o servidor de banco de dados. Não se aplica em safe mode.

`mysqli.default_password` string

  A senha padrão para usar ao conectar ao servidor de banco de dados se não for especificado outra senha. Não se aplica em safe mode.

# Classes pré-definidas

## mysqli

Representa uma conexão entre o PHP e um banco de dados MySQL.

### Construtor

- mysqli() - constroi um novo objeto mysqli

### Métodos

- autocommit() - ativa ou desativa o salvar automaticamente as modificações no banco de dados

- change_user() - modifica o usuário da conexão com o banco de dados especficada

- character_set_name - retorna o conjunto de caracteres padrão para a conexão com o banco de dados

- close - fecha uma conexão aberta anteriormente

- commit - grava a transação atual

- connect - abre uma nova conexão com o servidor de banco de dados MySQL

- debug - realiza operações de debug

- dump_debug_info - mostra informações de debug

- get_client_info - retorna a versão do cliente

- get_host_info - retorna o tipo da conexão usada

- get_server_info - retorna a versão do servidor MySQL

- get_server_version - retorna a versão do servidor MySQL

- init - inicia o objeto mysqli

- info - retorna informação sobre a consulta mais recente executada

- kill - diz ao servidor para matar uma thread do mysql

- multi_query - executa multiplas consultas

- more_results - confere se existem mais resultados na consulta multipla atual

- next_result - lê o próximo resultado da consulta multipla atual

- options - define opções

- ping - pinga uma conexão com o servidor ou reconecta se não houver conexão

- prepare - prepara uma consulta SQL

- query - executa uma consulta

- real_connect - tenta abrir uma conexão com o servidor de banco de dados MySQL

- escape_string - escapa os caracteres especiais para usar em uma consulta SQL, levando em conta o conjunto de caracteres atual

- rollback - desfaz a transação atual

- select_db - define o banco de dados padrão

- ssl_set - define parâmetros ssl

- stat - retorna o estado atual do sistema

- stmt_initInicia um comando para usar com mysqli_stmt_prepare

- store_result - transfere um conjunto de resultados da ultima consulta

- use_result - transfere um conjunto de resultados não guardado em buffer da ultima consulta

- thread-safe - retorna quando thread safety é dado ou não

### Propriedades

- affected_rows - retorna o número de linhas afetadas pela operação MySQL anterior

- errno - retorna o código de erro da chamada de função mais recente

- error - retorna a string de erro da chamada de função mais recente

- field_count - retorna o número de colunas da consulta mais recente

- host_info - retorna uma string representando o tipo de conexão usada

- info - retorna informação sobre a consulta mais recente executada

- insert-id - retorna o id gerado automaticamente usado na ultima consulta

- protocol_version - retorna a versão usada do protocolo MySQL

- sqlstate - retorna uma string contendo o código de erro SQLSTATE do ultimo erro

- thread_id - retorna o thread ID da conexão atual

- warning-count - retorna o número de warnings(avisos) gerados durante a execução da consulta SQL anterior

## mysqli_stmt

Representa um comando preparado.

### Métodos

- bind_param - Binds variables to a prepared statement

- bind_result - Binds variables to a prepared statement for result storage

- close - Fecha um comando preparado

- data-seek - Move para uma linha arbritária em um conjuto de resultads em um comando preparado

- execute - Executa um comando preparado

- fetch - Obtém resultados de um comando preparado em variáveis

- free_result - Libera a memória do resultado de um comando preparado

- result_metadata - Retorna um conjunto de resultados de um comando preparado para informação de metadados

- prepare - Prepara uma consulta SQL

- send_long_data - Envia os dados em pedaços

- store_result - Guarda todo o conjunto de resultados de um comando preparado em buffer

### Propriedades

- affected_rows - Retorna as linhas afetadas pela ultima consulta executada

- errno - Retorna o código de erro pela ultima função do comando

- errno - Retorna a mensagem de erro pela última função do comando

- param_count - Retorna o número de parâmetros para o comando preparado

- sqlstate - Retorna uma string contendo o código de erro SQLSTATE pela última função do comando

## mysqli_result

Representa o conjunto de resultados da consulta feit ao banco de dados.

### Métodos

- close - fecha o conjunto de resultados

- data_seek - move o ponteiro interno dos resultados

- fetch_field - retorna informação sobre uma coluna do conjunto de resulatdos

- fetch_fields - retorna informação sobre todas as colunas do conjunto de resultados

- fetch_field_direct - retorna informação da coluna especificada

- fetch_array - retorna uma linha em uma matriz associativa, uma matriz numérica, ou ambas.

- fetch_assoc - retorna uma linha do resultado como uma matriz associativa

- fetch_object - retorna uma linha do resultado como um objeto

- fetch_row - retorna uma linha do resultado como uma matriz numérica

- close - libera a memória usada

- field_seek - define o ponteiro do resultado para o índice de campo especificado

### Propriedades

- current_field - retorna o índice do campo atual

- field_count - retorna o número de campos do conjunto de resultados

- lengths - retorna uma matriz com os tamanhos das colunas

- num_rows - retorna o número de linhas em um conjunto de resultados

# Constantes pré-definidas

Tabela 2. Constantes MySQLi

Nome | Descrição
--- | ---
`MYSQLI_READ_DEFAULT_GROUP` (integer) | Lê opções do grupo especificado apartir do arquivo `my.cnf' ou do arquivo especificado por `MYSQLI_READ_DEFAULT_FILE`
`MYSQLI_READ_DEFAULT_FILE` (integer) | Lê opções apartir do arquivo indicado ao invés de `my.cnf`
`MYSQLI_OPT_CONNECT_TIMEOUT` (integer) | Limite de tempo para conectar em segundos
`MYSQLI_OPT_LOCAL_INFILE` (integer) | Ativa o comando `LOAD LOCAL INFILE`
`MYSQLI_INIT_COMMAND` (integer) | Comando para executar ao conectar no servidor MySQL. Será automaticamente executado novamente ao reconectar.
`MYSQLI_CLIENT_SSL` (integer) | Usar SSL (protocolo criptografado). Esta opção não deve ser definida por programas aplicativos; ela é definida internamente na biblioteca de cliente MySQL
`MYSQLI_CLIENT_COMPRESS` (integer) | Usar o protocolo de compressão
`MYSQLI_CLIENT_INTERACTIVE` (integer) | Permite interactive_timeout segundos (ao invés de wait_timeout segundo) de inatividade antes de fechar a conexão. A variável de sessão do cliente wait_timeout variable será definida com o valor da variável interactive_timeout.
`MYSQLI_CLIENT_IGNORE_SPACE` (integer) | Permite espaçoes após os nomes de função. Torna todos os nomes de função palavras reservadas.
`MYSQLI_CLIENT_NO_SCHEMA` (integer) | Não permite a sintaxe nome_bancodados.nome_tabela.nome_coluna
`MYSQLI_CLIENT_MULTI_QUERIES` (integer) |
`MYSQLI_STORE_RESULT` (integer) | Para usar conjuntos de resultados guardados em buffer
`MYSQLI_USE_RESULT` (integer) | Para usar conjuntos de resultados não guardados em buffer
`MYSQLI_ASSOC` (integer) | As colunas são retornadas em uma matriz tendo o nome dos campos como indices da matriz.
`MYSQLI_NUM` (integer) | As colunas são retornadas em uma matriz tendo os índices numerados.
`MYSQLI_BOTH` (integer) | As colunas são retornadas em uma matriz tendo ambos os índices, numérico e o nome do campo como índice associativo.
`MYSQLI_NOT_NULL_FLAG` (integer) | Indica que um campo é definido como `NOT NULL`
`MYSQLI_PRI_KEY_FLAG` (integer) | O campo é parte do índice primário
`MYSQLI_UNIQUE_KEY_FLAG` (integer) | O campo é parte de um índice único.
`MYSQLI_MULTIPLE_KEY_FLAG` (integer) | O campo é parte de um índice.
`MYSQLI_BLOB_FLAG` (integer) | O campo é definido como `BLOB`
`MYSQLI_UNSIGNED_FLAG` (integer) | O campo é definido como `UNSIGNED`
`MYSQLI_ZEROFILL_FLAG` (integer) | O campo é definido como `ZEROFILL`
`MYSQLI_AUTO_INCREMENT_FLAG` (integer) | O campo é definido como `AUTO_INCREMENT`
`MYSQLI_TIMESTAMP_FLAG` (integer) | O campo é definido como `TIMESTAMP`
`MYSQLI_SET_FLAG` (integer) | O campo é definido como `SET`
`MYSQLI_NUM_FLAG` (integer) | O campo é definido como `NUMERIC`
`MYSQLI_PART_KEY_FLAG` (integer) | O campo é parte de um índice múltiplo
`MYSQLI_GROUP_FLAG` (integer) | O campo é parte de `GROUP BY`
`MYSQLI_TYPE_DECIMAL` (integer) | O campo é definido como `DECIMAL`
`MYSQLI_TYPE_TINY` (integer) | O campo é definido como `TINYINT`
`MYSQLI_TYPE_SHORT` (integer) | O campo é definido como `INT`
`MYSQLI_TYPE_LONG` (integer) | O campo é definido como `INT`
`MYSQLI_TYPE_FLOAT` (integer) | O campo é definido como `FLOAT`
`MYSQLI_TYPE_DOUBLE` (integer) | O campo é definido como `DOUBLE`
`MYSQLI_TYPE_NULL` (integer) | O campo é definido como `DEFAULT NULL`
`MYSQLI_TYPE_TIMESTAMP` (integer) | O campo é definido como `TIMESTAMP`
`MYSQLI_TYPE_LONGLONG` (integer) | O campo é definido como `BIGINT`
`MYSQLI_TYPE_INT24` (integer) | O campo é definido como `MEDIUMINT`
`MYSQLI_TYPE_DATE` (integer) | O campo é definido como `DATE`
`MYSQLI_TYPE_TIME` (integer) | O campo é definido como `TIME`
`MYSQLI_TYPE_DATETIME` (integer) | O campo é definido como `DATETIME`
`MYSQLI_TYPE_YEAR` (integer) | O campo é definido como `YEAR`
`MYSQLI_TYPE_NEWDATE` (integer) | O campo é definido como `DATE`
`MYSQLI_TYPE_ENUM` (integer) | O campo é definido como `ENUM`
`MYSQLI_TYPE_SET` (integer) | Field is defined as `SET`
`MYSQLI_TYPE_TINY_BLOB` (integer) | Field is defined as `TINYBLOB`
`MYSQLI_TYPE_MEDIUM_BLOB` (integer) | O campo é definido como `MEDIUMBLOB`
`MYSQLI_TYPE_LONG_BLOB` (integer) | O campo é definido como `LONGBLOB`
`MYSQLI_TYPE_BLOB` (integer) | O campo é definido como `BLOB`
`MYSQLI_TYPE_STRING` (integer) | O campo é definido como `VARCHAR`
`MYSQLI_TYPE_CHAR` (integer) | O campo é definido como `CHAR`
`MYSQLI_TYPE_GEOMETRY` (integer) | O campo é definido como `GEOMETRY`
`MYSQLI_NEED_DATA` (integer) | More data available for bind variable
`MYSQLI_NO_DATA` (integer) | No more data available for bind variable

# Exemplos

Todos os exemplos na documentação MySQLI usam o banco de dados world da MySQL AB. O banco de dados world pode ser encontrado em http://dev.mysql.com/get/Downloads/Manual/world.sql.gz/from/pick

Anterior | Principal | Próxima
PDO_MYSQL DSN | Acima | mysqli_affected_rows