Curso de MariaDB / Conectar Python e usar consultas parametrizadas com PyMySQL

Para conectar Python ao MariaDB, passe o texto SQL e os valores informados pelo usuário como argumentos separados da API do driver. Consultas parametrizadas evitam construir SQL com esses valores; uma conta com permissões limitadas e a decisão explícita entre commit e rollback controlam as alterações.

Preparar o ambiente e a conta da aplicação

O exemplo usa Python 3, PyMySQL 1.1.2 e uma conexão TCP local com MariaDB. Seu comportamento central foi verificado com Python 3.12 e MariaDB 12.3.3. PyMySQL é o driver que comunica Python com o banco; os marcadores de valores deste exemplo são %s. Não os substitua pelos pontos de interrogação de outro driver.

Execute a preparação por uma conexão administrativa. Substitua o marcador público Replace_With_Your_Own_Lab_Password pela senha de estudos. CREATE USER corresponde à primeira criação: se a conta ou a tabela já existir, examine-a antes de repetir o bloco. Confirme que um banco appops_lab existente pertence a estas práticas. O tutorial de contas e permissões do MariaDB diferencia essas responsabilidades.

CREATE DATABASE IF NOT EXISTS appops_lab
  CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE appops_lab;
CREATE TABLE app_notes (
  note_id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
  note_name VARCHAR(80) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE USER 'appops_app'@'127.0.0.1'
  IDENTIFIED BY 'Replace_With_Your_Own_Lab_Password';
GRANT SELECT, INSERT ON appops_lab.app_notes TO 'appops_app'@'127.0.0.1';

O Host da conta, 127.0.0.1, pressupõe acesso TCP a um servidor local nativo. Um contêiner ou servidor remoto pode enxergar outra origem de conexão. Confira a correspondência entre origens de contas e caminhos de conexão em vez de permitir acesso administrativo de qualquer origem para evitar um erro.

Criar um projeto isolado e salvar o programa completo

Crie uma pasta nova e abra PowerShell nela. Com Python instalado e disponível pelo comando python, crie o ambiente e instale a versão do driver usada no exemplo:

python -m venv .venv
.venv\Scripts\python.exe -m pip install PyMySQL==1.1.2

Chamar diretamente o Python do ambiente evita alterar a política de execução dos scripts de ativação. No Linux ou macOS, crie o ambiente com python3 -m venv .venv e execute .venv/bin/python -m pip install PyMySQL==1.1.2. Salve o programa completo abaixo em UTF-8 como notes_app.py, na raiz do projeto:

import argparse
import getpass
import os
import pymysql

def save_and_find(conn, name, sort_key="id"):
    if not name or len(name) > 80:
        raise ValueError("Name must contain 1 to 80 characters")
    columns = {"id": "note_id", "name": "note_name, note_id"}
    if sort_key not in columns:
        raise ValueError("Unknown sort key")
    with conn.cursor() as cur:
        cur.execute("INSERT INTO app_notes (note_name) VALUES (%s)", (name,))
        cur.execute(
            "SELECT note_id, note_name FROM app_notes "
            "WHERE note_name = %s ORDER BY " + columns[sort_key],
            (name,),
        )
        return cur.fetchall()

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--name", default="O'Reilly")
    parser.add_argument("--sort", choices=("id", "name"), default="id")
    args = parser.parse_args()
    password = getpass.getpass("Database password: ")
    conn = pymysql.connect(
        host=os.getenv("DB_HOST", "127.0.0.1"),
        port=int(os.getenv("DB_PORT", "3306")),
        user=os.getenv("DB_USER", "appops_app"),
        password=password,
        database="appops_lab",
        charset="utf8mb4", autocommit=False,
        connect_timeout=5, read_timeout=10, write_timeout=10,
    )
    try:
        rows = save_and_find(conn, args.name, args.sort)
        conn.commit()
        for note_id, note_name in rows:
            print(note_id, note_name)
    except Exception:
        conn.rollback()
        raise
    finally:
        conn.close()

if __name__ == "__main__":
    main()

O programa solicita a senha ao iniciar com getpass, em vez de armazená-la no código-fonte ou no SQL. Também define limites de tempo para conexão, leitura e gravação e usa utf8mb4 para Unicode. A mensagem Database password: solicita a senha do banco.

A configuração corresponde a estudos locais no computador. Uma conexão que atravesse outra rede exige também TLS, protocolo de proteção dos dados em trânsito, com verificação do certificado do servidor: fornecer uma senha não protege sozinho o transporte.

Testar um nome comum e outro com apóstrofo

Na pasta que contém notes_app.py, execute os dois comandos separadamente:

.venv\Scripts\python.exe notes_app.py --name "Notebook"
.venv\Scripts\python.exe notes_app.py --name "O'Reilly" --sort name

Informe a senha em cada inicialização. O primeiro armazena Notebook, e o segundo, O'Reilly, incluindo o apóstrofo; depois procuram linhas com o mesmo nome. Em uma tabela nova, após uma execução de cada comando, cada resultado contém sua linha correspondente. Não exija um identificador AUTO_INCREMENT específico: dados anteriores e inserções desfeitas podem alterar a numeração.

Repetir um nome insere outra linha e retorna todas as linhas correspondentes. O exemplo não declara nomes únicos. Se seu processo exigir evitar duplicidades, defina o que identifica uma nota e a restrição adequada, em vez de presumir que o programa já resolve isso.

Separar valores da sintaxe SQL

A chamada central é cur.execute(sql, (name,)): o SQL e a tupla de valores são argumentos separados. A vírgula cria uma tupla de um elemento. Não acrescente aspas SQL manualmente em torno de %s nem interpole entradas do usuário com o operador % do Python, f-string ou concatenação. Os exemplos oficiais do PyMySQL mostram essa separação.

Um nome como x' OR 1=1 -- precisa permanecer um único valor armazenado e pesquisado literalmente. Ele não deve virar uma condição que selecione todas as linhas. “Consulta parametrizada” descreve aqui a API utilizada; não significa que todo driver use necessariamente o protocolo de instruções preparadas do servidor.

Identificadores e palavras-chave SQL, como nomes de colunas, ASC e DESC, não são substituídos por parâmetros comuns de valores. O trecho ORDER BY vem exclusivamente do dicionário columns definido pelo desenvolvedor. argparse e a própria função verificam a seleção, portanto outro chamador também não pode ignorar a lista permitida. Consulte a referência dos argumentos de Cursor.execute.

Verificar transações e permissões em conjunto

Com autocommit=False, concluir save_and_find corretamente não torna a inserção persistente por si só. main confirma depois de INSERT e SELECT terem sucesso, desfaz diante de uma exceção e fecha a conexão em finally. Diferencie essa confirmação do que outra conexão consegue observar; o tutorial de transações InnoDB, COMMIT e ROLLBACK explica os limites.

A função rejeita nome vazio, mais de 80 caracteres ou chave de ordenação desconhecida antes de inserir. Esses controles complementam os parâmetros e as restrições da tabela. As mensagens Name must contain 1 to 80 characters e Unknown sort key indicam essas falhas de validação. Se uma exceção ocorrer após INSERT e antes do commit, o rollback da tentativa deve impedir que a linha seja preservada.

A conta tem somente SELECT e INSERT sobre app_notes. Como não cria nem remove tabelas, não precisa de CREATE ou DROP. Limitar permissões complementa o tratamento correto de valores e reduz as operações disponíveis diante de outro defeito no programa. A referência de conexão do PyMySQL detalha autocommit e os limites de tempo.

Diagnosticar erros e remover a prática

Sintoma O que conferir
ModuleNotFoundError Execute com o mesmo Python de .venv usado para instalar PyMySQL.
Access denied Confira usuário, senha, origem permitida e endereço do cliente visto pelo servidor.
Conexão recusada ou tempo esgotado Confira servidor, DB_HOST, DB_PORT, firewall e caminho real de rede.
A linha não aparece após o processo Verifique se uma exceção causou rollback e se consulta o banco correto após confirmar.
Falha somente com apóstrofos Procure interpolação manual das entradas em vez de passá-las como valores a execute.

Para ajustes que não sejam secretos, PowerShell permite uma substituição como $env:DB_PORT = "3307". Preserve a solicitação interativa de senha. Remova uma substituição desnecessária com Remove-Item Env:DB_PORT ou restaure o valor anterior se já estivesse configurado antes do exercício.

Ao terminar, pare o programa e confirme com o administrador que a conta e a tabela abaixo são os objetos de estudos que deseja remover:

DROP USER 'appops_app'@'127.0.0.1';
DROP TABLE appops_lab.app_notes;

Não substitua esses nomes por contas ou tabelas de negócio. A remoção não pode ser desfeita com ROLLBACK comum; preserve antes os dados necessários.