# CRUD completo con CRUD-L sobre MySQL
En esta guía publicará el catálogo de clientes de una tienda con el marco [CRUD-L](/es/devkron/2.0/marcos/crudl/): primero como servicio REST en JSON (sin escribir código de operaciones) y luego con una interfaz HTML de lista y formulario, con búsqueda, alta, edición, control de concurrencia y borrado lógico. Todo se probó con Devkron 2.0 y MySQL 8 partiendo de una base vacía.
Requisitos: un sitio funcionando (aquí `tienda.localhost`, de la guía [Crear un sitio nuevo](/es/devkron/2.0/guias/sitio-nuevo-nginx.md)) y MySQL 8 con una base `tienda2` y un usuario con permisos sobre ella.
## 1. Prepare la base de datos
`tienda.sql`: las tablas de sistema que usa `dbr.login`, el usuario con el que se conecta el sistema y la tabla de clientes con los campos de control de Devkron.
```sql
-- Tablas de sistema que usan dbr.login y las sesiones
create table tuser (
sys_pk int not null auto_increment primary key,
sys_timestamp datetime not null, sys_guid varchar(32) not null unique, sys_dtcreated datetime,
sys_user varchar(5), sys_lastuser varchar(5), sys_exported bool, sys_dtexported datetime, sys_info varchar(32),
locked bool, message varchar(255), notes longtext,
pwd varchar(32), userid varchar(120) not null unique, username varchar(120) not null, pwdmd5 varchar(64),
sys_recver int null, sys_deleted bool null, sys_lock int null
);
create table sys_session (
sys_pk int not null auto_increment primary key,
sys_timestamp datetime not null, sys_guid varchar(32) not null unique, sys_dtcreated datetime,
sys_user varchar(5), sys_lastuser varchar(5), sys_exported bool, sys_dtexported datetime, sys_info varchar(32),
sys_recver int null, sys_deleted bool null, sys_lock int null,
iuser int not null, clientinfo varchar(64) not null
);
-- Usuario con el que se conecta el sistema (contraseña: MiClave#2026)
insert into tuser(sys_timestamp, sys_guid, sys_dtcreated, userid, username, pwd, pwdmd5)
values (now(), replace(uuid(),'-',''), now(), 'web', 'Usuario web', md5('MiClave#2026'), md5('MiClave#2026'));
-- La entidad
create table cliente (
sys_pk int auto_increment primary key,
sys_guid varchar(32), sys_dtcreated datetime, sys_timestamp datetime,
sys_recver int default 0, sys_deleted tinyint default 0, sys_lock int null,
codigo varchar(20) not null unique,
nombre varchar(120) not null,
estado varchar(20) not null default 'activo',
saldo decimal(14,2) not null default 0
);
```
```bash
mysql --default-character-set=utf8mb4 -h 127.0.0.1 -u mi_usuario -p tienda2 < tienda.sql
```
Si su base ya sigue el patrón de diseño de Devkron (por ejemplo, la creó otra aplicación suya sobre `dbr`), `tuser` y `sys_session` ya existen: solo cree la tabla `cliente` y use un usuario de `tuser`.
## 2. Registre la conexión
En `connections.xml` de la instalación, una aplicación `tienda2` con la conexión `principal` ([Conexiones](/es/devkron/2.0/instalacion/conexiones.md)):
```xml
tienda2principalMY_SQLMY_SQL127.0.0.1mi_usuarioMiClave#2026tienda23306]]>connections.sqldictrue
```
En producción, [cifre la conexión](/es/devkron/2.0/instalacion/cifrar-conexiones.md).
## 3. La ruta y el punto de entrada
`web/tienda.localhost/_protected/routes.map`:
```text
/clientes/{_entities_type}/{_entity_id?} > clientes/entry-point.dkl
```
`web/tienda.localhost/clientes/entry-point.dkl` (basado en la plantilla `crudl/entry-point.dkl`):
```dkl
#include "dkli.dkh"
#!
module "Configuración del CRUD-L de clientes"
{
#include "functions.dkh"
#include "serialize.dkh"
#include "dbr.dkh"
#include "crudl/crudl.dk"
// Rutas
@path_root = "web/tienda.localhost"
@base_path = "clientes/entidades"
@dbmvc_path = "crudl/"
do crudl.load_config()
do crudl.loadRoutesJSON()
// Comportamiento y vistas
@auto_crud = @true
@db_engine = "MY_SQL"
@list_view = "list.dk"
@form_view = "form.dk"
@error_view = "error.dk"
@entity_id_blank = "_new"
@dkl_view_ext = ".dk"
@websencia_ext = ".jsnwm"
// Conexión constante
@crudl.qname = "principal@tienda2"
@crudl.user = "web"
@crudl.pwd = "MiClave#2026"
// Suplantación de identidad
@ws = @@(@http_context,"request/get/ws")
@crudl.access_privilege = '{"access":[{"workspace":"' + @ws + '"}]}'
do errordet(@false)
#include "crudl/controller.dkl"
}
```
Cree la carpeta de la entidad (aunque esté vacía): `web/tienda.localhost/clientes/entidades/cliente/`.
## 4. Pruebe el servicio REST
Sin una línea más de código ya tiene las cinco operaciones. Respuestas reales:
```bash
curl -X POST http://tienda.localhost/clientes/cliente/ \
-H "Content-Type: application/json;charset=utf-8" \
-d '{"codigo":"CLI-0001","nombre":"Abarrotes López"}'
```
```json
{"sys_pk":1,"sys_guid":"104527ef7d4848848403deb232715035","sys_dtcreated":"2026-10-28T00:18:40Z","sys_timestamp":"2026-10-28T00:18:40Z","sys_recver":0,"sys_deleted":null,"sys_lock":null,"codigo":"CLI-0001","nombre":"Abarrotes López","estado":"activo","saldo":0.00}
```
| Petición | Respuesta |
|---|---|
| `GET /clientes/cliente/` | 200, arreglo con los clientes |
| `GET /clientes/cliente/1` | 200, el cliente 1 |
| `POST` con un `codigo` repetido | 500 `{"message":"Error en 'dbr.save. (Save Error. Duplicate entry 'CLI-0001' for key 'cliente.codigo'..."}` |
| `PATCH /clientes/cliente/1` `{"sys_recver":0,"estado":"suspendido"}` | 200, `sys_recver` 1 y `estado` suspendido |
| El mismo `PATCH` otra vez (con `sys_recver` 0) | 500 `Save Error. No fue posible actualizar la entidad` (alguien guardó antes) |
| `DELETE /clientes/cliente/2` | 204; ya no aparece en la lista |
El detalle de cada operación está en [Servicios REST](/es/devkron/2.0/marcos/crudl/rest.md).
## 5. El modelo: búsqueda, valores iniciales y borrado lógico
`clientes/entidades/cliente/model.dk`:
```dkl
#include "dkli.dkh"
#!
module "Modelo de cliente"
{
@list_query = "
select sys_pk, codigo, nombre, estado, saldo
from cliente
where ifnull(sys_deleted,0)=0
and (ifnull(@texto,'')='' or codigo=@texto or nombre like concat('%',@texto,'%'))
order by nombre
limit 250;"
// El saldo no se captura
@create_exclude_fields = "saldo"
@update_exclude_fields = "sys_pk,sys_guid,sys_dtcreated,saldo"
Cliente.blank::&db, ¶ms
{
new r { @"estado": "activo" }
return r
}
Cliente.borrado_logico::&db, table, sys_pk
{
new p { @"sys_pk": sys_pk }
do dbr.execute(db, "update cliente set sys_deleted=1 where sys_pk=@sys_pk;", p)
}
point @blank to Cliente.blank
point @custom_delete to Cliente.borrado_logico
}
```
Ahora `GET /clientes/cliente/?texto=Ferre` filtra, `GET /clientes/cliente/_new` devuelve `{"estado":"activo"}` y `DELETE` marca `sys_deleted` en lugar de borrar la fila. Más opciones en [El modelo](/es/devkron/2.0/marcos/crudl/modelo.md).
## 6. La lista
`clientes/entidades/cliente/list.dk`:
```dkl
#include "dkli.dkh"
#set "meta-xml-declaration" "\r\n"
#$
html(lang="es")
{
##
#include "functions.dkh"
#include "serialize.dkh"
ref filas = @@(@crud_context,"&output")
seleccionado = @@(@crud_context,"$parameters/_select")
texto = @@(@crud_context,"$parameters/texto")
##
head
{
meta(charset="utf-8"){}
title{"Clientes"}
}
body
{
h1{"Clientes"}
form(method="GET" action="./")
{
input(type="text" name="texto" value="#" placeholder="Código o nombre"){}
button(type="submit"){"Buscar"}
}
p{ a(href="_new"){"Agregar cliente"} }
table(border="1")
{
thead{ tr{ th{"Código"} th{"Nombre"} th{"Estado"} } }
tbody
{
##
for i=0; i<@count(filas)
{
ref f = @item(filas,i)
estilo = ifstr(@@(f,"$sys_pk")==seleccionado,"background:#ffd","")
##
tr(style="#")
{
td{ a(href="#<@@(f,'$sys_pk')>"){ $"#<@@(f,'$codigo')>" } }
td{ $"#<@@(f,'$nombre')>" }
td{ $"#<@@(f,'$estado')>" }
}
##
}
##
}
}
}
}
```
Abra `http://tienda.localhost/clientes/cliente/` en el navegador (envía `Accept: text/html`). Con `curl`, agregue `-H "Accept: text/html"`. Respuesta real de la búsqueda `?texto=Ferre`:
```html
```
## 7. El formulario
`clientes/entidades/cliente/form.dk`. Sirve para alta y edición; lee de `.` para repintar lo capturado si el guardado falla:
```dkl
#include "dkli.dkh"
#set "meta-xml-declaration" "\r\n"
#$
html(lang="es")
{
##
#include "functions.dkh"
#include "serialize.dkh"
ref d = @@(@crud_context,"&.")
ref e = @@(@crud_context,"&error")
es_nuevo = @@(@crud_context,"$parameters/_entity_id") == "_new"
titulo = ifstr(es_nuevo, "Nuevo cliente", "Cliente " + @@(d,"$codigo"))
activo = ifstr(@@(d,"$estado")=="activo","selected","")
suspendido = ifstr(@@(d,"$estado")=="suspendido","selected","")
##
head
{
meta(charset="utf-8"){}
title{$"#"}
}
body
{
h1{$"#"}
##
if not(isnull(e))
{
##
p(style="color:#b00"){ $"#<@@(e,'$message')>" }
##
}
##
form(method="POST" action="")
{
input(type="hidden" name="sys_recver" value="#<@@(d,'$sys_recver')>"){}
input(type="hidden" name="---from_url" value="/clientes/cliente/"){}
p{ label{"Código "} input(type="text" name="codigo" value="#<@@(d,'$codigo')>" required="required"){} }
p{ label{"Nombre "} input(type="text" name="nombre" value="#<@@(d,'$nombre')>" required="required"){} }
p
{
label{"Estado "}
select(name="estado")
{
option(value="activo" "#"="#"){"Activo"}
option(value="suspendido" "#"="#"){"Suspendido"}
}
}
button(type="submit"){"Guardar"}
$" "
a(href="./"){"Volver"}
}
}
}
```
El truco de `"#"="#"`: el nombre del atributo es una marca; cuando vale `selected` sale `selected = "selected"`, y cuando está vacía el atributo no se escribe. Resultado real del formulario nuevo:
```html
```
## 8. Recorra el ciclo completo
Resultados reales con `Accept: text/html`:
| Acción | Respuesta |
|---|---|
| `GET /clientes/cliente/_new` | El formulario con título `Nuevo cliente` |
| `POST /clientes/cliente/_new` con `codigo=CLI-0003`, `nombre=Ferretería Norte` | `302`, `Location: /clientes/cliente/` (por `---from_url`) |
| El mismo POST otra vez | `500` con el formulario, el mensaje `Duplicate entry 'CLI-0003'...` y el nombre capturado (`Repetido`) repintado |
| `GET /clientes/cliente/1` | El formulario con `sys_recver` 1 y `Suspendido` seleccionado |
| `POST /clientes/cliente/1` con `sys_recver=1` | `302`, `Location: /clientes/cliente/?_select=1&_key=sys_pk` (sin `---from_url` se usa la URL predeterminada) |
| `GET /clientes/cliente/?_select=1&_key=sys_pk` | La lista con la fila 1 resaltada |
El patrón completo está en [PRG y redirección](/es/devkron/2.0/marcos/crudl/prg-y-redireccion.md).
## Errores típicos
| Síntoma | Causa y solución |
|---|---|
| `Error de inicio de sesión, verifique Usuario y Contraseña` | `@crudl.user`/`@crudl.pwd` no coinciden con `tuser` (la contraseña se guarda como MD5 en `pwd` o `pwdmd5`) |
| `Variable global '@entity_id_blank' no definida` | Falta esa variable en el punto de entrada |
| La lista se ve como JSON | La petición no trae `Accept: text/html` |
| El formulario con error sale vacío | La vista lee de `&output`; use `&.` |
| `Vista de lista no disponible` | La vista no está en la carpeta de la entidad ni en `clientes/entidades/` |
| Un cliente borrado se puede abrir por su URL | `@read_query` no filtra `sys_deleted`; agregue la condición en el modelo |
## Siguientes pasos
- Partidas en la misma entidad: [Maestro-detalle](/es/devkron/2.0/marcos/crudl/maestro-detalle.md).
- Solo usuarios con sesión: [Inicio de sesión y permisos](/es/devkron/2.0/guias/inicio-de-sesion.md) y [Conexión y sesión](/es/devkron/2.0/marcos/crudl/conexion-y-sesion.md).
- Listas desplegables y tablas con totales en las vistas: [uie](/es/devkron/2.0/marcos/uie/).