Project Structure Recommendation

When developing a connector with the Fivetran Connector SDK, we recommend the following project structure to ensure smooth local development, debugging, and deployment:

project_name/
├── myenv/            # (Optional) Local virtual environment directory
├── connector.py      # Main connector script
├── requirements.txt  # Dependency file for pip (or use pyproject.toml instead)
├── pyproject.toml    # (Optional alternative to requirements.txt) PEP 518/517 dependency file
├── configuration.json # (Optional) File for passing configuration parameters, such as credentials during connector deployment
├── .gitignore  # (Optional) File listing files and folders to ignore during packaging and deployment
├── AGENTS.md       # (Optional) Instruction file for your AI agents

Guidelines

• Place connector.py and your dependency file (requirements.txt or pyproject.toml) directly in the project root. If both are present, pyproject.toml takes precedence.
• If you use a local Python virtual environment (for example, myenv/), store it in a separate folder within your project.
• If you create a configuration.json file in the project, remember to add it to .gitignore to avoid committing sensitive credentials.
• Always run fivetran debug, fivetran reset and fivetran deploy commands from the project root — the same directory that contains connector.py.
• An optional .gitignore file allows you to define the list of ignored files when we package and deploy code. It uses the standard .gitignore pattern format. Use it to exclude files from your project directory that don't need to be part of the deployed connector.
• An optional AGENTS.md file can be included to provide instructions for any AI agents you may be using in your connector development. Depending on your use cases, you can place your AI agent instructions files in the project root, a dedicated subdirectory, or outside of the project directory.
• If you have multiple Python files for your project, consider organizing them into a subdirectory (for example, src/ or utils/) and adjusting your import statements accordingly. Ensure the main connector.py file remains in the project's root for compatibility with the Connector SDK project structure. Refer to this example for more details.

This setup supports better compatibility with IDE tooling and ensures that the Connector SDK runtime environment properly locates your scripts and dependencies.