# Databases with Claude Code: schema, queries and migrations

> MCP connectors, agents and skills for schema, SQL queries, migrations and performance.

- Source: https://doutorai.pt/en/for/databases
- Site: Doutor AI (https://doutorai.pt/en) - AI tools for small businesses

Almost every project ends up with a database at its center. The problem rarely shows up on day one: it shows up when the orders table reaches millions of rows, when a query that used to run in 20 ms starts holding up the whole page, or when you need to change a column in a database that is in production and cannot stop. At that point the job is no longer writing SQL, it is understanding what the database is really doing.

The components on this page deal with three different things. The connectors (MCP) give Claude Code a real connection to your database, so it can list tables, read the schema and run queries instead of guessing from the application code. The agents and skills bring the method: how to normalize a model, which index to create from an execution plan, how to split a migration into reversible steps.

Start with the connector for the engine you use, because almost everything else improves when Claude Code can see the real schema. Then choose by concrete problem: design from scratch, a slow query, or a schema change in production. Avoid installing everything. Two or three well-chosen components do more than a long list nobody reviews, and most of them only ask for an environment variable with the connection string.

20 hand-picked components, from 4 different angles.

## Connectors (MCP) to connect to the database

These connectors give Claude Code direct access to the engine, through a connection string stored in an environment variable. Without them, Claude Code only knows the schema it can infer from the code.

- **postgresql-integration** (Connectors): Built on the @modelcontextprotocol/server-postgres server and connects through POSTGRES_CONNECTION_STRING, the most direct way to explore tables and run queries on an existing Postgres database. [page](https://doutorai.pt/en/components/mcps__postgresql-integration)
- **mysql-integration** (Connectors): For projects built on MySQL: it starts with uvx and only asks for MYSQL_CONNECTION_STRING, giving access to the data and to database management within the working session. [page](https://doutorai.pt/en/components/mcps__mysql-integration)
- **supabase** (Connectors): Connects to your Supabase project with the --read-only and --project-ref arguments, which keeps the session limited to reads. It authenticates with a personal access token. [page](https://doutorai.pt/en/components/mcps__supabase)
- **mongodb** (Connectors): Comes configured with --readOnly, so it works well for inspecting collections and documents in a local MongoDB or an Atlas cluster without the risk of writing by mistake. [page](https://doutorai.pt/en/components/mcps__mongodb)
- **redis** (Connectors): The official Redis server for querying and managing data in natural language, useful when the question is what is really in the cache and under which keys. [page](https://doutorai.pt/en/components/mcps__redis)
- **dbhub** (Connectors): An alternative worth considering when the project touches several engines: a single connector covers PostgreSQL, MySQL, MariaDB, SQL Server and SQLite from one DSN. [page](https://doutorai.pt/en/components/mcps__dbhub)

## Schema design and data modeling

For when the model is still being decided, or when the existing one can no longer handle the way the application accesses data.

- **database-architect** (Agents): A starting point for architecture decisions: technology choice, modeling and data patterns in microservices. It plans and designs, handing fine Postgres tuning over to specialized agents. [page](https://doutorai.pt/en/components/agents__database-architect)
- **database-schema-designer** (Skills): Describe the domain and get a schema with normalization, constraints and indexes already thought through, for SQL or NoSQL. A good choice to get past the blank page without losing data integrity. [page](https://doutorai.pt/en/components/skills__database-schema-designer)
- **postgresql** (Skills): Specific to Postgres: data types, indexes, constraints and advanced features. Use it once the engine has been chosen, so the schema takes advantage of what is unique to Postgres. [page](https://doutorai.pt/en/components/skills__postgresql)
- **supabase-schema-architect** (Agents): In Supabase projects, the schema cannot be separated from the RLS policies. This agent handles both together, including planning the migrations that result from them. [page](https://doutorai.pt/en/components/agents__supabase-schema-architect)
- **nosql-specialist** (Agents): When the data does not fit well into tables: modeling and architecture decisions for MongoDB, Redis, Cassandra and other document or key-value stores. [page](https://doutorai.pt/en/components/agents__nosql-specialist)

## Slow queries, indexes and performance

The group to open when the application already works but some pages are slow, or database load is rising with no clear explanation.

- **sql-pro** (Agents): For complex SQL that spans PostgreSQL, MySQL, SQL Server and Oracle. It handles rewriting heavy queries and index strategies once performance has become the problem. [page](https://doutorai.pt/en/components/agents__sql-pro)
- **database-optimization** (Agents): Works from measurements instead of guesses: it profiles first, uses EXPLAIN ANALYZE to read the execution plan and only then designs indexes based on real access patterns. [page](https://doutorai.pt/en/components/agents__database-optimization)
- **supabase-postgres-best-practices** (Skills): Brings together Postgres performance practices published by Supabase, which apply when writing, reviewing or tuning queries, schema designs and database configuration. [page](https://doutorai.pt/en/components/skills__supabase-postgres-best-practices)
- **postgresql-optimization** (Skills): A complete workflow for query tuning in Postgres, with performance analysis, indexing strategies and management of the database in production. [page](https://doutorai.pt/en/components/skills__postgresql-optimization)
- **mongodb-performance-advisor** (Agents): On the MongoDB side, it analyzes database performance and returns concrete recommendations on queries and indexes, instead of generic modeling advice. [page](https://doutorai.pt/en/components/agents__mongodb-performance-advisor)

## Migrations and schema changes in production

Changing the schema of a live database is the riskiest part. These components handle versioning, rollback and steps that do not stop the service.

- **database-migration** (Skills): Covers schema and data migrations in Sequelize, TypeORM and Prisma, with rollback strategies and steps that avoid service interruption. It also helps when switching ORMs. [page](https://doutorai.pt/en/components/skills__database-migration)
- **create-database-migrations** (Commands): Detects the ORM from package.json or requirements.txt, looks for the migrations that already exist in the repository and creates the new one with versioning and rollback from the start. [page](https://doutorai.pt/en/components/commands__create-database-migrations)
- **supabase-migration-assistant** (Commands): Generates and manages Supabase migrations with automatic testing and validation, a good fit for anyone whose project and schema are already built on Supabase. [page](https://doutorai.pt/en/components/commands__supabase-migration-assistant)
- **prisma-expert** (Skills): In Prisma projects, the problems concentrate in four places: the schema, failing migrations, poorly modeled relations and slow queries. That is exactly the scope of this skill. [page](https://doutorai.pt/en/components/skills__prisma-expert)

## How to install each type of component

The four types are installed in different ways. Agents go in .claude/agents/, skills in .claude/skills/ and commands in .claude/commands/, inside the project or in your home folder, and Claude Code loads them in the next session. The connectors (MCP) are not markdown files: they are a JSON block with the mcpServers key, which specifies the command to run (npx or uvx) and the environment variables it needs. The connection string should not be written in plain text in a shared repository. Store it in a system environment variable or in a .env file outside version control, and confirm the connection with a read query before giving any write instruction.

## Always start in read mode

The connectors on this page take different stances on writing. The MongoDB one comes with --readOnly and the Supabase one with --read-only in its arguments, which limits the session to queries. The PostgreSQL, MySQL and dbhub ones, however, depend entirely on the permissions of the user you put in the connection string. The prudent way to start is to create a database user with SELECT only and point the connector at that user. You keep the part that matters, which is Claude Code seeing the real schema and the real data, without a misread request turning into an UPDATE with no WHERE clause.

## How to combine these components in one task

These components do more when chained than when used alone. A common example: the PostgreSQL connector gives access to the schema and the execution plans, the optimization agent reads those plans and proposes an index, and the migrations skill turns that index into a versioned file with rollback, instead of a command typed by hand in the console. The same chain works for design from scratch, with the architecture agent deciding the engine and the model and the Postgres-specific skill fine-tuning types and constraints. Avoid loading two components that do the same thing, because Claude Code ends up with competing instructions for the same decision.

## Keep reading

- [MCP (Model Context Protocol)](https://doutorai.pt/en/how-to/mcp)

## Frequently asked questions

### Do I really need an MCP connector, or is an agent enough?

They are different things. An agent or a skill brings method and knowledge, but only works with what it can read in the project's code. A connector (MCP) connects Claude Code to the engine and lets it list tables, query the schema and run queries. To design from scratch, the agent is enough. To diagnose a slow query in a database that already exists, the connector makes the difference.

### Is it safe to give Claude Code access to the production database?

It is not the recommended starting point. Use a copy or a test environment whenever possible. If it really has to be production, create a dedicated user with read permissions only, turn on the connector's read-only options when they exist, and review any write SQL before running it.

### Which of the optimization agents should I choose?

It depends on the engine and the stage you are at. For complex SQL across several engines, sql-pro. To go from an execution plan to indexes, database-optimization. In Postgres, the specific skills go into detail the generic agents do not cover. In MongoDB, the reasoning about indexes is different and calls for its own agent.

### Do these components work for NoSQL databases?

They do, but with less choice. There is a connector for MongoDB, another for Redis, a modeling agent for document and key-value stores, and a performance agent for MongoDB. Most of the rest of this page assumes SQL, especially Postgres, which is where the Doutor AI technical library has the most material available.

### Can the generated migrations be applied without review?

No. A migration is code that changes data that already exists and it is not always reversible. Read the generated file, confirm it has a rollback step, and test it first on a copy of the schema with a similar data volume. Changes to columns with many rows can lock tables, and you only notice that with real data.

---
Content by Doutor AI (https://doutorai.pt/en). When quoting, please cite the source: https://doutorai.pt/en/for/databases