Pular para conteúdo

LocalDB

As ações LocalDB criam e manipulam bancos SQLite locais no host do robô, incluindo insert, select, update, delete, execução de SQL e importação de CSV/Excel.

Os valores de retorno viram variáveis de estado do robô (por exemplo $success, $rows, $result).

Índice

Ações

localdb.create_database

Cria ou abre um banco de dados SQLite.

Se o arquivo ainda não existir, ele é criado. Se já existir, a action apenas o abre.

Parâmetros:

database_name (opcional) - caminho ou nome do arquivo do banco SQLite (padrão="marvin.db").

Retornar:

success - True quando o banco for criado ou aberto com sucesso; False em caso de falha.

database - caminho ou nome do banco criado/aberto (apenas em sucesso).

error - mensagem de erro (apenas em caso de falha).

Exceções:

Esta ação não retorna nenhuma exceção.

Exemplo de uso
script.mvn
localdb.create_database("dados.db")
prompt.alert(str($success))
prompt.alert(str($database))

localdb.insert

Insere um ou múltiplos registros em uma tabela do banco de dados.

Aceita um dicionário único ou uma lista de dicionários. Quando pk é informado, a coluna é usada como chave primária na inserção.

Parâmetros:

database_name - caminho ou nome do arquivo do banco SQLite.

table - nome da tabela onde os dados serão inseridos.

data - dados a inserir. Aceita um dicionário único ou uma lista de dicionários.

pk (opcional) - nome da coluna a ser usada como chave primária.

Retornar:

success - True quando a inserção for bem-sucedida; False em caso de falha.

error - mensagem de erro (apenas em caso de falha).

Exceções:

Esta ação não retorna nenhuma exceção.

Exemplo de uso
script.mvn
localdb.create_database("dados.db")
localdb.execute(
    "dados.db",
    "CREATE TABLE IF NOT EXISTS usuarios (id INTEGER PRIMARY KEY, nome TEXT, idade INTEGER)"
)
localdb.insert(
    "dados.db",
    "usuarios",
    {"nome": "Ana", "idade": 25},
    pk="id"
)
prompt.alert(str($success))

localdb.select_table

Recupera registros de uma tabela do banco de dados.

É possível filtrar com condição WHERE e argumentos posicionais para os placeholders.

Parâmetros:

database_name - caminho ou nome do arquivo do banco SQLite.

table - nome da tabela a ser consultada.

where (opcional) - condição SQL WHERE usada para filtrar os registros. Exemplo: "idade = ?".

where_args (opcional) - valores usados para substituir os placeholders da condição WHERE. Exemplo: [25].

Retornar:

rows - lista de dicionários com os registros encontrados (apenas em sucesso).

error - mensagem de erro (apenas em caso de falha).

Exceções:

Esta ação não retorna nenhuma exceção.

Exemplo de uso
script.mvn
localdb.select_table("dados.db", "usuarios", where="idade = ?", where_args=[25])
prompt.alert(str($rows))

localdb.execute

Executa um comando SQL bruto no banco de dados.

Suporta comandos como DELETE, UPDATE, INSERT, CREATE TABLE e ALTER TABLE.

Parâmetros:

database_name - caminho ou nome do arquivo do banco SQLite.

query_str - comando SQL a ser executado.

Retornar:

success - True quando o comando for executado com sucesso; False em caso de falha.

rows_affected - número de linhas afetadas pela execução (apenas em sucesso).

error - mensagem de erro (apenas em caso de falha).

Exceções:

Esta ação não retorna nenhuma exceção.

Exemplo de uso
script.mvn
localdb.execute(
    "dados.db",
    "CREATE TABLE IF NOT EXISTS produtos (id INTEGER PRIMARY KEY, nome TEXT, preco REAL)"
)
prompt.alert(str($success))
prompt.alert(str($rows_affected))

localdb.query

Executa uma consulta SQL que retorna dados.

Normalmente usada com SELECT e PRAGMA.

Parâmetros:

database_name - caminho ou nome do arquivo do banco SQLite.

query_str - comando SQL de consulta a ser executado. Exemplos: SELECT * FROM usuarios, PRAGMA table_info(usuarios).

Retornar:

result - lista com os registros retornados pela consulta (apenas em sucesso).

error - mensagem de erro (apenas em caso de falha).

Exceções:

Esta ação não retorna nenhuma exceção.

Exemplo de uso
script.mvn
localdb.query("dados.db", "SELECT * FROM usuarios")
prompt.alert(str($result))

localdb.update

Atualiza um registro existente em uma tabela do banco de dados a partir do valor da chave primária.

Parâmetros:

database_name - caminho ou nome do arquivo do banco SQLite.

table - nome da tabela que contém o registro.

pk_value - valor da chave primária do registro a ser atualizado.

data - dicionário contendo os campos e os novos valores.

Retornar:

success - True quando a atualização for bem-sucedida; False em caso de falha.

error - mensagem de erro (apenas em caso de falha).

Exceções:

Esta ação não retorna nenhuma exceção.

Exemplo de uso
script.mvn
localdb.update("dados.db", "usuarios", 1, {"nome": "Ana Silva", "idade": 26})
prompt.alert(str($success))

localdb.delete

Exclui um registro de uma tabela do banco de dados a partir do valor da chave primária.

Parâmetros:

database_name - caminho ou nome do arquivo do banco SQLite.

table - nome da tabela que contém o registro.

pk_value - valor da chave primária do registro a ser excluído.

Retornar:

success - True quando a exclusão for bem-sucedida; False em caso de falha.

error - mensagem de erro (apenas em caso de falha).

Exceções:

Esta ação não retorna nenhuma exceção.

Exemplo de uso
script.mvn
localdb.delete("dados.db", "usuarios", 1)
prompt.alert(str($success))

localdb.import_table

Importa dados de arquivos CSV ou Excel (.csv, .xlsx) para uma tabela do banco de dados.

Parâmetros:

database_name - caminho ou nome do arquivo do banco SQLite.

file_path - caminho do arquivo a ser importado (.csv ou .xlsx).

table_name - nome da tabela de destino.

delimiter (opcional) - separador do CSV (padrão=",").

sheet_name (opcional) - nome da planilha do Excel. Por padrão, usa a planilha ativa.

has_pk (opcional) - define se a tabela possui chave primária (padrão=False).

pk_name (opcional) - nome da coluna de chave primária (padrão="id").

first_col_id (opcional) - define se a primeira coluna deve se tornar "id" (padrão=False).

Retornar:

success - True quando a importação for bem-sucedida; False em caso de falha.

rows_inserted - número de linhas inseridas (apenas em sucesso).

error - mensagem de erro (apenas em caso de falha).

Exceções:

Esta ação não retorna nenhuma exceção.

Exemplo de uso
script.mvn
localdb.import_table(
    "dados.db",
    "C:/assets/usuarios.csv",
    "usuarios",
    delimiter=",",
    has_pk=True,
    pk_name="id"
)
prompt.alert(str($success))
prompt.alert(str($rows_inserted))