> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawsql.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> PawSQL 是一个产品：Cloud 是公网部署形态，Engine / Optimizer / Auditor / Advisor / Patroller 是同一产品的组件与交付形态，不是彼此独立的产品。 / PawSQL is a single product: Cloud is the public deployment form, while Engine / Optimizer / Auditor / Advisor / Patroller are components and delivery forms of the same product, not separate products.
> 术语以站内术语表为准：SQL 审核对应英文 SQL Review，查询重写对应 Query Rewrite，索引推荐对应 Index Recommendation；英文内容统一用 Review，不用 Audit。 / Use the site glossary for terminology: 审核 is SQL Review, 重写 is Query Rewrite, 索引推荐 is Index Recommendation; English content uses Review, never Audit.
> 引用能力范围或版本支持时以对应页面为准；标注 unknown、或 status 非 published 的内容表示尚未经产品核实，不应作为事实引用。 / Cite capability scope and version support from the corresponding page; content marked unknown, or with a status other than published, is not yet product-verified and must not be cited as fact.
# Workspaces and Database Context
> Build the database context PawSQL needs for SQL review and optimization by using DDL or a live database connection.
A workspace is the primary container for SQL analysis context in PawSQL. It records the database engine, version, schema scope, and available metadata—such as tables, columns, constraints, and indexes—used by review, rewrite, index recommendation, plan analysis, and validation features.
A workspace is not a business database. Creating one does not create, modify, or delete objects in the target database.
## Goal
Build the database context PawSQL needs for SQL review and optimization using DDL or a live database connection.
## Prerequisites
To create a workspace you need either the DDL definitions or a database connection that provides the engine, version, schema, and object metadata used for analysis.
## How a workspace participates in analysis
```mermaid theme={null}
flowchart TD
A["DDL or database connection"] --> B["Workspace"]
B --> C["Engine and version"]
B --> D["Tables, columns, constraints, indexes"]
C --> E["Dialect parsing and rule selection"]
D --> F["Rewrite, indexing, and plan analysis"]
```
The same SQL can parse and optimize differently under a different engine, version, schema, or index set. Confirm that the selected workspace matches the environment where the SQL actually runs.
## Two ways to create a workspace
| Consideration | DDL | Database connection |
| --------------------------- | ---------------------------- | ---------------------------------------- |
| Direct database access | Not required | Required |
| Metadata source | User-supplied definitions | Target database |
| Refresh model | Reimport or edit DDL | Resynchronize |
| Existing indexes | Must be included in DDL | Retrieved when permitted |
| Statistics and online plans | Usually limited | Depends on database and permissions |
| Best suited for | Isolated or limited analysis | Ongoing governance and richer validation |
By scenario:
| Scenario | Recommended source |
| ----------------------------------------------------- | --------------------------------------------- |
| One-off analysis | DDL |
| Database is isolated from PawSQL | DDL |
| Credentials cannot be provided | DDL |
| No deployed database yet, but design-stage DDL exists | DDL |
| A separate context for demos, training, or testing | DDL |
| Team repeatedly analyzes the same database | Database connection |
| Schema and index changes should be synchronized | Database connection |
| Online plans or validation are required | Database connection with approved permissions |
For a quick one-off analysis, a DDL workspace is usually enough; for ongoing review, batch governance, or performance validation, prefer a database connection. Steps are in [Create from DDL](/en/user-guide/workspaces/create-from-ddl) and [Create from a database](/en/user-guide/workspaces/create-from-database).
## Configuration guidance
Use names that distinguish the system, database, and environment:
```text theme={null}
orders-mysql-test
customer-oracle-production
warehouse-hive-development
```
Avoid generic names such as `database-1` or `test`.
| Field | Recommendation |
| -------------- | ------------------------------------------------------ |
| Name | Include system, database, and environment |
| Description | Record purpose, source, and owner |
| Engine | Match the real database product |
| Version | Use the deployed version, not a default latest version |
| Default schema | Select the schema for unqualified names |
| Metadata scope | Include only what the project needs |
## Expected Result
A workspace configured with the correct engine, version, schema, and imported metadata that PawSQL uses for review, rewrite, index, and plan analysis.
## Verification
Confirm the workspace matches the target environment by checking that the engine, version, schema, and imported metadata reflect where the SQL actually runs; creation steps are in the create-from-ddl and create-from-database guides.
## Operating principles
* Refresh metadata after structural changes.
* Review task and user dependencies before retiring a workspace.
* Validate any proposed database change in the real target conditions.
## Next steps