Gerenciamento de migrations, modelos, seeders e gerador de query
Criado com o intuito de abstratir toda uma modelagem de dados, de forma fácil. Sua criação é baseada na biblioteca Eloquent vista no Laravel, framework PHP. A principio, não há muitos ORMs para python que são intuitivos no uso, inicialemente, neste pacote, era utilizado o SqlAlchemy, mas seu uso e documentação são complicados, com uma curva grande para aprendizado, não desmerecendo ele, sabemos o quão robusto e estável está atualmente, mas precisavamos de algo mais direto e que entendessemos a fundo o uso.
- Criar e executar
- Configurando uma migration
- Lista de tipos de campos e outras ferramentas
- Relacionamentos
Uso de migrations são importantes para manter o versionamento do banco de dados. Veja abaixo como utilizar.
Utilize o metodo 'make_file_migration()' informando o nome, diretório, nome da tabela e opcionalmente um comentário. O nome da migration tem como prefixos 'create_' e 'alter_', então gere o nome com eles para que as regras de cada tipo sejam setadas no arquivo gerado.
name_migration = "create_users"
dir_migration = "database"
table = "users"
comment = "criação da tabela de usuários"
Migration().make_file_migration(name_migration, dir_migration, table, comment)
Para executar as migrations informe apenas o local onde elas estão no método "migrate()", este comando também cria uma tabela ( migrations ) para gerenciamento de qual migration já foi executada.
dir_migration = "database"
Migration().migrate(dir_migration)
Para reiniciar o processo, fazendo o rollback das migrations, use o metodo 'drop_all_migrations()'
dir_migration = "database"
Migration().drop_all_migrations(dir_migration)
O arquivo gerado terá a seguinte aparência:
from KassOrm import Migration
class migrate(Migration):
__type__ = 'create'
__table__ = 'users'
__comment__ = 'criação da tabela de usuários'
def up(self):
self.id().add()
self.datetime('created_at').add()
def down(self):
self.dropTableIfExists()
Um valor opcional __ conn __ pode ser passado na classe, para determinar qual conexão usar, essa conexão deverá estar configurada em configs/database. Não informando será usado a conexão padrão.
É aqui que será criado os campos da tabela e seus relacionamentos. o metodo up(), é executado quando a migration é executada para criar, nesse caso, uma tabela, o down(), é o metodo responsavel por fazer o inverso, no caso dropar a tabela.
# colunas
id()
string(name, qnt)
bigInteger(name)
bigIntegerUnisigned(name)
text(name)
enum(name, values)
integer(name,qnt)
datetime(name)
# propriedades para as colunas
foreign(table, key, local_key)
nullable()
unsigned()
comment(comment)
unique(columns,name)
current_timestamp()
update_timestamp()
addColumn()
dropColumn(name)
after(column)
first(column)
dropTableIfExists()
Para relacionar duas tabelas, use foreign() como abaixo:
from KassOrm import Migration
class adresses(Migration):
__type__ = 'create'
__table__ = 'adress'
__comment__ = 'contem endereços'
def up(self):
self.id().add()
self.string('name').add()
self.string('number).add()
def down(self):
self.dropTableIfExists()
class migrate(Migration):
__type__ = 'create'
__table__ = 'users'
__comment__ = 'criação da tabela de usuários'
def up(self):
self.id().add()
self.datetime('created_at').add()
self.unsignedBigInteger('adress_id').add()
self.foreign(table="adress", key="id", local_key="adress_id").add()
def down(self):
self.dropTableIfExists()
Criador de querys para maior segurança e abstração de banco de dados.
Querier() recebe como parametro o nome da conexão (Querier('api')) que estará configurado dentro das configurações, caso não seja informada, será usada a conexão padrão (default).
Instanciar a classe e informar a tabela:
query = Querier('api').table("users")
Agora poderá usar a var query para fazer diversas buscas e filtros na mesma tabela.
query.get()
# SELECT * FROM users
query.where({"name":"kass"}).get()
# SELECT * FROM users WHERE (name = "kass")
Selecionando os campos, caso o método select não for chamado, será sempre retornado todos os campos
query.select(["name","login"])
Selecionando os campos e pegando todos os dados, get() finaliza a query
query.select(["name","login"]).get()
Selecionando os campos e pegando somente o primeiro registro, first() finaliza a query
query.select(["name","login"]).first()
Retornando a query a executar, toSql() finaliza a query
query.select(["name","login"]).toSql()
Retornando a query separado dos parametros, toInfo() finaliza a query
query.select(["name","login"]).toInfo()
Limit e offset
query.limit(10).offset(2).get()
Para filtrar os dados podemos usar vários metodos encadeados.
query.where({"name":"admin,"id":1}).get()
# SELECT * FROM users WHERE ( name = admin AND id = 1 )
query.where({"name":"admin,"id":1}).orWhere({"id":2}).get()
# SELECT * FROM users WHERE ( name = admin AND id = 1 ) OR ( id = 2 )
query.whereIn("name",["admin","kass"]).get()
# SELECT * FROM users WHERE (name IN ('admin', 'kass'))
query.whereIsNull("admin").get()
# SELECT * FROM users WHERE ( admin IS NULL )
query.whereIsNotNull("admin").get()
# SELECT * FROM users WHERE ( admin IS NOT NULL )
query.whereLike("name","%kass%").get()
# SELECT * FROM users WHERE ( name LIKE %kass% )
query.whereNotIn("name",["marcos","bee"]).get()
# SELECT * FROM users WHERE (name NOT IN ('marcos', 'bee'))
Para agrupar basta passar uma string com as colunas:
query.groupBy("name, login").get()
ou uma lista de colunas:
query.groupBy(["name","login"]).get()
Ordenação, pode-se passar uma string:
query.orderBy("name asc, login desc").get()
ou um dicionário informando a coluna e a direção:
query.orderBy({"name":"asc", "login":"desc"}).get()
Insere um ou mais registros
Querier().table("users").insert({"name":"kass"})
Querier().table("users").insert([{"name":"kass"},{"name":"admin"}])
Atualizando um valor.
Querier().table("users").where({"id":1}).update({"name":"ADMINISTRADOR","login":"ADMIN"})
OBS: Não esqueça de sempre utilizar a clausula *where* quando for atualizar registros.
Exclua um ou mais registros definitivamente
Querier().table("users").whereIn("id",[1,2]).delete()
Para trabalhar com softDelete, ou seja, não deletar um registro e sim desativar, você somente precisará configurar a classe Querier() com o parametro softDelete e informar nele qual a coluna que representa a desativação do registro, essa coluna deverá ser do tipo datetime, geralmente a coluna se chama deleted_at.
Querier(softDelete="deleted_at").table("users").where({"id":1}).delete()
O registro é atualizado na coluna determinada com a data e hora do delete.
Com essa configuração o select será afetado, não retornando os registros em que o campo determinado não for nulo.
Querier(softDelete="deleted_at").table("users").get()
# retorna tudo menos o id 1 que esta 'deletado'
Para retornar tudo, inclusive o que foi deletado, use o método withTrashed()
Querier(softDelete="deleted_at").table("users").withTrashed().get()
Utilize o método active(), para ativar um registro anteriormente deletado com softDelete. Este método só tem efeito utilizando o withTrashed().
Querier(softDelete="deleted_at").table("users").withTrashed().active()
OBS: Não esqueça de sempre utilizar a clausula *where* quando for excluir registros.
Classe para abstrair a classe Querier() e facilitar o uso dos dados nas tabelas, relacionamentos e informações sobre as queries de forma facilitada.
Veja a estrutura básica de um modelo:
from KassOrm import Modelr
class User(Modelr)
__conn__ = 'api'
__table__ = 'users'
Sendo que foi necessário fazer o import da classe Modelr e a injeção do mesmo no modelo. Duas configurações apra o modelo são: qual a conexão (conn) e qual a tabela do banco (table) que o model representa. Se não informar a conexão, ele irá pegar a conexaõ padrão (default) configurada.
Pegando todos os dados
User().get()
Pegando somente o primeiro registro
User().first()
Escolhendo colunas exibir
User().select(['name','login']).get()
Pegando todos os dados filtrados
User().where({"name":"admin,"id":1}).get()
Pegando sql e parametros
# exibe a query executada
User().where({"name":"admin,"id":1}).toSql()
# exibe a query e seus parametros separados
User().where({"name":"admin,"id":1}).toInfo()
Limit e offset
User().where({"name":"admin,"id":1}).limit(10).offset(2).get()
Para filtrar os dados podemos usar vários metodos encadeados.
User().where({"name":"admin,"id":1}).get()
# SELECT * FROM users WHERE ( name = admin AND id = 1 )
User().where({"name":"admin,"id":1}).orWhere({"id":2}).get()
# SELECT * FROM users WHERE ( name = admin AND id = 1 ) OR ( id = 2 )
User().whereIn("name",["admin","kass"]).get()
# SELECT * FROM users WHERE (name IN ('admin', 'kass'))
User().whereIsNull("admin").get()
# SELECT * FROM users WHERE ( admin IS NULL )
User().whereIsNotNull("admin").get()
# SELECT * FROM users WHERE ( admin IS NOT NULL )
User().whereLike("name","%kass%").get()
# SELECT * FROM users WHERE ( name LIKE %kass% )
User().whereNotIn("name",["marcos","bee"]).get()
# SELECT * FROM users WHERE (name NOT IN ('marcos', 'bee'))
Para montar seus relacionamentos, crie métodos dentro do seu modelo como abaixo.
Pensando que cada User (campo id) tem um Phone (campo user_id) (1 para 1):
from KassOrm import Modelr
class Phone(Modelr)
__conn__ = 'api'
__table__ = 'phones'
class User(Modelr)
__conn__ = 'api'
__table__ = 'users'
def phone(self):
return self.hasOne(Phone, "user_id","id")
Usando o relacionamento.
User().related('phone').get()
O método "related()" recebe uma string ou uma lista de strings.
Retorno do relacionamento seria:
[
{
"id":1,
"name":"admin",
"phone":{
"id":1,
"user_id":1,
"number":"12334567"
}
}
]
Onde a chave 'phone' representa os dados do relacionamento de User com Phone.
O método "hasOne" recebe os parametros:
- Phone => (model) modelo a se relacionar
- user_id => (model_key) nome do campo dentro de Phone que representa o user
- id => (local_key) identificador de User
Agora vamos exemplificar que cada User tem muitos endereços (Address).
from KassOrm import Modelr
class Phone(Modelr)
__conn__ = 'api'
__table__ = 'phones'
class Address(Modelr)
__conn__ = 'api'
__table__ = 'addresses'
class User(Modelr)
__conn__ = 'api'
__table__ = 'users'
def phone(self):
return self.hasOne(Phone, "user_id","id")
def addresses(self):
return self.hasMany(Address, "user_id","id")
Usando o relacionamento.
User().related(['phone','addresses']).get()
O método "related()" recebe uma string ou uma lista de strings. Retorno dos relacionamentos seria:
[
{
"id":1,
"name":"admin",
"phone":{
"id":1,
"user_id":1,
"number":"12334567"
},
"addresses":[
{
"id":1,
"user_id:1,
"address":"RUA 1"
},
{
"id":2,
"user_id:1,
"address":"RUA 2"
},
]
}
]
Onde a chave 'addresses' representa os dados do relacionamento de User com Address.
O método "hasMany" recebe os parametros:
- Address => (model) modelo a se relacionar
- user_id => (model_key) nome do campo dentro de Address que representa o user
- id => (local_key) identificador de User
Para casos que há muitos para muitos, devemos usar uma tabela intermediária. Segue como deria um relacionamento de User com Permission (permissões).
from KassOrm import Modelr
class Phone(Modelr)
__conn__ = 'api'
__table__ = 'phones'
class Address(Modelr)
__conn__ = 'api'
__table__ = 'addresses'
class Permission(Modelr)
__conn__ = 'api'
__table__ = 'permissions'
class User(Modelr)
__conn__ = 'api'
__table__ = 'users'
def phone(self):
return self.hasOne(Phone, "user_id","id")
def addresses(self):
return self.hasMany(Address, "user_id","id")
def permissions(self):
return self.hasManyToMany(Permission, 'id', 'permission_id', 'users_apps_permissions', 'user_id', 'id')
Usando o relacionamento.
User().related(['phone','addresses','permissions']).get()
O método "related()" recebe uma string ou uma lista de strings.
Retorno dos relacionamentos seria:
[
{
"id":1,
"name":"admin",
"phone":{
"id":1,
"user_id":1,
"number":"12334567"
},
"addresses":[
{
"id":1,
"user_id:1,
"address":"RUA 1"
},
{
"id":2,
"user_id:1,
"address":"RUA 2"
},
],
"permissions":[
{
"id":1,
"name":"acesso geral"
},
{
"id":2,
"name":"acesso a cadastrar"
},
{
"id":3,
"name":"acesso a excluir"
}
]
}
]
Onde a chave 'permissions' representa os dados do relacionamento de User com Permission.
O método "hasManyToMany" recebe os parametros:
- Permission => (model) modelo a se relacionar
- id => (model_key) identificador de Permission
- permission_id => (intermediate_model_key) identificador de Permission na tabela intermediária
- users_apps_permissions => (intermediate_table) nome da tabela intermediária
- user_id => (intermediate_local_key) identificador de User na tabela intermediária
- id => (local_key) identificador de User
O metodo "hasManyToMany" ainda pode receber o encadeamento de "withPivot()", que pode receber uma lista de nomes dos campos a exibir da tabela intermediária, se não for passado a lista, será retornado todos os campos da tabela intermediária. Veja o exemplo:
from KassOrm import Modelr
.
.
.
class User(Modelr)
__conn__ = 'api'
__table__ = 'users'
def phone(self):
return self.hasOne(Phone, "user_id","id")
def addresses(self):
return self.hasMany(Address, "user_id","id")
def permissions(self):
return self.hasManyToMany(Permission, 'id', 'permission_id', 'users_apps_permissions', 'user_id', 'id')->withPivot()
Alterando o retorno da chave permissions para:
[
{
.
.
.
"permissions":[
{
"id":1,
"name":"acesso geral",
"pivot":{
"user_id":1,
"permission_id":1,
}
},
{
"id":2,
"name":"acesso a cadastrar",
"pivot":{
"user_id":1,
"permission_id":2,
}
},
{
"id":3,
"name":"acesso a excluir",
"pivot":{
"user_id":1,
"permission_id":3,
}
}
]
}
]
Passando, "->withPivot(["user_id"])", somente o campo user_id seria exibido
Para agrupar basta passar uma string com as colunas:
User().groupBy("name, login").get()
ou uma lista de colunas:
User().groupBy(["name","login"]).get()
Ordenação, pode-se passar uma string:
User().orderBy("name asc, login desc").get()
ou um dicionário informando a coluna e a direção:
User().orderBy({"name":"asc", "login":"desc"}).get()
id = User().insert({"name":"kass"})
print(id)
ids = User().insert([{"name":"admin"},{"name":"kass"}])
print(ids)
Atualizando um registro.
User().where({"id":1}).update({"name":"admin"})
OBS: Não esqueça de sempre utilizar a clausula *where* quando for atualizar registros.
Para excluir um registro utilize o método delete().
User().where({"id":1}).delete()
Para trabalhar com softDelete, ou seja, não deletar um registro e sim desativar, você somente precisará configurar o seu model com a constante sofDelete e informar nele qual a coluna que representa a desativação do registro, essa coluna deverá ser do tipo datetime, geralmente a coluna se chama deleted_at.
class User(Modelr):
__sofDelete__="deleted_at"
para excluir use normal o metodo delete.
User().where({"id":1}).delete()
O registro é atualizado na coluna determinada com a data e hora do delete.
Com essa configuração o select será afetado, não retornando os registros em que o campo determinado não for nulo.
User().get()
# retorna tudo menos o registro que esta 'deletado'
Para retornar tudo, inclusive o que foi deletado, use o método withTrashed()
User().withTrashed().get()
Utilize o método active(), para ativar um registro anteriormente deletado com softDelete. Este método só terá efeito utilizando o withTrashed().
User().where({"id":1}).withTrashed().active()
OBS: Não esqueça de sempre utilizar a clausula *where* quando for excluir registros.
