Quickstart Guide

​

Overview

1. Create an account and sign in
2. Create your first project
3. Add a database connection
4. Create visualization widgets
5. Customize your dashboard

​

Getting Started

Connection Name: Store Database
Host: localhost
Port: 5433
Database: vizboard_test1
Username: postgres
Password: testdbpass1234

Widget Title: Recent Sales
Widget Description: Latest sales transactions
Widget Type: Simple DataTable
Database Connection: Store Database
Table: sales
Columns: Select all or specific columns (id, product_name, quantity, price, sale_date)

Widget Title: Sales by Product
Widget Description: Compare product sales performance
Widget Type: Chart
Chart Type: Bar Chart
Database Connection: Store Database
Table: sales
X-Axis: product_name
Y-Axis: quantity
Aggregation: Sum
Group By: product_name

Connection Name: Store Database 2
Host: localhost
Port: 5434
Database: vizboard_test2
Username: postgres
Password: testdbpass1234

​

Example: Complete Dashboard

​

Sales Analytics Dashboard

{
  title: "Sales Analytics Dashboard",
  description: "Real-time sales and product performance",
  isPublic: false,
  connections: [
    {
      title: "Store Database",
      host: "localhost",
      port: 5433,
      database: "vizboard_test1"
    }
  ]
}

1. Recent Sales Table
   • Type: Simple DataTable
   • Table: sales
   • Columns: id, product_name, quantity, price, sale_date
   • Shows last 50 transactions with sorting and filtering
2. Sales by Product Chart
   • Type: Bar Chart
   • X-Axis: product_name
   • Y-Axis: quantity (Sum)
   • Shows total units sold per product
3. Revenue Over Time Chart
   • Type: Line Chart
   • X-Axis: sale_date
   • Y-Axis: price (Sum)
   • Shows revenue trends over time
4. Product Reviews Table
   • Type: Simple DataTable
   • Table: reviews
   • Columns: product_name, rating, comment, created_at
   • Shows customer feedback
5. Average Rating by Product Chart
   • Type: Bar Chart
   • X-Axis: product_name
   • Y-Axis: rating (Average)
   • Shows product satisfaction scores

​

Code Examples

​

Creating a Project Programmatically

import { createProjectWithConnections } from "@/app/actions/project/crud"

// Create project with database connection
const result = await createProjectWithConnections({
  userId: session.user.id,
  title: "Sales Analytics",
  description: "Store performance dashboard",
  isPublic: false,
  connections: [
    {
      title: "Store Database",
      host: "localhost",
      port: 5433,
      database: "vizboard_test1",
      user: "postgres",
      password: "testdbpass1234"
    }
  ]
})

if (result.success) {
  console.log("Project created:", result.projectId)
  // Auto-introspection runs automatically for valid connections
}

​

Creating a Widget

import { createWidget } from "@/app/actions/dashboard/crudWidgets"

// Create a bar chart widget
const widget = await createWidget({
  projectId: "project-uuid",
  title: "Sales by Product",
  description: "Total units sold per product",
  type: "chart",
  subtype: "bar",
  configs: {
    connectionId: "connection-uuid",
    table: "sales",
    xAxis: "product_name",
    yAxis: "quantity",
    aggregation: "sum",
    groupBy: "product_name"
  }
})

console.log("Widget created:", widget.id)

​

Fetching Table Data

import knex from "knex"
import { decrypt } from "@/lib/crypto/crypto"

// Fetch data from external database
const connection = await prisma.dbConnection.findUnique({
  where: { id: connectionId }
})

// Decrypt credentials
const credentials = JSON.parse(decrypt(connection.dbAccess))

// Create Knex instance
const db = knex({
  client: "pg",
  connection: credentials
})

// Query data
const data = await db("sales")
  .select("product_name", "quantity", "price")
  .orderBy("sale_date", "desc")
  .limit(50)

return data

​

Best Practices

​

Security

• Read-Only Credentials: Use database users with SELECT-only permissions
• Network Isolation: Only connect to databases on trusted networks
• Regular Key Rotation: Rotate ENCRYPTION_KEY and AUTH_SECRET periodically
• Private Projects: Keep sensitive data in private projects

​

Performance

• Limit Large Tables: Use filters and pagination for tables with millions of rows
• Index Columns: Ensure queried columns are indexed in your database
• Connection Pooling: VizBoard uses connection pooling automatically with Knex.js
• Caching: SWR caches widget data for fast navigation

​

Dashboard Design

• Focused Dashboards: Create separate projects for different use cases
• Descriptive Names: Use clear widget titles and descriptions
• Consistent Styling: Take advantage of VizBoard’s theming for cohesive design
• Regular Updates: Regenerate schemas when your database structure changes

​

Troubleshooting

​

Connection Failed

1. Verify Credentials: Double-check host, port, username, and password
2. Check Network: Ensure the database is accessible from VizBoard
3. Firewall Rules: Add VizBoard’s IP to database firewall allowlist
4. Database Running: Verify the database container is running: docker ps

# Test connection manually
docker exec -it <container-name> psql -U postgres -d vizboard_test1 -c "SELECT 1;"

​

Widget Not Showing Data

1. Schema Introspection: Regenerate schema in project settings
2. Table Exists: Verify the table exists in the database
3. Permissions: Ensure database user has SELECT permission
4. Data Exists: Check if the table has data: SELECT * FROM table_name LIMIT 1;

​

Slow Dashboard Loading

1. Large Tables: Add LIMIT clauses or filters to widgets
2. Too Many Widgets: Consider splitting into multiple projects
3. Unindexed Columns: Add database indexes on frequently queried columns
4. Network Latency: Use local or nearby databases for best performance

​

Next Steps

​

API Reference

​

Project Actions

• createProjectWithConnections(): Create project with database connections
• updateProject(): Update project details and connections
• deleteProject(): Delete project and all widgets
• getUserProjects(): Get all projects for current user
• regenerateProjectSchemas(): Re-introspect all database schemas

​

Widget Actions

• createWidget(): Create a new visualization widget
• updateWidget(): Update widget configuration
• deleteWidget(): Remove widget from dashboard
• updateWidgetOrder(): Change widget order on dashboard

​

Connection Actions

• deleteConnection(): Remove a database connection
• getProjectSchema(): Get introspected database schema

• Authentication checks
• Input validation with Zod
• Error handling
• Automatic cache revalidation

​

Example Database Schema

-- Store Database (test1, test2)
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  first_name VARCHAR(100),
  last_name VARCHAR(100),
  email VARCHAR(255) UNIQUE,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255),
  category VARCHAR(100),
  price DECIMAL(10,2),
  stock INTEGER,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE sales (
  id SERIAL PRIMARY KEY,
  product_name VARCHAR(255),
  quantity INTEGER,
  price DECIMAL(10,2),
  sale_date TIMESTAMP DEFAULT NOW()
);

CREATE TABLE reviews (
  id SERIAL PRIMARY KEY,
  product_name VARCHAR(255),
  rating INTEGER CHECK (rating >= 1 AND rating <= 5),
  comment TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);