Issue #10: Fix README.md

Signed-off-by: Lucas Fernandes de Oliveira's avatarLucas Fernandes de Oliveira <lfoliveira@inf.ufpr.br>
parent afbe0913
Pipeline #20989 passed with stage
in 1 minute
# PSQL Manager
# Ultimate SQL Manager
Ferramenta para auxiliar o versionamento de bases de dados do PostgreSQL.
Ferramenta desenvolvida para auxiliar na gestão de bancos de dados. O principal
objetivo da ferramenta é funcionar como uma interface única para realizar
operações básicas nos bancos de dados, independente do **SGBD** utilizado.
## Idiomas
O mesmo README está disponível em outros idiomas:
* ![alt text](./readme/brazil-flag.png "Brazilian Flag") [Portuguese](./README.md)
* ![alt text](./readme/united-kingdom-flag.png "UK Flag") [English](./readme/english.md)
## Como utilizar
```bash
./manger.sh <sgbd> <operação> [./workspace]
```
Se uma *workspace* não for fornecida, o diretório padrão (./data) é utilizado.
Todo diretório *workspace* deve seguir a mesma estrutura do diretório ./data
## Funcionalidades
A seguir é listado as funcionalidades atualmente disponíveis.
### Construção (Criação) do banco (*create*)
Dado um banco de dados recém criado, isto é, sem tabelas ou outros elementos, o
comando **create** pode ser utilizado para carregar os arquivos de construção do
banco de dados, gerando uma estrutura sem nenhum dado inserido.
Ao executar a operação **create** os arquivos do diretório **create** serão
executados em ordem alfabética, permitindo a criação de estruturas com
dependências.
### Carregamento em massa (*load*)
A operação **load** pode ser utilizada para inserir dados em massa. Cada um dos
arquivos no diretório **load** será inserido na tabela com o mesmo nome
(removendo a extensão).
Dois formatos de arquivo são permitidos:
* **exemplo.csv**: arquivo CSV com **;** como separador, **\n** como fim de
linha. O arquivo deve obrigatoriamente conter cabeçalho.
* **exemplo.csv.tar.bz2**: Versão compactada do arquivo CSV previamente
descrito. O arquivo compactado deve conter apenas um único arquivo CSV que será
inserido depois de descompactado. Os comandos utilizados para compactar e
descompactar são respectivamente:
```bash
tar cjf exemplo.csv.tar.bz2 exemplo.csv
tar xjOf exemplo.csv.tar.bz2 > exemplo.csv
```
ATENÇÃO: A operação **load** é aditiva, isto é, os dados serão
adicionados ao banco, mas os dados já existentes não serão removidos. Para
garantir que o banco tem exatamente os dados contidos em um diretório, a
operação **fixture** deve ser utilizada.
### Limpeza do banco (*clean*)
Remoção de todos os dados inseridos no banco, mas mantendo a estrutura, isto é,
o banco retorna ao estado que estava logo depois da execução da operação
**create**. A operação **clean** é usada para realizar essa tarefa
### Carregamento de *Fixtures* (*fixture*)
Limpa o banco de dados e depois carrega em massa os dados do diretório
**fixture** seguindo o mesmo padrão e restrições da operação **load**.
Operação utilizada para testes, uma vez que garante que o banco contém
exatamente os dados contidos no diretório **fixture**.
AVISO: Embora a operação **fixture** seja equivalente a operação **clean**
seguida de uma operação **load** a operação **fixture** carrega os dados do
diretório **fixture** e não do diretório **load**.
AVISO: A operação **fixture** TODOS removerá os dados já existentes no banco.
### Destruição do banco (*drop*)
Remoção de todas as estruturas do banco de dados. Ao utilizar essa operação
todos os dados e estruturas do banco são removidas. O estado do banco é igual a
o estado antes da operação **create** ser executada. A operação **drop** é
utilizada para realizar essa tarefa.
## SGBD's
Atualmente a ferramenta pode ser utilizada com os seguintes SGBDs:
* PostgreSQL: Testado com a versão 10
* MonetDB: Testado com a versão Apr2019
## Trabalhos Futuros
Conforme demanda o objetivo do projeto é adcionar cada vez mais SGBDs a lista
de SGBDs permitos e mais operações.
SGBDs candidatos a inserção na ferramenta:
* MariaDB
Operações candidatas a inserção na ferramenta:
* Versionamento do banco (migrações)
## Imagens
As imagens das bandeiras foram obtidas em: https://www.iconfinder.com/iconsets/142-mini-country-flags-16x16px
# Ultimate SQL Manager
Tool developed to ease database management. The main goal of this tool is to
become a interface to perform basic operations in databases independent of the
**DBMS** used.
## Languages
The same README is available other languages:
* ![alt text](./brazil-flag.png "Brazilian Flag") [Portuguese](../README.md)
* ![alt text](./united-kingdom-flag.png "UK Flag") [English](./english.md)
## How to use
```bash
./manger.sh <dbms> <operation> [./workspace]
```
If workspace is not provided, the default directory (./data) is used instead.
Any workspace directory MUST follow the same structure of ./data directory.
## Features
The list of features and operations allowed is listed bellow:
### Database building (creation) (*create*)
Given a freshly created database, in other words, a database with no tables and
any other elements, the **create** command can be used to load building files to
the database, generating a database schema, without any record inserted.
The **create** operation executes the files in **create** directory in
alphabetical order, allowing structures with dependencies.
### Bulk insertion (*load*)
The **load** operation can be used to perform bulk data insertion. Each file in
the **load** directory will be inserted in a table with the same same (removing
the extension).
Two data formats are allowed:
* **example.csv**: CSV file with **;** as separator and **\n** as end-of-line.
The file MUST contain a header.
* **example.csv.tar.bz2**: Compacter version of the CSV file previously
mentioned. The file must contain a single CSV file which will be inserted after
its decompression . The following commands are used to compress e decompress
respectively:
```bash
tar cjf example.csv.tar.bz2 example.csv
tar xjOf example.csv.tar.bz2 > example.csv
```
WARNING: The **load** operation additiva, which means that the records will be
added in the database, but the existent data will NOT be removed. To ensure that
the database contains exactly the data contained in the directory, the operation
**fixture** should be used.
### Database cleaning (*clean*)
Removal of all records inserted in the databse, but keeping the structure, which
means that the databse returns to the state which was after the **create**
operation was performed. The operation **clean** must be used to perform this
task.
### Fixtures bulk insertion (*fixture*)
Clean the database then bulk inserts records in the **fixture** directory,
using the same restrictions and patterns described in the **load** operation.
This operation is normally used in test scenarios to ensure that the database
state is exactly the same as described in the **fixture** directory.
WARNING: The **fixture** operation is equivalent to a **clean** followed by a
**load** operation, however, the **fixture** operation loads its data from the
**fixture** not from the **load** directory.
WARNING: The **fixture** operation will remove ALL existent records in the
database.
### Database destruction (*drop*)
Removal of all database structures. After this operation all records and
structures will be removed. The database state is the same as the state before
the use of the **create** operation. The **drop** operation is used to perform
this task.
## DMBSs
Nowadays the supported DBMSs are:
* PostgreSQL: Tested with the version 10
* MonetDB: Tested with the version Apr2019
## Future Work
The objective of the project in the future is to extend the support to others
DBMSs and to add more operations.
Candidate DBMSs to receive support:
* MariaDB
Candidate operations to be added:
* Database versioning (migrations)
## Images
The flag images were imported from: https://www.iconfinder.com/iconsets/142-mini-country-flags-16x16px
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment