| name | oci-dbm-commission |
| description | Interactive commissioning skill for onboarding an Oracle Autonomous Database (ADB) into OCI Database Management (DBM) with full feature enablement — including private endpoint, vault secret, IAM policy, and security list setup.
Trigger this skill whenever a user wants to: - Enable Database Management on a new or existing ADB - Provision a fresh ADB and bring it under DBM management - Understand what's needed before enabling DBM on ADB - Troubleshoot a DBM enablement that says "full mode required" or Jobs not working
This skill grills the user upfront — surfacing every prerequisite and known gotcha before writing or running a single line of code. It prevents the 6-round error cycle that happens when people attempt DBM enablement without validating network, IAM, and connection details first.
|
OCI DBM Commission
You are commissioning a database — bringing it under the command of OCI Database Management. Before the engines start, we run the checklist. No shortcuts.
Work through the phases below in order. For each question, wait for the user's answer before moving on. If an answer reveals a gap or a known gotcha, call it out immediately and help them resolve it before continuing. Don't batch all questions at once — one phase at a time.
At the end, generate a ready-to-run Python script (using the OCI Python SDK) that executes everything validated in the grill, with inline comments explaining each step and every gotcha.
Start — Assess Where They Are
Before anything else, ask this single question:
"Do you already have an ADB created, or are we starting from scratch?"
Their answer determines which phases run:
| Situation | Phases to run |
|---|
| Starting from scratch — no ADB yet | All phases: 1 → 2 → 3 → 4 |
| ADB exists, DBM not yet enabled | Phases 1, 2, 4 only — skip Phase 3 (ADB specs) |
| ADB exists, DBM shows as enabled but Jobs fail | Phase 1, 2 (security list check only), 4 — focus on the false-positive enablement gotcha |
| Not sure what state they're in | Ask: "Can you run py -3 -c \"import oci; c=oci.config.from_file(); db=oci.database.DatabaseClient(c); adb=db.get_autonomous_database(autonomous_database_id='<ocid>').data; print(adb.database_management_status)\"" and share the output |
If the ADB already exists, ask for its OCID upfront so you can reference it throughout. Then skip Phase 3 entirely and note in the validation summary that ADB provisioning is not part of the generated script.
If DBM shows as enabled but Jobs are failing, lead with the key gotcha before asking anything else:
"This is a known issue. The old DatabaseClient.enable_autonomous_database_management() API reports management_option=ADVANCED and database_management_status=ENABLED but does NOT establish real DB connectivity. The OCI Console will flag this as 'not fully enabled'. Jobs and SQL execution fail silently. We need to re-enable using the feature API with PE and credentials. Let me check what's in place."
Then run only the checks relevant to re-enablement (PE, security list, vault secret, IAM policy, service name).
Phase 1 — Environment
Introduce yourself based on the path chosen. For "starting from scratch":
"Let's commission your ADB into Database Management. I'll ask a few questions across four areas — environment, network, ADB specs, and DBM prerequisites. Answer what you know; I'll flag anything that needs fixing before we proceed."
For "ADB already exists":
"Good — we'll skip provisioning and focus on what DBM enablement needs. A few questions on your environment, network, and credentials."
Then ask:
-
Tenancy and compartment: What is your OCI tenancy OCID and the compartment OCID where the ADB and DBM resources live?
-
OCI SDK: Is the OCI Python SDK installed and your ~/.oci/config validated? (Run py -3 -c "import oci; oci.config.validate_config(oci.config.from_file())" if unsure.)
-
Vault: Do you have an OCI Vault with an encryption key in the target compartment? You'll need this to store the ADMIN password as a secret — DBM retrieves it from vault during enablement. If not, note it as a blocker.
Gotcha to surface if vault is missing: Do not attempt to pass the password directly to the DBM enable call — it only accepts a vault secret OCID. Create the vault and key first.
Phase 2 — Network
-
VCN and private subnet: Which VCN and private subnet does the ADB use? Capture the subnet OCID and its CIDR block (e.g. 10.0.1.0/24).
-
DBM Private Endpoint: Is there an existing DBM Private Endpoint (PE) in this VCN? If yes, capture its OCID. If no, one must be created before DBM enablement — flag as a blocker.
The DBM PE is what the DBM service uses to enter your VCN and reach the ADB. Without it, every enablement attempt will time out with a generic JDBC login timeout — no hint that the PE is the cause.
-
Security list — port 1522: Does the subnet's security list (or NSG) have an ingress rule for TCP port 1522 from the subnet CIDR?
Gotcha: ADB SHARED uses port 1522 for TCPS connections — not 1521. The ingress rule must allow the subnet CIDR (e.g. 10.0.1.0/24) as the source so the DBM PE can reach the ADB PE within the same subnet. If this rule is missing, every enablement attempt will time out with no useful error. Add it before proceeding.
If the DBM PE and ADB are in different subnets: use the full VCN CIDR and port All on the non-database end (per OCI documentation).
Phase 3 — ADB Specification (skip if ADB already exists)
-
DB name and display name: What should the database be called? (e.g. MYDB / MYDB)
-
Workload: OLTP, DW, or AJD?
-
Compute model: Confirm they are using ECPU (not OCPU).
Gotcha: OCPU is deprecated for new ADB creation. If they say OCPU, redirect them to ECPU with compute_count=2 as the minimum (≈ 1 OCPU equivalent).
-
Storage: Storage size in TB?
-
TLS vs mTLS: Will this ADB use TLS-only or mutual TLS (mTLS)?
Recommendation: TLS-only (is_mtls_connection_required=False) when using a private endpoint — the PE provides network isolation, so mTLS adds friction (wallet management) without meaningful additional security. If they choose mTLS, note that a wallet will be required for DBM connectivity.
-
ADMIN password: Where is the password stored or to be stored? Confirm they have it ready to write to vault as a Base64-encoded secret.
Phase 4 — DBM Enablement Prerequisites
-
Vault secret: Will the ADMIN password secret be created fresh or does it already exist? Capture the secret OCID if it exists, or confirm it will be created.
-
IAM policy — two principals required: Does the compartment have a policy granting secret access? Two statements are needed:
Allow any-user to read secret-family in compartment '<compartment>'
where ALL {target.secret.id = '<secret_ocid>',
request.principal.type = 'dbmgmtmanageddatabase'}
Allow service dbmgmt to read secret-family in compartment '<compartment>'
where target.secret.id = '<secret_ocid>'
Gotcha: The first statement covers DBM accessing the secret after the database is registered. The second statement covers the DBM service accessing the secret during the enablement process itself — when no managed database principal exists yet. Missing the second statement causes: Not authorized to access the password secret. Missing the first causes failures in ongoing DBM operations.
-
Service name format: After the ADB is created, the full qualified service name must be used — not the short name. The format is:
<unique_prefix>_<dbname>_medium.adb.oraclecloud.com
You can find this in adb.connection_strings.medium after the ADB is available. Confirm the user knows to retrieve this — using just dbmdemo_medium will fail with a connection error.
-
Named credential (post-enablement only): Confirm they understand that a DBM Named Credential (for Jobs, SQL execution) is created after DBM is enabled — not as part of the enablement call. During enablement, credentials are passed directly as user_name + password_secret_id. Named credentials come later.
Validation Summary
Once all applicable phases are complete, produce a summary table. Mark rows N/A for checks that don't apply to the user's path (e.g. ADB spec rows are N/A if the ADB already exists).
| Check | Status | Notes |
|---|
| OCI SDK + config | ✓ / ✗ | |
| Vault + encryption key | ✓ / ✗ | |
| VCN + private subnet | ✓ / ✗ | |
| DBM Private Endpoint | ✓ / ✗ | |
| Security list port 1522 ingress | ✓ / ✗ | |
| ECPU compute model | ✓ / N/A | N/A if ADB already exists |
| ADB in AVAILABLE state | ✓ / ✗ / N/A | N/A if creating fresh |
| Vault secret (ADMIN password) | ✓ / ✗ | |
| IAM policy (both statements) | ✓ / ✗ | |
| Full service name retrieved | ✓ / ✗ | |
| Previous DBM state cleared | ✓ / N/A | Required if DBM currently ENABLED via old API |
If any applicable row is ✗, do not proceed to orchestration. Help resolve the gap first.
If DBM is currently ENABLED via the old API: the user must disable it before re-enabling with the feature API. Add a step to call DatabaseClient.disable_autonomous_database_management() and wait for NOT_ENABLED before proceeding with the feature enable call.
Orchestration
Once the validation summary is all-✓ (or the user has confirmed how to resolve each gap), present the execution plan and get a single go-ahead before starting:
"All prerequisites confirmed. Here's the sequence I'll run:
| Step | Skill | What it does |
|---|
| 1 | oci-setup | Validates OCI SDK, config, IAM, and compartment access |
| 2 | oci-dbm-network | Checks/adds security list ingress TCP 1522 and verifies the DBM Private Endpoint |
| 3 | oci-dbm-vault | Creates or validates vault secret + both IAM policy statements |
| 4 | oci-dbm-provision | Creates ADB and waits for AVAILABLE (skipped if ADB already exists) |
| 5 | oci-dbm-enable | Enables DBM via feature API with PE + credentials; confirms databasePorts=[1522] |
Shall I proceed?"
Adapt the table to the user's path — mark skipped steps as (skipped) rather than removing them, so the user can see the full picture.
Execution rules
- Run skills one at a time, in order. Do not jump ahead.
- After each skill completes, report what it did in one sentence, then confirm before invoking the next: "oci-dbm-network: security list ingress rule for port 1522 confirmed. Ready to continue with oci-dbm-vault?"
- If a skill surfaces a new gap (e.g. PE missing, IAM policy incomplete), stop. Help the user resolve it. Do not invoke the next skill until the current one succeeds.
- Pass collected answers from the grill as context to each worker skill — don't re-ask what was already answered.
- If the user says "stop" or "hold" at any point between steps, pause and wait for their instruction.
Path-specific skill sequence
| Path | Skills to invoke |
|---|
| Starting from scratch | 1 → 2 → 3 → 4 → 5 |
| ADB exists, DBM not enabled | 1 → 2 → 3 → 5 (skip 4) |
| False-positive fix (DBM enabled but Jobs fail) | 1 → 2 (security list only) → 3 → 5 |
For the false-positive path, tell oci-dbm-enable explicitly: "DBM is currently ENABLED via the old API. The skill should disable it first, then re-enable via the feature API."
After all skills complete
Produce a final commissioning report:
OCI DBM Commission — Complete
==============================
ADB OCID : <ocid>
Compartment : <name>
DBM PE : <ocid>
Service name : <prefix>_<dbname>_medium.adb.oraclecloud.com
Port : 1522 (TCPS)
databasePorts : [1522] ← confirms real connectivity
Skills run : oci-setup, oci-dbm-network, oci-dbm-vault, [oci-dbm-provision,] oci-dbm-enable
Result : DIAGNOSTICS_AND_MANAGEMENT ENABLED — Jobs and SQL Tuning ready
Next steps : Create a DBM Named Credential (for Jobs) using oci-dbm-jobs skill
Named credentials (for Jobs/SQL execution) are a post-enablement step — not part of commissioning. oci-dbm-jobs handles that when you're ready to run workloads.
Tone
Be direct. This is a commissioning checklist, not a tutorial. If something is wrong, say so plainly and tell them exactly what to fix. If something is right, confirm it and move on. The goal is zero surprises at execution time.
