This project is a Next.js application that allows users to query a PostgreSQL database using natural language and visualize the results. It's powered by the AI SDK by Vercel and uses OpenAI's GPT-4o model to translate natural language queries into SQL.
This project is based on the Natural Language PostgreSQL project by Vercel Labs, which is licensed under the Apache License 2.0. I've extended and modified the original project to add additional features and improvements.
- Full CRUD Operations: Complete support for Create, Read, Update, and Delete operations on local databases through natural language
- Visual Operation Feedback: Clear visual indicators for successful database operations with affected row counts
- Improved Database Connectivity: Better handling of local database connections with detailed error reporting
- Selected Column Viewing: Ability to see which columns are being selected in queries for better transparency
- Categorized Query Recommendations: Better organized suggestions grouped by analysis type (Regional, Industry, Growth, etc.)
- Geographic Focus: Specialized recommendations focusing on India, China, and USA unicorn data
- Data Export Options: Download query results as CSV or JSON files for further analysis
- Enhanced Loading States: Multi-step loading indicators showing progress through query generation and execution
- Responsive Design: Optimized layout for all screen sizes with mobile-first approach
- Dark Mode Support: Theme toggle for comfortable viewing in any lighting condition
- Dynamic Chart Selection: Automatically selects the most appropriate chart type based on data structure
- Multiple Chart Types: Support for bar, line, area, and pie charts with proper formatting
- Interactive Charts: Added tooltips, legends, and axis labels for better data interpretation
- Natural Language to SQL: Users can input queries in plain English or any other language, which are then converted to SQL using AI.
- AI-Powered Chatbot: Interactive chatbot interface for natural language database queries and assistance
- Full CRUD Operations: Support for INSERT, UPDATE, and DELETE operations through natural language with visual feedback.
- Data Visualization: Results are displayed in both table and chart formats, with the chart type automatically selected based on the data.
- Query Explanation: Users can view the full SQL query and get an AI-generated explanation of each part of the query.
- Categorized Recommendations: Pre-built query suggestions organized by analysis type to help users explore the data.
- Geographic Focus: Specialized recommendations focusing on India, China, and USA unicorn data.
- Data Export: Export query results as CSV or JSON files for further analysis.
- Selected Column Viewing: See which columns are being selected in queries for better transparency.
- Dark Mode: Toggle between light and dark themes for comfortable viewing in any environment.
- Responsive Design: Optimized layout for all screen sizes with mobile-first approach.
- Next.js for the frontend and API routes
- AI SDK by Vercel for AI integration
- OpenAI's GPT-4o for natural language processing
- PostgreSQL for data storage
- Framer Motion for animations
- ShadcnUI for UI components
- Tailwind CSS for styling
- Recharts for data visualization
Before you begin, ensure you have the following installed:
- Node.js (v18 or higher)
- pnpm (v8 or higher)
- PostgreSQL (v15 or higher)
-
Install PostgreSQL
- Linux (Ubuntu/Debian):
sudo apt update sudo apt install postgresql postgresql-contrib
- Start PostgreSQL service:
sudo systemctl start postgresql sudo systemctl enable postgresql - Create a database and user:
sudo -u postgres psql CREATE DATABASE echodb; CREATE USER yourusername WITH PASSWORD 'yourpassword'; GRANT ALL PRIVILEGES ON DATABASE echodb TO yourusername; \q
- Linux (Ubuntu/Debian):
-
Clone and Setup the Project
git clone https://github.com/yourusername/echodb-nlp-to-query.git cd echodb-nlp-to-query pnpm install -
Configure Environment Variables
cp .env.example .env
Edit
.envand add your configuration:OPENAI_API_KEY=your_api_key_here POSTGRES_URL="postgres://yourusername:yourpassword@localhost:5432/echodb" POSTGRES_PRISMA_URL="postgres://yourusername:yourpassword@localhost:5432/echodb?pgbouncer=true&connect_timeout=15" POSTGRES_URL_NO_SSL="postgres://yourusername:yourpassword@localhost:5432/echodb?sslmode=disable" POSTGRES_URL_NON_POOLING="postgres://yourusername:yourpassword@localhost:5432/echodb?connect_timeout=15" POSTGRES_USER="yourusername" POSTGRES_HOST="localhost" POSTGRES_PASSWORD="yourpassword" POSTGRES_DATABASE="echodb" -
Download and Prepare the Dataset
- Go to https://www.cbinsights.com/research-unicorn-companies
- Download the unicorn companies dataset
- Save it as
unicorns.csvin the root of your project
-
Seed the Database
pnpm run seed
-
Start the Development Server
pnpm run dev
Your project should now be running on http://localhost:3000.
- Connection Refused: Make sure PostgreSQL is running:
sudo systemctl status postgresql
- Permission Denied: Ensure your user has the correct permissions:
sudo -u postgres psql -c "ALTER USER yourusername WITH SUPERUSER;" - Database Doesn't Exist: Create it manually:
sudo -u postgres createdb echodb
- Port Already in Use: Kill the process using port 3000:
kill $(lsof -t -i:3000)
- Build Errors: Try cleaning the cache:
rm -rf .next pnpm install pnpm run build
To learn more about the technologies used in this project, check out the following resources: