Drupal and CiviCRM integration starts with a decision about data ownership
Most nonprofits, associations and membership bodies that want CiviCRM alongside Drupal face one decision before any installation work: which system owns the contact record, the membership, the donation and the event registration. Drupal is the website that serves public content, forms and member pages. CiviCRM is the contact and contribution system that holds the people, their memberships, their payments and their event history. Settle that split on paper first, because it determines the database layout, the user accounts, the permissions and the reporting that follow. Ask who will edit a contact's name and address, who processes a renewal, and which system a member logs into to see their own record. Each answer points to one owner, and any field used by both systems needs a named source of truth. When Drupal needs to show CiviCRM data in views, blocks or forms, the supported bridge is the contributed CiviCRM Entity module, which exposes CiviCRM records to Drupal's entity system. The current release for this line is 4.0.9, which targets Drupal 10.3 and Drupal 11. Confirm that release against your chosen Drupal version on its Drupal.org release history before you plan around it. Also confirm the CiviCRM release you intend to run, its supported PHP and database versions, and its hosting requirements in CiviCRM's own documentation, because those details change independently of Drupal and are not covered by this page. In practice, the decision shows up as a short list of questions a partner should answer in writing: which entities and fields Drupal will read, which it will write, whether member self-service edits happen in Drupal forms or in CiviCRM screens, and who approves changes to shared fields. Clarifying these early keeps the integration small and makes the later choice between a shared or separate database easier to evaluate.
What you need in place before a Drupal CiviCRM integration starts
A CiviCRM integration sits on top of a Drupal site, so the Drupal version, PHP runtime, database and web server choices come first. Access, cron, backups and a staging copy decide whether the build can be tested and operated safely once it is live.
Drupal and PHP version
Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later. Drupal 10 reaches end of life on December 9, 2026, so a new build should target Drupal 11 unless there is a documented reason not to. Confirm that the CiviCRM release you select supports the same PHP and Drupal combination, and check its extension requirements before you commit to a version.
CiviCRM release compatibility
CiviCRM publishes its own PHP, database and extension requirements for each release, and these can differ from Drupal's minimums. The CiviCRM Entity module has release 4.0.9 for Drupal 10.3 and 11, so confirm that every contributed module you plan to use targets the same Drupal branch. Record the chosen CiviCRM and Drupal versions together in the project plan.
Web server and database
Drupal runs on Apache, Nginx and other web servers, with MariaDB, MySQL, PostgreSQL or SQLite as the database. Confirm which database your CiviCRM release supports, because the choice affects whether CiviCRM can share a database with Drupal or needs its own. Agree on the server and database versions with your operations team before provisioning.
Accounts and access
Plan who holds the Composer repository access, database credentials, Drupal administrator role and CiviCRM administrator role before the build starts. Separate deployment credentials from day-to-day administrator accounts, and confirm who can approve changes to the CiviCRM settings and extensions. Missing access is one of the most common causes of delay in the first sprint.
Cron access
CiviCRM relies on scheduled jobs for tasks such as membership renewals, reminders and processing of queued activities. Confirm that you can run Drupal cron on a fixed schedule, with a system cron or Drush command rather than page-load triggers, and that the schedule is visible to the team that operates the server. Decide who responds when a scheduled job fails.
Backup capacity and staging
Before the first CiviCRM data import, confirm that you have capacity for full database and file backups, and that restores have been tested. A staging environment with a recent copy of production data lets you test extension upgrades and field changes before they reach donor, member or event records. Ask whether your hosting platform can provision that copy on demand and who approves it.
Shared or separate database: which layout fits your site
In a shared layout, Drupal and CiviCRM live in one database server and one database, separated by schema or by table prefixes. Everything sits in one place, so a single dump captures both systems at the same point in time, and the two applications can join tables directly without crossing a network boundary. The cost is that the two systems share a failure domain. A bad migration, a runaway query or a corrupted table in one application affects the other.
- Backups: One backup job covers both systems, which keeps them consistent with each other, but a restore usually returns both to the same earlier point.
- Restores: Restoring only CiviCRM or only Drupal means extracting one schema or prefix set from a full dump, which is possible but needs a tested runbook.
- Upgrades: Drupal and CiviCRM upgrades touch the same server and may need to be sequenced so each application's schema changes do not block the other.
- Permissions: Database accounts can be scoped per schema, but a single account with broad rights is common in practice, so confirm least-privilege grants before go-live.
- Data isolation: Drupal's entity layer can read CiviCRM tables directly, which is convenient for views but widens what a Drupal compromise can reach.
Before committing, confirm with the CiviCRM project documentation which shared-database layout is supported for your Drupal and CiviCRM release, and test a restore of a single system.
In a separate layout, Drupal and CiviCRM each have their own database, and often their own database user, with a defined path for Drupal to read CiviCRM data. That path might be the Entity module's access to the CiviCRM database, a dedicated read-only account, or an API-based exchange. Failures stay more contained, and each system can be sized, backed up and upgraded on its own schedule. The trade-off is more moving parts and a join that is no longer free.
- Backups: Each database gets its own backup schedule and retention, so one system can be restored to a point in time without rewinding the other.
- Restores: Restoring CiviCRM alone is straightforward, but Drupal views that depend on CiviCRM data must be checked against the restored state.
- Upgrades: Drupal and CiviCRM can be upgraded in separate change windows, provided the read path and module versions remain compatible at each step.
- Permissions: A read-only database account for Drupal limits what a Drupal compromise can change in CiviCRM, which is a clear isolation benefit.
- Data isolation: Personal data for donors and members can be held under stricter controls in the CiviCRM database, and the read path becomes a documented control point.
Ask the CiviCRM and Entity module maintainers which read patterns are supported with a separate database for your release, and confirm the read path in a staging environment before you commit.
The choice is less about performance than about who must be able to recover what, and how independently. The same question drives the decision: if CiviCRM data is corrupted or deleted, does the team need to restore it without rolling back Drupal content, and can Drupal keep serving pages while CiviCRM is down? Membership, donation and event records usually carry more regulatory and financial weight than marketing content, so organizations often lean toward separation for those reasons. Smaller sites with one administrative team and simple data flows may find the shared layout easier to run.
- Recovery scope: Decide whether you need to restore one system alone, and test that scenario before choosing.
- Access model: Map which teams and accounts can reach each database, and whether Drupal editors should ever see raw CiviCRM tables.
- Operational ownership: If different teams run Drupal and CiviCRM, a separate database usually matches the ownership boundary.
- Read path stability: A direct table read is simpler but tied to schema details, while an API-based path is more stable across upgrades but adds latency and build work.
- Hosting constraints: Confirm the database server, version and backup tooling your hosting model supports for each option.
Write the chosen layout, its restore runbook and the supported release combination into the design record before any build starts.
Whichever layout you pick, the question of how Drupal reads CiviCRM data determines much of the risk. The CiviCRM Entity module exposes CiviCRM data to Drupal so that it can be used in views and forms. Its release 4.0.9 supports Drupal 10.3 and 11, according to the Drupal.org release history, so confirm that your Drupal and CiviCRM versions fall within a supported combination. The module's configuration determines which entities and fields Drupal can see, and that choice is an access control decision as much as a display decision.
- Entity exposure: Expose only the CiviCRM entities that a view or form needs, rather than every table the module can reach.
- Write paths: Decide whether Drupal forms may write to CiviCRM at all, and if so, route writes through CiviCRM's own logic rather than direct SQL.
- Account scope: Use a dedicated database user with read rights for views, and a separate account with write rights only where a documented form needs it.
- Caching: Views built on CiviCRM data need cache invalidation rules that match how often membership and donation records change.
- Upgrade testing: Re-test every view that reads CiviCRM after each Drupal or CiviCRM upgrade, since schema changes can break direct reads.
Confirm the Entity module release and the CiviCRM version against the supported combination for your environment before you finalize the read path.
How to install CiviCRM and connect it to Drupal in sequence
This sequence takes a team from a confirmed Drupal 10.3 or 11 target to a working CiviCRM instance whose contacts, memberships, donations and events appear in Drupal views and forms. Each step closes with a check so problems surface before the next layer is added.
Confirm the target Drupal site and PHP runtime
Confirm that the target is Drupal 10.3 or 11, not an older branch, and that the hosting stack runs a PHP version the chosen Drupal release supports. The Drupal.org PHP requirements page sets Drupal 10 at PHP 8.1 or later and Drupal 11 at PHP 8.3 or later, so check the runtime against that page and against the CiviCRM release notes before anything is installed. Also confirm the web server and database pair from the system requirements page. Done means the team has a written version matrix signed off by the platform owner, and a staging environment that matches production in PHP version and extensions.
Plan the database layout and credentials
Decide whether CiviCRM will share the Drupal database or use its own. A shared database simplifies backups and restores but mixes two schemas and their upgrade cycles; a separate database isolates CiviCRM upgrades and access control at the cost of a second connection to manage. Record the database names, users, privileges and the location of credentials, and keep secrets out of version control. Done means a reviewed database diagram and a credential inventory that the operations team has approved.
Install Drupal with Composer
Build the Drupal codebase with Composer from the Drupal project template so that core, contributed modules and CiviCRM dependencies are pinned in a lock file that can be reviewed and rebuilt. Install Drupal through the web installer or Drush, pointing it at the planned database. Done means the Drupal administration login works on staging, a clean composer install reproduces the same lock file, and cron runs without errors on the status report.
Install CiviCRM as documented for the release
Add CiviCRM using the installation method documented by the CiviCRM project for the release that supports your Drupal version, rather than copying steps from older blog posts. Complete the CiviCRM setup wizard, set the site key and the database connection, and configure the base URL and the directories CiviCRM needs for uploads and templates. Done means you can log in as a CiviCRM administrator, the CiviCRM dashboard loads without errors, and a test contact can be created and retrieved.
Install the CiviCRM Entity module
Install the CiviCRM Entity module at a release that supports Drupal 10.3 and 11. The Drupal.org release history lists release 4.0.9 for those versions, so pin that release in Composer unless the release history shows a newer one for your target. Enable the module with its CiviCRM integration dependencies and clear caches. Done means the module appears as enabled in the Drupal extend page, the status report shows no missing requirements, and the Drupal admin can see CiviCRM entity types in the configuration screens.
Configure the CiviCRM connection and permissions
Map CiviCRM permissions to Drupal roles so that staff, members and anonymous visitors see only what their role allows. Decide which CiviCRM entities, such as contacts, contributions, memberships and events, are exposed to Drupal, and restrict Drupal-side access to them with the same care you give the CiviCRM admin interface. Done means test accounts for each role confirm the expected access, and a restricted account cannot open records outside its permission set.
Expose required entities to Views and webforms
Build a Drupal View that lists a test contact and a test contribution or membership record, then add a Webform or Drupal form that writes to a test CiviCRM entity. Use the CiviCRM Entity fields in Views filters and relationships, and confirm that the view respects the permissions set in the previous step. Done means the test contact is visible in the view, the form submission creates the expected record in CiviCRM, and the record matches the Drupal view after a cache clear.
Verify cron, queues and a restore into staging
Schedule Drupal cron and any CiviCRM scheduled jobs, confirm that queued work runs and that failures are logged, and check that jobs continue after a server restart. Then take a backup of both databases and the file directories and restore it into an empty staging environment to prove the backup is usable. Done means the scheduled job log shows successful runs, the restored staging site opens the CiviCRM dashboard and Drupal view with the same test records, and the restore steps are documented for the operations team.
How CiviCRM contacts, contributions and events map to Drupal users and content
This table compares each CiviCRM object with the Drupal object it is most often matched to and the decision the team must make before build starts. Read it as a checklist: each row names a choice that changes permissions, data flow or page structure. Field-level mapping should come from your own data model and be checked against the CiviCRM Entity documentation for the release you deploy.
| Drupal object | CiviCRM object | Decision needed |
|---|---|---|
| User accounts | Contacts (individuals, households, organizations) | Decide which contact types get a Drupal login, and whether a contact is linked to a user by email, by stored ID or by both. |
| Drupal roles | CiviCRM permissions and groups | Decide which CiviCRM groups or permissions drive Drupal roles, and who maintains that mapping when staff change. |
| Content access by membership | Membership types and statuses | Decide which membership types and statuses (for example current, grace or lapsed) unlock gated pages, and how renewals update access. |
| Views and listings of gifts | Contribution records | Decide which contribution fields are exposed to Views, and whether donor-facing pages show totals, receipts or only thank-you content. |
| Event pages and registration | Event and participant records | Decide whether event details live in CiviCRM with Drupal displaying them, or in Drupal with CiviCRM storing registrations. |
| Profile and contact fields | Custom fields and profile forms | Decide which CiviCRM custom fields map to Drupal fields, which are read-only, and which stay in CiviCRM only. |
| Forms and submissions | Activities and contact updates | Decide which Drupal forms write to CiviCRM, how duplicates are matched, and who reviews failed submissions. |
Security settings that protect CiviCRM data inside Drupal
CiviCRM holds contact records, donation history, membership status and consent choices, and Drupal serves the pages that expose them. The controls below cover who can administer CiviCRM, what reaches public visitors, how database access is split, how Drupal and CiviCRM receive security updates, and how forms handle payments and consent.
Limit CiviCRM administrative permissions
CiviCRM has its own permission set on top of Drupal roles, so a user with Drupal administration rights is not automatically a CiviCRM administrator, and the reverse is also true. Name the individuals who may change settings, payment processors, custom fields and contact deletion, and keep that list short. Review it on a fixed schedule and when staff change roles. Confirm which CiviCRM permissions are granted to Drupal roles that editors use, since a broad grant can expose contact data through admin screens.
Keep personal data out of public views
Drupal views built on CiviCRM data can publish names, addresses, donation amounts or membership status if the filters do not check access. Every view that reads contacts, contributions or memberships should require a permission, and anonymous users should see only fields you intend to publish, such as event listings. Test each view while logged out and as each role. Pay special attention to exposed filters, contextual arguments and search pages, which often reveal records that the default display hides.
Protect database credentials and split access
CiviCRM reads and writes its own database, and Drupal usually connects to a database on the same server or cluster. Store credentials outside the web root and keep them out of version control. Use one account for the application with the rights it needs, and a separate read-only account for reporting tools and analysts. Confirm with your database team whether backups and replicas carry the same protections, because a copy of the CiviCRM schema is a copy of personal data.
Apply Drupal advisory process to contributed code
The Drupal Security Team publishes advisories with CVE identifiers and risk scores, and security releases ship on Wednesday release windows. Subscribe to advisories for Drupal core and for each contributed module your CiviCRM integration depends on, and set a rule for how quickly a critical advisory is applied to staging and then production. Record each advisory and the date it was applied, so an auditor or incident responder can trace the state of the site at any point.
Check CiviCRM component security notices
CiviCRM is maintained separately from Drupal core and its contributed modules, so Drupal advisories do not cover it. Watch the security notices for the CiviCRM core and the extensions your site installs, including payment processor extensions. Before each update, read the release notes for changes to permissions, API access or data handling. Treat any extension that has not been updated in a long period as a risk to assess, not a routine dependency.
Review payment and consent handling in forms
Donation, membership and event forms connect Drupal input to CiviCRM payment processors and consent records. Confirm which fields are stored in CiviCRM and which pass through to the processor, and whether card data ever touches your servers. Check that consent checkboxes record the choice, the time and the wording shown, and that opt-outs reach every mailing tool. Ask your payment provider and your compliance lead to confirm the scope of the form design before launch.
Common failures in CiviCRM and Drupal integrations and how to fix them
This table pairs each common symptom in a CiviCRM and Drupal integration with its likely cause and a specific fix. Use it as a triage list during build and after go-live, and check the release notes of the CiviCRM Entity module and CiviCRM itself before any upgrade.
| Symptom | Likely cause | Fix |
|---|---|---|
| CiviCRM Entity not visible after install | The module was installed through Composer but not enabled, or the CiviCRM bootstrap did not complete, so Drupal never registers its entity types. | Enable the CiviCRM Entity module, clear the Drupal cache, and confirm CiviCRM is installed and reachable from the Drupal settings. Check the Drupal status report for errors first. |
| PHP version mismatch when Drupal 11 is installed on an older PHP | Drupal 11 requires PHP 8.3 or later, and the server or PHP-FPM pool still runs an older version, so Composer resolves packages incorrectly or the site fails on load. | Confirm the PHP version used by the web server and by the command-line Composer and Drush. Upgrade PHP before installing Drupal 11, and align the Composer platform setting with the target version. |
| Views return empty results because of missing permissions | The anonymous or authenticated role lacks the CiviCRM permissions needed to read contacts, memberships or events, so the Views query filters out every row. | Grant only the specific CiviCRM view permissions each role needs, then test the view as each role. Avoid granting full CiviCRM administration to front-end roles. |
| Duplicate contacts created by Drupal user sign-up | The sign-up flow creates a new CiviCRM contact without matching an existing contact by email, often because the CiviCRM dedupe rule is not applied on that path. | Configure the CiviCRM dedupe rules for individuals and use a sync method that looks up existing contacts before creating one. Merge existing duplicates with the CiviCRM merge tool after a test on a copy. |
| Database restore fails because of the shared or separate layout | A backup taken from a shared database does not include the CiviCRM tables, or a separate CiviCRM database is restored without its matching Drupal database and settings file. | Document which database holds each system and back up both together with matching settings files. Restore to a staging copy and run the CiviCRM and Drupal status checks before reconnecting users. |
| Upgrade blocked because the Entity module release does not match the Drupal minor version | The installed CiviCRM Entity release supports a different Drupal minor version than the one being upgraded to, so Composer refuses to resolve the update. | Check the module's release history for the target Drupal minor version before upgrading. Confirm the supported version in the release notes, and plan the Drupal and module upgrade in one tested change on staging. |
| Cron or queue jobs stalling | CiviCRM scheduled jobs are not triggered, or the Drupal cron runs without the CiviCRM job runner, so memberships, reminders and imports queue without processing. | Set up a single scheduled trigger for both Drupal cron and CiviCRM scheduled jobs, run it from the command line rather than page loads, and monitor the job log for failed runs after each deployment. |
How CiviCRM data reaches Drupal views and forms
The CiviCRM Entity module is the layer that presents CiviCRM records, such as contacts, memberships, contributions and events, as Drupal entities, so that Views listings and Drupal forms can read and reference them the way they read nodes or users. The Topic Facts supplied for this page list release 4.0.9 of the module for Drupal 10.3 and 11, which is the version to plan around. Because the module maps CiviCRM data into Drupal's entity system, the practical consequences are that filters, sorts and relationships in a View are only as rich as the entity types and fields the module exposes, and that Drupal's caching layers (render cache, Views cache and any reverse proxy in front of the site) must be invalidated when CiviCRM changes, or listings will show stale membership status or event seats. Confirm how the release handles cache invalidation for each entity type you plan to list before you promise members live data.
The central decision is where listings are built. Views on the Drupal side can produce member directories, upcoming event pages and renewal lists quickly, and they fit editorial control and theming well. The cost is a second copy of the data that must stay consistent with CiviCRM, which remains the system of record for contributions, membership status, contact privacy and consent. A common pattern is to keep authoritative state in CiviCRM, expose only the fields a listing needs, and limit Views to read-only presentation, with any write path going through CiviCRM's own forms. Note that the entity types, field names, available filters and form options depend on the module release, so run a proof of concept against your actual CiviCRM version and record which relationships and fields you can use before you commit the design.
Questions buyers ask before hiring help with Drupal and CiviCRM
What drives the cost of a Drupal and CiviCRM integration?
The main cost drivers are the number of CiviCRM entities you expose to Drupal, the complexity of your membership and payment rules, the volume and cleanliness of any data you migrate, whether CiviCRM shares the Drupal database or runs on its own, and how much testing your acceptance criteria require. Each driver adds design, build and verification work. Most of the spend is one-time implementation, with hosting, security updates and CiviCRM and Drupal upgrades recurring afterward. Ask any provider for a written quote that breaks these items out, and expect it to follow from a fixed scope agreed in writing before work starts.
How long does a CiviCRM integration take to deliver?
Duration depends on what you are building, not on a fixed template. The biggest factors are how many membership types, contribution pages, events and payment processors you need, how many CiviCRM data objects must appear in Drupal views and forms, whether historical records must be migrated, and how quickly your staff can review and approve test results. Confirm the timeline with the provider against a written scope, and ask which milestones depend on your team's availability. A fixed-scope agreement is the place where the schedule and its assumptions should be recorded.
What must our organization provide before the work starts?
You need named data owners who can decide how memberships, donations and event registrations should behave, and who can sign off on those decisions. You also need sample records from each area, including edge cases such as lapsed memberships, refunds and multi-contact households, because realistic data exposes problems that clean test data hides. Finally, assign staff to acceptance testing with time set aside in their calendars. Without these people, the build stalls at the questions that only your organization can answer.
Can our internal team build and run this without a partner?
A team with strong Drupal and PHP experience and some CiviCRM familiarity can often build the integration, provided it has time and clear requirements. The risks sit in areas that are easy to underestimate: keeping CiviCRM and Drupal versions compatible through upgrades, deciding between shared and separate databases, handling payment and membership logic correctly, and verifying permissions so that data is not exposed to the wrong users. Ask whether your team has tested an upgrade of both systems together and who will own that work after launch.
Should CiviCRM share the Drupal database or use its own?
The choice affects installation effort, upgrade paths, backup scope and the blast radius of a mistake. A shared database can simplify some lookups but ties the two systems' schema changes and restore points together. A separate database isolates CiviCRM data and its backups, at the cost of more connection and synchronization design. Decide this before build starts, and document the backup and restore procedure for whichever option you choose. Confirm the approach with the provider and your own database administrators.
What should a written quote for this work include?
A useful quote lists the scope in specific terms: the CiviCRM features in use, the Drupal views and forms to be built, the entities exposed, the payment and membership rules, any data migration, the environments to be built, and the acceptance tests. It should state what is one-time and what recurs, such as hosting and maintenance, and name the assumptions behind the price and schedule. It should also describe what your organization must provide and how change requests are priced. Because DeployOpen works from fixed-scope written agreements, a quote is only as precise as the scope it follows from.
Which CiviCRM Entity module version is needed for current Drupal?
The CiviCRM Entity module has release 4.0.9 for Drupal 10.3 and Drupal 11, according to its Drupal.org release history. Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later, so confirm your PHP runtime before choosing versions. Check the compatibility of your CiviCRM release with your Drupal version as well, since both projects change over time. Verify these details against the release history and your own test environment before you commit to a version set.
How DeployOpen scopes and delivers a Drupal CiviCRM integration
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For a Drupal and CiviCRM integration, we work from a written scope so that membership, donation and event data, the Drupal site and the hosting model are agreed before any build begins.
How we scope
- Confirm which Drupal 10 or 11 site, PHP version and database engine the integration will run on.
- Decide with you whether CiviCRM shares the Drupal database or uses a separate one, and record the reasons.
- List the memberships, donation pages, events and Views or forms that must read CiviCRM data.
- Agree the written scope, deliverables and timeline before work starts, since most engagements are fixed-scope.
How we build
- Install CiviCRM with Composer and configure the Drupal modules, including the CiviCRM Entity module at a version confirmed for your Drupal release.
- Map CiviCRM contacts, contributions, memberships and events to Drupal views and forms with access rules you approve.
- Test permissions, payment and form flows, and data accuracy in a staging environment that mirrors production hosting.
- Document configuration, custom code and Composer dependencies so your team can review and maintain them.
How we hand over
- Deliver the source code, Composer lock files, configuration exports and deployment notes to your repositories.
- Walk your administrators and developers through CiviCRM roles, Drupal views and the update procedure for each component.
- Provide a checklist of backup, cron and queue settings that your operations team needs to verify after go-live.
- Record open items, known limits and the versions tested so that the next upgrade has a clear starting point.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer, scoped in writing.
- Plan CiviCRM and Drupal upgrades against the Drupal core release schedule and the CiviCRM release notes.
- Review contributed module and CiviCRM Entity updates before they reach production, with rollback steps agreed in advance.
- Ask for a quote based on the written scope, which sets out who is responsible for hosting, licensing and third-party services.
