Try free

Last updated 13 October 2026

Query a local database using Claude Code

Direct access to your database streamlines development

You are tired of copying table schemas from your terminal into a chat window every time you need help with a complex query. When you work on a local database, you usually jump between your IDE, a database client, and the terminal. This constant context switching breaks your focus and slows down your debugging process. Claude Code solves this by using tools to interact with your local environment directly. You can let the agent read your schema, execute select statements, and even suggest migrations without leaving your command line interface.

Instead of manually describing your data structures, you can give the agent the ability to explore the database itself. This approach reduces errors because the agent works with the actual state of your data rather than an outdated snippet you pasted. Whether you are troubleshooting a failing test or trying to optimize a slow join, having the agent connected to your local instance makes the process significantly faster. You can keep your hands on the keyboard and maintain a single flow of conversation that results in real code and verified data fixes.

Configure the connection using the Model Context Protocol

To make this work, you must define how Claude Code talks to your database. You do this through the Model Context Protocol, which acts as a bridge between the agent and external data sources. You store the configuration for these servers in a file named .mcp.json in your project root. This file contains the commands needed to start the server and the environment variables required for connection strings. If you want a global configuration that applies to every project on your machine, you can place these settings in your home directory under the .claude folder instead.

The configuration file is a standard format that specifies which command the agent should run to start the database bridge. For example, if you are using a PostgreSQL server, you would specify the connection string and the package runner command needed to execute the bridge software. The agent does not come with these bridges built-in; you must install the specific server for your database type. Once the file is saved, the agent will have access to a new set of tools specifically designed for querying and inspecting your database tables.

It is helpful to keep your .mcp.json file organized, especially if you work with multiple databases like Redis and SQLite simultaneously. Each entry in the file defines a separate server that the agent can call upon. You can also use the .claude/settings.json file to manage how the agent interacts with these tools. By setting up these files correctly, you ensure that every time you run the claude command in your project folder, the agent is ready to help with your data layer immediately.

Initialize and manage MCP servers in your project

Once you have defined your configuration, you can use the claude mcp command to manage your servers. This command allows you to list the active bridges and ensure they are running correctly. If you are already inside an interactive session, you can use the /mcp slash command to see the same information. This is useful for verifying that the agent actually sees the database tools you intended to provide. If a server fails to start, the agent will usually report the error, allowing you to fix the connection string or the command path.

If you encounter issues with the setup, you can run claude doctor to check the health of your installation. This utility verifies that the environment is set up correctly and that the agent can access the necessary configuration files. Sometimes a syntax error in your .mcp.json file can prevent the servers from loading. Using the doctor command helps you pinpoint these configuration problems quickly. Once the setup is verified, the agent will be able to use tools like Bash to interact with your local database CLI or specialized tools provided by the MCP server itself.

Control tool execution with specific permission modes

Security is a major concern when an automated agent has access to a database. You can control exactly what the agent is allowed to do by switching permission modes inside your session. By default, the agent asks for your approval before it runs any tool that might change your system. You can use Shift+Tab to cycle through modes like plan or bypassPermissions. This allows you to adjust the level of autonomy the agent has depending on the risk of the task you are performing.

In plan mode, the agent will only describe what it intends to do without actually executing the queries or modifying files. This is a safe way to review the SQL the agent generated before any data is touched. If you are performing a simple read-only task, you might stick to the default mode. However, if you are doing a large number of repetitive updates and you trust the agent's logic, bypassPermissions can speed up the process. You can also define specific tool permissions in your .claude/settings.json file to always allow or deny certain database operations.

If the agent starts a query that is taking too long or looks incorrect, you can press the Escape key to interrupt the process immediately. This is particularly important when working with large databases where a poorly optimized query could hang your terminal. Pressing Escape twice will offer you the chance to go back to an earlier message and refine your prompt. This gives you total control over the database interaction, ensuring that you can stop any dangerous operation before it completes.

Explore schemas and generate migrations effectively

When you need to change your database structure, the agent can help you write the necessary SQL. You can ask it to analyze your current schema by letting it read the table definitions. Because the agent can use tools to list tables and describe columns, it builds an accurate mental model of your application. You can then ask it to suggest a migration script to add a new column or create a join table. This reduces the time you spend looking up specific SQL syntax for your version of the database.

You can store project-specific instructions in a CLAUDE.md file in your repo root. This is a great place to document your database naming conventions or specific migration patterns. For example, if you always use UUIDs for primary keys, you can mention this in CLAUDE.md. The agent will read this file and ensure that any SQL it generates follows your team's standards. This ensures consistency across your codebase even when the agent is writing the initial drafts of your migration files.

Once the agent proposes a migration, you can ask it to save the script to a file using the Write tool. You can then run the migration using the Bash tool directly from the claude interface. This end-to-end workflow keeps everything in one place. You do not need to switch back to your editor to create the file and then back to the terminal to run it. The agent handles the file creation and the execution while you supervise the process in the interactive session.

Fix data inconsistencies and test queries locally

Debugging data issues is often faster when the agent can see the actual rows in your tables. If a user reports a bug that only happens with specific data, you can ask the agent to search for that data in your local instance. It can use the Grep tool to find patterns in exported logs or use database tools to run select statements. By seeing the data, the agent can more accurately identify why a piece of application logic is failing. It can then suggest a fix for the code or a one-time data correction script.

Testing complex queries becomes an interactive conversation. You can ask the agent to write a query that calculates a specific metric, and it can run that query against your local database to verify the results. If the output is not what you expected, you can refine the prompt and try again. This iterative process is much faster than the traditional method of writing a query, running it in a separate client, and then manually adjusting your application code. The agent bridges the gap between your data and your logic.

Monitor multiple database tasks using tiles

When you are running complex migrations across several microservices, keeping track of every terminal window is difficult. You might have one session running a long data validation script while another session prepares a schema update for a different service. This is where adhdTerminal provides a better way to work. It allows you to run many Claude Code sessions side by side as tiles on a wall. Each tile has its own color and name, and it clearly shows if the agent is currently working or waiting for your input. This visual layout prevents you from losing track of which database you are currently modifying.

The app is a native tool for macOS and Windows that helps you stay organized without searching through tabs. Because the tiles show the last few exchanges of the conversation, you can see at a glance what the agent discovered in your local database. If you need to step away from your desk, the free iPhone app mirrors your wall over an encrypted link. You can check the progress of a database task or even send the next prompt from your phone. It costs 99 dollars once and offers a 7 day free trial with no account needed, making it a simple addition to a professional developer's setup.

Manage session context for long database interactions

Long sessions involving many database queries can quickly fill up the context window. Every result from a select statement and every schema definition takes up space in the memory of the session. You can check how much you have spent on a specific task by using the /cost or /usage commands. These show you the financial cost and the token usage of your current session. To keep the session efficient, use /compact to summarize the work you have done so far and free up tokens for new queries.

If the conversation becomes too cluttered with old data results that are no longer relevant, use /clear to start the session over in the same folder. This resets the context while keeping your MCP configuration intact. For recurring tasks, you can define custom slash commands as markdown files in the .claude/commands directory. This allows you to trigger complex database reports or health checks with a single command. You can even create specialized agents in the .claude/agents folder that are specifically tuned for database administration tasks.

When you finish a session, you can exit with Ctrl+C. If you need to return to that specific database task later, you can use claude --resume to pick it from a list of previous sessions. If you only have one active project, claude --continue will take you right back to the last exchange you had. This persistence ensures that you do not lose the context of your investigation. The agent remembers the schema it learned and the queries it ran, allowing you to pick up exactly where you left off.

Questions people ask

Can Claude Code modify my production database?

It can only access what you configure in your .mcp.json file. If you provide a production connection string and the agent has permissions to run write queries, it could modify data. It is safer to only provide credentials for local or staging environments.

What happens if a query result is too large for the session?

The agent may struggle with very large data sets as they consume the context window quickly. You should use /compact after large data reads or ask the agent to summarize the results or save them to a file instead of printing them all to the terminal.

How do I stop a long running database query?

You can press the Escape key once to interrupt the agent's current tool use. If the underlying database process is still running in the background, you may need to use a separate terminal to kill the specific PID or use the Bash tool to stop the process.

Read next

More on claude code basics·All posts